Cấu hình HTTP và JSON cho gRPC JSON transcoding trong ASP.NET Core

gRPC JSON transcoding (chuyển mã gRPC JSON) tạo ra các RESTful JSON web API từ các gRPC method. Nó sử dụng các annotation (chú thích) và tùy chọn để tùy chỉnh cách một RESTful API ánh xạ đến các gRPC method.

HTTP rules (quy tắc HTTP)

Các gRPC method phải được chú thích với một HTTP rule trước khi chúng hỗ trợ transcoding. HTTP rule bao gồm thông tin về cách gọi gRPC method như một RESTful API, chẳng hạn như HTTP method và route.

import "google/api/annotations.proto";

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {
    option (google.api.http) = {
      get: "/v1/greeter/{name}"
    };
  }
}

Một HTTP rule là:

• Một annotation trên gRPC method.
• Được xác định bởi tên google.api.http.
• Được import từ file google/api/annotations.proto. Các file google/api/http.proto và google/api/annotations.proto cần phải có trong project.

HTTP method (phương thức HTTP)

HTTP method được chỉ định bằng cách đặt route vào tên trường HTTP method tương ứng:

• get
• put
• post
• delete
• patch

Trường custom cho phép các HTTP method khác.

Trong ví dụ sau, phương thức CreateAddress được ánh xạ đến POST với route đã chỉ định:

service Address {
  rpc CreateAddress (CreateAddressRequest) returns (CreateAddressReply) {
    option (google.api.http) = {
      post: "/v1/address",
      body: "*"
    };
  }
}

Route (đường dẫn)

Các route trong gRPC JSON transcoding hỗ trợ route parameter. Ví dụ: {name} trong một route ràng buộc với trường name trên request message.

Để ràng buộc một trường trên một nested message (message lồng nhau), chỉ định đường dẫn đến trường đó. Trong ví dụ sau, {params.org} ràng buộc với trường org trên message IssueParams:

service Repository {
  rpc GetIssue (GetIssueRequest) returns (GetIssueReply) {
    option (google.api.http) = {
      get: "/{apiVersion}/{params.org}/{params.repo}/issue/{params.issueId}"
    };
  }
}

message GetIssueRequest {
  int32 api_version = 1;
  IssueParams params = 2;
}
message IssueParams {
  string org = 1;
  string repo = 2;
  int32 issueId = 3;
}

Các route của transcoding và route của ASP.NET Core có cú pháp và tập tính năng tương tự. Tuy nhiên, một số tính năng routing của ASP.NET Core không được transcoding hỗ trợ. Bao gồm:

• Route constraints (ràng buộc route)
• Default values (giá trị mặc định)
• Optional parameters (tham số tùy chọn)
• Complex segments (phân đoạn phức tạp)

Request body (nội dung yêu cầu)

Transcoding deserialize request body JSON thành request message. Trường body chỉ định cách HTTP request body ánh xạ đến request message. Giá trị là tên của trường request có giá trị được ánh xạ đến HTTP request body, hoặc * để ánh xạ tất cả các trường request.

Trong ví dụ sau, HTTP request body được deserialize vào trường address:

service Address {
  rpc AddAddress (AddAddressRequest) returns (AddAddressReply) {
    option (google.api.http) = {
      post: "/{apiVersion}/address",
      body: "address"
    };
  }
}

message AddAddressRequest {
  int32 api_version = 1;
  Address address = 2;
}
message Address {
  string street = 1;
  string city = 2;
  string country = 3;
}

Query parameters (tham số truy vấn)

Bất kỳ trường nào trong request message không được ràng buộc bởi route parameter hoặc request body có thể được đặt bằng cách sử dụng HTTP query parameter.

service Repository {
  rpc GetIssues (GetIssuesRequest) returns (GetIssuesReply) {
    option (google.api.http) = {
      get: "/v1/{org}/{repo}/issue"
    };
  }
}

message GetIssuesRequest {
  string org = 1;
  string repo = 2;
  string text = 3;
  PageParams page = 4;
}
message PageParams {
  int32 index = 1;
  int32 size = 2;
}

Trong ví dụ trên:

• Các trường org và repo được ràng buộc từ route parameter.
• Các trường khác, chẳng hạn như text và các trường lồng nhau từ page, có thể được ràng buộc từ query string: ?text=value&page.index=0&page.size=10

Response body (nội dung phản hồi)

Theo mặc định, transcoding serialize toàn bộ response message thành JSON. Trường response_body cho phép serialize một tập con của response message.

service Address {
  rpc GetAddress (GetAddressRequest) returns (GetAddressReply) {
    option (google.api.http) = {
      get: "/v1/address/{id}",
      response_body: "address"
    };
  }
}

message GetAddressReply {
  int32 version = 1;
  Address address = 2;
}
message Address {
  string street = 1;
  string city = 2;
  string country = 3;
}

Trong ví dụ trên, trường address được serialize vào response body dưới dạng JSON.

Đặc tả

Để biết thêm thông tin về tùy chỉnh gRPC transcoding, xem HttpRule specification.

Tùy chỉnh JSON

Các message được chuyển đổi đến và từ JSON bằng cách sử dụng JSON mapping trong đặc tả Protobuf. Ánh xạ JSON của Protobuf là một cách chuẩn hóa để chuyển đổi giữa JSON và Protobuf, và tất cả việc serialization đều tuân theo các quy tắc này.

Tuy nhiên, gRPC JSON transcoding cung cấp một số tùy chọn hạn chế để tùy chỉnh JSON với GrpcJsonSettings, như được hiển thị trong bảng sau.

builder.Services.AddGrpc().AddJsonTranscoding(o =>
{
    o.JsonSettings.WriteIndented = true;
});

Trong file .proto, tùy chọn trường json_name tùy chỉnh tên của trường khi nó được serialize thành JSON, như trong ví dụ sau:

message TestMessage {
  string my_field = 1 [json_name="customFieldName"];
}

Transcoding không hỗ trợ tùy chỉnh JSON nâng cao. Các ứng dụng yêu cầu kiểm soát chính xác cấu trúc JSON nên cân nhắc sử dụng ASP.NET Core Web API.