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 JSWŁ. są podstawowym sposobem pobierania danych do aplikacji przeglądarki. Pomimo korzyści, jakie zapewnia gRPC, REST interfejsy API i JSusługa ON mają ważne miejsce w nowoczesnych aplikacjach. Kompilowanie interfejsów gRPC iJSON Web API zwiększa niepożądane obciążenie podczas tworzenia aplikacji.

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

Omówienie

Transkodowanie gRPC JSON to rozszerzenie dla ASP.NET Core, które tworzy RESTful JSON API 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
• JSW PRZYPADKU żądań/odpowiedzi

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

Uwaga

Transkodowanie gRPC ON zastępuje interfejs API HTTP gRPCJS, 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 JSinterfejs API ON:

• Żądanie: GET /v1/greeter/world
• Odpowiedzi: { "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 JSWŁ.

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 sposobu powiązania metody gRPC z interfejsem RESTAPI ful. Aby uzyskać więcej informacji na temat dodawania adnotacji do metod gRPC i dostosowywania JSwł., zobacz Konfigurowanie protokołu HTTP i JSWŁ. dla transkodowania gRPC 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 JSwierszem WŁ. Każda wiadomość napisana przy użyciu WriteAsync jest serializowana na wartość 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 rozdzielane JSwierszami obiekty ON:

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

Należy pamiętać, że WriteIndentedJSustawienie WŁĄCZONE nie ma zastosowania do metod przesyłania strumieniowego serwera. Drukowanie dość dodaje nowe linie i odstępy do JSWŁĄCZONE, które nie mogą być używane z ogranicznikami JSliniowymi WŁ.

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 RESTto interfejsy API z włączonym interfejsem JSAPI. 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 RESTful JSON API 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 RESTwywołania ful na gRPC+Protobuf i wysyła wywołania za pośrednictwem protokołu HTTP/2 do usługi gRPC. Zaletą tego podejścia jest to, że usługa gRPC nie wie o RESTful JSON API. Dowolny serwer gRPC może używać bramy grpc-gateway.

Tymczasem transkodowanie gRPC JSON działa wewnątrz aplikacji ASP.NET Core. Deserializuje JSon w komunikatach 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 zamapowane RESTinterfejs JSAPI ON kończy się jedną aplikacją ASP.NET Core.
• Lepsza wydajność: deserializowanie transkodowania JSna komunikaty Protobuf i bezpośrednio wywołuje 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łu HTTP i JSwł. dla transkodowania gRPC JSON ASP.NET Core aplikacji
• Używanie interfejsu OpenAPI z transkodowaniem gRPC JSON ASP.NET Core
• Korzystanie z usługi gRPC w aplikacjach przeglądarki
• gRPC-Web w aplikacjach gRPC ASP.NET Core