Mengonfigurasi Layanan gRPC

Untuk membuat layanan gRPC—baik Anda menggunakan Gateway API atau tidak—Anda harus menentukan definisi antarmuka dalam satu atau beberapa proto file, yang merupakan file teks dengan ekstensi .proto. Dalam file proto, Anda menentukan tampilan API, termasuk struktur data, metode, parameter metode, dan jenis nilai yang ditampilkan. Kemudian, Anda mengompilasi file proto menggunakan compiler buffer protokol khusus bahasa, protoc. Untuk mengetahui informasi selengkapnya, lihat Apa itu gRPC? dan Konsep gRPC.

Agar layanan gRPC Anda dikelola oleh API Gateway, selain file proto yang dikompilasi, Anda harus menentukan konfigurasi layanan dalam satu atau beberapa file YAML. Konfigurasi layanan adalah spesifikasi yang memungkinkan Anda menentukan perilaku layanan gRPC, termasuk autentikasi, kuota, dan lainnya.

Ringkasan konfigurasi layanan

Di bagian atas file YAML, Anda dapat menentukan informasi dasar tentang layanan, seperti nama dan judulnya. Aspek lain dari layanan ini dikonfigurasi di subbagian file YAML, misalnya:

• API mana yang ditayangkan.
• Cara mengautentikasi pemanggil.
• Cara membatasi atau memberikan akses API dengan kunci API.
• Cara mengakses API menggunakan HTTP REST.

Contoh:

type: google.api.Service
config_version: 3
name: calendar.googleapis.com
title: Google Calendar API
apis:
- name: google.calendar.v3.Calendar
authentication:
  providers:
  - id: google_calendar_auth
    jwks_uri: https://www.googleapis.com/oauth2/v1/certs
    issuer: https://securetoken.google.com
  rules:
  - selector: "*"
    requirements:
      provider_id: google_calendar_auth
backend:
  rules:
    - selector: "*"
      address: grpcs://my-service-98sdf8sd0-uc.a.run.app

Setiap subbagian biasanya sesuai dengan pesan .proto tempat Anda mengonfigurasi berbagai aspek layanan. Contoh:

• authentication: menentukan cara mengautentikasi pemanggil.
• backend: mengontrol perutean backend jarak jauh.
• http: menentukan aturan untuk memetakan metode RPC ke satu atau beberapa metode HTTP REST API.
• usage: memungkinkan Anda mengaktifkan dan menonaktifkan validasi kunci API secara selektif.

Skema resmi untuk konfigurasi layanan ditentukan oleh .proto pesan google.api.Service.

Konfigurasi dasar

Contoh Bookstore, yang digunakan dalam tutorial Memulai API Gateway dan Cloud Run untuk gRPC, mencakup file definisi antarmuka dasar dan file konfigurasi layanan.

Definisi antarmuka Bookstore, bookstore.proto:

syntax = "proto3";

package endpoints.examples.bookstore;

option java_multiple_files = true;
option java_outer_classname = "BookstoreProto";
option java_package = "com.google.endpoints.examples.bookstore";

import "google/protobuf/empty.proto";

service Bookstore {
  rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {}
  rpc CreateShelf(CreateShelfRequest) returns (Shelf) {}
  rpc GetShelf(GetShelfRequest) returns (Shelf) {}
  rpc DeleteShelf(DeleteShelfRequest) returns (google.protobuf.Empty) {}
  rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {}
  rpc CreateBook(CreateBookRequest) returns (Book) {}
  rpc GetBook(GetBookRequest) returns (Book) {}
  rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {}
}

message Shelf {
  int64 id = 1;
  string theme = 2;
}

message Book {
  int64 id = 1;
  string author = 2;
  string title = 3;
}

Konfigurasi layanan Bookstore, api_config.yaml:

type: google.api.Service
config_version: 3

name: *.apigateway.PROJECT_ID.cloud.goog

title: Bookstore gRPC API
apis:
- name: endpoints.examples.bookstore.Bookstore

Contoh kode sebelumnya adalah konfigurasi layanan paling sederhana karena:

• Menentukan layanan bernama *.apigateway.PROJECT_ID.cloud.goog dengan PROJECT_ID adalah nama Google Cloud project ID Anda.
• Menentukan bahwa layanan ini mengekspos API endpoints.examples.bookstore.Bookstore, seperti yang ditentukan dalam file bookstore.proto.

Aturan dan pemilih

Dalam beberapa kasus, Anda mungkin memerlukan kemampuan untuk mengaitkan konfigurasi dengan elemen individual layanan—misalnya, untuk menerapkan autentikasi pada metode tertentu, tetapi tidak pada metode lainnya. Untuk mengonfigurasi hal ini dalam konfigurasi layanan, beberapa bagian konfigurasi layanan, seperti authentication dan http, memungkinkan Anda menentukan aturan dan pemilih. Pemilih mengidentifikasi elemen layanan, seperti nama metode yang diterapkan oleh konfigurasi yang terkait dengan aturan.

Pemilih adalah daftar nama yang memenuhi syarat dan dipisahkan koma yang ditentukan dalam layanan: metode, pesan, kolom, enum, atau nilai enum. Segmen terakhir nama dapat berupa karakter pengganti *, yang cocok dengan akhiran apa pun. Karakter pengganti hanya diizinkan di akhir nama dan hanya untuk seluruh segmen nama. Misalnya: foo.* boleh, tetapi tidak foo.b* atau foo.*.bar. Untuk mengonfigurasi default untuk semua elemen yang berlaku, Anda harus menentukan * dengan sendirinya.

Contoh 1 (memengaruhi seluruh layanan):

usage:
  rules:
  # Allow unregistered calls for all methods.
  - selector: "*"
    allow_unregistered_calls: true

Contoh 2 (memengaruhi satu metode):

usage:
  rules: # IMPORTANT: ONLY LAST MATCHING RULE IS APPLIED
  # Disable API key validation on just the ListShelves method
  # while requiring an API key for the rest of the API.
  - selector: "*"
    allow_unregistered_calls: false
  - selector: "endpoints.examples.bookstore.BookStore.ListShelves"
    allow_unregistered_calls: true

Contoh sebelumnya menunjukkan cara mewajibkan validasi kunci API untuk semua metode kecuali metode ListShelves.

Aturan dievaluasi secara berurutan, dan aturan terakhir yang cocok dalam urutan deklarasi akan diterapkan.

Kuota

Untuk menerapkan kuota ke layanan gRPC, tentukan metrik di bagian tingkat atas metrics konfigurasi layanan, batas di quota.limits, dan biaya yang dikeluarkan setiap metode di quota.metric_rules. Contoh:

metrics:
  - name: "read-requests"
    display_name: "Read requests"
    value_type: INT64
    metric_kind: DELTA
quota:
  limits:
    - name: "read-limit"
      metric: "read-requests"
      unit: "1/min/{project}"
      values:
        STANDARD: 1000
  metric_rules:
    - selector: "endpoints.examples.bookstore.Bookstore.ListShelves"
      metric_costs:
        "read-requests": 1

Untuk mengetahui petunjuk mendetail tentang setiap kolom ini, lihat dokumen Cloud Endpoints di Mengonfigurasi kuota.

Perhatian: Pastikan metrik dan batas kuota Anda tetap konsisten di semua konfigurasi API aktif sebelum Anda membuat konfigurasi API baru. API Gateway menerapkan metrics dan quota ke seluruh API, bukan ke konfigurasi API individual, sehingga metrik atau batas apa pun yang dideklarasikan oleh konfigurasi API baru akan menggantikan definisi untuk seluruh API. Jika Anda mengganti nama atau menghapus metrik, gateway apa pun yang masih menayangkan konfigurasi API sebelumnya akan menolak panggilan ke metode yang menerapkan kuota dengan kode status gRPC Internal. Untuk mengetahui informasi selengkapnya, lihat Kuota berlaku untuk seluruh API.

Menggunakan beberapa file YAML

Anda mungkin merasa berguna untuk menggunakan lebih dari satu file YAML untuk mengonfigurasi berbagai fitur untuk layanan yang sama. Menggunakan beberapa file YAML akan memudahkan penggunaan ulang file dan mengubahnya untuk lingkungan yang berbeda. Misalnya, dalam contoh Bookstore, konfigurasi dasar ditentukan dalam file api_config.yaml dan aturan HTTP-nya ditentukan dalam file api_config_http.yaml. Hal ini memungkinkan Anda men-deploy aturan HTTP hanya jika ingin mengaktifkan transkode JSON/HTTP ke gRPC untuk Bookstore.

Jika Anda menggunakan beberapa file YAML untuk konfigurasi layanan, saat konfigurasi di-deploy , setiap file akan dikonversi ke google.api.Service pesan proto, lalu semua pesan akan digabungkan menggunakan semantik penggabungan proto. Artinya, semua kolom skalar tunggal dalam instance terakhir akan menggantikan kolom skalar tunggal dalam instance sebelumnya. Jadi, jika Anda memberikan nilai tunggal yang berbeda untuk aturan yang sama dalam dua file, nilai dalam file kedua yang Anda tentukan saat men-deploy konfigurasi akan digunakan. Pesan tersemat tunggal digabungkan, dan kolom berulang digabungkan.

Seperti aturan, penggabungan bersifat peka terhadap urutan. Jika ada dua konfigurasi layanan, konfigurasi layanan kedua akan menggantikan konfigurasi layanan pertama.

Anotasi (khusus aturan HTTP)

Sebagai alternatif untuk menggunakan file YAML guna mengonfigurasi opsi HTTP, Anda dapat mengonfigurasinya langsung di file proto, menggunakan mekanisme opsi. Anotasi API ditentukan dalam annotations.proto.

Gunakan anotasi jika opsi konfigurasi dimaksudkan agar tidak berubah di semua penggunaan definisi antarmuka buffer protokol. Misalnya, jika API memiliki satu implementasi, atau semua implementasi harus memiliki antarmuka HTTP yang sama, Anda dapat menganotasi konfigurasi HTTP dalam file proto.

Jika opsi konfigurasi disediakan, baik dalam file proto maupun file YAML konfigurasi layanan, konfigurasi layanan akan menggantikan anotasi.

Contoh anotasi dalam file proto:

rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {
    option (google.api.http) = { get: "/v1/shelves" };
}


# The preceding annotation is equivalent to the following service configuration:

http:
  rules:
  - selector: endpoints.examples.bookstore.BookStore.ListShelves
    get: '/v1/shelves'

Untuk mengetahui informasi selengkapnya, lihat Transkode HTTP/JSON ke gRPC.

Langkah berikutnya

• Memulai API Gateway dan Cloud Run untuk gRPC
• Men-deploy API ke gateway
• Referensi konfigurasi layanan gRPC