Konfigurowanie protokołu HTTP i JSWŁ. dla transkodowania gRPC JSON

Artykuł
11/30/2023

Transkodowanie gRPC JSON tworzy RESTful JSON internetowych interfejsów API na podstawie metod gRPC. Używa adnotacji i opcji dostosowywania sposobu RESTmapowania interfejsu API na metody gRPC.

Reguły HTTP

Metody gRPC muszą być oznaczone adnotacjami z regułą HTTP, zanim obsługują transkodowanie. Reguła HTTP zawiera informacje o wywoływaniu metody gRPC jako RESTinterfejsu API ful, 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 dla metod gRPC.
Zidentyfikowane przez nazwę google.api.http.
Zaimportowane z google/api/annotations.proto pliku. Pliki google/api/http.proto i google/api/annotations.proto muszą znajdować się w projekcie.

Uwaga

Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).

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 CreateAddress metoda jest mapowana na POST określoną trasę:

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

Marszruta

Trasy transkodowania gRPC JSON obsługują parametry trasy. Na przykład {name} w trasie wiąże się z name polem w komunikacie żądania.

Aby powiązać pole z zagnieżdżonym komunikatem, określ ścieżkę do pola. W poniższym przykładzie {params.org} powiązanie z polem org w IssueParams komunikacie:

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:

Treść żądania

Transkodowanie deserializuje treść JSżądania WŁĄCZONE do komunikatu żądania. Pole body określa sposób mapowania treści żądania HTTP na komunikat żądania. Wartość jest nazwą pola żądania, którego wartość jest mapowana na treść żądania HTTP lub * do mapowania wszystkich pól żądania.

W poniższym przykładzie treść żądania HTTP jest deserializowana do address pola:

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ść żą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 poprzednim przykładzie:

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

Treść odpowiedzi

Domyślnie transkodowanie serializuje cały komunikat odpowiedzi jako JSWŁĄCZONY. Pole response_body umożliwia serializacji 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 address pole jest serializowane do treści odpowiedzi jako JSWŁĄCZONE.

Specyfikacja

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

Dostosowywanie JSwł.

Komunikaty są konwertowane na i z JSWŁĄCZONE przy użyciu JSmapowania ON w specyfikacji Protobuf. Mapowanie ON firmy Protobuf JSto ustandaryzowany sposób konwersji między elementami JSON i Protobuf, a wszystkie serializacji są zgodne z tymi regułami.

Jednak transkodowanie gRPC JSON oferuje pewne ograniczone opcje dostosowywania JSfunkcji WŁĄCZONE za pomocą GrpcJsonSettingspolecenia , jak pokazano w poniższej tabeli.

Opcja	Wartość domyślna	opis
IgnoreDefaultValues	`false`	W przypadku ustawienia wartości `true`pola z wartościami domyślnymi są ignorowane podczas serializacji.
WriteEnumsAsIntegers	`false`	Jeśli ustawiono `true`wartość , wartości wyliczenia są zapisywane jako liczby całkowite zamiast ciągów.
WriteInt64sAsStrings	`false`	Jeśli ustawiono `true`wartość , `Int64` a `UInt64` wartości są zapisywane jako ciągi zamiast liczb.
WriteIndented	`false`	Jeśli jest ustawiona wartość `true`, JSfunkcja ON jest zapisywana przy użyciu dość drukowania. Ta opcja nie ma wpływu na metody przesyłania strumieniowego, które zapisują komunikaty rozdzielane JSwierszami i nie mogą używać dość drukowania.

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

.proto W pliku json_name opcja pola dostosowuje nazwę pola, gdy jest serializowany jako JSWŁĄCZONE, jak w poniższym przykładzie:

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

Transkodowanie nie obsługuje zaawansowanego JSdostosowywania ON. Aplikacje wymagające precyzyjnej JSkontroli struktury ON powinny rozważyć użycie ASP.NET core internetowego interfejsu API.

Udostępnij za pośrednictwem