Transkódování JSON gRPC v ASP.NET Core

Autor: James Newton-King

gRPC je vysoce výkonná architektura vzdáleného volání procedur (RPC). GRPC používá k vytváření vysoce výkonných služeb v reálném čase protokol HTTP/2, streamování, Protobuf a kontrakty zpráv.

Jedním omezením gRPC je, že ji nemůže používat každá platforma. Prohlížeče plně nepodporují protokol HTTP/2, takže REST rozhraní API a JSON jsou primárním způsobem, jak získat data do aplikací prohlížeče. Navzdory výhodám, které gRPC přináší, REST mají rozhraní API a JSON důležité místo v moderních aplikacích. Vytváření webových rozhraní API gRPC a JSON zvyšuje nežádoucí režii při vývoji aplikací.

Tento dokument popisuje, jak vytvořit webová rozhraní API JSON pomocí služeb gRPC.

Přehled

gRPC JSON transkódování je rozšíření pro ASP.NET Core, které vytváří rozhraní RESTful JSON API pro služby gRPC. Po nakonfigurování transkódování umožňuje aplikacím volat služby gRPC se známými koncepty HTTP:

• Příkazy HTTP
• Vazba parametrů adresy URL
• Požadavky nebo odpovědi JSON

GRPC je stále možné použít k volání služeb.

Poznámka:

Transkódování json gRPC nahrazuje rozhraní API HTTP gRPC, alternativní experimentální rozšíření.

Využití

1. Přidejte odkaz na balíček .Microsoft.AspNetCore.Grpc.JsonTranscoding

2. Zaregistrujte překódování v spouštěcím kódu serveru přidáním AddJsonTranscoding: V Program.cs souboru změňte builder.Services.AddGrpc(); na builder.Services.AddGrpc().AddJsonTranscoding();.

3. Přidejte <IncludeHttpRuleProtos>true</IncludeHttpRuleProtos> do skupiny vlastností v souboru 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. Anotace metod gRPC v .proto souborech pomocí vazeb HTTP a 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;
   }
   

Metodu SayHello gRPC teď můžete vyvolat jako gRPC a jako webové rozhraní API JSON:

• Prosba: GET /v1/greeter/world
• Odpověď: { "message": "Hello world" }

Pokud je server nakonfigurovaný tak, aby zapisoval protokoly pro každý požadavek, protokoly serveru ukazují, že služba gRPC provádí volání HTTP. Překódování mapuje příchozí požadavek HTTP na zprávu gRPC a převede zprávu odpovědi na 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

Anotace metod gRPC

Metody gRPC musí být před podporou překódování opatřeny poznámkami s pravidlem HTTP. Pravidlo HTTP obsahuje informace o tom, jak volat metodu gRPC, například metodu HTTP a trasu.

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

Příklad pokračování:

• Definuje Greeter službu pomocí SayHello metody. Metoda má zadané pravidlo HTTP pomocí názvu google.api.http.
• Metoda je přístupná s GET požadavky a trasou /v1/greeter/{name} .
• Pole name zprávy požadavku je vázáno na parametr trasy.

K dispozici je mnoho možností pro přizpůsobení způsobu, jakým metoda gRPC sváže rozhraní RESTful API. Další informace o přidávání poznámek metod gRPC a přizpůsobení FORMÁTU JSON najdete v tématu Konfigurace http a JSON pro transkódování json gRPC.

Metody streamování

Tradiční gRPC přes HTTP/2 podporuje streamování ve všech směrech. Kódování je omezené jenom na streamování serveru. Streamování klientů a obousměrné metody streamování se nepodporují.

Metody streamování serveru používají JSON s oddělovači řádků. Každá zpráva napsaná pomocí WriteAsync se serializuje do formátu JSON a za ní následuje nový řádek.

Následující metoda streamování serveru zapisuje tři zprávy:

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 obdrží tři objekty JSON s oddělovači řádků:

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

Všimněte si, že WriteIndented nastavení JSON se nevztahuje na metody streamování serveru. Při tisku se do FORMÁTU JSON přidávají nové řádky a prázdné znaky, které se nedají použít s json s oddělovači řádků.

Zobrazte nebo stáhněte ukázku transkódování a streamovací aplikace ASP.NET Core gPRC.

Protokol HTTP

Šablona služby ASP.NET Core gRPC, která je součástí sady .NET SDK, vytvoří aplikaci, která je nakonfigurovaná jenom pro HTTP/2. Http/2 je dobrým výchozím nastavením, když aplikace podporuje pouze tradiční gRPC přes HTTP/2. Překódování ale funguje s HTTP/1.1 i HTTP/2. Některé platformy, jako je UPW nebo Unity, nemůžou používat PROTOKOL HTTP/2. Pokud chcete podporovat všechny klientské aplikace, nakonfigurujte server tak, aby povolil PROTOKOL HTTP/1.1 a HTTP/2.

Aktualizujte výchozí protokol v appsettings.json:

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

Případně nakonfigurujte Kestrel koncové body ve spouštěcím kódu.

Povolení protokolu HTTP/1.1 a HTTP/2 na stejném portu vyžaduje protokol TLS. Další informace o konfiguraci protokolů HTTP v aplikaci gRPC najdete v tématu ASP.NET Vyjednávání protokolu GRPC core.

Transkódování JSON vs. gRPC-Web

Transkódování i gRPC-Web umožňují volat služby gRPC z prohlížeče. Způsob, jakým se ale každý z nich dělá, je jiný:

• gRPC-Web umožňuje aplikacím prohlížeče volat služby gRPC z prohlížeče pomocí klienta gRPC-Web a Protobuf. GRPC-Web vyžaduje, aby aplikace prohlížeče vygenerovala klienta gRPC a má výhodu odesílání malých, rychlých zpráv Protobuf.
• Překódování umožňuje aplikacím v prohlížeči volat služby gRPC, jako by šlo o rozhraní RESTful API s JSON. Aplikace prohlížeče nemusí generovat klienta gRPC ani nic vědět o gRPC.

Předchozí Greeter službu je možné volat pomocí javascriptových rozhraní API prohlížeče:

var name = nameInput.value;

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

grpc-gateway

grpc-gateway je další technologie pro vytváření rozhraní RESTful JSON API ze služeb gRPC. Používá stejné .proto poznámky k mapování konceptů HTTP na služby gRPC.

grpc-gateway používá generování kódu k vytvoření reverzního proxy serveru. Reverzní proxy překládá volání RESTful do gRPC+Protobuf a odesílá volání přes HTTP/2 do služby gRPC. Výhodou tohoto přístupu je, že služba gRPC neví o rozhraních RESTful JSON API. Každý server gRPC může používat grpc-gateway.

Mezitím se transkódování JSON gRPC spouští v aplikaci ASP.NET Core. Deserializuje JSON do zpráv Protobuf a pak přímo vyvolá službu gRPC. Překódování v ASP.NET Core nabízí vývojářům aplikací .NET výhody:

• Méně složité: Z jedné aplikace ASP.NET Core dojdou služby gRPC i mapované rozhraní RESTful JSON API.
• Lepší výkon: Překódování deserializes JSON do zpráv Protobuf a vyvolá službu gRPC přímo. Při tomto procesu existují významné výhody výkonu a nové volání gRPC na jiný server.
• Nižší náklady: Menší počet serverů vede k menšímu měsíčnímu vyúčtování hostování.

Informace o instalaci a použití brány grpc-gateway najdete v souboru README brány grpc.

Další materiály

• Konfigurace HTTP a JSON pro transkódování gRPC JSON ASP.NET core aplikací
• Použití OpenAPI s transkódováním json gRPC ASP.NET core aplikací
• Použití gRPC v aplikacích prohlížeče
• gRPC-Web v aplikacích ASP.NET Core gRPC