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 d'OpenAPI 3.x avec API Gateway.

Pour en savoir plus sur les versions de 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 accepte 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 n'est pas 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 répartis sur 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 avoir 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 de l'objet servers sont traitées comme un chemin de base, car aucun nom d'hôte n'est 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 commencent 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 50 fichiers pour les fichiers OpenAPI 3.x importés.

Limites de MCP

Pendant la version Preview 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 acceptés.
Streaming : le streaming d'é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 de requêtes par lot JSON-RPC sont rejetés.
Charges utiles multimodales : 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 compatibles : les méthodes spécialisées telles que resources/*, prompts/*, sampling/*, completion/*, ping et logging/* ne sont pas compatibles 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'outils.
Requête préliminaire CORS : la gestion automatisée des requêtes préliminaires CORS (requêtes OPTIONS) sur le chemin d'accès /mcp n'est pas gérée par la passerelle.
Exclusion mutuelle du routage vers les modèles : vous ne pouvez pas utiliser à la fois le MCP et le routage vers les modèles dans la même configuration d'API.
Réponses MCP non compatibles : les opérations qui renvoient des corps vides dans la réponse, comme les réponses HTTP 204, ne sont pas compatibles.
Découverte de schémas : les schémas d'objets imbriqués complexes dérivés de votre spécification OpenAPI peuvent ne pas s'afficher complètement ou correctement dans la réponse de découverte tools/list en raison d'une limite connue de traitement de la configuration.
Aucune notification de modification de la liste d'outils : la passerelle n'émet pas de notifications/tools/list_changed. Après avoir déployé une nouvelle configuration d'API, les clients doivent appeler à nouveau tools/list. Consultez Mettre à jour les outils MCP exposés.

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 avec des champs d'application définis dans un objet de schéma de sécurité, API Gateway ne vérifie pas ni n'applique ces champs d'application.

Exigences de sécurité multiples

Exigences concernant les clés API : API Gateway n'est pas compatible avec les exigences de sécurité alternatives (OU logique) si l'un des schémas est une clé API. Toutefois, API Gateway accepte les conjonctions (ET logique), ce qui vous permet d'exiger à la fois une clé API et un jeton OAuth2.
Exigences OAuth2 : API Gateway accepte d'autres exigences de sécurité (OU 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 le permet pas 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 d'accès entiers, par exemple /items/{itemId}. API Gateway n'accepte pas et rejette les paramètres correspondant à des segments partiels, par exemple /items/prefix_{id}_suffix.

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