Membuat konfigurasi API

Prasyarat

Sebelum Anda dapat membuat konfigurasi API, pastikan Anda telah:

Siapkan lingkungan pengembangan Anda seperti yang dijelaskan dalam Mengonfigurasi lingkungan pengembangan Anda.
Membuat definisi API sebagai spesifikasi OpenAPI.
Secara opsional, membuat API seperti yang dijelaskan dalam Membuat API. Jika API belum ada, pembuatan konfigurasi API akan membuatnya.

Persyaratan ID konfigurasi API

Banyak dari perintah gcloud yang ditampilkan di bawah ini mengharuskan Anda menentukan ID konfigurasi API, dalam bentuk: CONFIG_ID. Gateway API menerapkan persyaratan berikut untuk ID konfigurasi API:

Harus memiliki panjang maksimum 63 karakter.
Hanya boleh berisi huruf kecil, angka, atau tanda pisah.
Tidak boleh diawali dengan tanda hubung.
Tidak boleh berisi garis bawah.

Membuat konfigurasi API

Gunakan Google Cloud CLI untuk mengupload definisi API Anda guna membuat konfigurasi API. Saat mengupload definisi API, Anda harus menentukan nama API tersebut. Jika API belum ada di Gateway API, perintah ini juga akan membuatnya.

Untuk membuat konfigurasi API:

Ubah direktori ke direktori yang berisi definisi API Anda.

Untuk informasi selengkapnya tentang cara membuat spesifikasi OpenAPI untuk definisi API, lihat Ringkasan OpenAPI dan Panduan memulai: Men-deploy API di Gateway API.

Untuk informasi selengkapnya tentang cara membuat definisi dan konfigurasi layanan gRPC untuk definisi API Anda, lihat Mengonfigurasi layanan gRPC dan Memulai Gateway API dan Cloud Run untuk gRPC.
Validasi project ID yang ditampilkan dari perintah berikut untuk memastikan layanan tidak dibuat dalam project yang salah.
```
gcloud config list project
```
Jika Anda perlu mengubah project default, jalankan perintah berikut dan ganti PROJECT_ID dengan project ID Google Cloud yang ingin digunakan untuk membuat layanan:
```
gcloud config set project PROJECT_ID
```
Lihat bantuan untuk perintah api-configs create:
```
gcloud api-gateway api-configs create --help
```
Jalankan perintah berikut untuk membuat konfigurasi API:
```
gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
dengan:
- CONFIG_ID menentukan ID konfigurasi API baru.
- API_ID menentukan ID API Gateway API yang terkait dengan konfigurasi API ini. Jika API belum ada, perintah ini akan membuatnya.
- API_DEFINITION menentukan nama spesifikasi OpenAPI yang berisi definisi API.
- PROJECT_ID menentukan ID project Google Cloud.
- SERVICE_ACCOUNT_EMAIL menentukan akun layanan yang digunakan untuk menandatangani token bagi backend dengan autentikasi yang dikonfigurasi. Lihat Mengonfigurasi akun layanan untuk detail selengkapnya.
Saat membuat konfigurasi API dan API, Gateway API menghasilkan informasi ke terminal. Operasi ini mungkin memerlukan waktu beberapa menit untuk diselesaikan karena konfigurasi API diterapkan ke sistem downstream. Pembuatan konfigurasi API yang kompleks dapat memerlukan waktu hingga sepuluh menit agar berhasil diselesaikan. Saat konfigurasi sedang dibuat, jangan mencoba membuat konfigurasi lain untuk API yang sama. Hanya satu konfigurasi yang dapat dibuat untuk API mana pun pada satu waktu.

Setelah berhasil diselesaikan, Anda dapat menggunakan perintah berikut untuk melihat detail tentang konfigurasi API baru:

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID

Perintah ini akan menampilkan hal berikut:

createTime: '2020-02-04T18:33:11.882707149Z'
displayName: CONFIG_ID
gatewayConfig:
  backendConfig:
    googleServiceAccount: 1111111@developer.gserviceaccount.com
labels: ''
name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
serviceRollout:
  rolloutId: 2020-02-04r2
state: ACTIVE
updateTime: '2020-02-04T18:33:12.219323647Z'

Aktifkan API menggunakan nama layanan terkelola dari API. Anda dapat menemukan nilai ini di kolom Layanan Terkelola untuk API di halaman landing API:
```
gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
```
Anda hanya perlu menjalankan perintah ini sekali saat membuat API. Jika nanti Anda memodifikasi API, Anda tidak perlu menjalankan kembali perintah tersebut.

Google Cloud CLI menggunakan banyak opsi, termasuk yang dijelaskan dalam Referensi gcloud. Selain itu, untuk Gateway API, Anda dapat menetapkan opsi berikut saat membuat konfigurasi API:

--async: Segera mengembalikan kontrol ke terminal, tanpa menunggu operasi selesai.
--display-name=NAME: Menetapkan nama tampilan konfigurasi API, artinya nama yang ditampilkan di UI. Jangan gunakan spasi dalam nama. Gunakan tanda hubung dan garis bawah sebagai gantinya. Nilai defaultnya adalah CONFIG_ID.
--labels=KEY1=VALUE1,KEY2=VALUE2,...: Menentukan label yang terkait dengan konfigurasi API.

Contoh:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL \
  --async --display-name=MyConfig --labels=a=1,b=2

Anda dapat melihat label di output perintah describe yang ditunjukkan di atas, atau di perintah list dengan menyertakan opsi --format:

gcloud api-gateway api-configs list \
  --api=API_ID --project=PROJECT_ID --format="table(name, labels)"

Membuat daftar konfigurasi API

Untuk mencantumkan konfigurasi API untuk project tertentu:

gcloud api-gateway api-configs list --project=PROJECT_ID

Perintah ini akan menampilkan hal berikut:

NAME                                                                DISPLAY_NAME  ROLLOUT_ID    STATE   CREATE_TIME
projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID  CONFIG_ID     2020-02-04r0  ACTIVE  2020-02-04T16:18:02.369859863Z

Untuk mencantumkan konfigurasi API untuk API tertentu dalam sebuah project:

gcloud api-gateway api-configs list --api=API_ID --project=PROJECT_ID

Gunakan project, API, dan ID konfigurasi untuk mendapatkan informasi mendetail tentang konfigurasi API:

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID

Mengupdate konfigurasi API

Anda tidak dapat mengubah konfigurasi API yang sudah ada selain untuk memperbarui label dan nama tampilannya.

Gunakan gcloud berikut untuk mengupdate konfigurasi API yang ada:

--display-name
--update-labels
--clear-labels
--remove-labels

Contoh:

gcloud api-gateway api-configs update CONFIG_ID \
  --api=API_ID  --project=PROJECT_ID \
  --update-labels=a=1,b=2

Gunakan perintah berikut untuk melihat semua opsi update:

gcloud api-gateway api-configs update --help

Menghapus konfigurasi API

Gunakan perintah gcloud berikut untuk menghapus konfigurasi API yang ada:

gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID

Langkah selanjutnya

Men-deploy API ke gateway