Restrictions et problèmes connus relatifs à l’importation d’API

  • Article

S’APPLIQUE À : Tous les niveaux de Gestion des API

Lors de l'importation d'une API, il se peut que vous rencontriez certaines restrictions ou que vous deviez identifier et rectifier des problèmes avant de pouvoir réussir l'importation. Cet article porte sur les points suivants :

  • Comportement de Gestion des API pendant l’importation OpenAPI.
  • Limitations de l’importation OpenAPI et fonctionnement de l’exportation OpenAPI.
  • Exigences et limitations de l’importation WSDL et WADL.

Gestion des API lors de l’importation OpenAPI

Lors de l’importation OpenAPI, Gestion des API :

  • Vérifie spécifiquement les paramètres de chaîne de requête marqués comme obligatoires.
  • Par défaut, convertit les paramètres de chaîne de requête requis en paramètres de modèle requis.

Si vous préférez que les paramètres de requête requis dans la spécification soient traduits en paramètres de requête dans Gestion des API, désactivez le paramètre Inclure les paramètres de requête dans les modèles d’opération lors de la création de l’API dans le portail. Pour ce faire, utilisez les API - Créer ou mettre à jour l’API REST pour définir la propriété de l’API translateRequiredQueryParameters sur query.

Pour les opérations GET, HEAD et OPTIONS, API Management ignore un paramètre de corps de requête s’il est défini dans la spécification OpenAPI.

Limitations relatives à l’importation OpenAPI/Swagger

Si vous recevez des erreurs lors de l’importation de votre document OpenAPI, vérifiez que vous l’avez validée à l’aide de l’une des opérations suivantes :

  • À l’aide du concepteur du portail Azure (Conception > Front-end > Éditeur de spécification OpenAPI) ou
  • Avec un outil tiers, tel que Swagger Editor.

Généralités

Spécifications de modèle URL

Condition requise Description
Noms uniques pour le chemin d’accès et les paramètres de requête requis Dans OpenAPI :
  • Un nom de paramètre doit être unique seulement dans un emplacement, par exemple, pour un chemin, une requête, un en-tête.
Dans Gestion des API :
  • Nous permettons aux opérations d'être différenciées à la fois par le chemin d'accès et les paramètres de la requête.
  • Étant donné qu’OpenAPI ne prend pas en charge cette différenciation, les noms de paramètres doivent être uniques dans l’ensemble du modèle d’URL.
Paramètre d’URL défini Doit faire partie du modèle d’URL.
URL du fichier source disponible Appliquée aux URL de serveur relatives.
\$ref pointeurs Ne peuvent pas référencer des fichiers externes.

Spécifications OpenAPI

Versions prises en charge

Gestion des API prend en charge uniquement les éléments suivants :

  • OpenAPI version 2.
  • OpenAPI version 3.0.x (jusqu’à la version 3.0.3).
  • OpenAPI version 3.1 (importation uniquement)

Limitations de taille

Taille maximale Description
Jusqu’à 4 Mo Lorsqu’une spécification OpenAPI est importée en ligne dans Gestion des API.
Taille des requêtes d’API Azure Resource Manager Quand un document OpenAPI est fourni via l’URL d’un emplacement accessible à partir de votre service Gestion des API. Consultez Limites des abonnements Azure.

Extensions prises en charge

Les seules extensions prises en charge sont :

Extension Description
x-ms-paths
  • Vous permet de définir des chemins qui se différencient par des paramètres de requête dans l’URL.
  • Sujets abordés dans les documents AutoRest.
x-servers Un rétroportage de l’objet OpenAPI 3 servers pour OpenAPI 2.

Extensions non prises en charge

Extension Description
Recursion Gestion des API ne prend pas en charge les définitions définies de manière récursive.
Par exemple, les schémas qui font référence à eux-mêmes.
Server objet Non pris en charge au niveau des opérations de l’API.
Produces mot clé Décrit les types MIME retournés par une API.
Non pris en charge.

Extensions personnalisées

  • Ignorées lors de l’importation.
  • Non enregistrées ou conservées pour l’exportation.

Définitions non prises en charge

Les définitions de schéma Inline pour les opérations d’API ne sont pas prises en charge. Définitions de schéma :

  • Définies dans l’étendue de l’API.
  • Peuvent être référencées dans les étendues de requête ou de réponse des opérations de l’API.

Définitions ignorées

Les définitions de sécurité sont ignorées.

Restrictions de définition

Lors de l’importation de paramètres de requête, seule la méthode de sérialisation de tableau par défaut (style: form, explode: true) est prise en charge. Pour plus d’informations sur les paramètres de requête dans les spécifications OpenAPI, reportez-vous à la spécification de sérialisation.

Les paramètres définis dans les cookies ne sont pas pris en charge. Vous pouvez toujours utiliser la stratégie pour décoder et valider le contenu des cookies.

OpenAPI version 2

La prise en charge d’OpenAPI version 2 est limitée au format JSON uniquement.

Les paramètres de type Form ne sont pas pris en charge. Vous pouvez utiliser la stratégie pour décoder et valider et valider les charges utiles application/x-www-form-urlencoded et application/form-data.

OpenAPI version 3.x

Gestion des API prend en charge les versions de spécification suivantes :

URL HTTPS

  • Si plusieurs servers sont spécifiés, Gestion des API utilise la première URL HTTPS trouvée.
  • S’il n’y a pas d’URL HTTPS, l’URL du serveur est vide.

Prise en charge

  • example

Non pris en charge

Les champs suivants sont inclus dans OpenAPI version 3.0.x ou OpenAPI version 3.1.x, mais ne sont pas pris en charge :

Object Champ
OpenAPI externalDocs
Info summary
Composants
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
opération
  • externalDocs
  • callbacks
  • security
  • servers
Paramètre
  • allowEmptyValue
  • style
  • explode
  • allowReserved

Mécanismes d’importation, de mise à jour et d’exportation OpenAPI

Général

Les définitions d’API exportées à partir d’un service Gestion des API sont :

  • Principalement destinées aux applications externes qui doivent appeler l'API hébergée dans le service Gestion des API.
  • Non destinées à être importées dans le même service Gestion des API ou dans un service différent.

Pour la gestion de la configuration des définitions d’API dans différents services/environnements, consultez la documentation relative à l’utilisation du service Gestion des API avec Git.

Ajouter une nouvelle API via l’importation OpenAPI

Pour chaque opération trouvée dans le document OpenAPI, une nouvelle opération est créée avec :

  • Nom de la ressource Azure définie sur operationId.

    • La valeur operationId est normalisée.
    • Si operationId n’est pas spécifié (non présent, null ou vide), la valeur du nom de la ressource Azure est générée en combinant la méthode HTTP et le modèle de chemin.
      • Par exemple : get-foo.

  • Nom complet défini sur summary.

    • valeur summary :
      • Importée telle quelle.
      • La longueur est limitée à 300 caractères.
    • Si summary n’est pas spécifié (non présent, null ou vide), la valeur du nom complet est définie sur operationId.

Règles de normalisation pour operationId

  • Convertit les caractères en minuscules.
  • Remplacez chaque séquence de caractères non alphanumériques par un tiret unique.
    • Par exemple, GET-/foo/{bar}?buzz={quix} est transformé en get-foo-bar-buzz-quix-.
  • Coupez les tirets des deux côtés.
    • Par exemple, get-foo-bar-buzz-quix- devient get-foo-bar-buzz-quix.
  • Tronquez pour obtenir 76 caractères, quatre caractères de moins que la limite maximale pour un nom de ressource.
  • Utilisez les quatre caractères restants pour un suffixe de déduplication, si nécessaire, sous la forme -1, -2, ..., -999.

Mettre à jour une API existante via l’importation OpenAPI

Lors de l’importation, l’opération d’API existante :

  • Change pour correspondre à l’API décrite dans le document OpenAPI.
  • Effectue une correspondance sur une opération dans le document OpenAPI en comparant sa valeur operationId au nom de ressource Azure de l’opération existante.
    • Si une correspondance est trouvée, les propriétés de l’opération existante sont mises à jour « sur place ».
    • Si aucune correspondance n’est trouvée :
      • Une nouvelle opération est créée en combinant la méthode HTTP et le modèle de chemin, par exemple get-foo.
      • Pour chaque nouvelle opération, l’importation tente de copier les stratégies à partir d’une opération existante avec la même méthode HTTP et le même modèle de chemin d’accès.

Toutes les opérations sans correspondance existantes sont supprimées.

Pour que l’importation soit plus prévisible, suivez les instructions ci-dessous :

  • Spécifiez la propriété operationId pour chaque opération.
  • Évitez de modifier operationId après l’importation initiale.
  • Ne modifiez jamais operationId et la méthode HTTP ou le modèle de chemin d’accès en même temps.

Règles de normalisation pour operationId

  • Convertit les caractères en minuscules.
  • Remplacez chaque séquence de caractères non alphanumériques par un tiret unique.
    • Par exemple, GET-/foo/{bar}?buzz={quix} est transformé en get-foo-bar-buzz-quix-.
  • Coupez les tirets des deux côtés.
    • Par exemple, get-foo-bar-buzz-quix- devient get-foo-bar-buzz-quix.
  • Tronquez pour obtenir 76 caractères, quatre caractères de moins que la limite maximale pour un nom de ressource.
  • Utilisez les quatre caractères restants pour un suffixe de déduplication, si nécessaire, sous la forme -1, -2, ..., -999.

Exporter l’API comme OpenAPI

Pour chaque opération :

  • Le nom de la ressource Azure est exporté en tant que operationId.
  • Le nom d’affichage est exporté en tant que summary.

Notez que la normalisation de l’opération operationId est effectuée sur l’importation, et non sur l’exportation.

WSDL

Vous pouvez créer des API SOAP direct et SOAP à REST avec des fichiers WSDL.

Liaisons SOAP

  • Seules les liaisons SOAP de style d’encodage « document » et « literal » sont prises en charge.
  • Les encodages SOAP ou de style « rpc » ne sont pas pris en charge.

Importations et inclut

  • Les directives wsdl:import, xsd:import et xsd:include ne sont pas prises en charge. Au lieu de cela, fusionnez les dépendances au sein d’un même document.

  • Pour obtenir un outil open source permettant de résoudre et de fusionner les dépendances wsdl:import, xsd:import et xsd:include dans un fichier WSDL, consultez ce dépôt GitHub.

Spécifications WS-*

Les fichiers WSDL incorporant des spécifications WS-* ne sont pas pris en charge.

Messages avec plusieurs parties

Ce type de message n’est pas pris en charge.

WCF wsHttpBinding

  • Les services SOAP créés avec Windows Communication Foundation doivent utiliser basicHttpBinding.
  • wsHttpBinding n’est pas pris en charge.

MTOM

  • Les services utilisant MTOMpeuvent fonctionner.
  • Aucune prise en charge officielle n’est disponible pour l’instant.

Récursivité

  • Les types définis de manière récursive ne sont pas pris en charge par Gestion des API.
  • Par exemple, s’ils font référence à un tableau d’eux-mêmes.

Espaces de noms multiples

Si plusieurs espaces de noms peuvent être utilisés dans un schéma, seul l’espace de noms cible peut être utilisé pour définir des parties de message. Ces espaces de noms sont utilisés pour définir d’autres éléments d’entrée ou de sortie.

Les espaces de noms autres que la cible ne sont pas conservés lors de l’exportation. Bien que vous puissiez importer un document WSDL qui définit des parties de message avec d’autres espaces de noms, toutes les parties de message disposent de l’espace de noms cible WSDL lors de l’exportation.

Points de terminaison multiples

Des fichiers WSDL peuvent définir plusieurs services et points de terminaison (ports) par un ou plusieurs éléments wsdl:service et wsdl:port. Toutefois, la passerelle Gestion des API peut importer et proxyser des requêtes vers un unique service et point de terminaison. Si plusieurs services ou points de terminaison sont définis dans le fichier WSDL, identifiez le nom et le point de terminaison du service cible lors de l’importation de l’API au moyen de la propriété wsdlSelector.

Conseil

Si vous souhaitez équilibrer la charge des requêtes entre plusieurs services et points de terminaison, envisagez de configurer un pool backend à charge équilibrée.

Tableaux

La transformation SOAP à REST prend uniquement en charge les tableaux encapsulés indiqués dans l’exemple ci-dessous :

    <complexType name="arrayTypeName">
        <sequence>
            <element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <complexType name="typeName">
        <sequence>
            <element name="element1" type="someTypeName" minOccurs="1" maxOccurs="1"/>
            <element name="element2" type="someOtherTypeName" minOccurs="0" maxOccurs="1" nillable="true"/>
            <element name="arrayElement" type="arrayTypeName" minOccurs="1" maxOccurs="1"/>
        </sequence>
    </complexType>

WADL

Il n’existe aucun problème connu relatif à l’importation WADL.