Tworzenie internetowych interfejsów API JSON z usługi gRPCCreate JSON Web APIs from gRPC

Przez Kuba Kowalski-królaBy James Newton-King

Ważne

gRPC HTTP API to eksperymentalny projekt, a nie zatwierdzony produkt.gRPC HTTP API is an experimental project, not a committed product. Chcemy:We want to:

  • Przetestuj, że nasze podejście do tworzenia interfejsów API sieci Web JSON dla usług gRPC Services działa.Test that our approach to creating JSON Web APIs for gRPC services works.
  • Uzyskaj opinię na temat tego, czy takie podejście jest przydatne dla deweloperów platformy .NET.Get feedback on if this approach is useful to .NET developers.

Prosimy o opinię , aby upewnić się, że kompilujemy coś, co deweloperzy są podobne i wydajne.Please leave feedback to ensure we build something that developers like and are productive with.

gRPC to nowoczesny sposób komunikacji między aplikacjami.gRPC is a modern way to communicate between apps. gRPC używa protokołu HTTP/2, przesyłania strumieniowego, protobuf i komunikatów z wiadomościami, aby tworzyć wysokiej wydajności usługi w czasie rzeczywistym.gRPC uses HTTP/2, streaming, Protobuf and message contracts to create high-performance, real-time services.

Jedno ograniczenie z gRPC nie dotyczy każdej platformy.One limitation with gRPC is not every platform can use it. Przeglądarki nie obsługują w pełni protokołu HTTP/2, co umożliwia tworzenie i wprowadzanie danych w notacji JSON do aplikacji przeglądarki.Browsers don't fully support HTTP/2, making REST and JSON the primary way to get data into browser apps. Nawet w przypadku korzyści, które gRPC, REST i JSON mają ważne miejsce w nowoczesnych aplikacjach.Even with the benefits that gRPC brings, REST and JSON have an important place in modern apps. Kompilowanie interfejsów API sieci Web gRPC *i _ JSON pozwala uzyskać niepożądane koszty związane z programowaniem aplikacji.Building gRPC *and _ JSON Web APIs adds unwanted overhead to app development.

W tym dokumencie omówiono sposób tworzenia interfejsów API sieci Web JSON przy użyciu usług gRPC Services.This document discusses how to create JSON Web APIs using gRPC services.

Interfejs API HTTP gRPCgRPC HTTP API

gRPC HTTP API to eksperymentalne rozszerzenie dla ASP.NET Core, które tworzy RESTful interfejsu API JSON dla usług gRPC Services.gRPC HTTP API is an experimental extension for ASP.NET Core that creates RESTful JSON APIs for gRPC services. Po skonfigurowaniu interfejs API protokołu HTTP gRPC umożliwia aplikacjom wywoływanie usług gRPC Services przy użyciu znanych pojęć związanych z protokołem HTTP:Once configured, gRPC HTTP API allows apps to call gRPC services with familiar HTTP concepts:

_ Czasowniki HTTP_ HTTP verbs

  • Powiązanie parametru adresu URLURL parameter binding
  • Żądania/odpowiedzi JSONJSON requests/responses

gRPC nadal mogą być używane do wywoływania usług.gRPC can still be used to call services.

UżycieUsage

  1. Dodaj odwołanie do pakietu do Microsoft. AspNetCore. GRPC. pliku Httpapi.Add a package reference to Microsoft.AspNetCore.Grpc.HttpApi.
  2. Zarejestruj usługi w Startup.cs z AddGrpcHttpApi .Register services in Startup.cs with AddGrpcHttpApi.
  3. Dodaj pliki Google/API/http. proto oraz Google/API/Annotations. proto do projektu.Add google/api/http.proto and google/api/annotations.proto files to your project.
  4. Adnotuj metody gRPC w plikach proto z powiązaniami i trasami http:Annotate gRPC methods in your .proto files with HTTP bindings and routes:
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;
}

SayHelloMetodę gRPC można teraz wywołać jako gRPC + protobuf i jako interfejs API protokołu http:The SayHello gRPC method can now be invoked as gRPC+Protobuf and as an HTTP API:

  • Żądając HTTP/1.1 GET /v1/greeter/worldRequest: HTTP/1.1 GET /v1/greeter/world
  • Reakcji { "message": "Hello world" }Response: { "message": "Hello world" }

Dzienniki serwera pokazują, że wywołanie HTTP jest wykonywane przez usługę gRPC.Server logs show that the HTTP call is executed by a gRPC service. Interfejs API protokołu HTTP gRPC mapuje przychodzące żądanie HTTP do komunikatu gRPC, a następnie konwertuje komunikat odpowiedzi na format JSON.gRPC HTTP API maps the incoming HTTP request to a gRPC message, and then converts the response message to 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

Jest to przykład podstawowy.This is a basic example. Zobacz HttpRule , aby uzyskać więcej opcji dostosowywania.See HttpRule for more customization options.

Włącz obsługę struktury Swagger/OpenAPIEnable Swagger/OpenAPI support

Swagger (OpenAPI) to specyfikacja języka niezależny od opisująca opisywanie interfejsów API REST.Swagger (OpenAPI) is a language-agnostic specification for describing REST APIs. Interfejs API protokołu HTTP gRPC można zintegrować z usługą Swashbuckle w celu wygenerowania punktu końcowego struktury Swagger dla usług RESTful gRPC.gRPC HTTP API can integrate with Swashbuckle to generate a Swagger endpoint for RESTful gRPC services. Punktu końcowego struktury Swagger można używać z interfejsem użytkownika programu Swagger i innymi narzędziami.The Swagger endpoint can then be used with Swagger UI and other tooling.

Aby włączyć strukturę Swagger przy użyciu interfejsu API HTTP gRPC:To enable Swagger with gRPC HTTP API:

  1. Dodaj odwołanie do pakietu do Microsoft. AspNetCore. GRPC. Swagger.Add a package reference to Microsoft.AspNetCore.Grpc.Swagger.
  2. Skonfiguruj Swashbuckle w Startup.cs.Configure Swashbuckle in Startup.cs. AddGrpcSwaggerMetoda konfiguruje Swashbuckle w celu uwzględnienia punktów końcowych interfejsu API http gRPC.The AddGrpcSwagger method configures Swashbuckle to include gRPC HTTP API endpoints.
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>();
    });
}

Aby potwierdzić, że usługa Swashbuckle generuje strukturę Swagger dla usług RESTful gRPC, uruchom aplikację i przejdź do strony interfejsu użytkownika struktury Swagger:To confirm that Swashbuckle is generating Swagger for the RESTful gRPC services, start the app and navigate to the Swagger UI page:

Interfejs użytkownika struktury Swagger

gRPC HTTP API vs gRPC-WebgRPC HTTP API vs gRPC-Web

Zarówno gRPC HTTP API, jak i gRPC-Web zezwalają na wywoływanie usług gRPC Services z przeglądarki.Both gRPC HTTP API and gRPC-Web allow gRPC services to be called from a browser. Jednak każdy z nich działa inaczej:However, the way each does this is different:

  • gRPC-Web umożliwia aplikacjom przeglądarki wywoływanie usług gRPC z przeglądarki za pomocą klienta gRPC-Web i protobuf.gRPC-Web lets browser apps call gRPC services from the browser with the gRPC-Web client and Protobuf. gRPC — sieć Web wymaga, aby aplikacja przeglądarki generowała klienta gRPC i korzystała z wysyłania małych i szybkich komunikatów protobuf.gRPC-Web requires the browser app generate a gRPC client, and has the advantage of sending small, fast Protobuf messages.
  • Interfejs API protokołu HTTP gRPC umożliwia aplikacjom przeglądarki wywoływanie usług gRPC, tak jakby były RESTful interfejsy API z notacją JSON.gRPC HTTP API allows browser apps to call gRPC services as if they were RESTful APIs with JSON. Aplikacja przeglądarki nie musi generować klienta gRPC ani wiedzieć o gRPC.The browser app doesn't need to generate a gRPC client or know anything about gRPC.

Nie utworzono żadnego wygenerowanego klienta dla interfejsu API HTTP gRPC.No generated client is created for gRPC HTTP API. Poprzednią Greeter usługę można wywołać przy użyciu interfejsów API JavaScript przeglądarki:The previous Greeter service can be called using browser JavaScript APIs:

var name = nameInput.value;

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

Stan eksperymentalnyExperimental status

Interfejs API HTTP gRPC to eksperyment.gRPC HTTP API is an experiment. Nie jest ona kompletna i nie jest obsługiwana.It is not complete and it is not supported. Jesteśmy zainteresowani tą technologią oraz możliwość zapewniania deweloperom aplikacji szybkiego tworzenia usług gRPC i JSON w tym samym czasie.We're interested in this technology, and the ability it gives app developers to quickly create gRPC and JSON services at the same time. Nie istnieje zobowiązanie do ukończenia interfejsu API protokołu HTTP gRPC.There is no commitment to completing the gRPC HTTP API.

Chcemy mierzyć zainteresowanie deweloperem w interfejsie API HTTP gRPC.We want to gauge developer interest in gRPC HTTP API. Jeśli gRPC interfejs API HTTP jest interesujący, Przekaż opinię.If gRPC HTTP API is interesting to you then please give feedback.

GRPC — Bramagrpc-gateway

GRPC-Gateway jest kolejną technologią do tworzenia interfejsów API JSON RESTful z usług GRPC Services.grpc-gateway is another technology for creating RESTful JSON APIs from gRPC services. Używa tych samych adnotacji . proto , aby mapować koncepcje http do usług gRPC Services.It uses the same .proto annotations to map HTTP concepts to gRPC services.

Największą różnicą między GRPC-Gateway i gRPC interfejsu API protokołu HTTP jest GRPC-Gateway używa generowania kodu w celu utworzenia serwera zwrotnego serwera proxy.The biggest difference between grpc-gateway and gRPC HTTP API is grpc-gateway uses code generation to create a reverse-proxy server. Zwrotny serwer proxy tłumaczy wywołania RESTful na gRPC, a następnie wysyła je do usługi gRPC.The reverse-proxy translates RESTful calls into gRPC and then sends them on to the gRPC service.

Aby zainstalować i użyć usługi GRPC-Gateway, zobacz plik Readme GRPC-Gateway.For installation and usage of grpc-gateway, see the grpc-gateway README.

Dodatkowe zasobyAdditional resources