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 données pour REST APIs dans API Gateway
**Note**
Cette section explique les fonctionnalités que vous allez utiliser avec une intégration sans proxy. Toutefois, nous vous recommandons, dans la mesure du possible, d’utiliser une intégration proxy pour votre API REST. Une intégration proxy dispose d’une configuration d’intégration simplifiée et peut évoluer avec le backend sans qu’il soit nécessaire de modifier la configuration existante. Pour de plus amples informations, veuillez consulter [Choix d’un type d’intégration d’API API Gateway](api-gateway-api-integration-types.md).
Si vous utilisez une intégration sans proxy, vous pouvez utiliser deux fonctionnalités d’API Gateway pour transformer votre demande de méthode et votre réponse d’intégration. Vous pouvez transformer votre demande de méthode si elle utilise un format de données utiles différent de celui de la demande d’intégration. Vous pouvez transformer votre réponse d’intégration si elle renvoie un format de données utiles différent de celui que vous devez renvoyer dans la réponse de méthode. Pour plus d’informations sur le cycle de vie des demandes, consultez [Exemple de ressource pour une API REST](rest-api-develop.md#rest-api-develop-example).
L’exemple suivant montre une transformation de données dans laquelle, pour l’en-tête `"x-version:beta"`, le paramètre d’en-tête `x-version` est transformé en paramètre d’en-tête `app-version`. Les données passent de `x-version` à `app-version` dans la demande d’intégration. Ainsi, le point de terminaison d’intégration reçoit la valeur du paramètre d’en-tête transformé. Lorsque le point de terminaison d’intégration renvoie un code d’état, celui-ci passe de `200` à `204` avant la réponse de méthode.
![\[Schéma de transformation de données d’API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/develop-non-proxy.png)
Pour transformer des données, vous pouvez utiliser les fonctionnalités suivantes :
**Mappage de paramètres**
Dans un mappage des paramètres, vous pouvez modifier les paramètres du chemin d’URL de la demande d’intégration, les paramètres de la chaîne de requête d’URL ou les valeurs d’en-tête HTTP, mais vous ne pouvez pas modifier les données utiles de la demande d’intégration. Vous pouvez également modifier les valeurs de l’en-tête de réponse HTTP. Utilisez le mappage de paramètres pour créer des valeurs d’en-tête statiques pour le partage des ressources entre origines multiples (CORS).
Vous pouvez utiliser le mappage de paramètres dans votre demande d’intégration pour les intégrations proxy et sans proxy. En revanche, pour utiliser le mappage de paramètres dans une réponse d’intégration, vous avez besoin d’une intégration sans proxy. Le mappage de paramètres ne nécessite aucun script en [langage VTL (Velocity Template Language](https://velocity.apache.org/engine/devel/vtl-reference.html)). Pour de plus amples informations, veuillez consulter [Mappage des paramètres pour REST APIs dans API Gateway](rest-api-parameter-mapping.md).
**Transformations de modèles de mappage**
Pour transformer un modèle de mappage, vous allez utiliser un modèle de mappage pour mapper les paramètres de chemin d’URL, les paramètres de chaîne de requête d’URL, les en-têtes HTTP, ainsi que le corps de la demande d’intégration ou de la 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) l'aide d'[JSONPath expressions](https://goessner.net/articles/JsonPath/) et appliqué à la charge utile en fonction de l'`Content-type`en-tête.
Un modèle de mappage vous permet d’effectuer les opérations suivantes :
+ Sélectionnez les données à envoyer à l'aide de l'intégration Services AWS, telles que les fonctions Amazon DynamoDB ou Lambda, ou les points de terminaison HTTP. Pour de plus amples informations, veuillez consulter [Tutoriel : Modifier la demande et la réponse d'intégration pour les intégrations aux services AWS](set-up-data-transformations-in-api-gateway.md).
+ Remplacer de manière conditionnelle les paramètres de demande d’intégration et de réponse d’intégration d’une API, créer des valeurs d’en-tête et remplacer des codes d’état. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md).
Vous pouvez également spécifier le comportement de votre API lorsqu’un corps de demande d’intégration comporte un en-tête `Content-type` sans modèles de mappage correspondants. C’est ce qu’on appelle le comportement de transmission d’intégration. Pour de plus amples informations, veuillez consulter [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).
## Choisissez entre le mappage de paramètres et la transformation du modèle de mappage
Nous vous recommandons d’utiliser le mappage de paramètres pour transformer vos données lorsque cela est possible. Si votre API vous oblige à modifier le corps ou à effectuer des remplacements et modifications conditionnelles en fonction de la demande d’intégration entrante ou de la réponse d’intégration, et que vous ne pouvez pas utiliser d’intégration proxy, optez pour la transformation du modèle de mappage.
# Mappage des paramètres pour REST APIs dans API Gateway
**Note**
Si vous utilisez une API HTTP, consultez [Transformation des demandes et des réponses d’API HTTP dans API Gateway](http-api-parameter-mapping.md).
Dans le mappage de paramètres, vous mappez les paramètres de la demande ou de la réponse. Vous pouvez mapper des paramètres à l’aide d’expressions de mappage de paramètres ou de valeurs statiques. Pour obtenir la liste des expressions de mappage, consultez [Référence de source de mappage de paramètres pour REST APIs dans API Gateway](rest-api-parameter-mapping-sources.md). Vous pouvez utiliser le mappage de paramètres dans votre demande d’intégration pour les intégrations proxy et sans proxy. En revanche, pour utiliser le mappage de paramètres dans une réponse d’intégration, vous avez besoin d’une intégration sans proxy.
Par exemple, vous pouvez mapper le paramètre d’en-tête `puppies` de la demande de méthode au paramètre d’en-tête `DogsAge0` de la demande d’intégration. Si un client envoie l’en-tête `puppies:true` à votre API, la demande d’intégration envoie alors l’en-tête de demande `DogsAge0:true` au point de terminaison d’intégration. Le schéma suivant illustre le cycle de vie de la demande de cet exemple.
![\[Schéma d’un exemple de mappage des paramètres d’API Gateway pour une demande\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
Pour créer cet exemple à l’aide d’API Gateway, consultez [Exemple 1 : association d’un paramètre de demande de méthode à un paramètre de demande d’intégration](request-response-data-mappings.md#request-response-data-mappings-example-1).
Autre exemple, vous pouvez également mapper le paramètre d’en-tête de réponse d’intégration `kittens` au paramètre d’en-tête de réponse de méthode`CatsAge0`. Ensuite, si le point de terminaison d’intégration renvoie `kittens:false`, le client reçoit l’en-tête `CatsAge0:false`. Le schéma suivant illustre le cycle de vie de la demande de cet exemple.
![\[Schéma d’un exemple de mappage de paramètres API Gateway pour une réponse\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [Exemples de mappage de paramètres pour REST APIs dans API Gateway](request-response-data-mappings.md)
+ [Référence de source de mappage de paramètres pour REST APIs dans API Gateway](rest-api-parameter-mapping-sources.md)
# Exemples de mappage de paramètres pour REST APIs dans API Gateway
Les exemples suivants montrent comment créer des expressions de mappage de paramètres à l’aide de la console API Gateway, d’OpenAPI et de modèles CloudFormation . Pour voir un exemple d’utilisation du mappage de paramètres dans le but de créer les en-têtes CORS requis, consultez [CORS pour REST APIs dans API Gateway](how-to-cors.md).
## Exemple 1 : association d’un paramètre de demande de méthode à un paramètre de demande d’intégration
L’exemple suivant mappe le paramètre d’en-tête `puppies` de la demande de méthode au paramètre d’en-tête `DogsAge0` de la demande d’intégration.
------
#### [ AWS Management Console ]
**Pour mapper le paramètre de la demande de méthode**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API REST.
1. Choisissez une méthode.
Votre méthode doit avoir une intégration sans proxy.
1. Pour **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Développez **En-têtes de demande HTTP**.
1. Sélectionnez **Add header**.
1. Pour **Nom**, saisissez **puppies**.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Requête d’intégration**, puis dans la section **Paramètres de requête d’intégration**, choisissez **Modifier**.
Ajoute AWS Management Console automatiquement un mappage de paramètres de `method.request.header.puppies ` à `puppies` pour vous, mais vous devez modifier le **nom** pour qu'il corresponde au paramètre d'en-tête de demande attendu par votre point de terminaison d'intégration.
1. Pour **Nom**, saisissez **DogsAge0**.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
Les étapes suivantes montrent comment vérifier que votre mappage de paramètres a été effectué avec succès.
**(Facultatif) Testez votre mappage de paramètres.**
1. Choisissez l’onglet **Test**. Vous devrez peut-être choisir la flèche droite pour afficher l’onglet.
1. Pour les en-têtes, saisissez **puppies:true**.
1. Sélectionnez **Tester)**.
1. Dans **Journaux**, le résultat doit se présenter comme suit :
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
Le paramètre d’en-tête de la demande est passé de `puppies` à `DogsAge0`.
------
#### [ 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: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
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 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## Exemple 2 : association de plusieurs paramètres de requête de méthode à différents paramètres de demande d’intégration
L’exemple suivant mappe le paramètre `methodRequestQueryParam` de la chaîne de requête de méthode à valeurs multiples au paramètre `integrationQueryParam` de la chaîne de requête de demande d’intégration, et mappe le paramètre d’en-tête `methodRequestHeaderParam` de la demande de méthode au paramètre de chemin `integrationPathParam` de la demande d’intégration.
------
#### [ AWS Management Console ]
**Pour mapper les paramètres de requête de méthode**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API REST.
1. Choisissez une méthode.
Votre méthode doit avoir une intégration sans proxy.
1. Pour **Paramètres de requête de méthode**, choisissez **Modifier**.
1. Choisissez **Paramètres de chaîne de requête d’URL**.
1. Sélectionnez **Add query string** (Ajouter une chaîne de requêtes).
1. Pour **Nom**, saisissez **methodRequestQueryParam**.
1. Développez **En-têtes de demande HTTP**.
1. Sélectionnez **Add header**.
1. Pour **Nom**, saisissez **methodRequestHeaderParam**.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Requête d’intégration**, puis dans la section **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Choisissez **paramètres de chemin d’URL**.
1. Choisissez **Ajouter un paramètre de chemin**.
1. Pour **Nom**, saisissez **integrationPathParam**.
1. Pour **Mappage à partir de**, entrez **method.request.header.methodRequestHeaderParam**.
Cette opération mappe l’en-tête de demande de méthode que vous avez spécifié dans la demande de méthode à un nouveau paramètre de chemin de la demande d’intégration.
1. Choisissez **Paramètres de chaîne de requête d’URL**.
1. Sélectionnez **Add query string** (Ajouter une chaîne de requêtes).
1. Pour **Nom**, saisissez **integrationQueryParam**.
1. Pour **Mappage à partir de**, entrez **method.request.multivaluequerystring.methodRequestQueryParam**.
Cette opération mappe le paramètre de chaîne de requête à valeurs multiples à un nouveau paramètre de chaîne de requête de demande d’intégration à valeur unique.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
------
#### [ 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.
La définition OpenAPI suivante crée les mappages de paramètres suivants pour une intégration HTTP :
+ l’en-tête de la demande de méthode, nommé `methodRequestHeaderParam`, avec le paramètre de chemin de la demande d’intégration, nommé `integrationPathParam` ;
+ la chaîne de requête de la demande de méthode à valeurs multiples, nommée `methodRequestQueryParam`, avec la chaîne de requête de la demande d’intégration, nommée `integrationQueryParam`.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
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 les mappages de paramètres suivants pour une intégration HTTP :
+ l’en-tête de la demande de méthode, nommé `methodRequestHeaderParam`, avec le paramètre de chemin de la demande d’intégration, nommé `integrationPathParam` ;
+ la chaîne de requête de la demande de méthode à valeurs multiples, nommée `methodRequestQueryParam`, avec la chaîne de requête de la demande d’intégration, nommée `integrationQueryParam`.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Exemple 3 : mappage de champs du corps de la demande JSON aux paramètres de la demande d’intégration
Vous pouvez également mapper les paramètres de demande d'intégration à partir des champs du corps de la demande JSON à l'aide d'une [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2). L’exemple suivant mappe le corps de la demande de méthode à un en-tête de la demande d’intégration nommé `body-header`, et mappe une partie du corps de la demande, tel qu’il est exprimé par une expression JSON, à un en-tête de la demande d’intégration nommé `pet-price`.
Pour tester cet exemple, fournissez une entrée contenant une catégorie de prix, par exemple :
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ AWS Management Console ]
**Pour mapper les paramètres de requête de méthode**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez une API REST.
1. Choisissez la méthode `POST`, `PUT`, `PATCH` ou `ANY`.
Votre méthode doit avoir une intégration sans proxy.
1. Pour **Paramètres de requête d’intégration**, choisissez **Modifier**.
1. Sélectionnez **Paramètres des en-têtes de requête d’URL**.
1. Sélectionnez **Ajouter un paramètre d’en-tête de requête**.
1. Pour **Nom**, saisissez **body-header**.
1. Pour **Mappage à partir de**, entrez **method.request.body**.
Cette opération mappe le corps de la demande de méthode à un nouveau paramètre d’en-tête de la demande d’intégration.
1. Sélectionnez **Ajouter un paramètre d’en-tête de requête**.
1. Pour **Nom**, saisissez **pet-price**.
1. Pour **Mappage à partir de**, entrez ** method.request.body[0].price**.
Cette opération mappe une partie du corps de la demande de méthode à un nouveau paramètre d’en-tête de la demande d’intégration.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
------
#### [ 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: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
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 mappe les paramètres de la demande d’intégration à partir des champs du corps de la demande JSON.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Exemple 4 : mappage de la réponse d’intégration à la réponse de méthode
Vous pouvez également mapper la réponse d’intégration à la réponse de méthode. L’exemple suivant mappe le corps de la réponse d’intégration à un en-tête de la réponse de méthode nommé `location`, mappe l’en-tête `x-app-id` de la réponse d’intégration à l’en-tête `id` de la réponse de méthode, et mappe l’en-tête à valeurs multiples `item` de la réponse d’intégration à l’en-tête `items` de la réponse de méthode.
------
#### [ AWS Management Console ]
**Pour mapper 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. Choisissez une API REST.
1. Choisissez une méthode.
Votre méthode doit avoir une intégration sans proxy.
1. Choisissez l’onglet **Méthode de réponse**, puis pour **Réponse 200**, sélectionnez **Modifier**.
1. Sous **Nom de l’en-tête**, choisissez **Ajouter un en-tête**.
1. Créez trois en-têtes nommés **id**, **item** et **location**.
1. Choisissez **Enregistrer**.
1. Choisissez l’onglet **Réponse d’intégration**, puis pour **Par défaut - Réponse**, choisissez **Modifier**.
1. Sous **Mappages d’en-tête**, saisissez ce qui suit.
1. Sous **ID**, saisissez **integration.response.header.x-app-id**.
1. Sous **Élément**, saisissez **integration.response.multivalueheader.item**.
1. Sous **Emplacement**, saisissez **integration.response.body.redirect.url**.
1. Choisissez **Enregistrer**.
1. Redéployez l’API pour que les modifications prennent effet.
------
#### [ 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: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
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 d’OpenAPI suivante mappe la réponse d’intégration à la réponse de méthode.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# Référence de source de mappage de paramètres pour REST APIs dans API Gateway
Lorsque vous créez un mappage de paramètres, vous spécifiez les paramètres de demande de méthode ou de réponse d’intégration à modifier, et indiquez comment modifier ces paramètres.
Le tableau suivant indique les paramètres de requête de méthode que vous pouvez mapper, ainsi que l’expression permettant ce mappage. Dans ces expressions, *name* est le nom d'un paramètre de demande de méthode. Par exemple, pour mapper le paramètre d’en-tête de demande `puppies`, utilisez l’expression `method.request.header.puppies`. Votre expression doit respecter le modèle d’expression régulière `'^[a-zA-Z0-9._$-]+$]'`. Vous pouvez utiliser le mappage de paramètres dans votre demande d’intégration pour des intégrations avec ou sans proxy.
| **Source de données mappée** | **Expression de mappage** |
| --- | --- |
| Chemin de la demande de méthode | method.request.path.name |
| Chaîne de requête de la demande de méthode | method.request.querystring.name |
| Chaîne de requête de la demande de méthode à valeurs multiples | method.request.multivaluequerystring.name |
| En-tête de la demande de méthode | method.request.header.name |
| En-tête de demande de méthode à valeurs multiples | method.request.multivalueheader.name |
| Corps de la demande de méthode | method.request.body |
| corps de la demande de méthode (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION*est une JSONPath expression pour un champ JSON du corps d'une demande. Pour plus d'informations, voir [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variables d’étape | stageVariables.name |
| Variables de contexte | `context.name` Le nom doit être l’une des [variables de contexte prises en charge](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valeur statique | `'static_value'`. *static\$1value*Il s'agit d'une chaîne littérale qui doit être placée entre guillemets simples. Par exemple, `'https://www.example.com'`. |
Le tableau suivant indique les paramètres de réponse d’intégration que vous pouvez mapper, ainsi que l’expression permettant ce mappage. Dans ces expressions, *name* est le nom d'un paramètre de réponse d'intégration. Vous pouvez mapper les paramètres d’en-tête d’une réponse de méthode à partir de n’importe quel en-tête ou corps de réponse d’intégration, de variables \$1context ou de valeurs statiques. Pour utiliser le mappage de paramètres pour une réponse d’intégration, il vous faut une intégration sans proxy.
| Source de données mappée | Expression de mappage |
| --- | --- |
| En-tête de réponse d’intégration | integration.response.header.name |
| En-tête de réponse d’intégration | integration.response.multivalueheader.name |
| Corps de réponse intégration | integration.response.body |
| Organisme de réponse à l'intégration (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION*est une JSONPath expression pour un champ JSON du corps d'une réponse. Pour plus d'informations, voir [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variable d’étape | stageVariables.name |
| Variable de contexte | `context.name` Le nom doit être l’une des [variables de contexte prises en charge](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valeur statique | ` 'static_value'` *static\$1value*Il s'agit d'une chaîne littérale qui doit être placée entre guillemets simples. Par exemple, `'https://www.example.com'`. |
# 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\":{}}"}
```
# Variables pour les transformations de données pour API Gateway
Lorsque vous créez un mappage de paramètres, vous pouvez utiliser les variables context comme source de données. Lorsque vous transformez un modèle de mappage, vous pouvez utiliser les variables context, input et util dans les scripts que vous écrivez en [langage VTL (Velocity Template Language)](https://velocity.apache.org/engine/devel/vtl-reference.html). Pour des exemples de modèles de mappage qui utilisent ces variables de référence, consultez [Exemples d’utilisation de variables pour transformer des modèles de mappage pour API Gateway](api-gateway-mapping-variable-examples.md).
Pour obtenir la liste des variables de référence pour la journalisation des accès, consultez [Variables pour la journalisation des accès pour API Gateway](api-gateway-variables-for-access-logging.md).
## Variables context pour les transformations de données
Vous pouvez utiliser les variables `$context` suivantes (sensibles à la casse) pour les transformations de données.
| Paramètre | Description |
| --- | --- |
| \$1context.accountId | ID de AWS compte du propriétaire de l'API. |
| \$1context.apiId | Identifiant qu’API Gateway attribue à votre API. |
| \$1context.authorizer.claims.property | Propriété des requêtes renvoyées depuis le groupe d’utilisateurs Amazon Cognito une fois que l’appelant de la méthode a été authentifié avec succès. Pour de plus amples informations, veuillez consulter [Contrôlez l'accès à REST APIs en utilisant les groupes d'utilisateurs Amazon Cognito comme autorisateur](apigateway-integrate-with-cognito.md). L’appel de `$context.authorizer.claims` renvoie la valeur null. |
| \$1context.authorizer.principalId | Identifiant utilisateur principal associé au jeton envoyé par le client et retourné par un mécanisme d’autorisation Lambda API Gateway (anciennement appelé Custom Authorizer). Pour de plus amples informations, veuillez consulter [Utilisation des mécanismes d’autorisation Lambda API Gateway](apigateway-use-lambda-authorizer.md). |
| \$1context.authorizer.property | Valeur obtenue à l’aide de stringify de la paire clé-valeur spécifiée du mappage `context` renvoyé par une fonction du mécanisme d’autorisation Lambda API Gateway. Par exemple, si le mécanisme d’autorisation retourne le mappage `context` suivant : "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} l’appel de `$context.authorizer.key` renvoie la chaîne `"value"`, l’appel de `$context.authorizer.numKey` renvoie la chaîne `"1"` et l’appel de `$context.authorizer.boolKey` renvoie la chaîne `"true"`. En effet*property*, le seul caractère spécial pris en charge est le trait de soulignement`(_)`. Pour de plus amples informations, veuillez consulter [Utilisation des mécanismes d’autorisation Lambda API Gateway](apigateway-use-lambda-authorizer.md). |
| \$1context.awsEndpointRequestId | ID de demande du AWS point de terminaison. |
| \$1context.deploymentId | ID de déploiement de l’API. |
| \$1context.domainName | Nom de domaine complet utilisé pour invoquer l’API. Il doit être identique à l’en-tête `Host` entrant. |
| \$1context.domainPrefix | Première étiquette de `$context.domainName`. |
| \$1context.error.message | Chaîne contenant un message d’erreur API Gateway. Cette variable ne peut être utilisée que pour une simple substitution de variables dans un modèle de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)mappage corporel, qui n'est pas traité par le moteur Velocity Template Language, et dans la journalisation des accès. Pour plus d’informations, consultez [Surveillez WebSocket l'exécution des API à l'aide de CloudWatch métriques](apigateway-websocket-api-logging.md) et [Configuration de réponses de passerelle pour personnaliser des réponses d’erreur](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.messageString | La valeur entre guillemets de \$1context.error.message, à savoir "\$1context.error.message". |
| \$1context.error.responseType | Un [type](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). Cette variable ne peut être utilisée que pour une simple substitution de variables dans un modèle de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)mappage corporel, qui n'est pas traité par le moteur Velocity Template Language, et dans la journalisation des accès. Pour plus d’informations, consultez [Surveillez WebSocket l'exécution des API à l'aide de CloudWatch métriques](apigateway-websocket-api-logging.md) et [Configuration de réponses de passerelle pour personnaliser des réponses d’erreur](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.validationErrorString | Chaîne contenant un message d’erreur de validation détaillé. |
| \$1context.extendedRequestId | L’ID généré et attribué par API Gateway à la demande d’API. L’ID de requête étendu contient des informations utiles pour le débogage et le dépannage. |
| \$1context.httpMethod | Méthode HTTP utilisée. Les valeurs valides sont les suivantes : `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` et `PUT`. |
| \$1context.identity.accountId | L'ID de AWS compte associé à la demande. |
| \$1context.identity.apiKey | Pour les méthodes d’API qui nécessitent une clé d’API, cette variable est la clé d’API associée à la demande de méthode. Pour les méthodes qui ne nécessitent aucune clé d’API, cette variable est null. Pour de plus amples informations, veuillez consulter [Plans d'utilisation et clés d'API pour REST APIs dans API Gateway](api-gateway-api-usage-plans.md). |
| \$1context.identity.apiKeyId | ID de la clé d’API associé à une demande d’API qui nécessite une clé d’API. |
| \$1context.identity.caller | Identifiant principal de l’appelant qui a signé la demande. Pris en charge pour les ressources qui utilisent l’autorisation IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Liste séparée par des virgules de tous les fournisseurs d’authentification Amazon Cognito utilisés par l’appelant à l’origine de la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Par exemple, pour une identité provenant d’un groupe d’utilisateurs Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Pour plus d’informations sur les fournisseurs d’authentification Amazon Cognito disponibles, consultez [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) dans le *Guide du développeur Amazon Cognito*. |
| \$1context.identity.cognitoAuthenticationType | Type d’authentification Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Les valeurs possibles incluent `authenticated` pour les identités authentifiées et `unauthenticated` pour les identités non authentifiées. |
| \$1context.identity.cognitoIdentityId | ID d’identité Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | ID de groupe d’identités Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. |
| \$1context.identity.principalOrgId | [ID d’organisation AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). |
| \$1context.identity.sourceIp | Adresse IP source de la connexion TCP immédiate envoyant la demande au point de terminaison API Gateway. |
| \$1context.identity.clientCert.clientCertPem | Certificat client codé PEM présenté par le client lors de l’authentification TLS mutuelle. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.clientCert.subjectDN | Nom distinctif de l’objet du certificat présenté par un client. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.clientCert.issuerDN | Nom distinctif de l’émetteur du certificat présenté par un client. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.clientCert.serialNumber | Numéro de série du certificat. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.clientCert.validity.notBefore | Date avant laquelle le certificat n’est pas valide. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.clientCert.validity.notAfter | Date après laquelle le certificat n’est pas valide. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. |
| \$1context.identity.vpcId | ID du VPC qui fait la demande au point de terminaison API Gateway. |
| \$1context.identity.vpceId | ID du point de terminaison de VPC qui envoie la demande au point de terminaison API Gateway. Présent uniquement lorsque vous disposez d’une API privée. |
| \$1context.identity.user | Identifiant principal de l’utilisateur qui sera autorisé à accéder aux ressources. Pris en charge pour les ressources qui utilisent l’autorisation IAM. |
| \$1context.identity.userAgent | En-tête [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) de l’appelant d’API. |
| \$1context.identity.userArn | ARN (Amazon Resource Name) de l’utilisateur identifié après l’authentification. Pour de plus amples informations, veuillez consulter [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). |
| \$1context.isCanaryRequest | Renvoie `true` si la demande a été dirigée vers le canary et `false` si la demande n’a pas été dirigée vers le canary. Présent uniquement lorsqu’un canary a été activé. |
| \$1context.path | Chemin d’accès de la demande. Par exemple, pour une URL de demande autre que de proxy de https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, la valeur \$1context.path est /\$1stage\$1/root/child. |
| \$1context.protocol | Protocole de demande, par exemple, HTTP/1.1. API Gateway APIs peut accepter les requêtes HTTP/2, mais API Gateway envoie des demandes aux intégrations de backend à l'aide du protocole HTTP/1.1. Par conséquent, le protocole de requête est enregistré comme HTTP/1.1 même si un client envoie une requête qui utilise HTTP/2. |
| \$1context.requestId | Un ID pour la demande. Les clients peuvent remplacer cet ID de demande. Utiliser `$context.extendedRequestId` pour un ID de demande unique généré par API Gateway. |
| \$1context.requestOverride.header.header\$1name | Remplacement de l’en-tête de la requête. Si ce paramètre est défini, il contient les en-têtes à utiliser à la place des **HTTP Headers (En-têtes HTTP)** qui sont définis dans le volet **Integration Request (Demande d’intégration)**. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.path.path\$1name | Remplacement du chemin de la requête. Si ce paramètre est défini, il contient le chemin de requête à utiliser à la place des **URL Path Parameters (Paramètres de chemin d’URL)** qui sont définis dans le volet **Integration Request (Demande d’intégration)**. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.querystring.querystring\$1name | Remplacement de la chaîne d’interrogation de la requête. Si ce paramètre est défini, il contient les chaînes d’interrogation de la requête à utiliser à la place des **URL Query String Parameters (Paramètres de chaîne de requête d’URL)** qui sont définis dans le volet **Integration Request (Demande d’intégration)**. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.header.header\$1name | Remplacement de l’en-tête de la réponse. Si ce paramètre est défini, il contient l’en-tête qui est renvoyé à la place du Response header (En-tête de réponse) qui est défini comme le Default mapping (Mappage par défaut) dans le volet Integration Response (Réponse d’intégration). Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.status | Remplacement du code de statut de la réponse. Si ce paramètre est défini, il contient le code du statut qui est renvoyé à la place du Method response status (Statut de la réponse de méthode) qui est défini comme le Default mapping (Mappage par défaut) dans le volet Integration Response (Réponse d’intégration). Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestTime | Durée des demandes au format [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | Heure de la demande au format [Epoch](https://en.wikipedia.org/wiki/Unix_time), en millisecondes. |
| \$1context.resourceId | Identifiant attribué par API Gateway à votre ressource. |
| \$1context.resourcePath | Chemin de votre ressource. Par exemple, pour l’URI de demande autre que de proxy de `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, la valeur `$context.resourcePath` est `/root/child`. Pour de plus amples informations, veuillez consulter [Didacticiel : création d’une API REST avec une intégration HTTP sans proxy](api-gateway-create-api-step-by-step.md). |
| \$1context.stage | Étape de déploiement de la demande d’API (par exemple, `Beta` ou `Prod`). |
| \$1context.wafResponseCode | Réponse reçue de [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` ou `WAF_BLOCK`. N’est pas défini si l’étape n’est pas associée à une liste ACL web. Pour de plus amples informations, veuillez consulter [AWS WAF À utiliser pour protéger votre REST APIs dans API Gateway](apigateway-control-access-aws-waf.md). |
| \$1context.webaclArn | ARN complet de la liste ACL web utilisée pour déterminer s’il convient d’autoriser ou de bloquer la demande. N’est pas défini si l’étape n’est pas associée à une liste ACL web. Pour de plus amples informations, veuillez consulter [AWS WAF À utiliser pour protéger votre REST APIs dans API Gateway](apigateway-control-access-aws-waf.md). |
## Variables d’entrée
Vous pouvez utiliser les variables `$input` suivantes (sensibles à la casse) pour faire référence aux données utiles et aux paramètres de la demande de méthode. Les fonctions suivantes sont disponibles :
| Variable et fonction | Description |
| --- | --- |
| \$1input.body | Renvoie la charge utile de la demande brute sous forme de chaîne. Vous pouvez utiliser `$input.body` pour conserver des nombres à virgule flottante entiers, tels que `10.00`. |
| \$1input.json(x) | Cette fonction évalue une JSONPath expression et renvoie les résultats sous forme de chaîne JSON. Par exemple, `$input.json('$.pets')` renvoie une chaîne JSON représentant la structure `pets`. Pour plus d'informations sur JSONPath, voir [JSONPath](https://goessner.net/articles/JsonPath/)ou [JSONPath pour Java](https://github.com/json-path/JsonPath). |
| \$1input.params() | Renvoie une carte de tous les paramètres de demande. Nous vous recommandons d’utiliser `$util.escapeJavaScript` pour désinfecter le résultat afin d’éviter une attaque potentielle par injection. Pour un contrôle total de la désinfection des requêtes, utilisez une intégration proxy sans modèle et gérez la désinfection des requêtes dans votre intégration. |
| \$1input.params(x) | Renvoie la valeur d’un paramètre de demande de méthode à partir du chemin, de la chaîne de requête ou d’une valeur d’en-tête (dans cet ordre) avec une chaîne de nom de paramètre `x`. Nous vous recommandons d’utiliser `$util.escapeJavaScript` pour désinfecter le paramètre afin d’éviter une attaque potentielle par injection. Pour un contrôle total de la désinfection des paramètres, utilisez une intégration proxy sans modèle et gérez la désinfection des requêtes dans votre intégration. |
| \$1input.path(x) | Prend une chaîne JSONPath d'expression (`x`) et renvoie une représentation du résultat sous forme d'objet JSON. Cela vous permet d’accéder aux éléments de la charge utile et de les manipuler en mode natif en [langage VTL (Apache Velocity Template Language)](https://velocity.apache.org/engine/devel/vtl-reference.html). Par exemple, si l’expression `$input.path('$.pets')` renvoie un objet comme suit : [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').size()` renvoie `"3"`. Pour plus d'informations sur JSONPath, voir [JSONPath](https://goessner.net/articles/JsonPath/)ou [JSONPath pour Java](https://github.com/json-path/JsonPath). |
## Variables d’étape
Vous pouvez utiliser les variables d'étape suivantes comme espaces réservés pour ARNs et URLs dans les intégrations de méthodes. Pour de plus amples informations, veuillez consulter [Utilisation de variables d’étape pour une API REST dans API Gateway](stage-variables.md).
| Syntaxe | Description |
| --- | --- |
| \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'] ou \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name*représente le nom d'une variable d'étape. |
## Variables util
Vous pouvez utiliser les variables util `$util` suivantes (sensibles à la casse) pour les modèles de mappage. Sauf indication contraire, le jeu de caractères par défaut est UTF-8.
| Fonction | Description |
| --- | --- |
| \$1util.escapeJavaScript() | Échape les caractères d'une chaîne en utilisant des règles de JavaScript chaîne. Cette fonction convertit tout guillemet simple (`'`) en guillemet d’échappement (`\'`). Cependant, les guillemets simples d’échappement ne sont pas valides en JSON. Par conséquent, lorsque la sortie de cette fonction est utilisée dans une propriété JSON, vous devez reconvertir les guillemets simples d’échappement (`\'`) en guillemets simples (`'`), comme illustré dans l’exemple suivant : "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")" |
| \$1util.parseJson() | Prend la chaîne JSON (obtenue à l’aide de stringify) et renvoie une représentation objet du résultat. Vous pouvez utiliser le résultat de cette fonction pour accéder aux éléments de la charge utile et les manipuler en mode natif en langage VTL (Apache Velocity Template Language). Par exemple, si vous avez la charge utile suivante : {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} et utilisez le modèle de mappage suivant : #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
vous obtenez la sortie suivante : {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | Convertit une chaîne au format « application/ x-www-form-urlencoded ». |
| \$1util.urlDecode() | Décode une chaîne « application/ x-www-form-urlencoded ». |
| \$1util.base64Encode() | Encode les données dans une chaîne encodée en base64. |
| \$1util.base64Decode() | Décode les données d’une chaîne encodée en base64. |