Oleh James Newton-King

gRPC adalah kerangka kerja Remote Procedure Call (RPC) berkinerja tinggi. gRPC menggunakan HTTP/2, streaming, Protobuf, dan kontrak pesan untuk membuat layanan real-time berperforma tinggi.

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

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

Ringkasan

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

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

gRPC masih dapat digunakan untuk memanggil layanan.

Catatan

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

Penggunaan

  1. Tambahkan referensi paket ke Microsoft.AspNetCore.Grpc.JsonTranscoding.
  2. Daftarkan transcoding dalam kode startup server dengan menambahkan AddJsonTranscoding. Sebagai contoh, services.AddGrpc().AddJsonTranscoding().
  3. Menambahkan google/api/http.proto dan google/api/annotations.proto file ke proyek.
  4. Anotasi metode gRPC di . Anda .proto file dengan binding dan rute HTTP:
syntax = "proto3";

import "google/api/annotations.proto";

package greet;

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


message HelloRequest 
  string name = 1;


message HelloReply 
  string message = 1;

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

  • Meminta: HTTP/1.1 GET /v1/greeter/world
  • Tanggapan: "message": "Hello world"

Jika server dikonfigurasi untuk menulis log untuk setiap permintaan, log server menunjukkan bahwa panggilan HTTP dijalankan oleh layanan gRPC. Transcoding memetakan permintaan HTTP yang masuk ke pesan gRPC dan kemudian 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

Ini adalah contoh dasar. Lihat HttpRule untuk opsi penyesuaian lainnya.

Dukungan streaming

gRPC tradisional melalui HTTP/2 mendukung streaming ke segala arah. Transcoding terbatas pada streaming server saja. Streaming klien dan metode streaming dua arah tidak didukung.

Metode streaming server menggunakan JSON yang dibatasi baris. Setiap pesan ditulis menggunakan WriteAsync diserialkan 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 garis:

"Text":"Message 1"
"Text":"Message 2"
"Text":"Message 3"

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

Dukungan OpenAPI eksperimental

Ada eksperimental dukungan untuk menghasilkan OpenAPI dari RESTful API yang ditranskode gRPC. Paket Microsoft.AspNetCore.Grpc.Swagger:

  • Mengintegrasikan transcoding gRPC JSON dengan Swashbuckle.
  • Bersifat eksperimental di .NET 7 untuk memberi kami waktu menjelajahi cara terbaik untuk menyediakan dukungan OpenAPI.

Untuk mengaktifkan OpenAPI dengan transcoding jSON gRPC:

  1. Tambahkan referensi paket ke Microsoft.AspNetCore.Grpc.Swagger. Versi harus 0.3.0-xxx atau lebih tinggi.
  2. Konfigurasikan Swashbuckle saat startup. Itu AddGrpcSwagger metode mengonfigurasi Swashbuckle untuk menyertakan titik akhir gRPC.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddGrpc().AddJsonTranscoding();
builder.Services.AddGrpcSwagger();
builder.Services.AddSwaggerGen(c =>

    c.SwaggerDoc("v1",
        new OpenApiInfo  Title = "gRPC transcoding", Version = "v1" );
);

var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI(c =>

    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
);
app.MapGrpcService<GreeterService>();

app.Run();

Sertakan deskripsi dari .proto komentar

Komentar dari .proto kontrak dapat ditambahkan ke deskripsi OpenAPI yang dihasilkan.

// My amazing greeter service.
service Greeter 
  // Sends a greeting.
  rpc SayHello (HelloRequest) returns (HelloReply) 
    option (google.api.http) = 
      get: "/v1/greeter/name"
    ;
  


message HelloRequest 
  // Name to say hello to.
  string name = 1;


message HelloReply 
  // Hello reply message.
  string message = 1;

Untuk mengaktifkan komentar gRPC OpenAPI:

  1. Aktifkan file dokumentasi XML di proyek server dengan <GenerateDocumentationFile>true</GenerateDocumentationFile>.
  2. Konfigurasikan AddSwaggerGen untuk membaca file XML yang dihasilkan. Lewati jalur file XML ke IncludeXmlComments dan IncludeGrpcXmlComments.
builder.Services.AddSwaggerGen(c =>

    c.SwaggerDoc("v1",
        new OpenApiInfo  Title = "gRPC transcoding", Version = "v1" );

    var filePath = Path.Combine(System.AppContext.BaseDirectory, "Server.xml");
    c.IncludeXmlComments(filePath);
    c.IncludeGrpcXmlComments(filePath, includeControllerXmlComments: true);
);

Untuk mengonfirmasi bahwa Swashbuckle menghasilkan OpenAPI dengan komentar untuk layanan RESTful gRPC, mulai aplikasi dan navigasikan ke halaman Swagger UI:

protokol HTTP

Template layanan ASP.NET Core gRPC, yang disertakan dalam .NET SDK, membuat aplikasi yang hanya dikonfigurasi untuk HTTP/2. Ini adalah default yang bagus ketika aplikasi hanya mendukung gRPC tradisional melalui HTTP/2. Transcoding, bagaimanapun, bekerja dengan baik 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 titik akhir Kestrel 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 Negosiasi protokol gRPC ASP.NET Core.

gRPC JSON transcoding vs gRPC-Web

Baik transcoding maupun 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 memerlukan aplikasi browser untuk menghasilkan klien gRPC, dan memiliki keuntungan mengirim pesan Protobuf yang kecil dan cepat.
  • Transcoding memungkinkan aplikasi browser memanggil layanan gRPC seolah-olah itu adalah RESTful API dengan JSON. Aplikasi browser tidak perlu membuat klien gRPC atau mengetahui apa pun tentang gRPC.

Tidak ada klien yang dibuat untuk transcoding. Sebelumnya Greeter service 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 RESTful JSON API dari layanan gRPC. Ini menggunakan hal yang sama .proto anotasi untuk memetakan konsep HTTP ke layanan gRPC.

grpc-gateway menggunakan pembuatan kode untuk membuat server proxy terbalik. Proxy terbalik menerjemahkan panggilan RESTful menjadi gRPC+Protobuf dan mengirimkan panggilan melalui HTTP/2 ke layanan gRPC. Manfaat dari pendekatan ini adalah layanan gRPC tidak mengetahui tentang RESTful JSON API. Semua server gRPC dapat menggunakan grpc-gateway.

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

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

Untuk instalasi dan penggunaan grpc-gateway, lihat file README grpc-gateway.

Sumber daya tambahan

By AKDSEO