Transcoding JSON gRPC di ASP.NET Core

Oleh James Newton-King

gRPC adalah kerangka kerja Panggilan Prosedur Jarak Jauh (RPC) berkinerja tinggi. gRPC menggunakan kontrak HTTP/2, streaming, Protobuf, dan pesan untuk membuat layanan real-time berkinerja tinggi.

Salah satu batasan dengan gRPC adalah bahwa tidak setiap platform dapat menggunakannya. Browser tidak sepenuhnya mendukung HTTP/2, menjadikan REST API dan JSON sebagai cara utama untuk memasukkan data ke aplikasi browser. Terlepas dari manfaat yang dibawa gRPC, REST API dan JSON memiliki tempat penting di aplikasi modern. Membangun API Web gRPC dan JSON menambahkan overhead yang tidak diinginkan ke pengembangan aplikasi.

Dokumen ini membahas cara membuat API Web JSON menggunakan layanan gRPC.

Gambaran Umum

Transcoding JSON gRPC adalah ekstensi untuk ASP.NET Core yang membuat API JSON RESTful untuk layanan gRPC. Setelah dikonfigurasi, transcoding memungkinkan aplikasi untuk memanggil layanan gRPC dengan konsep HTTP yang sudah dikenal:

• Kata kerja HTTP
• Pengikatan parameter URL
• Permintaan/respons JSON

gRPC masih dapat digunakan untuk memanggil layanan.

Catatan

Transcoding JSON gRPC menggantikan API HTTP gRPC, ekstensi eksperimental alternatif.

Penggunaan

1. Tambahkan referensi paket ke Microsoft.AspNetCore.Grpc.JsonTranscoding.

2. Daftarkan transcoding dalam kode startup server dengan menambahkan AddJsonTranscoding: Dalam Program.cs file, ubah builder.Services.AddGrpc(); ke builder.Services.AddGrpc().AddJsonTranscoding();.

3. Tambahkan <IncludeHttpRuleProtos>true</IncludeHttpRuleProtos> ke grup properti dalam file proyek (.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. Anotasi metode gRPC dalam file Anda .proto dengan pengikatan dan rute HTTP:

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

Metode SayHello gRPC sekarang dapat dipanggil sebagai gRPC dan sebagai JSON Web API:

• Minta: GET /v1/greeter/world
• Jawaban: { "message": "Hello world" }

Jika server dikonfigurasi untuk menulis log untuk setiap permintaan, log server menunjukkan bahwa layanan gRPC menjalankan panggilan HTTP. Transcoding memetakan permintaan HTTP masuk ke pesan gRPC dan mengonversi pesan respons ke JSON.

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

Membuat anotasi metode gRPC

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

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

Contoh lanjutan:

• Greeter Menentukan layanan dengan SayHello metode . Metode ini memiliki aturan HTTP yang ditentukan menggunakan nama google.api.http.
• Metode ini dapat diakses dengan GET permintaan dan /v1/greeter/{name} rute.
• Bidang name pada pesan permintaan terikat ke parameter rute.

Banyak opsi tersedia untuk menyesuaikan bagaimana metode gRPC mengikat KE API RESTful. Untuk informasi selengkapnya tentang menganotasi metode gRPC dan menyesuaikan JSON, lihat Mengonfigurasi HTTP dan JSON untuk transcoding JSON gRPC.

Metode streaming

GRPC tradisional melalui HTTP/2 mendukung streaming di semua arah. Transcoding hanya terbatas pada streaming server. Streaming klien dan metode streaming dua arah tidak didukung.

Metode streaming server menggunakan JSON yang dibatasi baris. Setiap pesan yang ditulis menggunakan WriteAsync diserialisasikan ke JSON dan diikuti oleh baris baru.

Metode streaming server berikut menulis tiga pesan:

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

Klien menerima tiga objek JSON yang dibatasi baris:

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

Perhatikan bahwa WriteIndented pengaturan JSON tidak berlaku untuk metode streaming server. Pencetakan cantik menambahkan baris baru dan spasi kosong ke JSON, yang tidak dapat digunakan dengan JSON yang dibatasi garis.

Lihat atau unduh sampel aplikasi transcoding dan streaming gPRC Core ASP.NET.

Protokol HTTP

Templat layanan ASP.NET Core gRPC, yang disertakan dalam .NET SDK, membuat aplikasi yang hanya dikonfigurasi untuk HTTP/2. HTTP/2 adalah default yang baik ketika aplikasi hanya mendukung gRPC tradisional melalui HTTP/2. Transcoding, bagaimanapun, berfungsi dengan HTTP/1.1 dan HTTP/2. Beberapa platform, seperti UWP atau Unity, tidak dapat menggunakan HTTP/2. Untuk mendukung semua aplikasi klien, konfigurasikan server untuk mengaktifkan HTTP/1.1 dan HTTP/2.

Perbarui protokol default di appsettings.json:

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

Atau, konfigurasikan Kestrel titik akhir dalam kode startup.

Mengaktifkan HTTP/1.1 dan HTTP/2 pada port yang sama memerlukan TLS untuk negosiasi protokol. Untuk informasi selengkapnya tentang mengonfigurasi protokol HTTP di aplikasi gRPC, lihat ASP.NET negosiasi protokol gRPC Core.

transcoding JSON gRPC vs gRPC-Web

Transcoding dan gRPC-Web memungkinkan layanan gRPC dipanggil dari browser. Namun, cara masing-masing melakukan ini berbeda:

• gRPC-Web memungkinkan aplikasi browser memanggil layanan gRPC dari browser dengan klien gRPC-Web dan Protobuf. gRPC-Web mengharuskan aplikasi browser untuk menghasilkan klien gRPC dan memiliki keuntungan mengirim pesan Protobuf yang kecil dan cepat.
• Transcoding memungkinkan aplikasi browser untuk memanggil layanan gRPC seolah-olah mereka ADALAH API RESTful dengan JSON. Aplikasi browser tidak perlu menghasilkan klien gRPC atau tahu apa pun tentang gRPC.

Layanan sebelumnya Greeter dapat dipanggil menggunakan API JavaScript browser:

var name = nameInput.value;

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

grpc-gateway

grpc-gateway adalah teknologi lain untuk membuat API JSON RESTful dari layanan gRPC. Ini menggunakan anotasi yang sama .proto untuk memetakan konsep HTTP ke layanan gRPC.

grpc-gateway menggunakan pembuatan kode untuk membuat server proksi terbalik. Proksi terbalik menerjemahkan panggilan RESTful ke gRPC+Protobuf dan mengirim panggilan melalui HTTP/2 ke layanan gRPC. Manfaat dari pendekatan ini adalah layanan gRPC tidak tahu tentang API RESTful JSON. Server gRPC apa pun dapat menggunakan grpc-gateway.

Sementara itu, transcoding GRPC JSON berjalan di dalam aplikasi ASP.NET Core. Ini mendeserialisasi JSON ke dalam pesan Protobuf, lalu memanggil layanan gRPC secara langsung. Transcoding di ASP.NET Core menawarkan keuntungan bagi pengembang aplikasi .NET:

• Kurang kompleks: Layanan gRPC dan RESTful JSON API yang dipetakan kehabisan satu aplikasi ASP.NET Core.
• Performa yang lebih baik: Transcoding mendeserialisasi JSON ke pesan Protobuf dan memanggil layanan gRPC secara langsung. Ada manfaat performa yang signifikan dalam melakukan proses ini versus melakukan panggilan gRPC baru ke server yang berbeda.
• Biaya yang lebih rendah: Lebih sedikit server menghasilkan tagihan hosting bulanan yang lebih kecil.

Untuk penginstalan dan penggunaan grpc-gateway, lihat grpc-gateway README.

Sumber Daya Tambahan:

• Mengonfigurasi HTTP dan JSON untuk transcoding JSON gRPC ASP.NET aplikasi Core
• Menggunakan OpenAPI dengan transcoding JSON gRPC ASP.NET aplikasi Core
• Menggunakan gRPC di aplikasi browser
• gRPC-Web di aplikasi gRPC ASP.NET Core