Modèle de mappage API Gateway et référence à la variable de journalisation des accès - Amazon API Gateway

Modèle de mappage API Gateway et référence à la variable de journalisation des accès

Cette section fournit des informations de référence relatives aux variables et aux fonctions définies par Amazon API Gateway pour être utilisées avec des modèles de données, des mécanismes d'autorisation, des modèles de mappage et la journalisation des accès de CloudWatch. Pour obtenir des informations détaillées sur l'utilisation de ces variables et fonctions, consultez Utilisation de modèles et de modèles de mappage.

$context Variables des modèles de données, des mécanismes d'autorisation, des modèles de mappage et de la journalisation des accès de CloudWatch.

Les variables $context ci-après peuvent être utilisées dans les modèles de données, les mécanismes d'autorisation, les modèles de mappage et la journalisation des accès de CloudWatch.

Pour les variables $context qui peuvent être utilisées uniquement dans la journalisation des accès de CloudWatch, veuillez consulter Variables $context pour la journalisation des accès uniquement.

Paramètre Description
$context.accountId

ID du compte AWS du propriétaire de l'API.

$context.apiId

Identifiant qu'API Gateway attribue à votre API.

$context.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 plus d'informations, consultez Contrôle de l'accès à une API REST à l'aide de groupes d'utilisateurs Amazon Cognito en tant que mécanisme d'autorisation.

Note

L'appel de $context.authorizer.claims renvoie la valeur null.

$context.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é mécanisme d'autorisation personnalisée). Pour plus d'informations, consultez Utilisation des mécanismes d'autorisation Lambda API Gateway.

$context.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".

Pour plus d'informations, consultez Utilisation des mécanismes d'autorisation Lambda API Gateway.

$context.awsEndpointRequestId

ID de demande du point de terminaison AWS.

$context.domainName

Nom de domaine complet utilisé pour invoquer l'API. Il doit être identique à l'en-tête Host entrant.

$context.domainPrefix

Première étiquette de $context.domainName. Elle est souvent utilisée en tant qu'identifiant de l'appelant/du client.

$context.error.message

Chaîne contenant un message d'erreur API Gateway. Cette variable peut uniquement être utilisée pour les substitutions de variables simples dans un modèle de mappage de corps GatewayResponse qui n'est pas traité par le moteur VTL (Velocity Template Language) et pour la journalisation des accès. Pour de plus amples informations, veuillez consulter Surveillance de l'exécution de l'API WebSocket avec les métriques CloudWatch et Configuration de réponses de passerelle pour personnaliser des réponses d'erreur.

$context.error.messageString La valeur entre guillemets de $context.error.message, à savoir "$context.error.message".
$context.error.responseType

Type de GatewayResponse. Cette variable peut uniquement être utilisée pour les substitutions de variables simples dans un modèle de mappage de corps GatewayResponse qui n'est pas traité par le moteur VTL (Velocity Template Language) et pour la journalisation des accès. Pour plus d'informations, consultez Surveillance de l'exécution de l'API WebSocket avec les métriques CloudWatch et Configuration de réponses de passerelle pour personnaliser des réponses d'erreur.

$context.error.validationErrorString

Chaîne contenant un message d'erreur de validation détaillé.

$context.extendedRequestId ID étendu attribué par API Gateway à la demande d'API, qui contient davantage d'informations utiles pour le débogage et le dépannage.
$context.httpMethod

Méthode HTTP utilisée. Les valeurs valides sont les suivantes : DELETE, GET, HEAD, OPTIONS, PATCH, POST et PUT.

$context.identity.accountId

ID de compte AWS associé à la demande.

$context.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 plus d'informations, consultez Création et utilisation de plans d'utilisation avec des clés d'API.

$context.identity.apiKeyId ID de la clé d'API associé à une demande d'API qui nécessite une clé d'API.
$context.identity.caller

Identifiant principal de l'appelant qui a signé la demande. Pris en charge pour les ressources qui utilisent l'autorisation IAM.

$context.identity.cognitoAuthenticationProvider

Liste séparée par des virgules des 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 pool 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 de plus amples informations, veuillez consulter Utilisation des identités fédérées dans le Manuel du développeur Amazon Cognito.

$context.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.

$context.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.

$context.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.

$context.identity.principalOrgId

ID AWS organization.

$context.identity.sourceIp

L'adresse IP source de la connexion TCP envoyant la demande au point de terminaison de l'API Gateway.

$context.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.

$context.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.

$context.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.

$context.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.

$context.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.

$context.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.

$context.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.

$context.identity.userAgent

En-tête User-Agent de l'appelant d'API.

$context.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.

$context.path Chemin d'accès de la demande. Par exemple, pour une URL de demande autre que de proxy de https://{rest-api-id.execute-api.{region}.amazonaws.com/{stage}/root/child, la valeur $context.path est /{stage}/root/child.
$context.protocol Protocole de demande, par exemple HTTP/1.1.
$context.requestId

ID attribué par API Gateway à la demande d'API.

$context.requestOverride.header.header_name

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 Utiliser un modèle de mappage pour substituer les codes de statut et paramètres des requêtes et réponses d'une API.

$context.requestOverride.path.path_name

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 Utiliser un modèle de mappage pour substituer les codes de statut et paramètres des requêtes et réponses d'une API.

$context.requestOverride.querystring.querystring_name

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 Utiliser un modèle de mappage pour substituer les codes de statut et paramètres des requêtes et réponses d'une API.

$context.responseOverride.header.header_name 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 Utiliser un modèle de mappage pour substituer les codes de statut et paramètres des requêtes et réponses d'une API.
$context.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 Utiliser un modèle de mappage pour substituer les codes de statut et paramètres des requêtes et réponses d'une API.
$context.requestTime Durée des demandes au format CLF (dd/MMM/yyyy:HH:mm:ss +-hhmm).
$context.requestTimeEpoch Heure de la demande au format Epoch, en millisecondes.
$context.resourceId

Identifiant attribué par API Gateway à votre ressource.

$context.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 Tutoriel : Création d'une API REST avec une intégration HTTP autre que de proxy.

$context.stage

Étape de déploiement de la demande d'API (par exemple, Beta ou Prod).

$context.wafResponseCode

Réponse reçue du service AWS WAF : WAF_ALLOW ou WAF_BLOCK. N'est pas défini si l'étape n'est pas associée à une liste ACL web. Pour plus d'informations, consultez Utilisation d'AWS WAF pour protéger vos API.

$context.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 plus d'informations, consultez Utilisation d'AWS WAF pour protéger vos API.

Exemple de modèle de variable $context

Il peut s'avérer judicieux d'utiliser des variables $context dans un modèle de mappage si votre méthode d'API transmet des données structurées à un backend qui nécessite que les données aient un format particulier.

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 :

Note

Notez que l'une des variables est une clé d'API. Dans cet exemple, on suppose que l'exigence d'une clé d'API est activée pour la méthode.

{ "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" }

Variables $context pour la journalisation des accès uniquement

Les variables $context ci-après sont disponibles uniquement pour la journalisation des accès Pour plus d'informations, consultez Configuration de la journalisation CloudWatch pour une API REST dans API Gateway. (Pour les API WebSocket, consultez Surveillance de l'exécution de l'API WebSocket avec les métriques CloudWatch.)

Paramètre Description
$context.authorize.error Message d'erreur d'autorisation.
$context.authorize.latency Latence d'autorisation en millisecondes.
$context.authorize.status Code d'état renvoyé à la suite d'une tentative d'autorisation.
$context.authorizer.error Message d'erreur renvoyé par un mécanisme d'autorisation.
$context.authorizer.integrationLatency Latence du mécanisme d'autorisation en millisecondes (ms).
$context.authorizer.integrationStatus Code d'état renvoyé par un mécanisme d'autorisation Lambda.
$context.authorizer.latency Latence du mécanisme d'autorisation en millisecondes (ms).
$context.authorizer.requestId ID de demande du point de terminaison AWS.
$context.authorizer.status Code d'état renvoyé par un mécanisme d'autorisation.
$context.authenticate.error Message d'erreur renvoyé à la suite d'une tentative d'authentification.
$context.authenticate.latency Latence d'authentification en millisecondes.
$context.authenticate.status Code d'état renvoyé à la suite d'une tentative d'authentification.
$context.customDomain.basePathMatched

Chemin d'accès d'un mappage d'API correspondant à une demande entrante. Applicable lorsqu'un client utilise un nom de domaine personnalisé pour accéder à une API. Par exemple, si un client envoie une demande à https://api.example.com/v1/orders/1234 et que cette demande correspond au mappage d'API dont le chemin d'accès est v1/orders, la valeur est v1/orders. Pour en savoir plus, consultez la section Utilisation des mappages d'API pour les API REST.

$context.integration.error Message d'erreur renvoyé à partir d'une intégration. Équivalent à $context.integrationErrorMessage.
$context.integration.integrationStatus Pour l'intégration de proxy Lambda, code d'état renvoyé par AWS Lambda et non par le code de fonction Lambda du backend.
$context.integration.latency Latence d'intégration en millisecondes (ms). Équivalent à $context.integrationLatency.
$context.integration.requestId ID de demande du point de terminaison AWS. Équivalent à $context.awsEndpointRequestId.
$context.integration.status Code d'état renvoyé à partir d'une intégration. Pour les intégrations de proxy Lambda, code d'état que votre code de fonction Lambda renvoie. Équivalent à $context.integrationStatus.
$context.integrationErrorMessage

Chaîne contenant un message d'erreur d'intégration.

$context.integrationLatency Latence d'intégration en millisecondes (ms).
$context.integrationStatus Pour l'intégration de proxy Lambda, ce paramètre renvoie le code d'état renvoyé par AWS Lambda et non par le code de fonction Lambda du backend.
$context.responseLatency Latence de la réponse en millisecondes (ms).
$context.responseLength Longueur de la charge utile de la réponse.
$context.status Statut de la réponse de la méthode.
$context.waf.error Message d'erreur renvoyé par AWS WAF.
$context.waf.latency Latence AWS WAF en millisecondes.
$context.waf.status Code d'état renvoyé par AWS WAF
$context.xrayTraceId

ID du suivi X-Ray. Pour plus d'informations, consultez Configuration d'AWS X-Ray avec les API REST d'API Gateway.

Variables $input

La variable $input représente la charge utile de la demande de méthode et les paramètres devant être traités par un modèle de mappage. Elle fournit quatre fonctions :

Variable et fonction Description
$input.body

Renvoie la charge utile de la demande brute sous forme de chaîne.

$input.json(x)

Cette fonction évalue une expression JSONPath et renvoie les résultats sous la forme une chaîne JSON.

Par exemple, $input.json('$.pets') renvoie une chaîne JSON représentant la structure pets.

Pour plus d'informations sur JSONPath, consultez JSONPath ou JSONPath pour Java.

$input.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.

$input.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.

$input.path(x)

Prend une chaîne d'expression JSONPath (x) et renvoie une représentation d'objet JSON du résultat. 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).

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').count() renvoie "3".

Pour plus d'informations sur JSONPath, consultez JSONPath ou JSONPath pour Java.

Exemples de modèles de variable $input

Exemple de modèle de mappage de paramètres

L'exemple de mappage de paramètres suivant transmet tous les paramètres, y compris path, querystring et header, au point de terminaison d'intégration via une charge utile 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 } }

En effet, ce modèle de mappage fournit tous les paramètres de demande dans la charge utile, comme illustré ci-dessous :

{ "params" : { "path" : { "path_name" : "path_value", ... } "header" : { "header_name" : "header_value", ... } "querystring" : { "querystring_name" : "querystring_value", ... } } }

Vous pouvez utiliser la variable $input pour obtenir les chaînes de requête et le corps de la demande avec ou sans l'aide de modèles. Vous souhaiterez peut-être également obtenir le paramètre et la charge utile, ou une sous-section de la charge utile, dans votre fonction Lambda. Les exemples suivants illustrent la marche à suivre.

Exemple de modèle de mappage JSON utilisant $input

L'exemple suivant montre comment utiliser un mappage pour lire un nom à partir de la chaîne de requête, puis inclure l'intégralité du corps POST dans un élément :

{ "name" : "$input.params('name')", "body" : $input.json('$') }

Si les données d'entrée JSON contiennent des caractères sans séquence d'échappement qui ne peuvent pas être analysés par JavaScript, une réponse 400 peut être renvoyée. L'application de la fonction $util.escapeJavaScript($input.json('$')) ci-dessus garantit que les données d'entrée JSON peuvent être analysées correctement.

Exemple de modèle de mappage utilisant $input

L'exemple suivant montre comment transmettre une expression JSONPath à la méthode json(). Vous pouvez également lire une propriété spécifique de l'objet corps de votre demande en utilisant un point (.), suivi de votre nom de propriété :

{ "name" : "$input.params('name')", "body" : $input.json('$.mykey') }

Si la charge utile d'une demande de méthode contient des caractères sans séquence d'échappement qui ne peuvent pas être analysés par JavaScript, vous pouvez obtenir une réponse 400. Dans ce cas, vous devez appeler la fonction $util.escapeJavaScript() dans le modèle de mappage, comme illustré ci-dessous :

{ "name" : "$input.params('name')", "body" : $util.escapeJavaScript($input.json('$.mykey')) }

Exemple de demande et de réponse utilisant $input

Voici un exemple qui utilise les trois fonctions :

Modèle de demande :

Resource: /things/{id} With input template: { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : $util.escapeJavaScript($input.json('$.things')) } POST /things/abc { "things" : { "1" : {}, "2" : {}, "3" : {} } }

Réponse:

{ "id": "abc", "count": "3", "things": { "1": {}, "2": {}, "3": {} } }

Pour plus d'exemples de mappage, consultez Utilisation de modèles et de modèles de mappage.

$stageVariables

Les variables d'étape peuvent être utilisées dans le mappage des paramètres et les modèles de mappage, et comme espaces réservés dans les ARN et les URL utilisés dans les intégrations de méthode. Pour plus d'informations, consultez Configuration de variables d'étape pour le déploiement d'API REST.

Syntaxe Description
$stageVariables.<variable_name>

<variable_name> représente un nom de variable d'étape.

$stageVariables['<variable_name>']

<variable_name> représente n'importe quel nom de variable d'étape.

${stageVariables['<variable_name>']}

<variable_name> représente n'importe quel nom de variable d'étape.

Variables $util

La variable $util contient les fonctions utilitaires à utiliser dans les modèles de mappage.

Note

Sauf indication contraire, le jeu de caractères par défaut est UTF-8.

Fonction Description
$util.escapeJavaScript()

Place les caractères dans une séquence d'échappement dans une chaîne à l'aide de règles de chaîne JavaScript.

Note

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 :

$util.escapeJavaScript(data).replaceAll("\\'","'")
$util.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 }
$util.urlEncode()

Convertit une chaîne au format « application/x-www-form-urlencoded ».

$util.urlDecode()

Décode une chaîne « application/x-www-form-urlencoded ».

$util.base64Encode()

Encode les données dans une chaîne encodée en base64.

$util.base64Decode()

Décode les données d'une chaîne encodée en base64.