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 des fonctionnalités pour 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 d'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 des hôtes et des 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 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 varier 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 compatibles

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 50 fichiers pour les fichiers OpenAPI 3.x importés.

Limites du MCP

Pendant la version bêta publique, 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 des outils 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.
Restrictions d'authentification : la méthode tools/list n'accepte que l'authentification JWT. L'authentification par clé API n'est pas acceptée pour cette méthode.
Aucune annotation d'outil : les indices tels que destructiveHint ou readOnlyHint ne sont pas émis dans les déclarations d'outil.
Vérification préliminaire CORS : la gestion automatisée de la vérification préliminaire CORS (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 compatibles : les opérations qui renvoient des corps vides dans la réponse, telles que les réponses HTTP 204, ne sont pas compatibles.
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 d'OpenAPI 2.0 qui s'appliquent également à OpenAPI 3.x.

Champs d'application ignorés

Bien qu'API Gateway accepte les documents OpenAPI dont les champs d'application sont définis dans un objet de schéma de sécurité, il ne les vérifie ni ne les applique.

Exigences de sécurité multiples

Exigences concernant les clés API : API Gateway n'est pas compatible avec les exigences de sécurité avec alternatives (opérateur logique "OU") 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 est compatible avec les exigences de sécurité avec alternatives (opérateur logique "OU") pour différents schémas de sécurité OAuth2. API Gateway n'est pas compatible avec les conjonctions (opérateur logique "ET") 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èles de chemin d'URL qui représentent des segments de chemin complets, 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 tableau), mais ne les applique pas. API Gateway transfère les requêtes entrantes à 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 situés 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 jusqu'à 200 nœuds d'alias YAML.