Guide de référence du mappage des données de demande d'API et de réponse Amazon API Gateway

Cette section explique comment configurer les mappages de données de demande de méthode d'une API, y compris des autres données stockées dans les variables context, stage ou util, aux paramètres de demande d'intégration correspondants et les mappages de données de réponse d'intégration, y compris des autres données, aux paramètres de réponse de méthode. Les données de la demande de méthode incluent le corps et les paramètres de la demande (chemin, chaîne de requête, en-têtes). Les données de réponse d'intégration incluent les paramètres de réponse (en-têtes) et le corps. Pour plus d'informations sur l'utilisation des variables d'étape, consultez Référence des variables d'étape Amazon API Gateway.

Rubriques

• Mappage des données de demande de méthode aux paramètres de demande d'intégration
• Mappage des données de réponse d'intégration aux en-têtes de réponse de méthode
• Mappage des charges utiles de demande et de réponse entre méthode et intégration
• Comportements de transfert direct

Mappage des données de demande de méthode aux paramètres de demande d'intégration

Les paramètres de demande d'intégration, sous forme de variables de chemin, de chaînes de requête ou d'en-têtes, peuvent être mappés à partir de n'importe quels paramètres de demande de méthode définis et de la charge utile.

Dans le tableau suivant, PARAM_NAME est le nom d'un paramètre de demande de méthode du type de paramètre donné. Il doit respecter le modèle d'expression régulière '^[a-zA-Z0-9._$-]+$]'. Il doit être défini avant de pouvoir être référencé. JSONPath_EXPRESSION est une expression JSONPath pour un champ JSON du corps d'une demande ou une réponse.

Note

Le préfixe "$" est omis dans cette syntaxe.

Expressions de mappage de données de demande d'intégration
Source de données mappée	Expression de mappage
Chemin de la demande de méthode	method.request.path.PARAM_NAME
Chaîne de requête de la demande de méthode	method.request.querystring.PARAM_NAME
Chaîne de requête de la demande de méthode à valeurs multiples	method.request.multivaluequerystring.PARAM_NAME
En-tête de la demande de méthode	method.request.header.PARAM_NAME
En-tête de demande de méthode à valeurs multiples	method.request.multivalueheader.PARAM_NAME
Corps de la demande de méthode	method.request.body
corps de la demande de méthode (JsonPath)	method.request.body.JSONPath_EXPRESSION.
Variables d'étape	stageVariables.VARIABLE_NAME
Variables de contexte	context.VARIABLE_NAME qui doit être l'une des variables de contexte prises en charge.
Valeur statique	'STATIC_VALUE'. La valeur STATIC_VALUE est un littéral de chaîne qui doit être délimité par des guillemets simples.

Exemple Mappages du paramètre de demande de méthode au format OpenAPI

L'exemple suivant montre un extrait de code OpenAPI qui mappe :

• l'en-tête de la demande de méthode, nommé methodRequestHeaderParam, au 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, à la chaîne de requête de la demande d'intégration, nommée integrationQueryParam.

...
"requestParameters" : {
            
    "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam",        
    "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam"
            
}
...
                
            

Les paramètres de demande d'intégration peuvent également être mappés à partir des champs du corps de la demande JSON à l'aide d'une expression JSONPath. Le tableau suivant présente les expressions de mappage pour le corps d'une demande de méthode et ses champs JSON.

Exemple Mappage du corps d'une demande de méthode au format OpenAPI

L'exemple suivant présente un extrait de code OpenAPI qui mappe 1) le corps d'une demande de méthode à l'en-tête de demande d'intégration, nommé body-header, et 2) un champ JSON du corps, spécifié par une expression JSON (petstore.pets[0].name, sans le préfixe $.).

...
"requestParameters" : {
            
    "integration.request.header.body-header" : "method.request.body",
    "integration.request.path.pet-name" : "method.request.body.petstore.pets[0].name",
            
}
...
                
            

Mappage des données de réponse d'intégration aux en-têtes de réponse de méthode

Les paramètres d'en-tête de réponse de méthode peuvent être mappés à partir de n'importe quel en-tête de réponse d'intégration ou corps de réponse d'intégration, variables, $context, ou valeurs statiques.

Expressions de mappage d'en-tête de réponse de méthode
Source de données mappée	Expression de mappage
En-tête de réponse d'intégration	integration.response.header.PARAM_NAME
En-tête de réponse d'intégration	integration.response.multivalueheader.PARAM_NAME
Corps de réponse intégration	integration.response.body
Organisme de réponse à l'intégration (JsonPath)	integration.response.body.JSONPath_EXPRESSION
Variable d'étape	stageVariables.VARIABLE_NAME
Variable de contexte	context.VARIABLE_NAME qui doit être l'une des variables de contexte prises en charge.
Valeur statique	'STATIC_VALUE'. La valeur STATIC_VALUE est un littéral de chaîne qui doit être délimité par des guillemets simples.

Exemple Mappage de données à partir d'une réponse d'intégration au format OpenAPI

L'exemple suivant présente un extrait de code OpenAPI qui mappe 1) la valeur redirect.url de la réponse d'intégration, le champ JSONPath dans l'en-tête location de la réponse de demande ; et 2) l'en-tête x-app-id de la réponse intégration à l'en-tête id de la réponse de méthode.

...
"responseParameters" : {
            
    "method.response.header.location" : "integration.response.body.redirect.url",
    "method.response.header.id" : "integration.response.header.x-app-id",
    "method.response.header.items" : "integration.response.multivalueheader.item",
            
}
...
                
            

Mappage des charges utiles de demande et de réponse entre méthode et intégration

API Gateway utilise un moteur VTL (Velocity Template Language) pour traiter des modèles de mappage de corps pour la demande d'intégration et la réponse d'intégration. Les modèles de mappage convertissent les charges utiles de demande de méthode en les charges utiles de demande d'intégration correspondantes, et les corps de réponse d'intégration en corps de réponse de méthode.

Les modèles VTL utilisent des expressions JSONPath, d'autres paramètres comme des contextes d'appel et des variables d'étape, ainsi que des fonctions d'utilitaire pour traiter les données JSON.

Si un modèle est défini pour décrire la structure de données d'une charge utile, API Gateway peut utiliser le modèle pour générer un squelette de modèle de mappage pour une demande d'intégration ou une réponse d'intégration. Vous pouvez utiliser le squelette de modèle pour vous aider à personnaliser et étendre le script VTL de mappage. Cependant, vous pouvez créer un modèle de mappage à partir de zéro sans définir de modèle la structure de données de la charge utile.

Sélection d'un modèle de mappage VTL

API Gateway utilise la logique suivante pour sélectionner un modèle de mappage, dans Velocity Template Language (VTL), pour mapper la charge utile d'une demande de méthode à la demande d'intégration correspondante ou pour mapper la charge utile d'une réponse d'intégration à la réponse de méthode correspondante.

Pour une charge utile de demande, API Gateway utilise la valeur d'en-tête Content-Type de la demande en tant que clé pour sélectionner le modèle de mappage de la charge utile de demande. Pour une charge utile de réponse, API Gateway utilise la valeur d'en-tête Accept de la demande entrante en tant que clé pour sélectionner le modèle de mappage.

Lorsque l'en-tête Content-Type est absent dans la demande, API Gateway part du principe que sa valeur par défaut est application/json. Pour une telle demande, API Gateway utilise application/json comme clé par défaut pour sélectionner le modèle de mappage, s'il est défini. Lorsqu'aucun modèle ne correspond à cette clé, API Gateway transmet la charge utile via un contenu non mappé si la propriété passthroughBehavior est définie sur WHEN_NO_MATCH ou WHEN_NO_TEMPLATES.

Lorsque l'en-tête Accept n'est pas spécifié dans la demande, API Gateway part du principe que sa valeur par défaut est application/json. Dans ce cas, API Gateway sélectionne un modèle de mappage existant pour que application/json mappe la charge utile de réponse. Si aucun modèle n'est défini pour application/json, API Gateway sélectionne le premier modèle existant et l'utilise comme modèle par défaut pour mapper la charge utile de réponse. De même, API Gateway utilise le premier modèle existant lorsque la valeur d'en-tête Accept spécifiée ne correspond pas à une clé de modèle existante. Si aucun modèle n'est défini, API Gateway transmet simplement la charge utile de réponse via un contenu non mappé.

Supposons, par exemple, qu'une API a un modèle application/json défini pour une charge utile de demande et un modèle application/xml défini pour la charge utile de réponse. Si le client définit les en-têtes "Content-Type : application/json" et "Accept : application/xml" dans la demande, les charges utiles de demande et de réponse seront traitées avec les modèles de mappage correspondants. Si l'en-tête Accept:application/xml est absent, le modèle de mappage application/xml sera utilisé pour mapper la charge utile de réponse. Pour renvoyer la charge utile de réponse non mappé à la place, vous devez configurer un modèle vide pour application/json.

Seul le type MIME est utilisé dans les en-têtes Accept et Content-Type lors de la sélection d'un modèle de mappage. Par exemple, pour un en-tête "Content-Type: application/json; charset=UTF-8", un modèle de demande avec la clé application/json sera sélectionné.