Konfigurowanie HTTP i JSON na potrzeby transkodowania gRPC-JSON

James Newton-King

Transkodowanie gRPC JSON tworzy internetowe interfejsy API RESTful JSON z metod gRPC. Używa adnotacji i opcji dostosowywania sposobu mapowania interfejsu API RESTful na metody gRPC.

Reguły HTTP

Metody gRPC muszą być oznaczone adnotacją z regułą HTTP, zanim będą obsługiwać transkodowanie. Reguła HTTP zawiera informacje dotyczące wywoływania metody gRPC jako interfejsu API RESTful, takich jak metoda HTTP i trasa.

import "google/api/annotations.proto";

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

Reguła HTTP to:

• Adnotacja dotycząca metod gRPC.
• Zidentyfikowane o nazwie google.api.http.
• Zaimportowane z pliku google/api/annotations.proto. Pliki google/api/http.proto i google/api/annotations.proto muszą znajdować się w projekcie.

metoda HTTP

Metoda HTTP jest określana przez ustawienie trasy na zgodną nazwę pola metody HTTP:

• get
• put
• post
• delete
• patch

Pole custom umożliwia korzystanie z innych metod HTTP.

W poniższym przykładzie metoda CreateAddress jest mapowana na POST przy użyciu określonej trasy:

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

Trasa

Trasy transkodowania JSON gRPC obsługują parametry trasy. Na przykład {name} w trasie routingu jest powiązane z polem name w komunikacie żądania.

Aby powiązać pole w zagnieżdżonej wiadomości, określ ścieżkę do pola. W poniższym przykładzie {params.org} wiąże się z polem org w komunikacie 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;
}

Trasy transkodowania i trasy ASP.NET Core mają podobną składnię i zestaw funkcji. Jednak niektóre funkcje routingu ASP.NET Core nie są obsługiwane przez transkodowanie. Są to:

• Ograniczenia trasy
• Wartości domyślne
• Parametry opcjonalne
• Złożone segmenty

Treść żądania

Transkodowanie deserializuje treść żądania w formacie JSON do komunikatu żądania. Pole body określa sposób mapowania treści żądania HTTP na komunikat żądania. Wartość jest albo nazwą pola żądania, którego wartość jest mapowana na treść żądania HTTP, albo * do mapowania wszystkich pól żądania.

W poniższym przykładzie treść żądania HTTP jest deserializowana do pola 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;
}

Parametry zapytań

Wszystkie pola w komunikacie żądania, które nie są powiązane z parametrami trasy lub treścią żądania, można ustawić przy użyciu parametrów zapytania 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;
}

W powyższym przykładzie:

• Pola org i repo są powiązane z parametrami trasy.
• Inne pola, takie jak text, i pola zagnieżdżone z elementu page, mogą być powiązane z parametrami ciągu zapytania: ?text=value&page.index=0&page.size=10

Treść odpowiedzi

Domyślnie transkodowanie serializuje cały komunikat odpowiedzi w formacie JSON. Pole response_body umożliwia serializację podzestawu komunikatu odpowiedzi.

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;
}

W poprzednim przykładzie pole address jest serializowane do treści odpowiedzi jako JSON.

Specyfikacja

Aby uzyskać więcej informacji na temat dostosowywania transkodowania gRPC, zobacz specyfikację HttpRule.

Dostosuj JSON

Komunikaty są konwertowane na i z formatu JSON przy użyciu mapowania JSON w specyfikacji Protobuf. Mapowanie JSON w Protobuf to ustandaryzowany sposób konwersji między formatami JSON i Protobuf, a wszystkie serializacje są zgodne z tymi regułami.

Jednak transkodowanie gRPC JSON oferuje pewne ograniczone opcje dostosowywania kodu JSON za pomocą GrpcJsonSettings, jak pokazano w poniższej tabeli.

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

W pliku .proto opcja pola json_name dostosowuje nazwę pola używaną podczas serializacji do formatu JSON, jak w poniższym przykładzie:

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

Transkodowanie nie obsługuje zaawansowanego dostosowywania JSON. Aplikacje wymagające precyzyjnej kontroli struktury JSON powinny rozważyć użycie ASP.NET Core Web API.

Treści powiązane

• Transkodowanie gRPC JSON w aplikacjach gRPC ASP.NET Core
• Specyfikacja HttpRule