ASP.NET Core'da gRPC JSON kodlaması

Yayınlayan James Newton-King

gRPC , yüksek performanslı bir Uzaktan Yordam Çağrısı (RPC) çerçevesidir. 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 kullanamıyor olmasıdır. Tarayıcılar HTTP/2'yi tam olarak desteklemez ve API'leri ve JSON'ı tarayıcı uygulamalarına veri almak için birincil yol haline getirir.REST gRPC'nin getirdiği avantajlara rağmen, REST API'ler ve JSON modern uygulamalarda önemli bir yere sahiptir. gRPC ve JSON Web API'leri oluşturmak, uygulama geliştirmeye istenmeyen ek yük ekler.

Bu belgede gRPC hizmetlerini kullanarak JSON Web API'lerinin nasıl oluşturulacağı açıklanır.

Genel bakış

gRPC JSON kodlama, gRPC hizmetleri için RESTful JSON API'leri oluşturan ASP.NET Core uzantısıdır. Kod dönüştürme yapılandırıldıktan sonra uygulamaların tanıdık HTTP kavramlarıyla gRPC hizmetlerini çağırmasına olanak tanır:

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

gRPC hizmetleri çağırmak için kullanılabilir.

Not

gRPC JSON kodlaması, alternatif deneysel bir uzantı olan gRPC HTTP API'sini değiştirir.

Kullanım

1. öğesine Microsoft.AspNetCore.Grpc.JsonTranscodingbir paket başvurusu ekleyin.

2. öğesini ekleyerek AddJsonTranscodingsunucu başlangıç koduna kod dönüştürmeyi Program.cs kaydedin: dosyasında olarak değiştirin builder.Services.AddGrpc(); builder.Services.AddGrpc().AddJsonTranscoding();.

3. Proje dosyasında özellik grubuna ekleyin <IncludeHttpRuleProtos>true</IncludeHttpRuleProtos> (.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. HTTP bağlamaları ve yolları ile dosyalarınızdaki .proto gRPC yöntemlerine açıklama ekleyin:

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

SayHello gRPC yöntemi artık gRPC ve JSON Web API'si olarak çağrılabilir:

• İstek: GET /v1/greeter/world
• Yanıt: { "message": "Hello world" }

Sunucu her istek için günlük yazacak şekilde yapılandırılmışsa, sunucu günlükleri bir gRPC hizmetinin HTTP çağrısını yürüttüğüni gösterir. Kod dönüştürme, gelen HTTP isteğini gRPC iletisiyle eşler ve yanıt iletisini 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

gRPC yöntemlerine açıklama ekleme

gRPC yöntemleri, kodlamayı dönüştürmeyi desteklemeden önce bir HTTP kuralıyla açıklama eklenmelidir. HTTP kuralı, HTTP yöntemi ve yolu gibi gRPC yöntemini çağırma hakkında bilgi içerir.

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

Devam eden örnek:

• Yöntemi olan bir Greeter SayHello hizmeti tanımlar. yöntemi, adı google.api.httpkullanılarak belirtilen bir HTTP kuralına sahiptir.
• yöntemine istekler ve /v1/greeter/{name} yol ile GET erişilebilir.
• name İstek iletisindeki alan bir yol parametresine bağlıdır.

Bir gRPC yönteminin RESTful API'sine nasıl bağlanacağını özelleştirmek için birçok seçenek mevcuttur. gRPC yöntemlerine açıklama ekleme ve JSON'ı özelleştirme hakkında daha fazla bilgi için bkz . gRPC JSON kodlaması için HTTP ve JSON yapılandırma.

Akış yöntemleri

HTTP/2 üzerinden geleneksel gRPC, akışı her yönde destekler. Kod dönüştürme yalnızca sunucu akışıyla sınırlıdır. İstemci akışı ve çift yönlü akış yöntemleri desteklenmez.

Sunucu akış yöntemleri satırla ayrılmış JSON kullanır. kullanılarak WriteAsync yazılan her ileti JSON'a seri hale getirilir ve ardından yeni bir satır eklenir.

Aşağıdaki sunucu akış yöntemi üç ileti yazar:

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

İstemci, satırla ayrılmış üç JSON nesnesi alır:

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

JSON ayarının WriteIndented sunucu akış yöntemleri için geçerli olmadığını unutmayın. Güzel yazdırma, JSON'a yeni satırlar ve boşluk ekler ve bu satırla sınırlandırılmış JSON ile kullanılamaz.

ASP.NET Core gPRC kodlama ve akış uygulaması örneğini görüntüleyin veya indirin.

HTTP protokolü

.NET SDK'sında bulunan ASP.NET Core gRPC hizmet şablonu, yalnızca HTTP/2 için yapılandırılmış bir uygulama oluşturur. Bir uygulama yalnızca HTTP/2 üzerinden geleneksel gRPC'yi desteklediğinde HTTP/2 iyi bir varsayılan değerdir. Öte yandan kod dönüştürme, hem HTTP/1.1 hem de HTTP/2 ile çalışır. UWP veya Unity gibi bazı platformlar HTTP/2 kullanamaz. Tüm istemci uygulamalarını desteklemek için sunucuyu HTTP/1.1 ve HTTP/2'yi etkinleştirecek şekilde yapılandırın.

içindeki varsayılan protokolü güncelleştirin appsettings.json:

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

Alternatif olarak başlangıç kodunda uç noktaları yapılandırınKestrel.

Aynı bağlantı noktasında HTTP/1.1 ve HTTP/2'nin etkinleştirilmesi, protokol anlaşması için TLS gerektirir. gRPC uygulamasında HTTP protokollerini yapılandırma hakkında daha fazla bilgi için bkz . ASP.NET Core gRPC protokolü anlaşması.

gRPC JSON kodlama ve gRPC-Web karşılaştırması

Hem kod dönüştürme hem de gRPC-Web, gRPC hizmetlerinin bir tarayıcıdan çağrılmasına izin verir. Ancak, her birinin bunu nasıl yaptığı farklıdır:

• 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 sahiptir.
• Kod dönüştürme, tarayıcı uygulamalarının gRPC hizmetlerini JSON ile RESTful API'leriymiş gibi çağırmasına olanak tanır. Tarayıcı uygulamasının gRPC istemcisi oluşturması veya gRPC hakkında bir şey bilmesi gerekmez.

Önceki Greeter hizmet, tarayıcı JavaScript API'leri kullanılarak çağrılabilir:

var name = nameInput.value;

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

grpc-gateway

grpc-gateway , gRPC hizmetlerinden RESTful JSON API'leri oluşturmaya yönelik başka bir teknolojidir. HTTP kavramlarını gRPC hizmetlerine eşlemek için aynı .proto ek açıklamaları kullanır.

grpc-gateway, ters ara sunucu oluşturmak için kod oluşturmayı kullanır. Ters proxy, RESTful çağrılarını gRPC+Protobuf'a çevirir ve çağrıları HTTP/2 üzerinden gRPC hizmetine gönderir. Bu yaklaşımın avantajı, gRPC hizmetinin RESTful JSON API'lerini bilmemesidir. Herhangi bir gRPC sunucusu grpc-gateway kullanabilir.

Bu arada gRPC JSON kodlaması bir ASP.NET Core uygulamasında çalışır. JSON'ı Protobuf iletilerine seri durumdan çıkartır, ardından gRPC hizmetini doğrudan çağırır. ASP.NET Core'da kod dönüştürme, .NET uygulama geliştiricilerine avantajlar sunar:

• Daha az karmaşık: Hem gRPC hizmetleri hem de eşlenmiş RESTful JSON API'sinin tek bir ASP.NET Core uygulaması tükenir.
• Daha iyi performans: Seri durumdan çıkarma JSON'ı Protobuf iletilerine çevirir ve gRPC hizmetini doğrudan çağırır. Bu işlemi yaparken farklı bir sunucuya yeni bir gRPC çağrısı yapmak yerine önemli performans avantajları vardır.
• Daha düşük maliyet: Daha az sunucu, daha küçük bir aylık barındırma faturasına neden olur.

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

Ek kaynaklar

• gRPC JSON kod dönüştürme ASP.NET Core uygulamaları için HTTP ve JSON yapılandırma
• gRPC JSON transcoding ASP.NET Core uygulamalarıyla OpenAPI kullanma
• Tarayıcı uygulamalarında gRPC kullanma
• ASP.NET Core gRPC uygulamalarında gRPC-Web