Ekstensi OpenAPI 3.x di API Gateway

API Gateway menerima serangkaian ekstensi khusus Google untuk spesifikasi OpenAPI yang mengonfigurasi perilaku gateway. Dengan ekstensi ini, Anda dapat menentukan setelan pengelolaan API, metode autentikasi, batas kuota, dan integrasi backend langsung dalam dokumen OpenAPI. Memahami ekstensi ini akan membantu Anda menyesuaikan perilaku layanan dan berintegrasi dengan fitur API Gateway.

Halaman ini menjelaskan ekstensi khusus Google untuk spesifikasi OpenAPI 3.x.

Meskipun contoh yang diberikan dalam format YAML, JSON juga didukung.

x-google-api-management

Wajib.

Ekstensi x-google-api-management menentukan setelan pengelolaan API tingkat teratas untuk layanan Anda. Tempatkan ekstensi ini di root dokumen OpenAPI Anda.

Tabel berikut menjelaskan kolom untuk x-google-api-management:

Kolom Jenis Wajib Default Deskripsi
metrics map[string]Metric Tidak Kosong Tentukan metrik untuk menerapkan batas kuota.
quota map[string]Quota Tidak Kosong Tentukan batas kuota untuk layanan Anda.
backends map[string]Backend Ya Kosong Konfigurasi layanan backend.
apiName string Tidak Kosong Mengaitkan nama dengan operasi yang ditentukan dalam dokumen OpenAPI.

Objek Metric

Objek Metric menentukan metrik yang digunakan untuk penerapan kuota.

Tabel berikut menjelaskan kolom untuk Metric:

Kolom Jenis Wajib Default Deskripsi
displayName string Tidak Kosong Nama tampilan metrik.

Objek Quota

Objek Quota menentukan batas kuota.

Tabel berikut menjelaskan kolom untuk Quota:

Kolom Jenis Wajib Default Deskripsi
limits map[string]QuotaLimit Tidak Kosong Tentukan batas kuota.

Objek Quota Limit

Objek QuotaLimit menentukan batas kuota tertentu.

Tabel berikut menjelaskan kolom untuk QuotaLimit:

Kolom Jenis Wajib Deskripsi
metric string Ya Merujuk metrik yang dideklarasikan dalam dokumen OpenAPI ini.
values int64 Ya Tetapkan nilai maksimum yang dapat dicapai metrik sebelum permintaan klien ditolak.

Objek Backend

Objek Backend mengonfigurasi layanan backend. Anda harus menetapkan jwtAudience atau disableAuth.

Tabel berikut menjelaskan kolom untuk Backend:

Kolom Jenis Wajib Default Deskripsi
address string Tidak Kosong Tentukan URL backend.
jwtAudience string Tidak Kosong Secara default, Gateway API akan membuat token ID instance dengan audiens JWT yang cocok dengan kolom alamat. Menentukan jwt_audience secara manual hanya diperlukan jika backend target menggunakan autentikasi berbasis JWT dan audiens yang diharapkan berbeda dengan nilai yang ditentukan di kolom alamat. Untuk backend jarak jauh yang di-deploy di App Engine atau dengan IAP, Anda harus mengganti audiens JWT. App Engine dan IAP menggunakan client ID OAuth-nya sebagai audiens yang diharapkan.
disableAuth bool Tidak False Mencegah proxy bidang data mendapatkan token ID instance dan melampirkannya ke permintaan.
pathTranslation string Tidak APPEND_PATH_TO_ADDRESS atau CONSTANT_ADDRESS Tetapkan strategi terjemahan jalur saat melakukan proxy permintaan ke backend target. Jika x-google-backend ditetapkan di tingkat teratas dan tidak ada path_translation yang ditentukan, pathTranslation default adalah APPEND_PATH_TO_ADDRESS. Jika x-google-backend ditetapkan di tingkat operasi dan tidak ada path_translation yang ditentukan, defaultnya adalah CONSTANT_ADDRESS.
deadline double Tidak 15.0 Tentukan jumlah detik untuk menunggu respons penuh dari permintaan. Respons yang melebihi batas waktu ini akan habis.
protocol string Tidak http/1.1 Tetapkan protokol untuk mengirim permintaan ke backend. Nilai yang didukung mencakup http/1.1 dan h2.

x-google-auth

Opsional.

Ekstensi x-google-auth menentukan setelan autentikasi dalam Objek Skema Keamanan.

Tabel berikut menjelaskan kolom untuk x-google-auth:

Kolom Jenis Wajib Default Deskripsi
issuer string Tidak Kosong Tentukan penerbit kredensial. Nilai dapat berupa nama host atau alamat email.
jwksUri string Tidak Kosong

Berikan URI set kunci publik penyedia untuk memvalidasi tanda tangan Token Web JSON. API Gateway mendukung dua format kunci publik asimetris yang ditentukan oleh ekstensi OpenAPI ini:

  1. Format set JWK. Contoh: jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  2. X509. Contoh: jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Jika Anda menggunakan format kunci simetris, tetapkan jwksUri ke URI file yang berisi string kunci berenkode base64url.
audiences [string] Tidak Kosong Mencantumkan audiens yang harus cocok dengan kolom aud JWT selama autentikasi JWT.
jwtLocations [JwtLocations] Tidak Kosong Sesuaikan lokasi untuk token JWT. Secara default, JWT diteruskan di header Authorization (dengan awalan "Bearer "), header X-Goog-Iap-Jwt-Assertion, atau parameter kueri access_token.

Objek JwtLocations

Objek JwtLocations menyediakan lokasi yang disesuaikan untuk token JWT.

Tabel berikut menjelaskan kolom untuk JwtLocations:

Kolom Jenis Wajib Default Deskripsi
header | query string Ya T/A Tentukan nama untuk header yang berisi JWT, atau nama untuk parameter kueri yang berisi JWT.
valuePrefix string Tidak Kosong Hanya untuk header. Jika disetel, nilainya harus cocok dengan awalan nilai header yang berisi JWT.

x-google-quota

Opsional.

Ekstensi x-google-quota menentukan batas kuota. Anda dapat menentukan ekstensi ini di tingkat teratas dokumen OpenAPI atau untuk setiap operasi.

Tabel berikut menjelaskan kolom untuk x-google-quota:

Kolom Jenis Wajib Deskripsi
self map[string]int64 Ya Objek quota (self) mereferensikan semua metrik yang ditentukan dalam objek. Dalam hal ini, petakan metrik (seperti read-requests) ke jumlah untuk menaikkan metrik. Permintaan ditolak jika nilai metrik memenuhi batas kuota.

x-google-backend

Wajib.

Ekstensi x-google-backend mereferensikan backend yang ditentukan dalam x-google-api-management. Anda harus menyetel ekstensi ini untuk API Gateway. Anda dapat menentukan ekstensi ini di tingkat teratas dokumen OpenAPI atau untuk operasi individual.

Tabel berikut menjelaskan kolom untuk x-google-backend:

Kolom Jenis Wajib Deskripsi
self string Ya Merujuk ID backend yang ditentukan di x-google-api-management.

x-google-endpoint

Opsional.

Ekstensi x-google-endpoint digunakan untuk mengonfigurasi properti server yang ditentukan dalam array servers dari dokumen OpenAPI 3.x. Hanya satu entri server dalam dokumen OpenAPI yang dapat menggunakan ekstensi x-google-endpoint.

Ekstensi ini juga menentukan fitur backend lainnya, termasuk:

  • CORS: Anda dapat mengaktifkan Cross-Origin Resource Sharing (CORS) dengan menyetel properti allowCors ke true.

  • Jalur dasar: Jalur dasar yang ditetapkan di server dengan x-google-endpoint digunakan untuk API Anda. Misalnya, konfigurasi berikut menetapkan v1 sebagai jalur dasar:

servers:
  - url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
    x-google-endpoint: {}

Tabel berikut menjelaskan kolom untuk x-google-endpoint:

Kolom Jenis Wajib Default Deskripsi
allowCors bool Tidak false Izinkan permintaan CORS.

x-google-parameter

Opsional.

Ekstensi x-google-parameter ditentukan pada item parameter. Ini dapat digunakan saat jalur menggunakan pembuatan template jalur untuk menentukan bahwa perilaku pencocokan karakter pengganti ganda harus digunakan.

Tabel berikut menjelaskan kolom untuk x-google-parameter:

Kolom Jenis Wajib Deskripsi
pattern string Ya Nilai ini harus ditetapkan ke **.

Memahami Batasan Ekstensi OpenAPI

Ekstensi OpenAPI ini memiliki batasan tertentu. Untuk mempelajari lebih lanjut, lihat Batasan fitur OpenAPI 3.x.

Langkah berikutnya