Mengonfigurasi HTTP dan JSON untuk transcoding JSON gRPC

Artikel
11/06/2024

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Oleh James Newton-King

Transcoding JSON gRPC membuat API web RESTful JSON dari metode gRPC. Ini menggunakan anotasi dan opsi untuk menyesuaikan cara API RESTful memetakan ke metode gRPC.

Aturan HTTP

Metode gRPC harus diannotasi dengan aturan HTTP sebelum mendukung transcoding. Aturan HTTP mencakup informasi tentang memanggil metode gRPC sebagai API RESTful, seperti metode dan rute HTTP.

import "google/api/annotations.proto";

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

Aturan HTTP adalah:

Anotasi pada metode gRPC.
Diidentifikasi dengan nama google.api.http.
Diimpor dari google/api/annotations.proto file. File google/api/http.proto dan google/api/annotations.proto harus berada dalam proyek.

Catatan

Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis .NET berikutnya. Untuk memilih tag rilis tertentu, gunakan daftar dropdown Beralih cabang atau tag. Untuk informasi lebih lanjut, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Metode HTTP

Metode HTTP ditentukan dengan mengatur rute ke nama bidang metode HTTP yang cocok:

get
put
post
delete
patch

Bidang ini custom memungkinkan metode HTTP lainnya.

Dalam contoh berikut, metode dipetakan CreateAddress ke POST dengan rute yang ditentukan:

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

Rute

Rute transcoding JSON gRPC mendukung parameter rute. Misalnya, {name} dalam rute mengikat ke name bidang pada pesan permintaan.

Untuk mengikat bidang pada pesan berlapis, tentukan jalur ke bidang . Dalam contoh berikut, {params.org} mengikat ke org bidang pada IssueParams pesan:

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

Rute transcoding dan rute ASP.NET Core memiliki sintaksis dan set fitur yang sama. Namun, beberapa fitur perutean ASP.NET Core tidak didukung oleh transcoding. Ini termasuk:

Isi permintaan

Transcoding mendeserialisasi isi permintaan JSON ke pesan permintaan. Bidang body menentukan bagaimana isi permintaan HTTP memetakan ke pesan permintaan. Nilainya adalah nama bidang permintaan yang nilainya dipetakan ke isi permintaan HTTP atau * untuk memetakan semua bidang permintaan.

Dalam contoh berikut, isi permintaan HTTP dideserialisasi ke address bidang :

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

Parameter kueri

Bidang apa pun dalam pesan permintaan yang tidak terikat oleh parameter rute atau isi permintaan dapat diatur menggunakan parameter kueri HTTP.

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

Dalam contoh sebelumnya:

org bidang dan repo terikat dari parameter rute.
Bidang lain, seperti text dan bidang berlapis dari page, dapat terikat dari string kueri: ?text=value&page.index=0&page.size=10

Isi respons

Secara default, transcoding menserialisasikan seluruh pesan respons sebagai JSON. Bidang ini response_body memungkinkan serialisasi subset pesan respons.

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

Dalam contoh sebelumnya, bidang diserialisasikan address ke isi respons sebagai JSON.

Spesifikasi

Untuk informasi selengkapnya tentang menyesuaikan transcoding gRPC, lihat spesifikasi HttpRule.

Menyesuaikan JSON

Pesan dikonversi ke dan dari JSON menggunakan pemetaan JSON dalam spesifikasi Protobuf. Pemetaan JSON Protobuf adalah cara standar untuk mengonversi antara JSON dan Protobuf, dan semua serialisasi mengikuti aturan ini.

Namun, transcoding JSON gRPC menawarkan beberapa opsi terbatas untuk menyesuaikan JSON dengan GrpcJsonSettings, seperti yang ditunjukkan dalam tabel berikut.

Opsi	Nilai Default	Deskripsi
IgnoreDefaultValues	`false`	Jika diatur ke `true`, bidang dengan nilai default diabaikan selama serialisasi.
WriteEnumsAsIntegers	`false`	Jika diatur ke `true`, nilai enum ditulis sebagai bilangan bulat alih-alih string.
WriteInt64sAsStrings	`false`	Jika diatur ke `true`, `Int64` dan `UInt64` nilai ditulis sebagai string, bukan angka.
WriteIndented	`false`	Jika diatur ke `true`, JSON ditulis menggunakan pencetakan cantik. Opsi ini tidak memengaruhi metode streaming, yang menulis pesan JSON yang dibatasi baris dan tidak dapat menggunakan pencetakan yang cantik.

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

.proto Dalam file, json_name opsi bidang mengkustomisasi nama bidang saat diserialisasikan sebagai JSON, seperti dalam contoh berikut:

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

Transcoding tidak mendukung kustomisasi JSON tingkat lanjut. Aplikasi yang memerlukan kontrol struktur JSON yang tepat harus mempertimbangkan untuk menggunakan ASP.NET Core Web API.

Bagikan melalui