Membuat konfigurasi API

Prasyarat

Sebelum dapat membuat konfigurasi API, pastikan Anda memiliki:

• Menyiapkan lingkungan pengembangan seperti yang dijelaskan dalam Mengonfigurasi lingkungan pengembangan.

• Membuat definisi API sebagai spesifikasi OpenAPI.

• Secara opsional, buat API seperti yang dijelaskan dalam Membuat API. Jika API belum ada, pembuatan konfigurasi API akan membuatnya.

Persyaratan ID konfigurasi API

Banyak perintah gcloud yang ditampilkan di bawah ini mengharuskan Anda menentukan ID konfigurasi API, dalam bentuk: CONFIG_ID. API Gateway 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. Jika API belum ada di API Gateway, perintah ini juga akan membuatnya.

Catatan: API Gateway mendukung pembuatan definisi API sebagai spesifikasi OpenAPI untuk semua layanan backend yang tersedia. API Gateway juga mendukung penggunaan definisi dan konfigurasi layanan gRPC untuk layanan gRPC di Cloud Run.

Untuk membuat konfigurasi API:

1. Ubah direktori ke direktori yang berisi definisi API Anda.

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

   Untuk mengetahui informasi selengkapnya tentang cara membuat definisi dan konfigurasi layanan gRPC untuk definisi API Anda, lihat Mengonfigurasi layanan gRPC dan Memulai API Gateway dan Cloud Run untuk gRPC.

2. Validasi project ID yang ditampilkan dari perintah berikut untuk memastikan bahwa layanan tidak dibuat di 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 tempat Anda ingin membuat layanan:

   gcloud config set project PROJECT_ID

3. Lihat bantuan untuk perintah api-configs create:

   gcloud api-gateway api-configs create --help

4. 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 API Gateway 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 project ID Google Cloud.
   • SERVICE_ACCOUNT_EMAIL menentukan akun layanan yang digunakan untuk menandatangani token untuk backend dengan autentikasi yang dikonfigurasi. Lihat Mengonfigurasi akun layanan untuk mengetahui detail selengkapnya.

   Saat membuat API dan konfigurasi API, API Gateway akan menghasilkan informasi ke terminal. Operasi ini mungkin memerlukan waktu beberapa menit hingga selesai karena konfigurasi API disebarkan ke sistem downstream. Pembuatan konfigurasi API yang kompleks dapat memerlukan waktu hingga sepuluh menit untuk selesai. Saat konfigurasi sedang dibuat, jangan coba membuat konfigurasi lain untuk API yang sama. Hanya satu konfigurasi yang dapat dibuat untuk setiap API dalam satu waktu.

5. 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 menampilkan hal berikut:

   createTime: '2020-02-04T18:33:11.882707149Z'
   displayName: CONFIG_ID
   gatewayConfig:
     backendConfig:
       googleServiceAccount: [e-mail]
   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'

6. Aktifkan API menggunakan nama layanan terkelola API. Anda dapat menemukan nilai ini di kolom Managed Service untuk API Anda 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 mengubah API, Anda tidak perlu menjalankan kembali perintah.

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

• --async: Segera kembalikan kontrol ke terminal, tanpa menunggu operasi selesai.
• --display-name=NAME: Menentukan nama tampilan konfigurasi API, yang berarti nama yang ditampilkan di UI. Jangan gunakan spasi dalam nama. Sebagai gantinya, gunakan tanda hubung dan garis bawah. 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 dalam output perintah describe yang ditampilkan di atas, atau dalam perintah list dengan menyertakan opsi --format:

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

Konfigurasi Listing API

Untuk mencantumkan konfigurasi API untuk project tertentu:

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

Perintah ini 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 project:

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

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

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

Memperbarui konfigurasi API

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

Catatan: Setiap kali Anda mengupload definisi API, API Gateway akan membuat konfigurasi API baru.

Untuk memperbarui definisi API:

1. Perbarui spesifikasi OpenAPI yang berisi definisi API.
2. Upload definisi API untuk membuat konfigurasi API baru.

Gunakan perintah yang sama untuk membuat konfigurasi API baru seperti yang Anda gunakan untuk membuat konfigurasi API awal, seperti yang ditunjukkan di atas dalam Membuat konfigurasi API.

Gunakan gcloud berikut untuk memperbarui 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

Peringatan: Jika Anda men-deploy konfigurasi API ke gateway, konfigurasi API tidak dapat dihapus hingga gateway tidak lagi menggunakan konfigurasi API tersebut.

Sebelum menghapus konfigurasi API yang sedang digunakan, Anda harus:

• Deploy konfigurasi API yang berbeda ke gateway.
• Hapus gateway.

Lihat Men-deploy API ke gateway untuk mengetahui informasi selengkapnya.

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