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.
# Transformations de modèles de mappage pour REST APIs dans API Gateway
Une transformation de modèle de mappage utilise un modèle de mappage pour modifier votre demande d’intégration ou votre réponse d’intégration. Un *modèle de mappage* est un script exprimé dans le [langage VTL (Velocity Template Language)](https://velocity.apache.org/engine/devel/vtl-reference.html) et appliqué à une charge utile en [JSONPath ](https://goessner.net/articles/JsonPath/)fonction de l'`Content-type`en-tête. Vous utilisez des modèles de mappage lorsque vous transformez des modèles de mappage. Cette section décrit les informations conceptuelles relatives aux modèles de mappage.
Le schéma suivant montre le cycle de vie des demandes pour une `POST /pets` ressource intégrée à un point de terminaison PetStore d'intégration. Dans cette API, un utilisateur envoie des données sur un animal de compagnie, et le point de terminaison d’intégration renvoie les frais d’adoption relatifs à cet animal. Dans le cycle de vie de cette demande, les transformations du modèle de mappage filtrent le corps de la demande vers le point de terminaison d’intégration, et filtrent le corps de réponse provenant du point de terminaison d’intégration.
![\[Exemple de cycle de la demande\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/mapping-template-transforms.png)
Les sections suivantes expliquent le cycle de vie des demandes et réponses.
## Demande de méthode et demande d’intégration
Voici le corps de la demande envoyé à la demande de méthode dans l’exemple précédent :
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
Le corps de cette demande n’est pas au format approprié pour être utilisé par le point de terminaison d’intégration. API Gateway transforme donc le modèle de mappage. API Gateway transforme le modèle de mappage uniquement parce qu’un modèle de mappage est défini pour le Content-Type `application/json`. Si vous ne définissez pas de modèle de mappage pour Content-Type, API Gateway transmet par défaut le corps au point de terminaison d’intégration par le biais de la demande d’intégration. Pour modifier ce comportement, consultez [Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway](integration-passthrough-behaviors.md).
Le modèle de mappage suivant transforme les données de la demande de méthode dans la demande d’intégration avant qu’elles ne soient envoyées au point de terminaison d’intégration :
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. La variable `$inputRoot` représente l’objet racine dans les données JSON d’origine de la section précédente. Les directives commencent par le symbole `#`.
1. `dog` est une concaténation de la valeur de l’utilisateur `id` et d’une valeur de chaîne.
1. `Age` provient du corps de la demande de méthode.
La sortie suivante est ensuite transmise au point de terminaison d’intégration :
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## Réponse d’intégration et réponse de méthode
Une fois la demande envoyée avec succès au point de terminaison d’intégration, celui-ci envoie une réponse à la réponse d’intégration d’API Gateway. Voici un exemple de données de sortie provenant du point de terminaison d’intégration :
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
La réponse de méthode attend des données utiles différentes de celles renvoyées par la réponse d’intégration. API Gateway transforme le modèle de mappage. API Gateway transforme le modèle de mappage uniquement parce qu’un modèle de mappage est défini pour le Content-Type `application/json`. Si vous ne définissez pas de modèle de mappage pour Content-Type, API Gateway transmet par défaut le corps à la réponse de méthode par le biais de la réponse d’intégration. Pour modifier ce comportement, consultez [Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway](integration-passthrough-behaviors.md).
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
La sortie suivante est envoyée à la réponse de méthode :
```
{"adoptionFee": 19.95}
```
Ceci conclut l’exemple de transformation de modèle de mappage. Nous vous recommandons, dans la mesure du possible, d’utiliser une intégration de proxy pour transformer vos données au lieu de transformer le modèle de mappage. Pour de plus amples informations, veuillez consulter [Choix d’un type d’intégration d’API API Gateway](api-gateway-api-integration-types.md).
# Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway
Si votre demande de méthode comporte des données utiles et qu’aucun modèle de mappage n’est défini pour l’en-tête `Content-Type`, vous pouvez choisir de transmettre les données utiles de la demande fournie par le client au backend par l’intermédiaire de la demande d’intégration, sans recourir à une transformation. Ce processus est appelé transfert direct d’intégration.
Le comportement de transmission d’une demande entrante est déterminé par ce paramètre. Trois options sont disponibles :
**Quand aucun modèle ne correspond à l’en-tête Content-Type de la demande**
Sélectionnez cette option si vous voulez que le corps de la demande de méthode soit transmis au backend via la demande d’intégration sans transformation lorsque le type de contenu de la demande de méthode ne correspond à aucun type de contenu associé aux modèles de mappage.
Lorsque vous appelez l’API API Gateway, vous choisissez cette option en définissant `WHEN_NO_MATCH` en tant que valeur de la propriété `passthroughBehavior` sur [Intégration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Quand aucun modèle n’est défini (recommandé)**
Choisissez cette option si vous voulez que le corps de la demande de méthode soit transmis au backend via la demande d’intégration sans transformation lorsqu’aucun modèle de mappage n’est défini dans la demande d’intégration. Si un modèle est défini lorsque cette option est sélectionnée, la demande de méthode comprenant des données utiles et un type de contenu qui ne correspond pas au modèle de mappage défini sera rejetée avec une réponse HTTP 415 Unsupported Media Type.
Lorsque vous appelez l’API API Gateway, vous choisissez cette option en définissant `WHEN_NO_TEMPLATES` en tant que valeur de la propriété `passthroughBehavior` sur [Intégration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Jamais**
Choisissez cette option si vous ne voulez pas que le corps de la demande de méthode soit transmis au backend via la demande d’intégration sans transformation lorsqu’aucun modèle de mappage n’est défini dans la demande d’intégration. Si un modèle est défini lorsque cette option est sélectionnée, la demande de méthode d’un type de contenu non mappé est rejetée en renvoyant une réponse HTTP 415 Type de support non pris en charge.
Lorsque vous appelez l’API API Gateway, vous choisissez cette option en définissant `NEVER` en tant que valeur de la propriété `passthroughBehavior` sur [Intégration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
Les exemples suivants illustrent les comportements de transmission possibles.
Exemple 1 : un modèle de mappage est défini dans la demande d’intégration pour le type de contenu `application/json`.
| Content-Type | Option de transmission | Comportement |
| --- | --- | --- |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1MATCH | La charge utile de la demande est transformée à l’aide du modèle. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande est transformée à l’aide du modèle. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | NEVER | La charge utile de la demande est transformée à l’aide du modèle. |
| application/json | WHEN\$1NO\$1MATCH | La charge utile de la demande est transformée à l’aide du modèle. |
| application/json | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande est transformée à l’aide du modèle. |
| application/json | NEVER | La charge utile de la demande est transformée à l’aide du modèle. |
| application/xml | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/xml | WHEN\$1NO\$1TEMPLATES | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/xml | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
Exemple 2 : un modèle de mappage est défini dans la demande d’intégration pour le type de contenu `application/xml`.
| Content-Type | Option de transmission | Comportement |
| --- | --- | --- |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1TEMPLATES | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/json | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/json | WHEN\$1NO\$1TEMPLATES | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/json | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/xml | WHEN\$1NO\$1MATCH | La charge utile de la demande est transformée à l’aide du modèle. |
| application/xml | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande est transformée à l’aide du modèle. |
| application/xml | NEVER | La charge utile de la demande est transformée à l’aide du modèle. |
Exemple 3 : aucun modèle de mappage n’est défini dans la demande d’intégration.
| Content-Type | Option de transmission | Comportement |
| --- | --- | --- |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| Aucune La valeur par défaut d’API Gateway est `application/json` | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/json | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/json | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/json | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
| application/xml | WHEN\$1NO\$1MATCH | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/xml | WHEN\$1NO\$1TEMPLATES | La charge utile de la demande n’est pas transformée et est envoyée en l’état au backend. |
| application/xml | NEVER | La demande est rejetée avec une réponse HTTP 415 Unsupported Media Type. |
# Exemple de modèle de mappage supplémentaire pour REST APIs dans API Gateway
L’exemple suivant montre une API d’album photo API Gateway qui utilise des modèles de mappage pour transformer les données de la demande d’intégration et de la réponse d’intégration. Elle utilise également des modèles de données pour définir les données utiles de la demande de méthode et de la réponse d’intégration. Pour plus d’informations sur les modèles de données, consultez [Modèles de données pour REST APIs](models-mappings-models.md).
## Demande de méthode et demande d’intégration
Voici un modèle qui définit le corps de la demande de méthode. Ce modèle d’entrée exige le chargement d’une page de photos et un minimum de 10 photos pour chaque page. Vous pouvez utiliser ce modèle d’entrée pour générer un kit SDK ou utiliser le validateur de demande pour votre API. Dans ce dernier cas, si le corps de la demande de méthode ne respecte pas la structure de données du modèle, API Gateway fait échouer la demande.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
Voici un exemple de corps de demande de méthode qui respecte la structure de données du modèle de données précédent.
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
Dans cet exemple, si le précédent corps de la demande de méthode a été soumis par le client, ce modèle de mappage transforme les données utiles pour qu’elles correspondent au format requis par le point de terminaison d’intégration.
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
L’exemple suivant montre les données de sortie de la transformation :
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Ces données sont envoyées à la demande d’intégration, puis au point de terminaison d’intégration.
## Réponse d’intégration et réponse de méthode
Voici un exemple de modèle de sortie pour les données photo du point de terminaison d’intégration. Vous pouvez utiliser ce modèle comme modèle de réponse de méthode, ce qui s’avère nécessaire quand vous générez un kit SDK fortement typé pour l’API. Cela entraîne la conversion (cast) de la sortie en une classe appropriée en Java ou Objective-C.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
Le point de terminaison d’intégration peut ne pas répondre par une réponse conforme à la structure de données de ce modèle. Par exemple, la réponse d’intégration peut ressembler à ce qui suit :
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
L’exemple de modèle de mappage suivant transforme les données de la réponse d’intégration dans le format attendu par la réponse de méthode :
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
L’exemple suivant montre les données de sortie de la transformation :
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Ces données sont envoyées à la réponse de méthode, puis renvoyées au client.
# Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway
Vous pouvez recourir à la transformation de modèle de mappage pour remplacer n’importe quel type de paramètre de demande, d’en-tête de réponse ou de code d’état de réponse. Vous allez utiliser un modèle de mappage pour :
+ Effectuer des mappages de many-to-one paramètres
+ Remplacer les paramètres une fois que les mappages API Gateway standard ont été appliqués
+ Mapper les paramètres de façon conditionnelle, en fonction du contenu du corps ou d’autres valeurs de paramètres
+ Créer des paramètres par programmation
+ Remplacer les codes de statut renvoyés par votre point de terminaison d’intégration
Les remplacements sont définitifs. Un remplacement ne peut être appliqué qu’une seule fois à chaque paramètre. Si vous tentez de remplacer le même paramètre à plusieurs reprises, API Gateway renvoie une réponse `5XX`. Si vous devez remplacer le même paramètre plusieurs fois tout au long du modèle, nous vous recommandons de créer une variable et d’appliquer le remplacement à la fin du modèle. Le modèle n’est appliqué qu’après l’analyse de l’ensemble du modèle.
## Exemple 1 : remplacement du code d’état en fonction du corps de la réponse d’intégration
L’exemple suivant utilise l’[exemple d’API](api-gateway-create-api-from-example.md) pour remplacer le code d’état en fonction du corps de la réponse d’intégration.
------
#### [ AWS Management Console ]
**Pour remplacer un code d’état en fonction du corps de la réponse d’intégration**
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 **Création**.
1. Sous **Détails sur l’API**, choisissez **Exemple d’API**.
1. Sélectionnez **Create API** (Créer une API).
API Gateway crée un exemple d’API PetStore. Pour récupérer des informations sur un animal de compagnie, vous allez utiliser la demande de méthode d’API `GET /pets/{petId}`, où `{petId}` est un paramètre de chemin correspondant au numéro d’identification de l’animal.
Dans cet exemple, vous allez remplacer le code de réponse de la méthode `GET` par `400` lorsqu’une condition d’erreur est identifiée.
1. Dans l’arborescence **Ressources**, sous `GET`, choisissez la méthode sous `/{petId}`.
1. Tout d’abord, vous allez tester l’implémentation actuelle de l’API.
Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Pour **petId**, saisissez **-1**, puis choisissez **Tester**.
Le **corps de la réponse** indique une out-of-range erreur :
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
De plus, la dernière ligne sous **Journaux** se termine par : `Method completed with status: 200`.
L’intégration a été réalisée avec succès, mais une erreur s’est produite. Vous allez maintenant remplacer le code d’état en fonction de la réponse d’intégration.
1. Dans l’onglet **Réponse d’intégration**, pour **Par défaut - Réponse**, choisissez **Modifier**.
1. Choisissez **Modèles de mappage**.
1. Sélectionnez **Add mapping template**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, saisissez ce qui suit :
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
Ce modèle de mappage utilise la variable `$context.responseOverride.status` pour remplacer le code d’état par `400` si la réponse d’intégration contient la chaîne `error`.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Test**.
1. Pour **petId**, saisissez **-1**.
1. Dans les résultats, le **corps de réponse** indique une out-of-range erreur :
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Cependant, la dernière ligne sous **Journaux** se termine maintenant par : `Method completed with status: 400`.
------
#### [ CloudFormation ]
Dans cet exemple, vous allez utiliser la propriété [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) pour importer un fichier de définition OpenAPI dans API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La définition OpenAPI suivante crée la ressource `GET pets/{petId}` et remplace le code d’état en fonction du corps de la réponse d’intégration.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## Exemple 2 : remplacement de l’en-tête de la demande et création de nouveaux en-têtes
L’exemple suivant utilise l’[exemple d’API](api-gateway-create-api-from-example.md) pour remplacer l’en-tête de la demande et créer de nouveaux en-têtes.
------
#### [ AWS Management Console ]
**Pour remplacer l’en-tête de demande d’une méthode en créant un nouvel en-tête**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez l’exemple d’API que vous avez créé dans le tutoriel précédent. Le nom de l'API doit être **PetStore**.
1. Dans l’arborescence **Ressources**, sous `GET`, choisissez la méthode sous `/pet`.
1. Dans l’onglet **Requête de méthode**, pour **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Choisissez **En-têtes de demande HTTP**, puis **Ajouter un en-tête**.
1. Pour **Nom**, saisissez **header1**.
1. Choisissez **Ajouter un en-tête**, puis créez un second en-tête appelé **header2**.
1. Choisissez **Enregistrer**.
Vous pouvez maintenant combiner ces en-têtes en une seule valeur d’en-tête à l’aide d’un modèle de mappage.
1. Dans l’onglet **Demande d’intégration**, pour **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Pour **Transmission du corps de requête**, sélectionnez **Lorsqu’aucun modèle n’est défini (recommandé)**.
1. Choisissez **Modèles de mappage**, puis procédez comme suit :
1. Sélectionnez **Add mapping template**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, saisissez ce qui suit :
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
Ce modèle de mappage remplace `header1` par la chaîne `pets`, et crée un en-tête à valeurs multiples appelé `$header3Value`, qui combine `header1` et `header2`.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Test**.
1. Sous **En-têtes**, copiez le code suivant :
```
header1:header1Val
header2:header2Val
```
1. Sélectionnez **Test**.
Dans **Journaux**, vous devriez voir une entrée incluant ce texte :
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
Dans cet exemple, vous allez utiliser la propriété [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) pour importer un fichier de définition OpenAPI dans API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
La définition OpenAPI suivante crée la ressource `GET pets`, remplace l’en-tête de la demande et crée de nouveaux en-têtes.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
Pour remplacer un modèle de mappage, ajoutez une ou plusieurs des variables `$context` suivantes. Pour obtenir la liste des variables `$context`, consultez [Variables context pour les transformations de données](api-gateway-mapping-template-reference.md#context-variable-reference).
# Tutoriel : Modifier la demande et la réponse d'intégration pour les intégrations aux services AWS
Le didacticiel suivant explique comment utiliser les transformations de modèles de mappage pour configurer des modèles de mappage afin de transformer les demandes et réponses d'intégration à l'aide de la console et de la AWS CLI.
**Topics**
+ [
## Configuration d’une transformation de données à l’aide de la console API Gateway
](#mapping-example-console)
+ [
## Configuration de la transformation des données à l'aide de la AWS CLI
](#mapping-example-cli)
+ [
## CloudFormation Modèle de transformation de données terminé
](#api-gateway-data-transformations-full-cfn-stack)
## Configuration d’une transformation de données à l’aide de la console API Gateway
[Dans ce didacticiel, vous allez créer une API et une table DynamoDB incomplètes à l'aide du fichier .zip .zip suivant. data-transformation-tutorial-console](samples/data-transformation-tutorial-console.zip) Cette API incomplète possède une ressource `/pets` avec les méthodes `GET` et `POST`.
+ La méthode `GET` obtiendra des données à partir du point de terminaison HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Les données de sortie seront transformées conformément au modèle de mappage figurant dans [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
+ La méthode `POST` permettra à l’utilisateur de publier (`POST`) les informations sur les animaux dans une table Amazon DynamoDB à l’aide d’un modèle de mappage.
Téléchargez et décompressez [le modèle de création d'application pour CloudFormation](samples/data-transformation-tutorial-console.zip). Vous allez utiliser ce modèle pour créer une table DynamoDB afin de publier les informations sur les animaux et une API incomplète. Vous terminerez les étapes restantes dans la console API Gateway.
**Pour créer une CloudFormation pile**
1. Ouvrez la CloudFormation console à l'adresse [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/)
1. Choisissez **Créer une pile**, puis choisissez **Avec de nouvelles ressources (standard).**
1. Dans **Spécifier le modèle**, choisissez **Charger un modèle de fichier**.
1. Sélectionnez le modèle que vous avez téléchargé.
1. Choisissez **Suivant**.
1. Pour **Nom de la pile**, saisissez **data-transformation-tutorial-console**, puis choisissez **Suivant**.
1. Pour **Configurer les options de pile**, choisissez **Suivant**.
1. Pour les **fonctionnalités**, reconnaissez que CloudFormation vous pouvez créer des ressources IAM dans votre compte.
1. Choisissez **Suivant**, puis **Soumettre**.
CloudFormation fournit les ressources spécifiées dans le modèle. La fin du provisionnement de vos ressources peut prendre quelques minutes. Lorsque le statut de votre CloudFormation pile est **CREATE\$1COMPLETE**, vous êtes prêt à passer à l'étape suivante.
**Pour tester la réponse d’intégration `GET`**
1. Dans l'onglet **Ressources** de la CloudFormation pile pour**data-transformation-tutorial-console**, sélectionnez l'ID physique de votre API.
1. Dans le volet de navigation principal, choisissez **Ressources**, puis sélectionnez la méthode **GET**.
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
La sortie du test affichera les informations suivantes :
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Vous allez transformer cette sortie conformément au modèle de mappage figurant dans [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
**Pour transformer la réponse d’intégration `GET`**
1. Choisissez l’onglet **Réponse d’intégration**.
Aucun modèle de mappage n’est actuellement défini, de sorte que la réponse d’intégration ne sera pas transformée.
1. Pour **Par défaut - Réponse**, choisissez **Modifier**.
1. Choisissez **Modèles de mappage**, puis procédez comme suit :
1. Sélectionnez **Add mapping template**.
1. Pour **Type de contenu**, entrez **application/json**.
1. Pour **Corps du modèle**, saisissez ce qui suit :
```
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
Choisissez **Enregistrer**.
**Pour tester la réponse d’intégration `GET`**
+ Choisissez l’onglet **Tester**, puis choisissez **Tester**.
La sortie du test affichera la réponse transformée.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Pour transformer les données d’entrée issues de la méthode `POST`**
1. Choisissez la méthode **POST**.
1. Choisissez l’onglet **Requête d’intégration**, puis dans la section **Paramètres de requête d’intégration**, choisissez **Modifier**.
Le CloudFormation modèle a rempli certains champs de demande d'intégration.
+ Le type d'intégration est Service AWS.
+ Service AWS Il s'agit de DynamoDB.
+ La méthode HTTP est `POST`.
+ L’action est `PutItem`.
+ Le rôle d'exécution permettant à API Gateway de placer un élément dans la table DynamoDB est. `data-transformation-tutorial-console-APIGatewayRole` CloudFormation a créé ce rôle pour permettre à API Gateway de disposer des autorisations minimales nécessaires pour interagir avec DynamoDB.
Le nom de la table DynamoDB n’a pas été spécifié. Vous allez spécifier ce nom dans les étapes suivantes.
1. Pour **Transmission du corps de requête**, sélectionnez **Jamais**.
Cela signifie que l’API rejettera les données avec des types de contenu qui ne disposent pas d’un modèle de mappage.
1. Choisissez **Modèles de mappage**.
1. **Type de contenu** est défini sur `application/json`. Cela signifie que les types de contenu qui ne le sont pas application/json seront rejetés par l'API. Pour plus d’informations sur les comportements de transmission d’intégration, consultez [Comportement des demandes de méthode pour les charges utiles sans modèles de mappage pour REST APIs dans API Gateway](integration-passthrough-behaviors.md).
1. Saisissez le code suivant dans l’éditeur de texte.
```
{
"TableName":"data-transformation-tutorial-console-ddb",
"Item": {
"id": {
"N": $input.json("$.id")
},
"type": {
"S": $input.json("$.type")
},
"price": {
"N": $input.json("$.price")
}
}
}
```
Ce modèle spécifie la table en tant que `data-transformation-tutorial-console-ddb` et définit les éléments en tant que `id`, `type` et `price`. Ces éléments proviennent du corps de la méthode `POST`. Vous pouvez également utiliser un modèle de données pour favoriser la création d’un modèle de mappage. Pour de plus amples informations, veuillez consulter [Demande de validation pour REST APIs dans API Gateway](api-gateway-method-request-validation.md).
1. Choisissez **Enregistrer** pour enregistrer votre modèle de mappage.
**Pour ajouter une réponse de méthode et d’intégration à partir de la méthode `POST`**
Ils CloudFormation ont créé une méthode vide et une réponse d'intégration. Vous allez modifier cette réponse pour fournir plus d’informations. Pour plus d’informations sur la façon de modifier des réponses, consultez [Exemples de mappage de paramètres pour REST APIs dans API Gateway](request-response-data-mappings.md).
1. Dans l’onglet **Réponse d’intégration**, pour **Par défaut - Réponse**, choisissez **Modifier**.
1. Choisissez **Modèles de mappage**, puis choisissez **Ajouter un modèle de mappage**.
1. Pour **Type de contenu**, saisissez **application/json**.
1. Dans l’éditeur de code, entrez le modèle de mappage de sortie suivant pour envoyer un message de sortie :
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
Pour plus d’informations sur les variables de contexte, consultez [Variables context pour les transformations de données](api-gateway-mapping-template-reference.md#context-variable-reference).
1. Choisissez **Enregistrer** pour enregistrer votre modèle de mappage.
**Test de la méthode `POST`**
Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Dans le corps de la demande, entrez l’exemple suivant.
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. Sélectionnez **Tester)**.
La sortie doit afficher votre message de réussite.
Vous pouvez ouvrir la console DynamoDB [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)à l'adresse pour vérifier que l'exemple d'élément figure dans votre tableau.
**Pour supprimer une CloudFormation pile**
1. Ouvrez la CloudFormation console à l'adresse [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/)
1. Sélectionnez votre CloudFormation pile.
1. Choisissez **Supprimer**, puis confirmez votre choix.
## Configuration de la transformation des données à l'aide de la AWS CLI
[Dans ce didacticiel, vous allez créer une API et une table DynamoDB incomplètes à l'aide du fichier .zip .zip suivant. data-transformation-tutorial-cli](samples/data-transformation-tutorial-cli.zip) Cette API incomplète possède une ressource `/pets` avec une méthode `GET` intégrée au point de terminaison HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Vous allez créer une méthode `POST` pour vous connecter à une table DynamoDB et utiliser des modèles de mappage pour entrer des données dans une table DynamoDB.
+ Vous allez transformer les données de sortie conformément au modèle de mappage figurant dans [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
+ Vous allez créer une méthode `POST` pour permettre à l’utilisateur de publier (`POST`) les informations sur les animaux dans une table Amazon DynamoDB à l’aide d’un modèle de mappage.
**Pour créer une CloudFormation pile**
Téléchargez et décompressez [le modèle de création d'application pour CloudFormation](samples/data-transformation-tutorial-cli.zip).
Pour effectuer le didacticiel suivant, vous avez besoin de l’[AWS Command Line Interface (AWS CLI) version 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
Pour les commandes longues, un caractère d’échappement (`\`) est utilisé pour les fractionner en plusieurs lignes.
**Note**
Dans Windows, certaines commandes CLI Bash que vous utilisez couramment (par exemple `zip`) ne sont pas prises en charge par les terminaux intégrés du système d’exploitation. [Installez le sous-système Windows pour Linux](https://learn.microsoft.com/en-us/windows/wsl/install) afin d’obtenir une version intégrée avec Windows d’Ubuntu et Bash. Les exemples de commandes CLI de ce guide utilisent le formatage Linux. Les commandes qui incluent des documents JSON en ligne doivent être reformatées si vous utilisez la CLI Windows.
1. Utilisez la commande suivante pour créer la CloudFormation pile.
```
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormation fournit les ressources spécifiées dans le modèle. La fin du provisionnement de vos ressources peut prendre quelques minutes. Utilisez la commande suivante pour voir l'état de votre CloudFormation pile.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. Lorsque le statut de votre CloudFormation pile est défini`StackStatus: "CREATE_COMPLETE"`, utilisez la commande suivante pour récupérer les valeurs de sortie pertinentes pour les étapes futures.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
Les valeurs de sortie sont les suivantes :
+ ApiRole, qui est le nom du rôle qui permet à API Gateway de placer des éléments dans la table DynamoDB. Pour ce didacticiel, le nom du rôle est `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`.
+ DDBTableNom, qui est le nom de la table DynamoDB. Pour ce didacticiel, le nom de la table est `data-transformation-tutorial-cli-ddb`.
+ ResourceId, qui est l'identifiant de la ressource pour animaux de compagnie dans laquelle les `POST` méthodes `GET` et sont exposées. Pour ce didacticiel, l’ID de ressource est `efg456`.
+ ApiId, qui est l'ID de l'API. Pour ce didacticiel, l’ID d’API est `abc123`.
**Pour tester la méthode `GET` avant la transformation des données**
+ Utilisez la commande suivante pour tester la méthode `GET`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
La sortie du test affichera les informations suivantes.
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Vous allez transformer cette sortie conformément au modèle de mappage figurant dans [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
**Pour transformer la réponse d’intégration `GET`**
+ Utilisez la commande suivante pour mettre à jour la réponse d’intégration de la méthode `GET`. Remplacez le *rest-api-id* et *resource-id* par vos valeurs.
Utilisez la commande suivante pour créer la réponse d’intégration.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
```
**Pour tester la méthode `GET`**
+ Utilisez la commande suivante pour tester la méthode `GET`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
```
La sortie du test affichera la réponse transformée.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Pour créer une méthode `POST`**
1. Utilisez la commande suivante pour créer une nouvelle méthode sur la ressource `/pets`.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
```
Cette méthode vous permettra d'envoyer des informations relatives aux animaux de compagnie à la table DynamoDB que vous avez créée dans la pile. CloudFormation
1. Utilisez la commande suivante pour créer une Service AWS intégration sur la `POST` méthode.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \
--credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
--request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
```
1. Utilisez la commande suivante pour créer une réponse de méthode pour un appel réussi de la méthode `POST`.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. Utilisez la commande suivante pour créer une réponse d’intégration pour l’appel réussi de la méthode `POST`.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
```
**Pour tester la méthode `POST`**
+ Utilisez la commande suivante pour tester la méthode `POST`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'
```
La sortie affichera le message de réussite.
**Pour supprimer une CloudFormation pile**
+ Utilisez la commande suivante pour supprimer vos CloudFormation ressources.
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## CloudFormation Modèle de transformation de données terminé
L'exemple suivant est un CloudFormation modèle complet, qui crée une API et une table DynamoDB avec `/pets` une ressource `GET` avec des méthodes et. `POST`
+ La méthode `GET` obtiendra des données à partir du point de terminaison HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Les données de sortie seront transformées conformément au modèle de mappage figurant dans [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md).
+ La méthode `POST` permettra à l’utilisateur de publier (`POST`) les informations sur les animaux de compagnie dans une table DynamoDB à l’aide d’un modèle de mappage.
### Exemple de CloudFormation modèle
```
AWSTemplateFormatVersion: 2010-09-09
Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data.
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
DynamoDBTable:
Type: 'AWS::DynamoDB::Table'
Properties:
TableName: !Sub data-transformation-tutorial-complete
AttributeDefinitions:
- AttributeName: id
AttributeType: N
KeySchema:
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
APIGatewayRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'sts:AssumeRole'
Effect: Allow
Principal:
Service:
- apigateway.amazonaws.com
Policies:
- PolicyName: APIGatewayDynamoDBPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'dynamodb:PutItem'
Resource: !GetAtt DynamoDBTable.Arn
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: data-transformation-complete-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: HTTP
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"
MethodResponses:
- StatusCode: '200'
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: POST
Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem
PassthroughBehavior: NEVER
RequestTemplates:
application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}"
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiId:
Description: API ID for CLI commands
Value: !Ref Api
ResourceId:
Description: /pets resource ID for CLI commands
Value: !Ref PetsResource
ApiRole:
Description: Role ID to allow API Gateway to put and scan items in DynamoDB table
Value: !Ref APIGatewayRole
DDBTableName:
Description: DynamoDB table name
Value: !Ref DynamoDBTable
```
# Exemples d’utilisation de variables pour transformer des modèles de mappage pour API Gateway
Les exemples suivants montrent comment utiliser les variables `$context`, `input` et `util` dans des modèles de mappage. Vous pouvez utiliser une intégration simulée ou une intégration Lambda sans proxy qui renvoie l’événement d’entrée dans API Gateway. Pour obtenir la liste de toutes les variables prises en charge pour les transformations de données, consultez [Variables pour les transformations de données pour API Gateway](api-gateway-mapping-template-reference.md).
## Exemple 1 : transmission de plusieurs variables `$context` au point de terminaison d’intégration
L’exemple suivant illustre un modèle de mappage qui mappe les variables `$context` entrantes aux variables de backend avec des noms légèrement différents dans une charge utile de la demande d’intégration :
```
{
"stage" : "$context.stage",
"request_id" : "$context.requestId",
"api_id" : "$context.apiId",
"resource_path" : "$context.resourcePath",
"resource_id" : "$context.resourceId",
"http_method" : "$context.httpMethod",
"source_ip" : "$context.identity.sourceIp",
"user-agent" : "$context.identity.userAgent",
"account_id" : "$context.identity.accountId",
"api_key" : "$context.identity.apiKey",
"caller" : "$context.identity.caller",
"user" : "$context.identity.user",
"user_arn" : "$context.identity.userArn"
}
```
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{
stage: 'prod',
request_id: 'abcdefg-000-000-0000-abcdefg',
api_id: 'abcd1234',
resource_path: '/',
resource_id: 'efg567',
http_method: 'GET',
source_ip: '192.0.2.1',
user-agent: 'curl/7.84.0',
account_id: '111122223333',
api_key: 'MyTestKey',
caller: 'ABCD-0000-12345',
user: 'ABCD-0000-12345',
user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}
```
L’une des variables est une clé d’API. Dans cet exemple, on suppose que la méthode exige une clé d’API.
## Exemple 2 : transmission de tous les paramètres de la demande au point de terminaison d’intégration via des données utiles JSON
L’exemple suivant transmet tous les paramètres de la demande, y compris les paramètres `path`, `querystring` et `header`, au point de terminaison d’intégration via des données utiles JSON :
```
#set($allParams = $input.params())
{
"params" : {
#foreach($type in $allParams.keySet())
#set($params = $allParams.get($type))
"$type" : {
#foreach($paramName in $params.keySet())
"$paramName" : "$util.escapeJavaScript($params.get($paramName))"
#if($foreach.hasNext),#end
#end
}
#if($foreach.hasNext),#end
#end
}
}
```
Si une demande possède les paramètres d’entrée suivants :
+ Paramètre de chemin nommé `myparam`
+ Paramètres des chaînes de demande `querystring1=value1,value2`
+ En-têtes `"header1" : "value1"`.
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## Exemple 3 : transmission d’une sous-section d’une demande de méthode au point de terminaison d’intégration
L’exemple suivant utilise le paramètre d’entrée `name` pour récupérer uniquement le paramètre `name`, et le paramètre d’entrée `input.json('$')` pour récupérer l’intégralité du corps de la demande de méthode :
```
{
"name" : "$input.params('name')",
"body" : $input.json('$')
}
```
Pour une demande qui inclut les paramètres de chaîne de demande `name=Bella&type=dog` et le corps suivant :
```
{
"Price" : "249.99",
"Age": "6"
}
```
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{
"name" : "Bella",
"body" : {"Price":"249.99","Age":"6"}
}
```
Ce modèle de mappage supprime le paramètre de chaîne de requête `type=dog`.
Si l'entrée JSON contient des caractères non échappés qui ne peuvent pas être analysés JavaScript, API Gateway peut renvoyer une réponse 400. Appliquez `$util.escapeJavaScript($input.json('$'))` pour que les données d’entrée JSON puissent être analysées correctement.
L’exemple précédent avec application de `$util.escapeJavaScript($input.json('$'))` est le suivant :
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$'))"
}
```
Dans ce cas, le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{
"name" : "Bella",
"body": {"Price":"249.99","Age":"6"}
}
```
## Exemple 4 : Utiliser une JSONPath expression pour transmettre une sous-section d'une demande de méthode au point de terminaison d'intégration
L'exemple suivant utilise les JSONPath expressions pour récupérer uniquement le paramètre d'entrée `name` et le contenu `Age` du corps de la demande :
```
{
"name" : "$input.params('name')",
"body" : $input.json('$.Age')
}
```
Pour une demande qui inclut les paramètres de chaîne de demande `name=Bella&type=dog` et le corps suivant :
```
{
"Price" : "249.99",
"Age": "6"
}
```
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{
"name" : "Bella",
"body" : "6"
}
```
Ce modèle de mappage supprime le paramètre de chaîne de requête `type=dog` et le champ `Price` du corps.
Si la charge utile d'une demande de méthode contient des caractères non échappés qui ne peuvent pas être analysés, API JavaScript Gateway peut renvoyer une réponse. `400` Appliquez `$util.escapeJavaScript()` pour que les données d’entrée JSON puissent être analysées correctement.
L’exemple précédent avec application de `$util.escapeJavaScript($input.json('$.Age'))` est le suivant :
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$.Age'))"
}
```
Dans ce cas, le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{
"name" : "Bella",
"body": "\"6\""
}
```
## Exemple 5 : Utiliser une JSONPath expression pour transmettre des informations relatives à une demande de méthode au point de terminaison d'intégration
L’exemple suivant utilise `$input.params()`, `$input.path()` et `$input.json()` pour envoyer des informations sur une demande de méthode au point de terminaison d’intégration. Ce modèle de mappage utilise la méthode `size()` pour fournir le nombre d’éléments dans une liste.
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : $input.json('$.things')
}
```
Pour une demande qui inclut le paramètre de chemin `123` et le corps suivant :
```
{
"things": {
"1": {},
"2": {},
"3": {}
}
}
```
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}
```
Si la charge utile d'une demande de méthode contient des caractères non échappés qui ne peuvent pas être analysés, API JavaScript Gateway peut renvoyer une réponse. `400` Appliquez `$util.escapeJavaScript()` pour que les données d’entrée JSON puissent être analysées correctement.
L’exemple précédent avec application de `$util.escapeJavaScript($input.json('$.things'))` est le suivant :
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : "$util.escapeJavaScript($input.json('$.things'))"
}
```
Le résultat de ce modèle de mappage doit ressembler à ce qui suit :
```
{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}
```