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. # 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. |