Panduan memulai API Gateway dan Cloud Run

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

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

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

Membuat atau memilih project Google Cloud.
Jika Anda belum men-deploy Cloud Run Anda sendiri, deploy layanan sampel. Lihat langkah 7 di bagian Sebelum memulai.
Aktifkan layanan Gateway API yang diperlukan.
Buat spesifikasi OpenAPI yang mendeskripsikan API Anda, dan konfigurasikan rute ke layanan backend Cloud Run Anda. Lihat Membuat konfigurasi API.
Deploy Gateway API menggunakan konfigurasi API Anda. Lihat Men-deploy Gateway 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 yang ingin Anda gunakan untuk tutorial ini. Di bagian lain halaman ini, project ID ini disebut sebagai PROJECT_ID.
Mendownload dan menginstal Google Cloud CLI.
Mendownload gcloud CLI
Update komponen gcloud:
```
gcloud components update
```
Tetapkan project default. Ganti PROJECT_ID dengan ID project Google Cloud Anda
```
gcloud config set project PROJECT_ID
```
Jika Anda belum men-deploy layanan Cloud Run sendiri, ikuti langkah-langkah di bagian Quickstart: Deploy a Prebuilt Sample Container untuk memilih atau membuat project Google Cloud dan men-deploy backend contoh. Catat URL aplikasi, serta region dan project ID tempat aplikasi 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

Sebelum Gateway API dapat digunakan untuk mengelola traffic ke backend Cloud Run yang di-deploy, Gateway API memerlukan konfigurasi API.

Anda dapat membuat konfigurasi API menggunakan spesifikasi OpenAPI yang berisi anotasi khusus untuk menentukan perilaku API Gateway yang diinginkan. Anda harus menambahkan kolom khusus Google yang berisi URL untuk setiap aplikasi Cloud Run sehingga Gateway API memiliki informasi yang diperlukan untuk memanggil aplikasi.

Buat file teks bernama openapi2-run.yaml. (Untuk memudahkan, halaman ini mengacu pada spesifikasi OpenAPI berdasarkan nama file tersebut, tetapi Anda dapat menamainya dengan nama lain jika mau.)

Cantumkan setiap aplikasi Anda di bagian paths pada file openapi2-run.yaml, seperti yang ditunjukkan di bawah ini:

# openapi2-run.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Cloud Run backend
  version: 1.0.0
schemes:
- https
produces:
- application/json
x-google-backend:
  address: APP_URL
paths:
  /assets/{asset}:
    get:
      parameters:
        - in: path
          name: asset
          type: string
          required: true
          description: Name of the asset.
      summary: Assets
      operationId: getAsset
      responses:
        '200':
          description: A successful response
          schema:
            type: string
  /hello:
    get:
      summary: Cloud Run hello world
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string

Di kolom title, ganti API_ID dengan nama API Anda dan ganti optional-string dengan deskripsi singkat pilihan Anda. Jika API Anda belum ada, perintah untuk membuat API Config juga akan membuat API dengan nama yang Anda tentukan. Nilai kolom title digunakan saat membuat kunci API yang memberikan akses ke API ini. Lihat persyaratan ID API untuk panduan penamaan API.
Pada kolom address di bagian x-google-backend, ganti APP_URL dengan URL sebenarnya dari layanan Cloud Run Anda (jalur lengkap dari API yang dipanggil). Contoh: https://hello-abc1def2gh-uc.a.run.app.
Catatan: Jika berencana menggunakan tag revisi untuk membuat versi backend layanan Cloud Run, Anda harus menentukan kolom jwt_audience di bagian address di bagian x-google-backend. Nilai kolom jwt_audience harus berupa URL layanan Cloud Run. Contoh:
```
...
  x-google-backend:
      address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
      jwt_audience: https://SERVICE_HOSTNAME
...
```
Jika kolom jwt_audience tidak ada, ekstensi x-google-backend secara default akan menggunakan nilai kolom address untuk klaim audiens JWT. Hal ini dapat menyebabkan klaim audiens JWT yang tidak terduga untuk Cloud Run jika URL tag revisi digunakan untuk address dan tidak ada jwt_audience yang ditentukan.
Masukkan perintah berikut, dengan kondisi:
- CONFIG_ID menentukan nama konfigurasi API Anda.
- API_ID menentukan nama API Anda. Jika API belum ada, perintah ini akan membuatnya.
- PROJECT_ID menentukan nama project Google Cloud Anda.
- SERVICE_ACCOUNT_EMAIL menentukan akun layanan yang digunakan untuk menandatangani token bagi backend dengan autentikasi yang dikonfigurasi. Untuk informasi selengkapnya, lihat Membuat akun layanan.
  Catatan: Akun layanan yang digunakan untuk membuat konfigurasi API untuk backend Cloud Run harus memiliki peran run.invoker yang ditetapkan.
```
gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=openapi2-run.yaml \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
Operasi ini mungkin memerlukan waktu beberapa menit hingga konfigurasi API diterapkan ke sistem downstream. Pembuatan konfigurasi API yang kompleks dapat memerlukan waktu hingga sepuluh menit agar berhasil diselesaikan.
Setelah konfigurasi API dibuat, Anda dapat melihat detailnya dengan menjalankan perintah ini:
```
gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID
```

Men-deploy Gateway API

Sekarang Anda dapat men-deploy API di Gateway API. Men-deploy API di Gateway API juga menentukan URL eksternal yang dapat digunakan klien API untuk mengakses API Anda.

Jalankan perintah berikut untuk men-deploy konfigurasi API yang baru saja Anda buat ke Gateway API:

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.

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.

Menguji deployment API Anda

Sekarang Anda dapat mengirim permintaan ke API menggunakan URL yang dihasilkan setelah deployment gateway.

Masukkan URL berikut di browser web Anda, jika:

DEFAULT_HOSTNAME menentukan bagian nama host URL gateway yang di-deploy.
hello adalah jalur yang ditetapkan dalam konfigurasi API Anda.

https://DEFAULT_HOSTNAME/hello

Contoh:

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

Anda akan melihat container Cloud Run menjalankan aplikasi di browser.

Berhasil! Gateway API Anda mengelola akses ke layanan backend Cloud Run.

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.

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.