gRPC'den JSON Web API'leri oluşturma

James Newton-King

gRPC, uygulamalar arasında iletişim kurmak için modern bir yol sağlar. gRPC, yüksek performanslı, gerçek zamanlı hizmetler oluşturmak için HTTP/2, akış, Protobuf ve ileti sözleşmelerini kullanır.

gRPC ile ilgili bir sınırlama, her platformun bunu kullanamamasıdır. Tarayıcılar HTTP/2'yi tam olarak desteklemez ve bu nedenle REST ve JSON, tarayıcı uygulamalarına veri almak için birincil yol olur. gRPC'nin getirdiği avantajlarla bile REST ve JSON, modern uygulamalarda önemli bir yere sahip olur. gRPC ve JSON Web API'leri geliştirme, uygulama geliştirme için istenmeyen ek yük getirir.

Bu belgede, gRPC hizmetlerini kullanarak JSON Web API'leri oluşturma hakkında bilgi vemektedir.

gRPC HTTP API'si

gRPC HTTP API, gRPC hizmetleri ASP.NET Core RESTful JSON API'leri oluşturan deneysel bir uzantıdır. Yapılandırılan gRPC HTTP API'si, uygulamaların tanıdık HTTP kavramlarıyla gRPC hizmetlerini çağırmalarını sağlar:

• HTTP fiilleri
• URL parametresi bağlama
• JSON istekleri/yanıtları

gRPC, hizmetleri çağırmaya devam etmek için kullanılabilir.

Kullanım

1. Microsoft.AspNetCore.Grpc.HttpApi'ye paket başvurusu ekleyin.
2. Startup.cs'de hizmetleri ile AddGrpcHttpApi kaydetme.
3. Projenize google/api/http.proto ve google/api/annotations.proto dosyaları ekleyin.
4. .proto dosyalarınıza HTTP bağlamaları ve yolları ile gRPC yöntemlerine açıklama ek açıklama:

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

SayHellogRPC yöntemi artık gRPC+Protobuf ve bir HTTP API'si olarak çağrılabilir:

• Istek: HTTP/1.1 GET /v1/greeter/world
• Yanıt: { "message": "Hello world" }

Sunucu günlükleri, HTTP çağrısının bir gRPC hizmeti tarafından yürütülmektedir. gRPC HTTP API'si, gelen HTTP isteğini bir gRPC iletisiyle eşler ve ardından yanıt iletiyi JSON'a dönüştürür.

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

Bu temel bir örnektir. Daha fazla özelleştirme seçeneği için bkz. HttpRule.

Swagger/OpenAPI desteğini etkinleştirme

Swagger (OpenAPI), REST API'lerini açıklamaya uygun dilden bağımsız bir belirtimdir. gRPC HTTP API'si, RESTful gRPC hizmetleri için swagger uç noktası oluşturmak için Swashbuckle ile tümleşebilirsiniz. Swagger uç noktası daha sonra Swagger UI ve diğer araçlarla kullanılabilir.

gRPC HTTP API'si ile Swagger'ı etkinleştirmek için:

1. Microsoft.AspNetCore.Grpc.Swagger'apaket başvurusu ekleyin.
2. Startup.cs'de Swashbuckle'ı yapılandırma. yöntemi AddGrpcSwagger Swashbuckle'ı gRPC HTTP API uç noktalarını içerecek şekilde yapılandırıyor.

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

Swashbuckle'ın RESTful gRPC hizmetleri için Swagger'ı oluşturmuş olduğunu onaylamak için uygulamayı başlatarak Swagger UI sayfasına gidin:

gRPC HTTP API ile gRPC-Web karşılaştırması

Hem gRPC HTTP API'si hem de gRPC-Web, gRPC hizmetlerinin bir tarayıcıdan çağrıl olmasına olanak sağlar. Ancak, her biri bunu farklı yapar:

• gRPC-Web, tarayıcı uygulamalarının gRPC-Web istemcisi ve Protobuf ile tarayıcıdan gRPC hizmetlerini çağırmasını sağlar. gRPC-Web, tarayıcı uygulamasının bir gRPC istemcisi oluşturmasını gerektirir ve küçük, hızlı Protobuf iletileri gönderme avantajına sahip olur.
• gRPC HTTP API'si, tarayıcı uygulamalarının JSON ile RESTful API'ler gibi gRPC hizmetlerini çağırmalarını sağlar. Tarayıcı uygulamasının bir gRPC istemcisi oluşturması veya gRPC hakkında herhangi bir bilgisi olması gerekir.

gRPC HTTP API'si için oluşturulan istemci oluşturulmaz. Önceki hizmet Greeter tarayıcı JavaScript API'leri kullanılarak çağrılabilirsiniz:

var name = nameInput.value;

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

Deneysel durum

gRPC HTTP API bir denemedir. Bu tam değildir ve desteklenmiyor. Bu teknolojiyle ilgileniyoruz ve uygulama geliştiricilerine aynı anda hızla gRPC ve JSON hizmetleri oluşturma olanağı sunuyor. gRPC HTTP API'sini tamamlama taahhüdü yoktur.

gRPC HTTP API'sinde geliştirici ilgisini ölçmek istiyorum. gRPC HTTP API ilginizi çekici görünüyorsa lütfen geri bildirim gönderin.

grpc-gateway

grpc-gateway, gRPC hizmetlerinden RESTful JSON API'leri oluşturmak için bir diğer teknolojidir. HTTP kavramlarını gRPC hizmetleriyle eşlemek için aynı .proto ek açıklamalarını kullanır.

grpc-gateway ile gRPC HTTP API arasındaki en büyük fark, grpc-gateway'in ters ara sunucu oluşturmak için kod oluşturma kullanmasıdır. Ters ara sunucu, RESTful çağrılarını gRPC'ye çevirir ve gRPC hizmetine gönderir.

grpc-gateway yüklemesi ve kullanımı için bkz. grpc-gateway README.

Ek kaynaklar

• google.api.HttpRule belgeleri
• Tarayıcı uygulamalarında gRPC kullanma