gRPC JSON kodlaması için HTTP ve JSON yapılandırma

Makale
11/30/2023

gRPC JSON transcoding, gRPC yöntemlerinden ful JSON web API'leri oluştururREST. Bir dolu API'nin gRPC yöntemleriyle nasıl RESTeşleştirilmesini özelleştirmek için ek açıklamaları ve seçenekleri kullanır.

HTTP kuralları

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

import "google/api/annotations.proto";

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

HTTP kuralı:

gRPC yöntemleriyle ilgili bir ek açıklama.
adıyla google.api.httptanımlanır.
Dosyadan google/api/annotations.proto içeri aktarıldı. ve google/api/annotations.proto dosyalarının google/api/http.proto projede olması gerekir.

Dekont

.NET başvuru kaynağına yönelik belge bağlantıları genellikle deponun varsayılan dalını yükler ve bu dal .NET'in sonraki sürümü için geçerli geliştirmeyi temsil eder. Belirli bir sürümün etiketini seçmek için Dalları veya etiketleri değiştir açılan listesini kullanın. Daha fazla bilgi için bkz. ASP.NET Core kaynak kodunun sürüm etiketini seçme (dotnet/AspNetCore.Docs #26205).

HTTP yöntemi

HTTP yöntemi, yolu eşleşen HTTP yöntemi alan adına ayarlanarak belirtilir:

get
put
post
delete
patch

alanı custom diğer HTTP yöntemlerine izin verir.

Aşağıdaki örnekte, CreateAddress yöntemi belirtilen yol ile eşlenir POST :

service Address {
  rpc CreateAddress (CreateAddressRequest) returns (CreateAddressReply) {
    option (google.api.http) = {
      post: "/v1/address",
      body: "*"
    };
  }
}

Rota

gRPC JSON transcoding routes, yol parametrelerini destekler. Örneğin, {name} bir yol içinde istek iletisindeki name alana bağlanır.

İç içe iletideki bir alanı bağlamak için alanın yolunu belirtin. Aşağıdaki örnekte, {params.org} iletideki org alana IssueParams bağlanır:

service Repository {
  rpc GetIssue (GetIssueRequest) returns (GetIssueReply) {
    option (google.api.http) = {
      get: "/{apiVersion}/{params.org}/{params.repo}/issue/{params.issueId}"
    };
  }
}

message GetIssueRequest {
  int32 api_version = 1;
  IssueParams params = 2;
}
message IssueParams {
  string org = 1;
  string repo = 2;
  int32 issueId = 3;
}

Yolların ve ASP.NET Temel yolların kodlaması benzer bir söz dizimi ve özellik kümesine sahiptir. Ancak, bazı ASP.NET Temel yönlendirme özellikleri kod dönüştürme tarafından desteklenmez. Bu modüller şunlardır:

Request body

Kod dönüştürme, istek gövdesini JSON olarak istek iletisine seri durumdan çıkartır. alanı, body HTTP isteği gövdesinin istek iletisiyle nasıl eşleşeceklerini belirtir. Değer, değeri HTTP isteği gövdesine eşlenen istek alanının adı veya * tüm istek alanlarını eşlemek için olur.

Aşağıdaki örnekte, HTTP isteği gövdesi alana seri durumdan address çıkarılır:

service Address {
  rpc AddAddress (AddAddressRequest) returns (AddAddressReply) {
    option (google.api.http) = {
      post: "/{apiVersion}/address",
      body: "address"
    };
  }
}

message AddAddressRequest {
  int32 api_version = 1;
  Address address = 2;
}
message Address {
  string street = 1;
  string city = 2;
  string country = 3;
}

Sorgu parametreleri

İstek iletisinde yol parametrelerine veya istek gövdesine bağlı olmayan tüm alanlar HTTP sorgu parametreleri kullanılarak ayarlanabilir.

service Repository {
  rpc GetIssues (GetIssuesRequest) returns (GetIssuesReply) {
    option (google.api.http) = {
      get: "/v1/{org}/{repo}/issue"
    };
  }
}

message GetIssuesRequest {
  string org = 1;
  string repo = 2;
  string text = 3;
  PageParams page = 4;
}
message PageParams {
  int32 index = 1;
  int32 size = 2;
}

Yukarıdaki örnekte:

org ve repo alanları yol parametrelerinden bağlanır.
ve gibi text diğer alanlar pagesorgu dizesinden bağlanabilir: ?text=value&page.index=0&page.size=10

Yanıt gövdesi

Varsayılan olarak, kod dönüştürme, yanıt iletisinin tamamını ON olarak JSserileştirir. alanı, response_body yanıt iletisinin bir alt kümesinin seri hale getirilmesine izin verir.

service Address {
  rpc GetAddress (GetAddressRequest) returns (GetAddressReply) {
    option (google.api.http) = {
      get: "/v1/address/{id}",
      response_body: "address"
    };
  }
}

message GetAddressReply {
  int32 version = 1;
  Address address = 2;
}
message Address {
  string street = 1;
  string city = 2;
  string country = 3;
}

Yukarıdaki örnekte, address alan yanıt gövdesine ON olarak JSserileştirilir.

Belirtim

gRPC kodlamasını özelleştirme hakkında daha fazla bilgi için bkz . HttpRule belirtimi.

ON'i özelleştirme JS

İletiler, Protobuf belirtimindeki JSON eşlemesi kullanılarak ON'a ve on'dan JSdönüştürülür. Protobuf'un JSON eşlemesi, ON ve Protobuf arasında JSdönüştürmenin standartlaştırılmış bir yoludur ve tüm serileştirmeler bu kurallara uyar.

Ancak gRPC JSON kod dönüştürme, aşağıdaki tabloda gösterildiği gibi ile GrpcJsonSettingsON'yi özelleştirmek JSiçin bazı sınırlı seçenekler sunar.

Seçenek	Varsayılan Değer	Tanım
IgnoreDefaultValues	`false`	olarak ayarlanırsa `true`, serileştirme sırasında varsayılan değerlere sahip alanlar yoksayılır.
WriteEnumsAsIntegers	`false`	olarak ayarlanırsa `true`, sabit listesi değerleri dizeler yerine tamsayı olarak yazılır.
WriteInt64sAsStrings	`false`	olarak ayarlanırsa `trueInt64` ve `UInt64` değerler sayı yerine dize olarak yazılır.
WriteIndented	`false`	olarak ayarlanırsa `true`, JSON güzel yazdırma kullanılarak yazılır. Bu seçenek, satırla ayrılmış JSON iletileri yazan ve güzel yazdırmayı kullanabilen akış yöntemlerini etkilemez.

builder.Services.AddGrpc().AddJsonTranscoding(o =>
{
    o.JsonSettings.WriteIndented = true;
});

Dosyada .proto , json_name alan seçeneği aşağıdaki örnekte olduğu gibi alanın adını ON olarak JSseri hale getirildiğinde özelleştirir:

message TestMessage {
  string my_field = 1 [json_name="customFieldName"];
}

Kod dönüştürme gelişmiş JSON özelleştirmesini desteklemez. Kesin JSON yapısı denetimi gerektiren uygulamalar ASP.NET Core Web API'lerini kullanmayı göz önünde bulundurmalıdır.

Aracılığıyla paylaş