ASP.NET Core: Định cấu hình HTTP và JSON để chuyển mã JSON gRPC

Trong bài viết này

1. Quy tắc HTTP
2. Tùy chỉnh JSON
3. Tài nguyên bổ sung

Chuyển mã JSON gRPC tạo API web RESTful JSON từ các phương thức gRPC. Nó sử dụng các ghi chú (annotation) và tùy chọn để tùy chỉnh cách API RESTful ánh xạ tới các phương thức gRPC.

Quy tắc HTTP

Các phương thức gRPC phải được chú thích bằng quy tắc HTTP trước khi chúng hỗ trợ chuyển mã. Quy tắc HTTP bao gồm thông tin về cách gọi phương thức gRPC dưới dạng API RESTful, chẳng hạn như phương thức và định tuyến HTTP.

import "google/api/annotations.proto";

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

Một quy tắc HTTP là:

• Ghi chú về các phương thức gRPC.
• Được xác định bằng 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 dự án.

Ghi chú

Các liên kết tài liệu tới nguồn tham chiếu .NET thường tải nhánh mặc định của kho lưu trữ, thể hiện sự phát triển hiện tại cho bản phát hành tiếp theo của .NET. Để chọn thẻ cho một bản phát hành cụ thể, hãy sử dụng danh sách thả xuống Switch branches or tags. Để biết thêm thông tin, hãy xem Cách chọn thẻ phiên bản của mã nguồn ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Phương thức HTTP

Phương thức HTTP được chỉ định bằng cách đặt tuyến đến tên trường phương thức HTTP phù hợp:

• get
• put
• post
• delete
• patch

Trường custom cho phép các phương thức HTTP khác.

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

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

Định tuyến

Định tuyến chuyển mã JSON gRPC hỗ trợ các tham số định tuyến. Ví dụ: {name} trong một định tuyến liên kết với trường name trên message yêu cầu.

Để liên kết một trường trên một message lồng nhau, hãy chỉ định đường dẫn đến trường đó. Trong ví dụ sau, {params.org} liên kết 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 định tuyến chuyển mã và các định tuyến ASP.NET Core có bộ tính năng và cú pháp tương tự nhau. Tuy nhiên, một số tính năng định tuyến của ASP.NET Core không được chuyển mã hỗ trợ. Bao gồm các:

• Hạn chế về định tuyến
• Giá trị mặc định
• Thông số tùy chọn
• Phân đoạn phức tạp

Nội dụng yêu cầu (Request body)

Chuyển mã sẽ giải tuần tự hóa nội dung yêu cầu JSON thành message request. Trường body chỉ định cách ánh xạ nội dung yêu cầu HTTP tới message request. Giá trị này là tên của trường request có giá trị được ánh xạ tới nội dung HTTP hoặc * để ánh xạ tất cả các trường request.

Trong ví dụ sau, nội dung yêu cầu HTTP được giải tuần tự hóa thành 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;
}

Tham số truy vấn

Bất kỳ trường nào trong thông báo yêu cầu không bị ràng buộc bởi tham số định tuyến hoặc nội dung yêu cầu đều có thể được đặt bằng tham số truy vấn HTTP.

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 bị ràng buộc từ các tham số định tuyến.
• 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 liên kết khỏi chuỗi truy vấn: ?text=value&page.index=0&page.size=10

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

Theo mặc định, chuyển mã sẽ tuần tự hóa toàn bộ message phản hồi dưới dạng JSON. Trường response_body cho phép tuần tự hóa một tập hợp con của message phản hồi.

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 tuần tự hóa thành nội dung phản hồi dưới dạng JSON.

Đặc tả (Specification)

Để biết thêm thông tin về cách tùy chỉnh chuyển mã gRPC, hãy xem đặc tả HttpRule.

Tùy chỉnh JSON

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

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

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

Trong file .proto, trường tùy chọn json_name sẽ tùy chỉnh tên của trường khi nó được tuần tự hóa dưới dạng JSON, như trong ví dụ sau:

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

Chuyển mã 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 cấu trúc JSON chính xác nên cân nhắc sử dụng ASP.NET Core Web API.

Tài nguyên bổ sung

• Chuyển mã JSON gRPC trong ứng dụng gRPC ASP.NET Core
• Đặc tả HttpRule