Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Ekstensi OpenAPI 3.x di Gateway API

Gateway API 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 Gateway API.

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.
`ai`	`AI`	Tidak	Kosong	Mengonfigurasi fitur kecerdasan buatan, termasuk perutean model.

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 `Backends`

Wajib.

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

Tabel berikut menjelaskan kolom untuk Backends:

Kolom	Jenis	Wajib	Default	Deskripsi
`address`	`string`	Ya	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. Batas waktu maksimum adalah 600 detik.
`protocol`	`string`	Tidak	`http/1.1`	Tetapkan protokol untuk mengirim permintaan ke backend. Nilai yang didukung mencakup `http/1.1` dan `h2`.

Objek `AI`

Objek AI mengonfigurasi kemampuan kecerdasan buatan untuk layanan Anda, seperti perutean model.

Tabel berikut menjelaskan kolom untuk AI:

Kolom	Jenis	Wajib	Default	Deskripsi
`models`	`Models`	Tidak	Kosong	Mengonfigurasi integrasi model AI.

Objek `Models`

Objek Models menentukan konfigurasi khusus model.

Tabel berikut menjelaskan kolom untuk Models:

Kolom	Jenis	Wajib	Default	Deskripsi
`routing`	`Routing`	Tidak	Kosong	Konfigurasi setelan perutean model.

Objek `Routing`

Objek Routing menentukan aturan perutean dan perute model.

Tabel berikut menjelaskan kolom untuk Routing:

Kolom	Jenis	Wajib	Default	Deskripsi
`routers`	`map[string]Router`	Tidak	Kosong	Tentukan perute model bernama.

Objek `Router`

Objek Router menentukan perute model bernama.

Tabel berikut menjelaskan kolom untuk Router:

Kolom	Jenis	Wajib	Default	Deskripsi
`defaultModel`	`DefaultModel`	Ya	Kosong	Tujuan model penggantian yang diperlukan digunakan saat permintaan masuk tidak cocok dengan aturan eksplisit apa pun.
`rules`	`[Rule]`	Tidak	Kosong	Daftar aturan pemilihan rute model eksplisit.

Objek `DefaultModel`

Objek DefaultModel menentukan tujuan penggantian.

Tabel berikut menjelaskan kolom untuk DefaultModel:

Kolom	Jenis	Wajib	Default	Deskripsi
`backend`	`string`	Ya	Kosong	Merujuk ke backend yang dideklarasikan di `x-google-api-management.backends`.
`targetModel`	`string`	Ya	Kosong	Tentukan ID model target dalam bentuk `<provider>/<model-id>`. Untuk rute yang kompatibel dengan OpenAI, nilai ini diteruskan sebagai atribut `model` keluar dalam isi permintaan saat terjadi penggantian.

Objek `Rule`

Objek Rule menentukan aturan perutean model eksplisit.

Tabel berikut menjelaskan kolom untuk Rule:

Kolom	Jenis	Wajib	Default	Deskripsi
`model`	`string`	Ya	Kosong	String masuk yang cocok dengan atribut `model` dalam payload JSON klien. Untuk rute yang kompatibel dengan OpenAI, string ini diteruskan sebagai atribut `model` keluar di isi permintaan dan harus berupa string `<provider>/<model-id>` yang valid.
`backend`	`string`	Ya	Kosong	Merujuk ke backend yang dideklarasikan di `x-google-api-management.backends`.
`targetModel`	`string`	Ya	Kosong	Tentukan ID model target dalam bentuk `<provider>/<model-id>`. Nilai ini memilih terjemahan penyedia dan ditampilkan kembali di kolom `model` respons.

`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. Gateway API mendukung dua format kunci publik asimetris yang ditentukan oleh ekstensi OpenAPI ini: Format set JWK. Contoh: `jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"` 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 digunakan pada setiap operasi untuk menentukan metrik yang ditentukan dalam x-google-api-management.metrics yang terpengaruh oleh permintaan ke operasi tersebut.

x-google-quota adalah objek yang berisi pasangan nilai kunci, dengan setiap kunci adalah nama metrik dan nilainya adalah biaya bilangan bulat untuk setiap permintaan ke operasi. Contoh:

x-google-api-management:
  metrics:
    read-requests:
      displayName: "Greeter requests"
    write-requests:
      displayName: "Greeter requests by name"
  quota:
    limits:
      read-requests-limit:
        metric: read-requests
        values: 1
# Set at the top-level so this applies to all operations (unless overridden)
x-google-quota:
    read-requests: 1
paths:
  /v1/projects/projectId/pets:
    get:
      # Set at the path level, so it overrides the top level quota
      x-google-quota:
          write-requests: 1

`x-google-backend`

Wajib.

Ekstensi x-google-backend mereferensikan backend yang ditentukan dalam x-google-api-management.backends. Jika digunakan, nilainya harus berupa string yang cocok dengan nama backend yang ditentukan di x-google-api-management.backends. Anda harus menetapkan ekstensi ini untuk Gateway API. Anda dapat menentukan ekstensi ini di tingkat teratas dokumen OpenAPI atau untuk operasi individual guna mengganti backend tingkat teratas.

Contoh:

x-google-api-management:
  backends:
    my-backend:
      address: myapp.run.app
x-google-backend: my-backend

`x-google-model-router`

Opsional.

Ekstensi x-google-model-router mereferensikan perute model yang ditentukan dalam x-google-api-management.ai.models.routing.routers. Jika digunakan, nilainya harus berupa string yang cocok dengan nama router yang ditentukan dalam x-google-api-management.ai.models.routing.routers.

Ekstensi ini hanya didukung dalam spesifikasi OpenAPI 3.x; tidak dapat digunakan dengan spesifikasi OpenAPI 2.0 (Swagger). Anda dapat menentukan ekstensi ini hanya di tingkat operasi individual untuk operasi yang menggunakan metode HTTP POST. Anda tidak dapat menentukan x-google-model-router dan x-google-backend pada operasi yang sama, dan Anda juga tidak dapat menggabungkan operasi perutean model dan non-model di berbagai jalur dalam spesifikasi API yang sama.

Contoh:

x-google-api-management:
  backends:
    gemini-backend:
      address: https://aiplatform.googleapis.com/v1/...
  ai:
    models:
      routing:
        routers:
          my-router:
            defaultModel:
              backend: gemini-backend
              targetModel: google/gemini-3.5-flash-lite
paths:
  /v1/chat:
    post:
      x-google-model-router: my-router

`x-google-endpoint`

Opsional.

Ekstensi x-google-endpoint digunakan untuk mengonfigurasi properti server yang ditentukan dalam array servers 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

Jelajahi Spesifikasi OpenAPI.
Ubah gateway untuk menggunakan OpenAPI 3.0.

Ekstensi OpenAPI 3.x di Gateway API

x-google-api-management

Objek Metric

Objek Quota

Objek Quota Limit

Objek Backends

Objek AI

Objek Models

Objek Routing

Objek Router

Objek DefaultModel

Objek Rule

x-google-auth

Objek JwtLocations

x-google-quota

x-google-backend

x-google-model-router

x-google-endpoint

x-google-parameter

Memahami Batasan Ekstensi OpenAPI

Langkah berikutnya

`x-google-api-management`

Objek `Metric`

Objek `Quota`

Objek `Quota Limit`

Objek `Backends`

Objek `AI`

Objek `Models`

Objek `Routing`

Objek `Router`

Objek `DefaultModel`

Objek `Rule`

`x-google-auth`

Objek `JwtLocations`

`x-google-quota`

`x-google-backend`

`x-google-model-router`

`x-google-endpoint`

`x-google-parameter`