Membuat konfigurasi API

Halaman ini menjelaskan cara membuat konfigurasi API untuk di-deploy di API Gateway.

Sebelum memulai

Sebelum membuat konfigurasi API, pastikan Anda telah:

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

• Membuat definisi API sebagai spesifikasi OpenAPI.

  Catatan: Jika Anda ingin menggunakan OpenAPI 3.x, pastikan untuk memperbarui Google Cloud CLI sebelum Anda mulai Membuat konfigurasi API untuk menghindari error saat mengupload definisi API.

• 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 dalam tutorial ini mengharuskan Anda menentukan ID konfigurasi API, dalam bentuk: CONFIG_ID. API Gateway memberlakukan persyaratan berikut untuk ID konfigurasi API:

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

Membuat konfigurasi API

Gunakan Google Cloud CLI untuk mengupload definisi API 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.

Jika managedService dalam definisi API Anda ditetapkan ke layanan Beta ESPv2, pastikan kolom host (OpenAPI 2.0) atau server.url (OpenAPI 3.x) ditetapkan ke ekstensi x-google-endpoint dalam konfigurasi API Anda.

Untuk membuat konfigurasi API:

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

   Untuk mengetahui 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 Mulai menggunakan 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 tempat Anda ingin membuat layanan: Google Cloud

   gcloud config set project PROJECT_ID

3. Melihat 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 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.
   • 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 menampilkan informasi ke terminal. Operasi ini mungkin memerlukan waktu beberapa menit untuk selesai karena konfigurasi API disebarkan ke sistem hilir. 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 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

   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 satu kali saat membuat API. Jika nanti Anda 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 menyetel 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. 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 \
  --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, atau dalam perintah list dengan menyertakan opsi --format:

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

Mencantumkan konfigurasi API

Untuk mencantumkan konfigurasi API untuk project tertentu:

gcloud api-gateway api-configs list 

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 

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

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_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 dalam Membuat konfigurasi API.

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 \
  --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 mungkin 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 berikutnya

• Men-deploy API ke gateway