Transkódování gRPC JSON 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 JSona 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í rozhraní gRPC aJSON Web API zvyšuje nežádoucí režii při vývoji aplikací.

Tento dokument popisuje, jak vytvořit JSrozhraní API on Web pomocí služeb gRPC.

Přehled

gRPC JSON transkódování je rozšíření pro ASP.NET Core, které vytváří 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
• JSON requests/responses

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

Poznámka

Transkódování gRPC ON nahrazuje rozhraní API HTTP gRPCJS, 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 je teď možné vyvolat jako gRPC a jako JSwebové rozhraní API:

• Požadavek: GET /v1/greeter/world
• Reakce: { "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 JSZAPNUTO.

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í toho, jak metoda gRPC sváže RESTful API. Další informace o přidávání poznámek metod gRPC a přizpůsobení JSON naleznete v tématu Konfigurace HTTP a JSON pro transkódování gRPC JSON.

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í ZAPNUTO s JSoddělovači řádků. Každá zpráva napsaná pomocí WriteAsync je serializována na JSON a 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 ON s oddělovači JS:

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

Všimněte si, že WriteIndentedJSnastavení ZAPNUTO se nevztahuje na metody streamování serveru. Při tisku se do JSfunkce ON přidávají nové čáry a prázdné znaky, které nelze použít s oddělovači JSčar ON.

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.

gRPC JSON transkódování 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 RESTo ful 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í 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á RESTful volání 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 RESTful JSON API. Každý server gRPC může používat grpc-gateway.

Mezitím gRPC JSON transkódování běží uvnitř aplikace ASP.NET Core. Deserializuje JSON do protobuf zpráv a pak vyvolá gRPC služba přímo. 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 dorazí služby gRPC i mapované RESTJSv rozhraní 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ší prostředky

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