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

Batasan fitur OpenAPI 3.x

Dokumen ini menjelaskan batasan fitur untuk menggunakan OpenAPI 3.x dengan Gateway API.

Untuk mengetahui informasi selengkapnya tentang versi spesifikasi OpenAPI yang didukung, lihat Ringkasan OpenAPI.

Batasan OpenAPI 3.x baru

Bagian ini menjelaskan batasan untuk fitur baru di OpenAPI 3.x.

Server

OpenAPI 3.x mendukung beberapa objek server untuk menentukan host dan jalur dasar. Namun, Gateway API mengandalkan satu objek server, yang diidentifikasi oleh ekstensi x-google-endpoint, untuk mengonfigurasi layanan.

Meskipun Anda dapat menentukan beberapa server, Gateway API hanya mempertimbangkan server yang berisi ekstensi x-google-endpoint, dan hanya mengizinkan satu server tersebut. Untuk Gateway API, URL server tidak diperlukan, jadi Anda dapat tidak menentukan server atau menentukan satu server dengan ekstensi x-google-endpoint.

Misalnya, definisi berikut valid untuk Gateway API:

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

Definisi berikut tidak valid karena berisi beberapa ekstensi x-google-endpoint:

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

Definisi berikut valid untuk Gateway API, tetapi Gateway API mengabaikan objek server:

servers:
  - url: https://example.com

Server di beberapa file

Jika Anda mengupload beberapa file OpenAPI dan salah satu file berisi server dengan ekstensi x-google-endpoint, maka semua file juga harus memiliki server yang ditentukan dengan ekstensi x-google-endpoint yang identik dan host yang identik di URL server. Basepath dapat berbeda di antara file.

URL relatif

Untuk Gateway API, URL relatif dalam objek servers diperlakukan sebagai basepath dengan sendirinya karena nama host tidak diperlukan dalam spesifikasi. Hal ini berbeda dengan perilaku OpenAPI standar, yang menyelesaikan URL relatif terhadap server yang menghosting definisi OpenAPI. Misalnya, Gateway API memperlakukan url: /v1 sebagai basepath.

Basepath harus dimulai dengan '/'. Gateway API menolak URL yang tidak memiliki skema atau dimulai dengan '/' untuk menunjukkan basepath.

Ekstensi yang tidak didukung

Gateway API tidak mendukung ekstensi x-google-allow untuk OpenAPI 3.x.

Batas ukuran file

Gateway API menerapkan batas ukuran total 10 MB dan batas jumlah file 50 untuk file OpenAPI 3.x yang diupload.

Batasan MCP

Selama Pratinjau Publik, batasan berikut berlaku untuk dukungan Model Context Protocol (MCP):

Batas jumlah alat: Pelanggan dibatasi hingga maksimum 1.000 alat MCP per Gateway.
Metode HTTP: Hanya operasi GET, POST, PUT, PATCH, dan DELETE yang dapat diekspos sebagai alat MCP. HEAD, OPTIONS, dan TRACE tidak didukung.
Streaming: Streaming Peristiwa yang Dikirim Server (SSE) untuk panggilan alat yang berjalan lama tidak didukung.
Permintaan batch: Array batch JSON-RPC ditolak.
Payload multi-modal: Respons alat terbatas pada teks UTF-8. Respons biner tidak didukung.
Statelessness: Implementasinya stateless; ID sesi (seperti MCP-Session-Id) tidak digunakan atau dipertahankan.
Metode MCP yang tidak didukung: Metode khusus seperti resources/*, prompts/*, sampling/*, completion/*, ping, dan logging/* tidak didukung dan menampilkan kode error JSON-RPC -32601.
Batasan autentikasi: Metode tools/list hanya mendukung autentikasi JWT. Autentikasi kunci API tidak didukung untuk metode ini.
Tidak ada anotasi alat: Petunjuk seperti destructiveHint atau readOnlyHint tidak dikeluarkan dalam deklarasi alat.
Preflight CORS: Penanganan preflight CORS otomatis (permintaan OPTIONS) di jalur /mcp tidak dikelola oleh gateway.
Pengecualian Bersama Perutean Model: Anda tidak dapat menggunakan MCP dan Perutean Model dalam konfigurasi API yang sama.
Respons MCP yang tidak didukung: Operasi yang menampilkan isi kosong dalam respons, seperti respons HTTP 204, tidak didukung.
Penemuan Skema: Skema objek bertingkat kompleks yang berasal dari spesifikasi OpenAPI Anda mungkin tidak dirender sepenuhnya atau dengan benar dalam respons penemuan tools/list karena batasan pemrosesan konfigurasi yang diketahui.

Batasan yang sudah ada

Bagian ini menjelaskan batasan yang diwariskan dari OpenAPI 2.0 yang juga berlaku untuk OpenAPI 3.x.

Cakupan diabaikan

Meskipun Gateway API menerima dokumen OpenAPI dengan cakupan yang ditentukan dalam objek skema keamanan, Gateway API tidak memeriksa atau menerapkan cakupan ini.

Beberapa persyaratan keamanan

Persyaratan Kunci API: Gateway API tidak mendukung persyaratan keamanan alternatif (OR logis) jika salah satu skemanya adalah kunci API. Namun, Gateway API mendukung konjungsi (AND logis), yang memungkinkan Anda mewajibkan kunci API dan token OAuth2.
Persyaratan OAuth2: Gateway API mendukung persyaratan keamanan alternatif (OR logis) untuk berbagai skema keamanan OAuth2. Gateway API tidak mendukung konjungsi (AND logis) kecuali jika persyaratan keamanan tambahan adalah kunci API.
Keamanan Opsional: Anda dapat menggunakan persyaratan keamanan kosong (- {}) untuk membuat keamanan bersifat opsional untuk kunci API, tetapi Gateway API tidak mendukung hal ini untuk OAuth.

Validasi definisi keamanan

API Gateway akan menolak spesifikasi OpenAPI 3.x yang menggunakan persyaratan keamanan tanpa definisi yang sesuai di bagian securityDefinitions.

Pembuatan template jalur URL

Gateway API hanya mendukung parameter template jalur URL yang merepresentasikan seluruh segmen jalur, misalnya, /items/{itemId}. Gateway API tidak mendukung dan menolak parameter yang sesuai dengan segmen parsial, misalnya, /items/prefix_{id}_suffix.

Parameter, skema, isi permintaan, dan jenis

API Gateway menerima dokumen OpenAPI dengan berbagai definisi parameter dan jenis (misalnya, parameter required dan format array), tetapi tidak menerapkannya. Gateway API meneruskan permintaan masuk ke API Anda, terlepas dari definisi ini.

Gateway API hanya mendukung jenis primitif dalam parameter permintaan.

Referensi jenis eksternal

Gateway API tidak mendukung referensi ke jenis di luar dokumen OpenAPI yang disediakan. Misalnya, Gateway API tidak mengizinkan dan menolak $ref yang mengarah ke URL eksternal.

Port kustom di alamat host

Gateway API tidak mengizinkan port kustom di kolom servers.url dokumen OpenAPI.

Batasan alias YAML

Dokumen OpenAPI yang dikirimkan ke API Gateway dapat memiliki maksimum 200 node alias YAML.