Vytváření webových rozhraní API JSON z gRPC

James Newton-King

gRPC je moderní způsob komunikace mezi aplikacemi. GRPC používá http/2, streamování, protobuf a kontrakty zpráv k vytváření vysoce výkonných služeb v reálném čase.

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

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

gRPC HTTP API

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

• Příkazy HTTP
• Vazba parametru adresy URL
• Požadavky a odpovědi JSON

gRPC se stále může používat k volání služeb.

Využití

1. Přidejte odkaz na balíček do Microsoft.AspNetCore.Grpc.HttpApi.
2. Zaregistrujte služby v souboru Startup.cs pomocí AddGrpcHttpApi .
3. Přidejte do projektu soubory google/api/http.proto a google/api/annotations.proto.
4. Anotace metod gRPC v souborech .proto s vazbami a trasami HTTP:

syntax = "proto3";

import "google/api/annotations.proto";

package greet;

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

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

Metodu SayHello gRPC je teď možné vyvolat jako gRPC+Protobuf a jako rozhraní HTTP API:

• Požadavek: HTTP/1.1 GET /v1/greeter/world
• Reakce: { "message": "Hello world" }

Protokoly serveru ukazují, že volání HTTP provádí služba gRPC. Rozhraní HTTP API gRPC mapuje příchozí požadavek HTTP na zprávu gRPC a pak převádí 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

Toto je základní příklad. Další možnosti přizpůsobení najdete v tématu HttpRule.

Povolení podpory Swaggeru/OpenAPI

Swagger (OpenAPI) je jazyková specifikace pro popisování rozhraní REST API. Rozhraní HTTP API gRPC se může integrovat se Swashbucklem a vygenerovat koncový bod Swagger pro služby RESTful gRPC. Koncový bod Swagger je pak možné použít s uživatelským rozhraním Swagger a dalšími nástroji.

Povolení Swaggeru s gRPC HTTP API:

1. Přidejte odkaz na balíček pro Microsoft.AspNetCore.Grpc.Swagger.
2. Nakonfigurujte Swashbuckle v souboru Startup.cs. Metoda AddGrpcSwagger nakonfiguruje Swashbuckle tak, aby zahrnoval koncové body rozhraní HTTP API gRPC.

public void ConfigureServices(IServiceCollection services)
{
    services.AddGrpc();
    services.AddGrpcHttpApi();
    
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
    services.AddGrpcSwagger();
}

public void Configure(IApplicationBuilder app)
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapGrpcService<GreeterService>();
    });
}

Pokud chcete ověřit, že Swashbuckle generuje Swagger pro služby RESTful gRPC, spusťte aplikaci a přejděte na stránku Swagger UI:

gRPC HTTP API vs. gRPC-Web

Rozhraní gRPC HTTP API i gRPC-Web umožňují volání služeb gRPC z prohlížeče. Každý z nich to ale dělá jinak:

• gRPC-Web umožňuje aplikacím v prohlížeči 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 v odesílání malých rychlých zpráv Protobuf.
• Rozhraní HTTP API gRPC umožňuje aplikacím v prohlížeči volat služby gRPC, jako by to byla rozhraní RESTful API s JSON. Aplikace v prohlížeči nemusí generovat klienta gRPC ani vědět nic o gRPC.

Pro rozhraní HTTP API gRPC se negeneruje žádný vygenerovaný klient. Předchozí službu je možné volat pomocí javascriptových rozhraní Greeter API prohlížeče:

var name = nameInput.value;

fetch("/v1/greeter/" + name).then(function (response) {
  response.json().then(function (data) {
    console.log("Result: " + data.message);
  });
});

Experimentální stav

gRPC HTTP API je experiment. Není dokončený a není podporován. Tato technologie nás zajímá a umožňuje vývojářům aplikací rychle vytvářet služby gRPC a JSON současně. K dokončení rozhraní gRPC HTTP API se žádným závazkem nerušuje.

Chceme posoudit zájem vývojářů o rozhraní gRPC HTTP API. Pokud vás zajímá rozhraní HTTP API gRPC, podejte nám prosím zpětnou vazbu.

grpc-gateway

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

Největší rozdíl mezi grpc-gateway a rozhraním HTTP API gRPC je, že grpc-gateway používá generování kódu k vytvoření reverzního proxy server. Reverzní proxy překládá volání RESTful na gRPC a pak je odesílá do služby gRPC.

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

Další zdroje informací

• Dokumentace ke google.api.HttpRule
• Použití gRPC v prohlížečových aplikacích