Mulai menggunakan Gateway API dan Cloud Run untuk gRPC

Halaman ini menunjukkan cara menyiapkan Gateway API untuk mengelola dan mengamankan layanan backend Cloud Run dengan gRPC.

{i>Task List <i}(Daftar Tugas)

Gunakan daftar tugas berikut saat Anda mengerjakan tutorial. Semua tugas diperlukan untuk men-deploy Gateway API untuk layanan backend Cloud Run dengan gRPC.

Membuat atau memilih project Google Cloud.
Jika Anda belum men-deploy Cloud Run Anda sendiri, deploy contoh layanan gRPC backend. Lihat langkah 7 di bagian Sebelum memulai.
Aktifkan layanan Gateway API yang diperlukan.
Buat dokumen konfigurasi gRPC API yang mendeskripsikan API Anda, dan mengonfigurasi rute ke Cloud Run. Lihat Mengonfigurasi konfigurasi API dengan gRPC.
Deploy Gateway API menggunakan konfigurasi API Anda. Lihat Men-deploy Gateway API.
Uji deployment API Anda dengan mengirim permintaan. Lihat Mengirim permintaan ke API.
Lacak aktivitas ke layanan Anda. Lihat Aktivitas Tracking API.
Hindari menimbulkan tagihan ke akun Google Cloud Anda. Lihat Pembersihan.

Sebelum memulai

Di konsol Google Cloud, buka halaman Dashboard dan pilih atau buat project Google Cloud.
Buka halaman Dashboard

Catatan: Jika Anda tidak berencana untuk menyimpan resource yang dibuat dalam tutorial ini, buat project baru, bukan memilih project yang ada. Setelah menyelesaikan langkah-langkah ini, Anda dapat menghapus project, sehingga semua resource yang terkait dengan project tersebut akan dihapus.
Pastikan penagihan diaktifkan untuk project Anda.
Pelajari cara mengaktifkan penagihan
Catat ID project karena akan diperlukan nanti. Di bagian selanjutnya dari halaman ini, project ID ini disebut sebagai PROJECT_ID.
Catat nomor project karena akan diperlukan nanti. Di bagian selanjutnya halaman ini, nomor project ini disebut sebagai PROJECT_NUMBER.
Mendownload dan menginstal Google Cloud CLI.
Mendownload gcloud CLI
Ikuti langkah-langkah dalam panduan memulai Python gRPC untuk menginstal alat gRPC dan gRPC.
Deploy layanan backend contoh python-grpc-bookstore-server gRPC Cloud Run untuk digunakan dengan tutorial ini. Layanan gRPC menggunakan image container berikut:

gcr.io/endpointsv2/python-grpc-bookstore-server:2

Ikuti langkah-langkah di bagian Panduan Memulai: Men-deploy Container Contoh Bawaan untuk men-deploy layanan. Pastikan untuk mengganti image container yang ditentukan dalam panduan memulai tersebut dengan gcr.io/endpointsv2/python-grpc-bookstore-server:2

Catat URL layanan, serta region dan project ID tempat layanan Anda di-deploy.

Mengaktifkan layanan yang diperlukan

Gateway API mengharuskan Anda mengaktifkan layanan Google berikut:

Nama	Judul
`apigateway.googleapis.com`	API Gateway API
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

Untuk mengonfirmasi bahwa layanan yang diperlukan telah diaktifkan:

gcloud services list

Jika Anda tidak melihat layanan yang diperlukan tercantum, aktifkan layanan tersebut:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Untuk mengetahui informasi selengkapnya tentang layanan gcloud, lihat layanan gcloud.

Membuat konfigurasi API dengan gRPC

Contoh bookstore-grpc berisi file yang perlu Anda salin secara lokal dan konfigurasi.

Buat file deskriptor protobuf mandiri dari file .proto layanan Anda:
1. Simpan salinan bookstore.proto dari repositori contoh ke direktori kerja Anda saat ini. File ini menentukan API layanan Bookstore.
2. Buat direktori berikut di direktori kerja Anda: mkdir generated_pb2
3. Buat file deskripsi, api_descriptor.pb, menggunakan compiler buffering protokol protoc. Jalankan perintah berikut di direktori tempat Anda menyimpan bookstore.proto:
```
python3 -m grpc_tools.protoc \
    --include_imports \
    --include_source_info \
    --proto_path=. \
    --descriptor_set_out=api_descriptor.pb \
    --python_out=generated_pb2 \
    --grpc_python_out=generated_pb2 \
    bookstore.proto
```
  Dalam perintah sebelumnya, --proto_path ditetapkan ke direktori kerja saat ini. Di lingkungan build gRPC, jika Anda menggunakan direktori berbeda untuk file input .proto, ubah --proto_path agar compiler menelusuri direktori tempat Anda menyimpan bookstore.proto.

Buat file teks bernama api_config.yaml di direktori kerja Anda saat ini (direktori yang sama yang berisi bookstore.proto). Untuk memudahkan, halaman ini merujuk ke dokumen konfigurasi gRPC API dengan nama file tersebut, tetapi Anda dapat menamainya dengan nama lain jika ingin. Tambahkan konten berikut ke file tersebut:

# The configuration schema is defined by the service.proto file.
# https://github.com/googleapis/googleapis/blob/master/google/api/service.proto

type: google.api.Service
config_version: 3
name: "*.apigateway.PROJECT_ID.cloud.goog"
title: API Gateway + Cloud Run gRPC
apis:
  - name: endpoints.examples.bookstore.Bookstore
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true
backend:
  rules:
    - selector: "*"
      address: grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app

Indentasi penting untuk format yaml. Misalnya, kolom name harus berada pada level yang sama dengan type.

Di kolom name, terdapat layanan bernama *.apigateway.PROJECT_ID.cloud.goog dengan PROJECT_ID sebagai nama project ID Google Cloud Anda.
Pada kolom address di bagian backend.rules, ganti grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app dengan URL sebenarnya dari layanan backend gRPC Cloud Run backend python-grpc-bookstore-server, dengan HASH adalah kode hash unik yang dihasilkan saat Anda membuat layanan.

Catatan: Untuk menggunakan gRPC dengan TLS di Cloud Run, kolom address harus memiliki skema grpcs://, bukan https://.

Contoh ini mengasumsikan bahwa Anda menggunakan layanan backend gRPC Bookstore yang dibuat di Sebelum memulai. Jika perlu, ganti nilai ini dengan URL layanan Cloud Run Anda.
Simpan dokumen konfigurasi gRPC API Anda.

Buat konfigurasi API:

gcloud api-gateway api-configs create CONFIG_ID \
--api=API_ID --project=PROJECT_ID \
--grpc-files=api_descriptor.pb,api_config.yaml

dalam hal ini:

CONFIG_ID menentukan nama konfigurasi API Anda.
API_ID menentukan nama API Anda.
PROJECT_ID menentukan nama project Google Cloud Anda.

Contoh:

gcloud api-gateway api-configs create grpc-config \
--api=grpc-test --project=my-test-project \
--grpc-files=api_descriptor.pb,api_config.yaml

Men-deploy Gateway API

Untuk men-deploy konfigurasi gRPC API ke gateway, jalankan perintah berikut:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

dengan:

GATEWAY_ID menentukan nama gateway.
API_ID menentukan nama API Gateway API yang terkait dengan gateway ini.
CONFIG_ID menentukan nama konfigurasi API yang di-deploy ke gateway.
GCP_REGION adalah region Google Cloud untuk gateway yang di-deploy.
Catatan:
Nilai yang diizinkan adalah:
- asia-northeast1
- australia-southeast1
- europe-west1
- europe-west2
- us-east1
- us-east4
- us-central1
- us-west2
- us-west3
- us-west4
Dukungan untuk gateway Gateway API yang sebelumnya dibuat di asia-east1 akan berakhir pada 1 November 2022. Anda harus meninjau gateway apa pun yang saat ini berjalan di asia-east1 dan menghapus atau membuatnya ulang di lokasi baru sesuai kebutuhan.
PROJECT_ID menentukan nama project Google Cloud Anda.

Contoh:

gcloud api-gateway gateways create bookstore-grpc \
  --api=grpc-test --api-config=grpc-config \
  --location=us-central1 --project=my-project

Setelah berhasil diselesaikan, Anda dapat menggunakan perintah berikut untuk melihat detail tentang gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Catat nilai properti defaultHostname dalam output perintah ini. Ini adalah bagian nama host URL gateway yang Anda gunakan untuk menguji deployment pada langkah berikutnya.

Contoh:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Mengirim permintaan ke API

Untuk mengirim permintaan ke API contoh, Anda dapat menggunakan klien gRPC contoh yang ditulis di Python.

Clone repo git tempat kode klien gRPC dihosting:

git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

Ubah direktori kerja Anda:

cd python-docs-samples/endpoints/bookstore-grpc/

Instal dependensi:

pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt

Kirim permintaan ke API contoh:

python3 bookstore_client.py --host=DEFAULT_HOSTNAME --port 443 --use_tls true

Tentukan properti defaultHostname gateway Anda di DEFAULT_HOSTNAME, tanpa ID protokol. Contoh:

python3 bookstore_client.py --host=my-gateway-a12bcd345e67f89g0h.uc.gateway.dev --port 443 --use_tls true

Melacak aktivitas API

Lihat grafik aktivitas untuk API Anda di halaman Gateway API di Konsol Google Cloud. Klik API Anda untuk melihat grafik aktivitasnya di halaman Overview. Mungkin perlu waktu beberapa saat agar permintaan ditampilkan dalam grafik.
Lihat log permintaan untuk API Anda di halaman Logs Explorer. Link ke halaman Logs Explorer dapat ditemukan di halaman API Gateway pada Konsol Google Cloud.
Buka halaman Gateway API
Setelah berada di halaman Gateway API:
1. Pilih API untuk dilihat.
2. Klik tab Details.
3. Klik link di bagian Logs.

Anda baru saja men-deploy dan menguji API di Gateway API dengan gRPC.

Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam panduan memulai ini, Anda dapat:

Atau, Anda juga dapat menghapus project Google Cloud yang digunakan untuk tutorial ini.