Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Développez REST APIs à l'aide d'OpenAPI dans API Gateway Vous pouvez utiliser API Gateway pour importer une API REST à partir d’un fichier de définition externe dans API Gateway. Actuellement, API Gateway prend en charge les fichiers de définition [OpenAPI v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) et [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) avec les exceptions répertoriées dans [Remarques importantes relatives à Amazon API Gateway pour REST APIs](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis). Vous pouvez mettre à jour une API en la remplaçant par une nouvelle définition, ou vous pouvez fusionner une définition avec une API existante. Vous précisez les options grâce à un paramètre de requête `mode` dans l’URL de demande. Pour consulter un didacticiel sur l’utilisation de la fonction d’importation d’API à partir de la console API Gateway, consultez [Didacticiel : création d’une API REST par l’importation d’un exemple](api-gateway-create-api-from-example.md). **Topics** + [Importation d’une API optimisée pour la périphérie dans API Gateway](import-edge-optimized-api.md) + [Importation d’une API régionale dans API Gateway](import-export-api-endpoints.md) + [Importation d’un fichier OpenAPI pour mettre à jour une définition d’API existante](api-gateway-import-api-update.md) + [Définition de la propriété `basePath` OpenAPI](api-gateway-import-api-basePath.md) + [AWS variables pour l'importation d'OpenAPI](import-api-aws-variables.md) + [Erreurs et avertissements liés à l’importation de votre API dans API Gateway](api-gateway-import-api-errors-warnings.md) + [Exportation d’une API REST à partir d’API Gateway](api-gateway-export-api.md) # Importation d’une API optimisée pour la périphérie dans API Gateway Vous pouvez importer un fichier de définition d’API OpenAPI pour créer une API optimisée pour la périphérie en spécifiant le type de point de terminaison `EDGE` sous la forme d’une entrée supplémentaire, en plus du fichier OpenAPI, dans l’opération d’importation. Vous pouvez le faire à l'aide de la console API Gateway ou d'un AWS SDK. AWS CLI Pour consulter un didacticiel sur l’utilisation de la fonction d’importation d’API à partir de la console API Gateway, consultez [Didacticiel : création d’une API REST par l’importation d’un exemple](api-gateway-create-api-from-example.md). **Topics** + [Importation d’une API optimisée pour la périphérie à l’aide de la console API Gateway](#import-edge-optimized-api-with-console) + [Importez une API optimisée pour les périphériques à l'aide du AWS CLI](#import-edge-optimized-api-with-awscli) ## Importation d’une API optimisée pour la périphérie à l’aide de la console API Gateway Pour importer une API optimisée pour la périphérie à l’aide de la console API Gateway, procédez comme suit : 1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Sélectionnez **Create API (Créer une API)**. 1. Sous **API REST**, choisissez **Importer**. 1. Copiez une définition OpenAPI d’API et collez-la dans l’éditeur de code ou choisissez **Choisir un fichier** pour charger un fichier OpenAPI à partir d’un lecteur local. 1. Pour **Type de point de terminaison d’API**, sélectionnez **Optimisé pour la périphérie**. 1. Choisissez **Créer une API** pour importer les définitions OpenAPI. ## Importez une API optimisée pour les périphériques à l'aide du AWS CLI La [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)commande suivante importe une API depuis un fichier de définition OpenAPI pour créer une nouvelle API optimisée pour les périphériques : ``` aws apigateway import-rest-api \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` ou en spécifiant explicitement le paramètre de chaîne de requête `endpointConfigurationTypes` à `EDGE` : ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=EDGE \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importation d’une API régionale dans API Gateway Lors de l’importation d’une API, vous pouvez choisir la configuration de points de terminaison régionaux pour l’API. Vous pouvez utiliser la console API Gateway AWS CLI, le ou un AWS SDK. Lorsque vous exportez une API, sa configuration de point de terminaison ne figure pas dans les définitions d’API exportées. Pour consulter un didacticiel sur l’utilisation de la fonction d’importation d’API à partir de la console API Gateway, consultez [Didacticiel : création d’une API REST par l’importation d’un exemple](api-gateway-create-api-from-example.md). **Topics** + [Importation d’une API régionale à l’aide de la console API Gateway](#import-regional-api-with-console) + [Importez une API régionale à l'aide du AWS CLI](#import-regional-api-with-awscli) ## Importation d’une API régionale à l’aide de la console API Gateway Pour importer une API d’un point de terminaison régional à l’aide de la console API Gateway, procédez comme suit : 1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Sélectionnez **Create API (Créer une API)**. 1. Sous **API REST**, choisissez **Importer**. 1. Copiez une définition OpenAPI d’API et collez-la dans l’éditeur de code ou choisissez **Choisir un fichier** pour charger un fichier OpenAPI à partir d’un lecteur local. 1. Pour **Type de point de terminaison d’API**, sélectionnez **Régional**. 1. Choisissez **Créer une API** pour importer les définitions OpenAPI. ## Importez une API régionale à l'aide du AWS CLI La [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)commande suivante importe un fichier de définition OpenAPI et définit le type de point de terminaison sur Regional : ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=REGIONAL \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importation d’un fichier OpenAPI pour mettre à jour une définition d’API existante Vous pouvez importer des définitions d’API uniquement pour mettre à jour une API existante, sans modifier la configuration de son point de terminaison, ainsi que ses étapes et variables d’étapes ou ses références à des clés d’API. L' import-to-updateopération peut se produire selon deux modes : fusion ou remplacement. Lorsqu'une API (`A`) est fusionnée avec une autre (`B`), l'API résultante conserve les définitions des deux `A` et `B` si les deux APIs ne partagent aucune définition contradictoire. Lorsque des conflits surviennent, les définitions de méthode de l’API fusionnante (`A`) remplacent les définitions de méthode correspondantes de l’API fusionnée (`B`). Par exemple, supposons que `B` déclare les méthodes suivantes pour renvoyer les réponses `200` et `206` : ``` GET /a POST /a ``` et `A` déclare la méthode suivante pour renvoyer les réponses `200` et `400` : ``` GET /a ``` Lorsque `A` est fusionnée avec `B`, l’API résultante génère les méthodes suivantes : ``` GET /a ``` qui retourne les réponses `200` et `400`, et ``` POST /a ``` qui retourne les réponses `200` et `206`. La fusion d’une API s’avère utile lorsque vous avez décomposé vos définitions d’API externes en plusieurs parties plus petites et souhaitez seulement appliquer les modifications à partir d’une de ces parties à la fois. Cela peut être le cas, par exemple, si plusieurs équipes sont responsables de différentes parties d’une API et que leurs modifications deviennent disponibles à des rythmes différents. Dans ce mode, les éléments de l’API existante qui ne sont pas spécifiquement définis dans la définition importée seront conservés. Lorsqu’une API (`A`) remplace une autre (`B`), l’API résultante prend les définitions de l’API remplaçante (`A`). Le remplacement d’une API est utile lorsqu’une définition d’API externe contient la définition complète d’une API. Dans ce mode, les éléments d’une API existante qui ne sont pas spécifiquement définis dans la définition importée sont supprimés. Pour fusionner une API, envoyez une requête `PUT` à `https://apigateway..amazonaws.com/restapis/?mode=merge`. La valeur du paramètre de chemin `restapi_id` spécifie l’API avec laquelle la définition d’API fournie va être fusionnée. L’extrait de code suivant présente un exemple de requête `PUT` pour fusionner une définition d’API OpenAPI dans JSON en tant que charge utile, avec l’API spécifiée déjà présente dans API Gateway. ``` PUT /restapis/?mode=merge Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` L’opération de mise à jour par fusion prend deux définitions d’API complètes et les fusionne ensemble. Pour une petite modification incrémentielle, vous pouvez utiliser l’opération de [mise à jour des ressources](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). Pour remplacer une API, envoyez une requête `PUT` à `https://apigateway..amazonaws.com/restapis/?mode=overwrite`. Le paramètre de chemin `restapi_id` spécifie l’API qui sera remplacée par les définitions d’API fournies. L’extrait de code suivant présente un exemple de requête de remplacement avec la charge utile d’une définition OpenAPI au format JSON : ``` PUT /restapis/?mode=overwrite Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` Lorsque le paramètre `mode` de la requête n’est pas spécifié, le mode de fusion est sélectionné par défaut. **Note** Les opérations `PUT` sont idempotentes, mais pas atomiques. Cela signifie que si une erreur système se produit au cours du traitement, l’état final de l’API peut être incorrect. Cependant, la réussite de la répétition de l’opération fera passer l’API au même état final que si la première opération avait réussi. # Définition de la propriété `basePath` OpenAPI Dans [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md), vous pouvez utiliser la propriété `basePath` pour fournir une ou plusieurs parties de chemin précédant chaque chemin défini dans la propriété `paths`. API Gateway peut exprimer le chemin d’une ressource de plusieurs façons. Par conséquent, la fonction d’importation d’API propose les options ci-après pour interpréter la propriété `basePath` au cours d’une importation : ignorer, préfixer et fractionner. Dans [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/), `basePath` n’est plus une propriété de niveau supérieur. Au lieu de cela, API Gateway utilise une [variable serveur](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject) en tant que convention. La fonction d’importation d’une API fournit les mêmes options pour interpréter le chemin de base lors de l’importation. Le chemin de base est identifié comme suit : + Si l’API ne contient pas de variables `basePath`, la fonction d’importation d’API vérifie la chaîne `server.url` pour voir si elle contient un chemin au-delà de `"/"`. Si c’est le cas, ce chemin est utilisé comme chemin de base. + Si l’API contient une seule variable `basePath`, la fonction d’importation d’API l’utilise comme chemin de base, même si elle n’est pas référencée dans la chaîne `server.url`. + Si l’API contient plusieurs variables `basePath`, la fonction d’importation d’API utilise uniquement la première comme chemin de base. ## Ignorer Si le fichier OpenAPI comporte une valeur `basePath` `/a/b/c` et si la propriété `paths` contient `/e` et `/f`, la demande `POST` ou `PUT` suivante : ``` POST /restapis?mode=import&basepath=ignore ``` ``` PUT /restapis/api_id?basepath=ignore ``` génère les ressources suivantes dans l'API : + `/` + `/e` + `/f` Cela revient à traiter la propriété `basePath` comme si elle n’était pas présente, et toutes les ressources API déclarées sont traitées par rapport à l’hôte. Vous pouvez utiliser cette option, par exemple, lorsque vous avez un nom de domaine personnalisé avec un mappage d’API qui n’inclut pas de propriété *Base Path* et de valeur *Stage* faisant référence à votre étape de production. **Note** API Gateway crée automatiquement une ressource racine, même si elle n’est pas explicitement déclarée dans votre fichier de définition. Lorsqu’elle n’est pas spécifiée, la propriété `basePath` prend la valeur `ignore` par défaut. ## Prepend Si le fichier OpenAPI comporte une valeur `basePath` `/a/b/c` et si la propriété `paths` contient `/e` et `/f`, la demande `POST` ou `PUT` suivante : ``` POST /restapis?mode=import&basepath=prepend ``` ``` PUT /restapis/api_id?basepath=prepend ``` génère les ressources suivantes dans l'API : + `/` + `/a` + `/a/b` + `/a/b/c` + `/a/b/c/e` + `/a/b/c/f` Cela revient à traiter la propriété `basePath` comme des ressources supplémentaires de spécification (sans méthode) et à ajouter celles-ci à l’ensemble de ressources déclarées. Vous pouvez utiliser cette option, par exemple, lorsque différentes équipes sont responsables des différentes parties d’une API et que la propriété `basePath` peut faire référence à l’emplacement du chemin de la partie d’API de chaque équipe. **Note** API Gateway crée automatiquement les ressources intermédiaires, même si elles ne sont pas explicitement déclarées dans votre définition. ## Split Si le fichier OpenAPI comporte une valeur `basePath` `/a/b/c` et si la propriété `paths` contient `/e` et `/f`, la demande `POST` ou `PUT` suivante : ``` POST /restapis?mode=import&basepath=split ``` ``` PUT /restapis/api_id?basepath=split ``` génère les ressources suivantes dans l'API : + `/` + `/b` + `/b/c` + `/b/c/e` + `/b/c/f` Cela revient à traiter la partie supérieure du chemin, `/a`, comme le début du chemin de chaque ressource et à créer des ressources supplémentaires (sans méthode) au sein de l’API proprement dite. Vous pouvez utiliser cette option, par exemple, lorsque `a` est un nom d’étape que vous souhaitez exposer dans votre API. # AWS variables pour l'importation d'OpenAPI Vous pouvez utiliser les AWS variables suivantes dans les définitions d'OpenAPI. API Gateway résout les variables lorsque l’API est importée. Pour spécifier une variable, utilisez `${variable-name}`. Le tableau suivant décrit les AWS variables disponibles. | Nom de la variable | Description | | --- | --- | | AWS::AccountId | L'ID du AWS compte qui importe l'API. Par exemple, 123456789012. | | AWS::Partition | AWS Partition dans laquelle l'API est importée. Pour les AWS régions standard, la partition estaws. | | AWS::Region | AWS Région dans laquelle l'API est importée. Par exemple, us-east-2. | ## AWS exemple de variables L'exemple suivant utilise des AWS variables pour spécifier une AWS Lambda fonction pour une intégration. ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "tasks-api" version: "v1.0" paths: /: get: summary: List tasks description: Returns a list of tasks responses: 200: description: "OK" content: application/json: schema: type: array items: $ref: "#/components/schemas/Task" 500: description: "Internal Server Error" content: {} x-amazon-apigateway-integration: uri: arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations responses: default: statusCode: "200" passthroughBehavior: "when_no_match" httpMethod: "POST" contentHandling: "CONVERT_TO_TEXT" type: "aws_proxy" components: schemas: Task: type: object properties: id: type: integer name: type: string description: type: string ``` ------ # Erreurs et avertissements liés à l’importation de votre API dans API Gateway Lorsque vous importez votre fichier de définition externe dans API Gateway, des avertissements et des erreurs peuvent être générés. Les sections suivantes décrivent les erreurs et les avertissements susceptibles de se produire lors de l’importation. ## Erreurs lors de l’importation Lors de l’importation, des erreurs peuvent être générées pour les principaux problèmes, comme un document OpenAPI non valide. Les erreurs sont renvoyées en tant qu’exceptions (par exemple, `BadRequestException`) dans une réponse infructueuse. Lorsqu’une erreur se produit, la nouvelle définition d’API est ignorée et aucune modification n’est apportée à l’API existante. ## Avertissements lors de l’importation Lors de l’importation, des avertissements peuvent être générés pour les problèmes mineurs, tels que l’absence d’une référence de modèle. En cas d’avertissement, l’opération continue si l’expression de requête `failonwarnings=false` est ajoutée à l’URL de la demande. Sinon, les mises à jour sont annulées. Par défaut, la propriété `failonwarnings` a la valeur `false`. Dans ce cas, les avertissements sont renvoyés sous forme de champ dans la [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)ressource résultante. Sinon, les avertissements sont renvoyés sous la forme d’un message dans l’exception. # Exportation d’une API REST à partir d’API Gateway Une fois que vous avez créé et configuré une API REST dans API Gateway à l’aide de la console API Gateway ou par tout autre moyen, vous pouvez l’exporter dans un fichier OpenAPI à l’aide de la fonction d’exportation d’API API Gateway, qui fait partie du service de contrôle Amazon API Gateway. Pour utiliser l’API d’exportation d’API Gateway, vous devez signer vos demandes d’API. Pour plus d'informations sur les demandes de signature, consultez [la section Signing AWS API](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) du *Guide de l'utilisateur IAM*. Des options vous permettent d’inclure les extensions d’intégration API Gateway, ainsi que les extensions [Postman](https://www.postman.com) dans le fichier de définition OpenAPI exporté. **Note** Lorsque vous exportez l'API à l'aide de AWS CLI, veillez à inclure le paramètre extensions comme indiqué dans l'exemple suivant, afin de garantir que l'`x-amazon-apigateway-request-validator`extension est incluse : ``` aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json ``` Vous ne pouvez pas exporter une API si ses charges utiles ne sont pas de type `application/json`. Si vous essayez, vous obtenez un message d’erreur indiquant que les modèles de corps JSON sont introuvables. ## Demande d’exportation d’une API REST Avec l'API d'exportation, vous exportez une API REST existante en soumettant une requête GET, en spécifiant l' to-be-exportedAPI dans le cadre des chemins d'URL. L’URL de la requête est au format suivant : ------ #### [ OpenAPI 3.0 ] ``` https:///restapis//stages//exports/oas30 ``` ------ #### [ OpenAPI 2.0 ] ``` https:///restapis//stages//exports/swagger ``` ------ Vous pouvez ajouter la chaîne de requête `extensions` pour spécifier si vous souhaitez inclure les extensions API Gateway (avec la valeur `integration`) ou les extensions Postman (avec la valeur `postman`). En outre, vous pouvez affecter à l’en-tête `Accept` la valeur `application/json` ou `application/yaml` pour recevoir la définition d’API au format JSON ou YAML, respectivement. Pour plus d'informations sur la soumission de requêtes GET à l'aide de l'API API Gateway Export, consultez [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html). **Note** Si vous définissez des modèles dans votre API, ils doivent être définis pour le type de contenu « application/json » pour qu’API Gateway les exporte. Sinon, API Gateway lance une exception avec le message d’erreur « Only found non-JSON body models for... » (Seuls des modèles de corps non-JSON ont été détectés pour...). Les modèles doivent contenir des propriétés ou être définis comme un JSONSchema type particulier. ## Téléchargement d’une définition OpenAPI d’API REST au format JSON Pour exporter et télécharger une API REST dans des définitions OpenAPI au format JSON : ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/json ``` ------ Ici, `` pourrait être `us-east-1`, par exemple. Pour connaître toutes les régions où API Gateway est disponible, consultez [Régions et points de terminaison](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region). ## Téléchargement d’une définition OpenAPI d’API REST au format YAML Pour exporter et télécharger une API REST dans des définitions OpenAPI au format YAML : ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Téléchargement d’une définition OpenAPI d’API REST avec les extensions Postman au format JSON Pour exporter et télécharger une API REST dans des définitions OpenAPI avec Postman au format JSON : ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ ## Téléchargement d’une définition OpenAPI d’API REST avec intégration API Gateway au format YAML Pour exporter et télécharger une API REST dans des définitions OpenAPI avec intégration API Gateway au format YAML : ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Exportation d'une API REST à l'aide de la console API Gateway Après [avoir déployé votre API REST dans une étape](set-up-deployments.md#create-deployment), vous pouvez passer à l’exportation de cette API dans l’étape dans un fichier OpenAPI à l’aide de la console API Gateway. Dans le volet **Étapes** de la console API Gateway, choisissez **Actions d’étape**, **Exporter**. ![\[Exportation d'une API REST à l'aide de la console API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/export-new-console.png) Spécifiez un **type de spécification d’API**, un **format** et des **extensions** pour télécharger la définition OpenAPI de votre API.