Transkodowanie gRPC JSON w ASP.NET Core

Autor: James Newton-King

gRPC to wysokowydajna struktura zdalnego wywołania procedury (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. Kompilowanie interfejsów API sieci Web gRPC i JSON dodaje niepożądane obciążenie do tworzenia aplikacji.

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

Omówienie

Transkodowanie gRPC JSON to rozszerzenie dla ASP.NET Core, które tworzy interfejsy API RESTful 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

Usługa gRPC może być nadal używana do wywoływania usług.

Uwaga

Transkodowanie gRPC JSON zastępuje interfejs API HTTP gRPC, alternatywne rozszerzenie eksperymentalne.

Użycie

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

2. Zarejestruj transkodowanie w kodzie uruchamiania serwera, dodając AddJsonTranscodingpolecenie : W Program.cs pliku zmień wartość 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. Dodawanie adnotacji do metod gRPC w .proto plikach za pomocą powiązań HTTP i tras:

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

SayHello Teraz można wywołać metodę gRPC jako gRPC i jako internetowy interfejs API JSON:

• Prosić: 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ć oznaczone adnotacjami z regułą HTTP, zanim obsługują 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 z żądaniami GET i trasą /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 Configure HTTP and JSON for gRPC JSON transcoding (Konfigurowanie transkodowania JSON i HTTP i JSON).

Metody przesyłania strumieniowego

Tradycyjna gRPC za pośrednictwem protokołu HTTP/2 obsługuje przesyłanie strumieniowe we wszystkich kierunkach. Transkodowanie jest ograniczone tylko do przesyłania strumieniowego serwera. Metody przesyłania strumieniowego klienta i dwukierunkowego przesyłania strumieniowego 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.

Następująca metoda przesyłania strumieniowego 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 uruchamiania.

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 ASP.NET Core gRPC negocjacji protokołu gRPC.

transkodowanie gRPC JSON 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 mapowania pojęć HTTP na usługi gRPC.

Grpc-gateway używa generowania kodu w celu utworzenia serwera zwrotnego serwera proxy. Zwrotny serwer proxy tłumaczy wywołania RESTful na gRPC+Protobuf i wysyła wywołania za pośrednictwem protokołu HTTP/2 do usługi gRPC. Zaletą tego podejścia jest usługa gRPC nie wie o interfejsach API RESTful JSON. Dowolny serwer gRPC może używać bramy 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:

• Mniej złożone: Zarówno usługi gRPC, jak i zamapowany interfejs API JSON RESTful zabraknie jednej aplikacji ASP.NET Core.
• Lepsza wydajność: deserializuje kod JSON do komunikatów Protobuf i wywołuje bezpośrednio usługę gRPC. W tym procesie występują znaczące korzyści z wydajności w porównaniu z tworzeniem nowego wywołania gRPC na innym serwerze.
• 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.

Dodatkowe zasoby

• Konfigurowanie protokołów HTTP i JSON na potrzeby transkodowania w formacie gRPC JSON ASP.NET Core
• Używanie interfejsu OpenAPI z transkodowaniem w formacie gRPC JSON ASP.NET Core
• Korzystanie z usługi gRPC w aplikacjach przeglądarki
• gRPC-Web w aplikacjach gRPC ASP.NET Core