Udostępnij za pośrednictwem

Konfigurowanie transkodowania http i JSON dla transkodowania gRPC JSON

  • Artykuł

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Autor: 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 adnotacjami z regułą HTTP, zanim obsługują 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:

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 JSON gRPC 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ść żądania JSON 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 powyższym 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 w formacie JSON. 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 JSON.

Specyfikacja

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

Dostosowywanie formatu JSON

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

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

Opcja Wartość domyślna opis
IgnoreDefaultValues false W przypadku ustawienia wartości truepola z wartościami domyślnymi są ignorowane podczas serializacji.
WriteEnumsAsIntegers false Jeśli ustawiono truewartość , wartości wyliczenia są zapisywane jako liczby całkowite zamiast ciągów.
WriteInt64sAsStrings false Jeśli ustawiono truewartość , Int64 a UInt64 wartości są zapisywane jako ciągi zamiast liczb.
WriteIndented false Jeśli ustawiono wartość true, kod JSON jest zapisywany przy użyciu dość drukowania. Ta opcja nie ma wpływu na metody przesyłania strumieniowego, które zapisują komunikaty JSON rozdzielane wierszami 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 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 internetowego interfejsu API.

Dodatkowe zasoby