Transkodowanie gRPC JSON w ASP.NET Core

gRPC to wysokowydajny framework zdalnego wywoływania procedur (RPC). Usługa gRPC używa protokołu HTTP/2, przesyłania strumieniowego, protobuf i kontraktów komunikatów w celu tworzenia usług w czasie rzeczywistym o wysokiej wydajności.

Jednym z ograniczeń dotyczących gRPC jest to, że nie każda platforma może jej używać. Przeglądarki nie obsługują w pełni protokołu HTTP/2, dzięki czemu REST interfejsy API i kod JSON są podstawowym sposobem pobierania danych do aplikacji przeglądarki. Pomimo korzyści, jakie zapewnia gRPC, REST interfejsy API i kod JSON mają ważne miejsce w nowoczesnych aplikacjach. Tworzenie interfejsów API gRPC i internetowych interfejsów API JSON wprowadza niepotrzebny narzut przy tworzeniu aplikacji.

W tym dokumencie omówiono sposób tworzenia internetowych interfejsów API JSON przy użyciu usług gRPC.

Omówienie

Transkodowanie JSON dla gRPC to rozszerzenie dla platformy ASP.NET Core, które umożliwia tworzenie interfejsów API REST opartych na formacie JSON dla usług gRPC. Po skonfigurowaniu transkodowanie umożliwia aplikacjom wywoływanie usług gRPC za pomocą znanych pojęć protokołu HTTP:

• Czasowniki HTTP
• Powiązanie parametru adresu URL
• Żądania/odpowiedzi w formacie JSON

Nadal można używać gRPC do wywoływania usług.

Użycie

1. Dodaj odwołanie do pakietu w Microsoft.AspNetCore.Grpc.JsonTranscoding.

2. Zarejestruj transkodowanie w kodzie startowym serwera, dodając AddJsonTranscoding: W pliku Program.cs zmień builder.Services.AddGrpc(); na builder.Services.AddGrpc().AddJsonTranscoding();.

3. Dodaj <IncludeHttpRuleProtos>true</IncludeHttpRuleProtos> do grupy właściwości w pliku projektu (.csproj):

   <Project Sdk="Microsoft.NET.Sdk.Web">
   
     <PropertyGroup>
       <TargetFramework>net8.0</TargetFramework>
       <Nullable>enable</Nullable>
       <ImplicitUsings>enable</ImplicitUsings>
       <InvariantGlobalization>true</InvariantGlobalization>
       <IncludeHttpRuleProtos>true</IncludeHttpRuleProtos>
     </PropertyGroup>
   

4. Opatrz metody gRPC w plikach .proto adnotacjami z użyciem powiązań HTTP i tras routingu:

   syntax = "proto3";
   
   option csharp_namespace = "GrpcServiceTranscoding";
   import "google/api/annotations.proto";
   
   package greet;
   
   // The greeting service definition.
   service Greeter {
     rpc SayHello (HelloRequest) returns (HelloReply) {
       option (google.api.http) = {
         get: "/v1/greeter/{name}"
       };
     }
   }
   
   // The request message containing the user's name.
   message HelloRequest {
     string name = 1;
   }
   
   // The response message containing the greetings.
   message HelloReply {
     string message = 1;
   }
   

Metodę gRPC SayHello można teraz wywoływać za pomocą gRPC oraz jako interfejs API sieci Web JSON:

• Żądanie: GET /v1/greeter/world
• Odpowiedź: { "message": "Hello world" }

Jeśli serwer jest skonfigurowany do zapisywania dzienników dla każdego żądania, dzienniki serwera pokazują, że usługa gRPC wykonuje wywołanie HTTP. Transkodowanie mapuje przychodzące żądanie HTTP na komunikat gRPC i konwertuje komunikat odpowiedzi na kod JSON.

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/1.1 GET https://localhost:5001/v1/greeter/world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'gRPC - /v1/greeter/{name}'
info: Server.GreeterService[0]
      Sending hello to world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'gRPC - /v1/greeter/{name}'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 1.996ms 200 application/json

Dodawanie adnotacji do metod gRPC

Metody gRPC muszą być opatrzone adnotacją określającą regułę HTTP, aby mogły obsługiwać transkodowanie. Reguła HTTP zawiera informacje na temat wywoływania metody gRPC, takiej jak metoda HTTP i trasa.

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

Przykład postępowania:

• Definiuje usługę Greeter za pomocą SayHello metody . Metoda ma regułę HTTP określoną przy użyciu nazwy google.api.http.
• Metoda jest dostępna za pomocą żądań GET i ścieżki /v1/greeter/{name}.
• Pole name w komunikacie żądania jest powiązane z parametrem trasy.

Dostępnych jest wiele opcji dostosowywania powiązania metody gRPC z interfejsem API RESTful. Aby uzyskać więcej informacji na temat dodawania adnotacji do metod gRPC i dostosowywania formatu JSON, zobacz Konfigurowanie protokołu HTTP i formatu JSON na potrzeby transkodowania gRPC JSON.

Metody strumieniowania

Tradycyjny gRPC działający przez HTTP/2 obsługuje przesyłanie strumieniowe we wszystkich kierunkach. Transkodowanie jest dostępne wyłącznie dla strumieniowania z serwera. Metody strumieniowania po stronie klienta i dwukierunkowego strumieniowania nie są obsługiwane.

Metody przesyłania strumieniowego serwera używają rozdzielanego wierszem kodu JSON. Każdy komunikat napisany przy użyciu WriteAsync jest serializowany do formatu JSON i następuje nowy wiersz.

Poniższa metoda strumieniowania z serwera zapisuje trzy komunikaty:

public override async Task StreamingFromServer(ExampleRequest request,
    IServerStreamWriter<ExampleResponse> responseStream, ServerCallContext context)
{
    for (var i = 1; i <= 3; i++)
    {
        await responseStream.WriteAsync(new ExampleResponse { Text = $"Message {i}" });
        await Task.Delay(TimeSpan.FromSeconds(1));
    }
}

Klient odbiera trzy obiekty JSON rozdzielane wierszami:

{"Text":"Message 1"}
{"Text":"Message 2"}
{"Text":"Message 3"}

Należy pamiętać, że WriteIndented ustawienie JSON nie ma zastosowania do metod przesyłania strumieniowego serwera. Ładne drukowanie dodaje nowe wiersze i białe znaki do formatu JSON, który nie może być używany z rozdzielanym wierszem JSON.

Wyświetl lub pobierz przykładową aplikację do transkodowania i przesyłania strumieniowego ASP.NET Core gPRC.

Protokół HTTP

Szablon usługi gRPC platformy ASP.NET Core dołączony do zestawu SDK platformy .NET tworzy aplikację skonfigurowaną tylko dla protokołu HTTP/2. Http/2 jest dobrym ustawieniem domyślnym, gdy aplikacja obsługuje tylko tradycyjne gRPC za pośrednictwem protokołu HTTP/2. Transkodowanie działa jednak zarówno z protokołem HTTP/1.1, jak i http/2. Niektóre platformy, takie jak platforma UWP lub Unity, nie mogą używać protokołu HTTP/2. Aby obsługiwać wszystkie aplikacje klienckie, skonfiguruj serwer, aby włączyć protokół HTTP/1.1 i HTTP/2.

Zaktualizuj protokół domyślny w pliku appsettings.json:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1AndHttp2"
    }
  }
}

Alternatywnie skonfiguruj Kestrel punkty końcowe w kodzie startowym.

Włączenie protokołu HTTP/1.1 i HTTP/2 na tym samym porcie wymaga protokołu TLS do negocjacji protokołu. Aby uzyskać więcej informacji na temat konfigurowania protokołów HTTP w aplikacji gRPC, zobacz temat Negocjowanie protokołu gRPC w ASP.NET Core.

transkodowanie JSON w gRPC vs gRPC-Web

Zarówno transkodowanie, jak i gRPC-Web umożliwiają wywoływanie usług gRPC z przeglądarki. Jednak sposób, w jaki każdy robi to, jest inny:

• gRPC-Web umożliwia aplikacjom przeglądarki wywoływanie usług gRPC z przeglądarki przy użyciu klienta gRPC-Web i narzędzia Protobuf. gRPC-Web wymaga, aby aplikacja przeglądarki wygenerowała klienta gRPC i ma zaletę wysyłania małych, szybkich komunikatów Protobuf.
• Transkodowanie umożliwia aplikacjom przeglądarki wywoływanie usług gRPC tak, jakby były to interfejsy API RESTful z formatem JSON. Aplikacja przeglądarki nie musi generować klienta gRPC ani nic wiedzieć o gRPC.

Poprzednią Greeter usługę można wywołać przy użyciu interfejsów API języka JavaScript przeglądarki:

var name = nameInput.value;

fetch('/v1/greeter/' + name)
  .then((response) => response.json())
  .then((result) => {
    console.log(result.message);
    // Hello world
  });

grpc-gateway

grpc-gateway to inna technologia tworzenia interfejsów API RESTful JSON z usług gRPC. Używa tych samych .proto adnotacji do odwzorowywania koncepcji HTTP na usługi gRPC.

grpc-gateway wykorzystuje generowanie kodu do tworzenia serwera reverse proxy. Odwrotny serwer proxy tłumaczy wywołania RESTful na format gRPC+Protobuf, a następnie przesyła je przez protokół HTTP/2 do usługi gRPC. Zaletą tego podejścia jest usługa gRPC nie wie o interfejsach API RESTful JSON. Każdy serwer gRPC może korzystać z grpc-gateway.

Tymczasem transkodowanie gRPC JSON działa wewnątrz aplikacji ASP.NET Core. Deserializuje kod JSON do komunikatów Protobuf, a następnie wywołuje usługę gRPC bezpośrednio. Transkodowanie w programie ASP.NET Core oferuje korzyści deweloperom aplikacji platformy .NET:

• Mniejsza złożoność: Zarówno usługi gRPC, jak i mapowany interfejs API RESTful JSON działają w ramach jednej aplikacji ASP.NET Core.
• Lepsza wydajność: transkodowanie deserializuje dane JSON do komunikatów Protobuf i bezpośrednio wywołuje usługę gRPC. Wykonanie tego w tym samym procesie zapewnia znaczące korzyści wydajnościowe w porównaniu z wykonaniem nowego wywołania gRPC do innego serwera.
• Niższy koszt: mniej serwerów powoduje zmniejszenie miesięcznego rachunku za hosting.

Aby uzyskać informacje na temat instalacji i użycia bramy grpc-gateway, zobacz plik README bramy grpc-gateway.

Treści powiązane

• Konfigurowanie protokołów HTTP i JSON dla transkodowania gRPC JSON w aplikacjach ASP.NET Core
• Korzystanie z usługi gRPC w aplikacjach przeglądarki
• gRPC-Web w aplikacjach gRPC ASP.NET Core

gRPC to wysokowydajny framework zdalnego wywoływania procedur (RPC). Usługa gRPC używa protokołu HTTP/2, przesyłania strumieniowego, protobuf i kontraktów komunikatów w celu tworzenia usług w czasie rzeczywistym o wysokiej wydajności.

Jednym z ograniczeń dotyczących gRPC jest to, że nie każda platforma może jej używać. Przeglądarki nie obsługują w pełni protokołu HTTP/2, dzięki czemu REST interfejsy API i kod JSON są podstawowym sposobem pobierania danych do aplikacji przeglądarki. Pomimo korzyści, jakie zapewnia gRPC, REST interfejsy API i kod JSON mają ważne miejsce w nowoczesnych aplikacjach. Tworzenie interfejsów API gRPC i internetowych interfejsów API JSON wprowadza niepotrzebny narzut przy tworzeniu aplikacji.

W tym dokumencie omówiono sposób tworzenia internetowych interfejsów API JSON przy użyciu usług gRPC.

Omówienie

Transkodowanie JSON dla gRPC to rozszerzenie dla platformy ASP.NET Core, które umożliwia tworzenie interfejsów API REST opartych na formacie JSON dla usług gRPC. Po skonfigurowaniu transkodowanie umożliwia aplikacjom wywoływanie usług gRPC za pomocą znanych pojęć protokołu HTTP:

• Czasowniki HTTP
• Powiązanie parametru adresu URL
• Żądania/odpowiedzi w formacie JSON

Nadal można używać gRPC do wywoływania usług.

Użycie

1. Dodaj odwołanie do pakietu w Microsoft.AspNetCore.Grpc.JsonTranscoding.
2. Zarejestruj transkodowanie w kodzie startowym serwera, dodając AddJsonTranscoding: W pliku Program.cs zmień builder.Services.AddGrpc(); na builder.Services.AddGrpc().AddJsonTranscoding();.
3. Utwórz strukturę /google/api katalogów w katalogu projektu zawierającym .csproj plik.
4. Dodaj google/api/http.proto pliki i google/api/annotations.proto do /google/api katalogu.
5. Opatrz metody gRPC w plikach .proto adnotacjami z użyciem powiązań HTTP i tras routingu:

syntax = "proto3";

option csharp_namespace = "GrpcServiceTranscoding";
import "google/api/annotations.proto";

package greet;

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

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings.
message HelloReply {
  string message = 1;
}

Metodę gRPC SayHello można teraz wywoływać za pomocą gRPC oraz jako interfejs API sieci Web JSON:

• Żądanie: GET /v1/greeter/world
• Odpowiedź: { "message": "Hello world" }

Jeśli serwer jest skonfigurowany do zapisywania dzienników dla każdego żądania, dzienniki serwera pokazują, że usługa gRPC wykonuje wywołanie HTTP. Transkodowanie mapuje przychodzące żądanie HTTP na komunikat gRPC i konwertuje komunikat odpowiedzi na kod JSON.

info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/1.1 GET https://localhost:5001/v1/greeter/world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint 'gRPC - /v1/greeter/{name}'
info: Server.GreeterService[0]
      Sending hello to world
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint 'gRPC - /v1/greeter/{name}'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 1.996ms 200 application/json

Dodawanie adnotacji do metod gRPC

Metody gRPC muszą być opatrzone adnotacją określającą regułę HTTP, aby mogły obsługiwać transkodowanie. Reguła HTTP zawiera informacje na temat wywoływania metody gRPC, takiej jak metoda HTTP i trasa.

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

Przykład postępowania:

• Definiuje usługę Greeter za pomocą SayHello metody . Metoda ma regułę HTTP określoną przy użyciu nazwy google.api.http.
• Metoda jest dostępna za pomocą żądań GET i ścieżki /v1/greeter/{name}.
• Pole name w komunikacie żądania jest powiązane z parametrem trasy.

Dostępnych jest wiele opcji dostosowywania powiązania metody gRPC z interfejsem API RESTful. Aby uzyskać więcej informacji na temat dodawania adnotacji do metod gRPC i dostosowywania formatu JSON, zobacz Konfigurowanie protokołu HTTP i formatu JSON na potrzeby transkodowania gRPC JSON.

Metody strumieniowania

Tradycyjny gRPC działający przez HTTP/2 obsługuje przesyłanie strumieniowe we wszystkich kierunkach. Transkodowanie jest dostępne wyłącznie dla strumieniowania z serwera. Metody strumieniowania po stronie klienta i dwukierunkowego strumieniowania nie są obsługiwane.

Metody przesyłania strumieniowego serwera używają rozdzielanego wierszem kodu JSON. Każdy komunikat napisany przy użyciu WriteAsync jest serializowany do formatu JSON i następuje nowy wiersz.

Poniższa metoda strumieniowania z serwera zapisuje trzy komunikaty:

public override async Task StreamingFromServer(ExampleRequest request,
    IServerStreamWriter<ExampleResponse> responseStream, ServerCallContext context)
{
    for (var i = 1; i <= 3; i++)
    {
        await responseStream.WriteAsync(new ExampleResponse { Text = $"Message {i}" });
        await Task.Delay(TimeSpan.FromSeconds(1));
    }
}

Klient odbiera trzy obiekty JSON rozdzielane wierszami:

{"Text":"Message 1"}
{"Text":"Message 2"}
{"Text":"Message 3"}

Należy pamiętać, że WriteIndented ustawienie JSON nie ma zastosowania do metod przesyłania strumieniowego serwera. Ładne drukowanie dodaje nowe wiersze i białe znaki do formatu JSON, który nie może być używany z rozdzielanym wierszem JSON.

Wyświetl lub pobierz przykładową aplikację do transkodowania i przesyłania strumieniowego ASP.NET Core gPRC.

Protokół HTTP

Szablon usługi gRPC platformy ASP.NET Core dołączony do zestawu SDK platformy .NET tworzy aplikację skonfigurowaną tylko dla protokołu HTTP/2. Http/2 jest dobrym ustawieniem domyślnym, gdy aplikacja obsługuje tylko tradycyjne gRPC za pośrednictwem protokołu HTTP/2. Transkodowanie działa jednak zarówno z protokołem HTTP/1.1, jak i http/2. Niektóre platformy, takie jak platforma UWP lub Unity, nie mogą używać protokołu HTTP/2. Aby obsługiwać wszystkie aplikacje klienckie, skonfiguruj serwer, aby włączyć protokół HTTP/1.1 i HTTP/2.

Zaktualizuj protokół domyślny w pliku appsettings.json:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1AndHttp2"
    }
  }
}

Alternatywnie skonfiguruj Kestrel punkty końcowe w kodzie startowym.

Włączenie protokołu HTTP/1.1 i HTTP/2 na tym samym porcie wymaga protokołu TLS do negocjacji protokołu. Aby uzyskać więcej informacji na temat konfigurowania protokołów HTTP w aplikacji gRPC, zobacz temat Negocjowanie protokołu gRPC w ASP.NET Core.

transkodowanie JSON w gRPC vs gRPC-Web

Zarówno transkodowanie, jak i gRPC-Web umożliwiają wywoływanie usług gRPC z przeglądarki. Jednak sposób, w jaki każdy robi to, jest inny:

• gRPC-Web umożliwia aplikacjom przeglądarki wywoływanie usług gRPC z przeglądarki przy użyciu klienta gRPC-Web i narzędzia Protobuf. gRPC-Web wymaga, aby aplikacja przeglądarki wygenerowała klienta gRPC i ma zaletę wysyłania małych, szybkich komunikatów Protobuf.
• Transkodowanie umożliwia aplikacjom przeglądarki wywoływanie usług gRPC tak, jakby były to interfejsy API RESTful z formatem JSON. Aplikacja przeglądarki nie musi generować klienta gRPC ani nic wiedzieć o gRPC.

Poprzednią Greeter usługę można wywołać przy użyciu interfejsów API języka JavaScript przeglądarki:

var name = nameInput.value;

fetch('/v1/greeter/' + name)
  .then((response) => response.json())
  .then((result) => {
    console.log(result.message);
    // Hello world
  });

grpc-gateway

grpc-gateway to inna technologia tworzenia interfejsów API RESTful JSON z usług gRPC. Używa tych samych .proto adnotacji do odwzorowywania koncepcji HTTP na usługi gRPC.

grpc-gateway wykorzystuje generowanie kodu do tworzenia serwera reverse proxy. Odwrotny serwer proxy tłumaczy wywołania RESTful na format gRPC+Protobuf, a następnie przesyła je przez protokół HTTP/2 do usługi gRPC. Zaletą tego podejścia jest usługa gRPC nie wie o interfejsach API RESTful JSON. Każdy serwer gRPC może korzystać z grpc-gateway.

Tymczasem transkodowanie gRPC JSON działa wewnątrz aplikacji ASP.NET Core. Deserializuje kod JSON do komunikatów Protobuf, a następnie wywołuje usługę gRPC bezpośrednio. Transkodowanie w programie ASP.NET Core oferuje korzyści deweloperom aplikacji platformy .NET:

• Mniejsza złożoność: Zarówno usługi gRPC, jak i mapowany interfejs API RESTful JSON działają w ramach jednej aplikacji ASP.NET Core.
• Lepsza wydajność: transkodowanie deserializuje dane JSON do komunikatów Protobuf i bezpośrednio wywołuje usługę gRPC. Wykonanie tego w tym samym procesie zapewnia znaczące korzyści wydajnościowe w porównaniu z wykonaniem nowego wywołania gRPC do innego serwera.
• Niższy koszt: mniej serwerów powoduje zmniejszenie miesięcznego rachunku za hosting.

Aby uzyskać informacje na temat instalacji i użycia bramy grpc-gateway, zobacz plik README bramy grpc-gateway.

Treści powiązane

• Konfigurowanie protokołów HTTP i JSON dla transkodowania gRPC JSON w aplikacjach ASP.NET Core
• Korzystanie z usługi gRPC w aplikacjach przeglądarki
• gRPC-Web w aplikacjach gRPC ASP.NET Core