ASP.NET Core'da gRPC JSON kodlama

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 desteklemediğinden, REST API'ler ve JSON tarayıcı uygulamalarına veri almak için birincil yoldur. gRPC'nin getirdiği avantajlara rağmen, REST API'ler ve JSON modern uygulamalarda önemli bir yere sahiptir. gRPC veJSON Web API'leri oluşturmak, uygulama geliştirmeye istenmeyen ek yük ekler.

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

Genel Bakış

gRPC ON kodlama, gRPC JShizmetleri için ful JSON API'leri oluşturan RESTASP.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.

Dekont

gRPC JSON transcoding, alternatif bir deneysel 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 ON Web API olarak JSçağrılabilir:

• Istek: 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 ON'ya JSdö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 GreeterSayHello 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 bir dolu API'ye nasıl bağlanacağını özelleştirmek için RESTbirçok seçenek mevcuttur. gRPC yöntemlerine açıklama ekleme ve ON'yi özelleştirme JShakkı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 JSayrılmış ON kullanır. kullanılarak WriteAsync yazılan her ileti ON olarak serileştirilir JSve 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 JSayrılmış ON nesnesi alır:

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

ON ayarının WriteIndentedJSsunucu akış yöntemleri için geçerli olmadığını unutmayın. Güzel yazdırma, ON'a JSyeni satırlar ve boşluk ekler; bu, çizgiyle ayrı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 transcoding vs gRPC-Web

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 ON ile JSgerçek API'lermiş RESTgibi ç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 gerçek zamanlı JSON API'leri oluşturmaya RESTyönelik bir diğer 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, ful çağrılarını RESTgRPC+Protobuf'a çevirir ve çağrıları HTTP/2 üzerinden gRPC hizmetine gönderir. Bu yaklaşımın avantajı, gRPC hizmetinin ful JSON API'lerini RESTbilmemesidir. Herhangi bir gRPC sunucusu grpc-gateway kullanabilir.

Bu arada gRPC JSON kodlama işlemi bir ASP.NET Core uygulamasında çalışır. ON'yi Protobuf iletilerine seri durumdan çıkartır JS, 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 hizmetlerinin hem de eşlenen RESTful JSON API'sinin tek bir ASP.NET Core uygulaması tükenir.
• Daha iyi performans: Seri durumdan JSçıkarma, ON'yi 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 transcoding ASP.NET Core uygulamaları için HTTP ve JSON yapılandırma
• gRPC JSON kodlama ASP.NET Core uygulamalarıyla OpenAPI kullanma
• Tarayıcı uygulamalarında gRPC kullanma
• ASP.NET Core gRPC uygulamalarında gRPC-Web