Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Limites des fonctionnalités OpenAPI 3.x

Ce document décrit les limites de fonctionnalités liées à l'utilisation d'OpenAPI 3.x avec API Gateway.

Pour en savoir plus sur les versions de la spécification OpenAPI compatibles, consultez Présentation d'OpenAPI.

Nouvelles limites OpenAPI 3.x

Cette section décrit les limites des nouvelles fonctionnalités d'OpenAPI 3.x.

Serveurs

OpenAPI 3.x est compatible avec plusieurs objets server pour définir les hôtes et les chemins de base. Toutefois, API Gateway s'appuie sur un seul objet serveur, identifié par l'extension x-google-endpoint, pour configurer le service.

Bien que vous puissiez définir plusieurs serveurs, API Gateway ne prend en compte que le serveur contenant l'extension x-google-endpoint et n'autorise qu'un seul serveur de ce type. Pour API Gateway, une URL de serveur n'est pas requise. Vous pouvez donc ne définir aucun serveur ou un seul serveur avec l'extension x-google-endpoint.

Par exemple, les définitions suivantes sont valides pour API Gateway :

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

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

La définition suivante est non valide, car elle contient plusieurs extensions x-google-endpoint :

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

La définition suivante est valide pour API Gateway, mais API Gateway ignore l'objet serveur :

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

Serveurs dans plusieurs fichiers

Si vous importez plusieurs fichiers OpenAPI et qu'un fichier contient un serveur avec l'extension x-google-endpoint, tous les fichiers doivent également contenir un serveur défini avec une extension x-google-endpoint identique et un hôte identique dans l'URL du serveur. Le chemin de base peut différer d'un fichier à l'autre.

URL relative

Pour API Gateway, les URL relatives dans l'objet servers sont traitées comme un chemin de base à part entière, car un nom d'hôte n'est pas requis dans la spécification. Cela diffère du comportement OpenAPI standard, qui résout les URL relatives par rapport au serveur hébergeant la définition OpenAPI. Par exemple, API Gateway traite url: /v1 comme un chemin de base.

Les chemins de base doivent commencer par "/". API Gateway rejette les URL qui n'ont pas de schéma ou qui ne commencent pas par "/" pour indiquer un chemin de base.

Extensions non prises en charge

API Gateway n'est pas compatible avec l'extension x-google-allow pour OpenAPI 3.x.

Taille maximale des fichiers

API Gateway applique une limite de taille totale de 10 Mo et une limite de nombre de fichiers de 50 pour les fichiers OpenAPI 3.x importés.

Limites du MCP

Pendant l'aperçu public, les limites suivantes s'appliquent à la compatibilité avec le protocole MCP (Model Context Protocol) :

Limite du nombre d'outils : les clients sont limités à un maximum de 1 000 outils MCP par passerelle.
Méthodes HTTP : seules les opérations GET, POST, PUT, PATCH et DELETE peuvent être exposées en tant qu'outils MCP. HEAD, OPTIONS et TRACE ne sont pas compatibles.
Streaming : le streaming des événements envoyés par le serveur (SSE) pour les appels d'outils de longue durée n'est pas pris en charge.
Requêtes par lot : les tableaux par lot JSON-RPC sont refusés.
Charge utile multimodale : les réponses de l'outil sont limitées au texte UTF-8. Les réponses binaires ne sont pas acceptées.
Absence d'état : l'implémentation est sans état. Les identifiants de session (comme MCP-Session-Id) ne sont pas utilisés ni conservés.
Méthodes MCP non disponibles : les méthodes spécialisées telles que resources/*, prompts/*, sampling/*, completion/*, ping et logging/* ne sont pas disponibles et renvoient un code d'erreur JSON-RPC -32601.
Aucune annotation d'outil : les indications telles que destructiveHint ou readOnlyHint ne sont pas émises dans les déclarations d'outil.
Requête CORS préliminaire : la gestion automatisée des requêtes CORS préliminaires (requêtes OPTIONS) sur le chemin d'accès /mcp n'est pas gérée par la passerelle.
Exclusion mutuelle du routage de modèle : vous ne pouvez pas utiliser à la fois MCP et le routage de modèle dans la même configuration d'API.
Réponses MCP non acceptées : les opérations qui renvoient des corps vides dans la réponse, telles que les réponses HTTP 204, ne sont pas acceptées.
Découverte de schémas : il est possible que les schémas d'objets imbriqués complexes dérivés de votre spécification OpenAPI ne s'affichent pas entièrement ou correctement dans la réponse de découverte tools/list en raison d'une limite de traitement de la configuration connue.

Limites préexistantes

Cette section décrit les limites héritées d'OpenAPI 2.0 qui s'appliquent également à OpenAPI 3.x.

Champs d'application ignorés

Bien qu'API Gateway accepte les documents OpenAPI avec des niveaux d'accès définis dans un objet de schéma de sécurité, API Gateway ne vérifie ni n'applique ces niveaux d'accès.

Exigences de sécurité multiples

Exigences concernant les clés API : API Gateway n'est pas compatible avec les exigences de sécurité alternatives (OR logique) si l'un des schémas est une clé API. Toutefois, API Gateway est compatible avec les conjonctions (ET logique), ce qui vous permet d'exiger à la fois une clé API et un jeton OAuth2.
Exigences OAuth2 : API Gateway accepte les exigences de sécurité alternatives (OR logique) pour différents schémas de sécurité OAuth2. API Gateway n'est pas compatible avec les conjonctions (ET logique), sauf si l'exigence de sécurité supplémentaire est une clé API.
Sécurité facultative : vous pouvez utiliser une exigence de sécurité vide (- {}) pour rendre la sécurité facultative pour une clé API, mais API Gateway ne prend pas en charge cette option pour OAuth.

Validation de la définition de sécurité

API Gateway rejettera une spécification OpenAPI 3.x qui utilise une exigence de sécurité sans définition correspondante dans la section securityDefinitions.

Modèles de chemins d'URL

API Gateway n'accepte que les paramètres de modèle de chemin d'URL qui représentent des segments de chemin entiers, par exemple /items/{itemId}. API Gateway n'accepte pas les paramètres correspondant à des segments partiels (par exemple, /items/prefix_{id}_suffix) et les rejette.

Paramètres, schémas, corps de requête et types

API Gateway accepte les documents OpenAPI avec différentes définitions de paramètres et de types (par exemple, les paramètres required et les formats de tableaux), mais ne les applique pas. API Gateway transfère les requêtes entrantes vers votre API, quelles que soient ces définitions.

API Gateway n'accepte que les types primitifs dans les paramètres de requête.

Références à des types externes

API Gateway n'est pas compatible avec les références à des types en dehors du document OpenAPI fourni. Par exemple, API Gateway n'autorise pas et rejette un $ref qui pointe vers une URL externe.

Port personnalisé dans l'adresse de l'hôte

API Gateway n'autorise pas les ports personnalisés dans le champ servers.url d'un document OpenAPI.

Limites des alias YAML

Un document OpenAPI envoyé à API Gateway peut comporter au maximum 200 nœuds d'alias YAML.