Mengonfigurasi layanan gRPC

Untuk membuat layanan gRPC—baik Anda menggunakan Cloud Endpoints maupun tidak—Anda menentukan definisi antarmuka di satu atau beberapa file proto, yang merupakan file teks dengan ekstensi .proto. Dalam file proto, Anda menentukan platform API Anda, termasuk struktur data, metode, parameter metode, dan jenis nilai yang ditampilkan. Kemudian, kompilasi file proto menggunakan compiler buffering protokol khusus bahasa, protoc. Untuk informasi selengkapnya, lihat Apa yang dimaksud dengan gRPC? dan konsep gRPC.

Agar layanan gRPC Anda dikelola oleh Endpoint, 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 menentukan informasi dasar mengenai layanan, seperti nama dan judulnya. Anda mengonfigurasi aspek lain dari layanan di sub-bagian file YAML, misalnya:

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 pemanggil diautentikasi.
  • backend: mengontrol perutean backend jarak jauh.
  • http: menentukan aturan untuk memetakan metode RPC ke satu atau beberapa metode REST API HTTP.
  • usage: memungkinkan Anda mengaktifkan dan menonaktifkan validasi kunci API secara selektif.

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

Konfigurasi dasar

Contoh Bookstore, yang digunakan dalam tutorial gRPC, menyertakan 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: bookstore.endpoints.MY_PROJECT_ID.cloud.goog

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

Contoh kode sebelumnya adalah konfigurasi layanan yang paling sederhana karena:

  • Menentukan layanan bernama bookstore.endpoints.MY_PROJECT_ID.cloud.goog, dengan MY_PROJECT_ID mewakili ID project Google Cloud Anda.
  • Menentukan bahwa layanan mengekspos API endpoints.examples.bookstore.Bookstore, seperti yang ditentukan dalam file bookstore.proto.
  • Memberikan judul deskriptif yang muncul di halaman Endpoint > Layanan di Konsol Google Cloud setelah Anda men-deploy konfigurasi. Tinjau versi GitHub lengkap setiap file untuk komentar yang lebih mendetail.

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 yang lainnya. Untuk mengonfigurasinya dalam konfigurasi layanan, beberapa bagian konfigurasi layanan, seperti authentication dan http, memungkinkan Anda menentukan aturan dan pemilih. Pemilih mengidentifikasi elemen layanan, seperti nama metode tempat konfigurasi yang terkait dengan aturan diterapkan.

Pemilih adalah daftar yang dipisahkan koma untuk nama-nama yang memenuhi syarat yang ditentukan dalam layanan: nilai metode, pesan, kolom, enum, atau enum. Segmen terakhir pada 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.* tidak masalah, tetapi tidak untuk foo.b* atau foo.*.bar. Untuk mengonfigurasi nilai default bagi semua elemen yang berlaku, Anda harus menentukan * sendiri.

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, yang terakhir cocok dalam urutan deklarasi akan diterapkan.

Menggunakan beberapa file YAML

Penggunaan lebih dari satu file YAML akan berguna untuk mengonfigurasi fitur yang berbeda untuk layanan yang sama. Menggunakan beberapa file YAML akan mempermudah penggunaan kembali file dan perubahan file untuk lingkungan yang berbeda. Misalnya, dalam contoh Toko Buku, konfigurasi dasar ditentukan dalam file api_config.yaml dan aturan HTTP-nya ditentukan dalam file api_config_http.yaml. Tindakan ini memungkinkan Anda men-deploy aturan HTTP hanya jika ingin mengaktifkan transcoding JSON/HTTP ke gRPC untuk Bookstore.

Jika Anda menggunakan beberapa file YAML untuk konfigurasi layanan, saat konfigurasi di-deploy, setiap file dikonversi menjadi pesan proto google.api.Service, lalu semua pesan akan digabungkan menggunakan semantik penggabungan proto. Artinya, semua kolom skalar tunggal pada 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 halnya aturan, penggabungan bersifat sensitif terhadap urutan. Jika ada dua konfigurasi layanan, konfigurasi layanan kedua akan menggantikan konfigurasi layanan pertama.

Anotasi (khusus aturan HTTP)

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

Gunakan anotasi jika opsi konfigurasi dimaksudkan sebagai invarian atas semua penggunaan definisi antarmuka buffering protokol. Misalnya, jika sebuah API memiliki satu implementasi, atau semua implementasi harus memiliki antarmuka HTTP yang sama, Anda dapat menganotasikan 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 informasi selengkapnya, lihat Transcoding HTTP/JSON ke gRPC.

Validasi konfigurasi

Anda men-deploy konfigurasi layanan dan mengompilasi file proto menggunakan gcloud endpoints services deploy untuk membuat konfigurasi runtime layanan Anda. Perintah gcloud endpoints services deploy memvalidasi konfigurasi layanan serta menandai setiap error dan peringatan.

Peringatan dibagi menjadi peringatan reguler dan linter. Peringatan lint menggunakan ID dengan bentuk <group>-<rule>, dengan <group> menunjukkan grup konfigurasi, dan <rule> aturan linter tertentu. Misalnya, di bawah grup adalah versioning dan aturannya adalah http-version-prefix:

WARNING: bookstore.proto:51:3: (lint) versioning-http-version-prefix: method
'endpoints.examples.bookstore.BookStore.ListShelves' has a different version
prefix in HTTP path ('v2') than api version 'v1'.

Anda dapat menyembunyikan peringatan linter dengan menambahkan perintah ke dokumentasi elemen API. Anda dapat menambahkan perintah ini di file proto atau dalam file YAML konfigurasi layanan. Misalnya, kode berikut akan menyembunyikan peringatan sebelumnya:

service Bookstore {
  // Returns an object.
  // (== suppress_warning versioning-http-version-prefix ==)
  rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {
      option (google.api.http) = { get: "/v1/shelves" };
  }
}

Guna menyembunyikan peringatan untuk seluruh grup, Anda dapat menggunakan karakter pengganti (*), bukan nama aturan. Misalnya, versioning-* menyembunyikan semua peringatan yang terkait dengan grup versioning.

Perintah penyembunyian yang dilampirkan ke elemen induk juga berlaku untuk semua turunan. Misalnya, contoh berikut menyembunyikan semua peringatan grup versioning di semua metode dalam layanan:

// (== suppress_warning versioning-* ==)
service Bookstore {
  // Returns an object.
  rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {
      option (google.api.http) = { get: "/v1/shelves" };
  }
}

Untuk menyembunyikan peringatan secara global, lampirkan ke dokumentasi ringkasan konfigurasi layanan:

type: google.api.Service
name: your_api.endpoints.<producer-project-id>.cloud.goog
title: Bookstore gRPC API
apis:
- name: endpoints.examples.bookstore.BookStore
documentation:
    overview: |
      A simple Bookstore gRPC API.
      (== suppress_warning documentation-presence ==)

Perhatikan bahwa perintah dalam dokumentasi seperti suppress_warning harus muncul di barisnya sendiri. Jika tidak, perintah tersebut tidak akan dikenali. YAML akan menghapus penanda literal blok YAML seperti > menghapus semua baris baru. Jadi, jika Anda menggunakan overview: > dalam contoh sebelumnya, penyembunyian tidak akan berfungsi. Untuk mengetahui informasi lebih lanjut tentang literal blok di YAML, lihat Pemisahan indentasi.

Langkah selanjutnya