gRPC JSON-átkódolás a ASP.NET Core-ban

Írta: James Newton-King

A gRPC egy nagy teljesítményű távoli eljáráshívási (RPC) keretrendszer. A gRPC HTTP/2, streamelés, Protobuf és üzenetszerződések használatával hoz létre nagy teljesítményű, valós idejű szolgáltatásokat.

A gRPC egyik korlátozása, hogy nem minden platform használhatja. A böngészők nem támogatják teljes mértékben a HTTP/2-t, így REST az API-k és a JSON az elsődleges módja az adatok lekérésének a böngészőalkalmazásokba. A gRPC által nyújtott REST előnyök ellenére az API-k és a JSON fontos helyet élveznek a modern alkalmazásokban. A gRPC és A JSON webes API-k létrehozása szükségtelen többletterhelést okoz az alkalmazások fejlesztésében.

Ez a dokumentum bemutatja, hogyan hozhat létre JSON webes API-kat gRPC-szolgáltatások használatával.

Áttekintés

A gRPC JSON-átkódolás a ASP.NET Core bővítménye, amely RESTful JSON API-kat hoz létre a gRPC-szolgáltatásokhoz. A konfigurálás után a transzkódolás lehetővé teszi az alkalmazások számára, hogy ismert HTTP-fogalmakkal hívjanak gRPC-szolgáltatásokat:

• HTTP-műveletek
• URL-paraméter kötése
• JSON-kérelmek/válaszok

A gRPC továbbra is használható a szolgáltatások hívására.

Megjegyzés:

A gRPC JSON-transzkódolás a gRPC HTTP API alternatív kísérleti bővítményét váltja fel.

Usage

1. Adj hozzá egy csomaghivatkozást a Microsoft.AspNetCore.Grpc.JsonTranscoding-hoz.

2. Az átkódolást a kiszolgáló indítási kódjában a következővel regisztrálja: AddJsonTranscoding. A Program.cs fájlban módosítsa a builder.Services.AddGrpc();-t a következőre: builder.Services.AddGrpc().AddJsonTranscoding();.

3. Hozzáadás <IncludeHttpRuleProtos>true</IncludeHttpRuleProtos> a projektfájl tulajdonságcsoportjába (.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. A gRPC-metódusok annotálása a .proto fájlokban HTTP-kötésekkel és útvonalbeállításokkal:

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

A SayHello gRPC metódus mostantól gRPC-ként és JSON Webes API-ként hívható meg:

• Kérés: GET /v1/greeter/world
• Válasz: { "message": "Hello world" }

Ha a kiszolgáló úgy van konfigurálva, hogy minden kéréshez naplókat írjon, a kiszolgálónaplók azt mutatják, hogy egy gRPC-szolgáltatás végrehajtja a HTTP-hívást. A transzkódolás egy gRPC-üzenetre képezi le a bejövő HTTP-kérést, és JSON-ra konvertálja a válaszüzenetet.

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

gRPC-metódusok annotálása

A gRPC-metódusokat HTTP-szabállyal kell megjegyzésekként ellátni, mielőtt támogatnák a transzkódolást. A HTTP-szabály információkat tartalmaz a gRPC metódus meghívásáról, például a HTTP-metódusról és az útvonalról.

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

Az eljárás példája:

• Egy Greeter szolgáltatást definiál egy SayHello módszerrel. A metódushoz egy HTTP-szabály van megadva a név google.api.httpalapján.
• A metódus GET kérésekkel és /v1/greeter/{name} útvonallal érhető el.
• A name kérelemüzenet mezője egy útvonalparaméterhez van kötve.

Számos lehetőség áll rendelkezésre a gRPC-metódusOK RESTful API-hoz való kötésének testreszabására. A gRPC-metódusok megjegyzésével és a JSON testreszabásával kapcsolatos további információkért lásd: HTTP és JSON konfigurálása gRPC JSON-transzkódoláshoz.

Streamelési módszerek

A hagyományos gRPC HTTP/2-n keresztül minden irányban támogatja a streamelést. Az átkódolás csak a kiszolgáló streamelésére korlátozódik. Az ügyfélstreamelés és a kétirányú streamelési módszerek nem támogatottak.

A kiszolgálóstreamelési módszerek sorhatárolt JSON-t használnak. Minden üzenet, amelyet a WriteAsync használatával írtak, JSON formátumra van szerializálva, majd egy új sor következik.

A következő kiszolgálóstreamelési módszer három üzenetet ír:

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

Az ügyfél három sorra tagolt JSON-objektumot kap:

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

Vegye figyelembe, hogy a WriteIndented JSON-beállítás nem vonatkozik a kiszolgáló streamelési módszereire. A szép nyomtatás új vonalakat és térközöket ad hozzá a JSON-hoz, amely nem használható vonalhatárolt JSON-kkal.

ASP.NET Core gPRC-átkódolási és streamelési alkalmazásmintát tekinthet meg vagy tölthet le.

HTTP-protokoll

A .NET SDK-ban található ASP.NET Core gRPC szolgáltatássablon olyan alkalmazást hoz létre, amely csak HTTP/2-hez van konfigurálva. A HTTP/2 jó alapértelmezett, ha egy alkalmazás csak a hagyományos gRPC-t támogatja HTTP/2-n keresztül. A transzkódolás azonban a HTTP/1.1 és a HTTP/2 használatával is működik. Egyes platformok, például az UWP vagy a Unity nem tudják használni a HTTP/2-t. Az összes ügyfélalkalmazás támogatásához konfigurálja a kiszolgálót a HTTP/1.1 és a HTTP/2 engedélyezésére.

Frissítse az alapértelmezett protokollt a következő helyen appsettings.json:

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

Másik lehetőségként konfigurálja Kestrel a végpontokat az indítási kódban.

A HTTP/1.1 és a HTTP/2 ugyanazon a porton való engedélyezéséhez TLS szükséges a protokoll-egyeztetéshez. További információ a HTTP-protokollok gRPC-alkalmazásokban való konfigurálásáról: ASP.NET Core gRPC protokoll egyeztetése.

gRPC JSON-átkódolás és gRPC-Web

A transzkódolás és a gRPC-Web lehetővé teszi a gRPC-szolgáltatások böngészőből való meghívását. Az egyes lépések azonban eltérőek:

• A gRPC-Web lehetővé teszi, hogy a böngészőalkalmazások gRPC-szolgáltatásokat hívjanak meg a böngészőből a gRPC-Web ügyféllel és a Protobuftal. A gRPC-Web használatához a böngészőalkalmazásnak létre kell hoznia egy gRPC-ügyfelet, és előnye, hogy kisméretű, gyors Protobuf-üzeneteket küld.
• A transzkódolással a böngészőalkalmazások úgy hívhatják meg a gRPC-szolgáltatásokat, mintha RESTful API-k lennének JSON-nal. A böngészőalkalmazásnak nem kell gRPC-ügyfelet létrehoznia, és semmit sem tudnia a gRPC-ről.

Az előző Greeter szolgáltatás a böngésző JavaScript API-kkal hívható meg:

var name = nameInput.value;

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

grpc-gateway

A grpc-gateway egy másik technológia a RESTful JSON API-k gRPC-szolgáltatásokból való létrehozásához. Ugyanazokat .proto a széljegyzeteket használja a HTTP-fogalmak gRPC-szolgáltatásokhoz való leképezéséhez.

A grpc-gateway kódlétrehozás használatával hoz létre fordított proxykiszolgálót. A fordított proxy lefordítja a RESTful hívásokat a gRPC+Protobuf függvényre, és HTTP/2-n keresztül küldi el a hívásokat a gRPC szolgáltatásnak. Ennek a megközelítésnek az az előnye, hogy a gRPC szolgáltatás nem tud a RESTful JSON API-król. Minden gRPC-kiszolgáló használhatja a grpc-gatewayt.

Eközben a gRPC JSON-átkódolás egy ASP.NET Core-alkalmazásban fut. Deszerializálja a JSON-t Protobuf-üzenetekké, majd közvetlenül meghívja a gRPC szolgáltatást. A ASP.NET Core-ban történő átkódolás a .NET-alkalmazásfejlesztők számára nyújt előnyöket:

• Kevésbé összetett: Mind a gRPC-szolgáltatások, mind a leképezett RESTful JSON API egy ASP.NET Core alkalmazásban fut.
• Jobb teljesítmény: A transzkódolás deszerializálja a JSON-t a Protobuf-üzenetekbe, és közvetlenül meghívja a gRPC szolgáltatást. Ennek a folyamatnak a végrehajtása jelentős teljesítménybeli előnyökkel jár, szemben egy másik kiszolgálóra irányuló új gRPC-hívással.
• Alacsonyabb költség: A kevesebb kiszolgáló alacsonyabb havi üzemeltetési számlát eredményez.

A grpc-gateway telepítéséről és használatáról a grpc-gateway README című témakörben olvashat.

További erőforrások

• HTTP és JSON konfigurálása gRPC JSON-átkódoláshoz ASP.NET Core-alkalmazásokhoz
• Az OpenAPI használata gRPC JSON-átkódolással ASP.NET Core-alkalmazásokhoz
• GRPC használata böngészőalkalmazásokban
• gRPC-Web a ASP.NET Core gRPC-alkalmazásokban