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

Mode de mise au point

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

$contextVariables pour les modèles de données, les autorisateurs, les modèles de mappage et la journalisation des CloudWatch accès Exemple de modèle de variable $context Variables $context pour la journalisation des accès uniquement Variables $input Exemples de modèles de variable $input $stageVariables Variables $util

Cette section fournit des informations de référence sur les variables et les fonctions définies par Amazon API Gateway pour une utilisation avec les modèles de données, les autorisateurs, les modèles de mappage et la journalisation des CloudWatch accès. Pour obtenir des informations détaillées sur l’utilisation de ces variables et fonctions, consultez Modèles de mappage pour REST APIs. Pour plus d’informations sur le Velocity Template Language (VTL), consultez la Référence VTL.

Rubriques

$contextVariables pour les modèles de données, les autorisateurs, les modèles de mappage et la journalisation des CloudWatch accès
Exemple de modèle de variable $context
Variables $context pour la journalisation des accès uniquement
Variables $input
Exemples de modèles de variable $input
$stageVariables
Variables $util

Note

Pour les variables $method et $integration, consultez Guide de référence du mappage des données de demande d’API et de réponse Amazon API Gateway.

`$context`Variables pour les modèles de données, les autorisateurs, les modèles de mappage et la journalisation des CloudWatch accès

Les $context variables suivantes peuvent être utilisées dans les modèles de données, les autorisateurs, les modèles de mappage et la journalisation des CloudWatch accès. API Gateway peut ajouter des variables contextuelles supplémentaires.

Pour les $context variables qui ne peuvent être utilisées que dans la journalisation des CloudWatch accès, voirVariables $context pour la journalisation des accès uniquement.

Paramètre	Description
`$context.accountId`	ID de AWS compte 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 de plus amples informations, veuillez consulter Contrôle de l’accès aux 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é Custom Authorizer). Pour de plus amples informations, veuillez consulter 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"`. 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.
`$context.awsEndpointRequestId`	ID de demande du AWS point de terminaison.
`$context.deploymentId`	ID de déploiement de l’API.
`$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`.
`$context.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 GatewayResponsemappage corporel, qui n'est pas traité par le moteur Velocity Template Language, et dans 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.messageString`	La valeur entre guillemets de `$context.error.message`, à savoir `"$context.error.message"`.
`$context.error.responseType`	Un type de GatewayResponse. Cette variable ne peut être utilisée que pour une simple substitution de variables dans un modèle de GatewayResponsemappage corporel, qui n'est pas traité par le moteur Velocity Template Language, et dans 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`	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.
`$context.httpMethod`	Méthode HTTP utilisée. Les valeurs valides sont les suivantes : `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` et `PUT`.
`$context.identity.accountId`	L'ID de AWS compte 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 de plus amples informations, veuillez consulter Plans d'utilisation et clés d'API pour REST APIs dans API Gateway.
`$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 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 dans le Guide 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 d’organisation AWS.
`$context.identity.sourceIp`	Adresse IP source de la connexion TCP immédiate envoyant la demande au point de terminaison 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.vpcId`	ID du VPC qui fait la demande au point de terminaison API Gateway.
`$context.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.
`$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.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é.
`$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`. Note 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.
`$context.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.
`$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 Didacticiel : création d’une API REST avec une intégration HTTP sans proxy.
`$context.stage`	Étape de déploiement de la demande d’API (par exemple, `Beta` ou `Prod`).
`$context.wafResponseCode`	Réponse reçue de 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 de plus amples informations, veuillez consulter AWS WAF À utiliser pour protéger votre REST APIs dans API Gateway.
`$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 de plus amples informations, veuillez consulter AWS WAF À utiliser pour protéger votre REST APIs dans API Gateway.

Exemple de modèle de variable `$context`

Vous pouvez 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

L’une des variables est une clé d’API. Dans cet exemple, on suppose que la méthode exige une clé d’API.


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

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 de plus amples informations, veuillez consulter Configuration de la CloudWatch journalisation pour REST APIs dans API Gateway. (Pour WebSocket APIs, voirSurveillance 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 de statut 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 d’intégration du mécanisme d’autorisation en millisecondes (ms).
`$context.authorizer.integrationStatus`	Code de statut 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 AWS point de terminaison.
`$context.authorizer.status`	Code de statut 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 de statut 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 Associer les étapes de l'API à un nom de domaine personnalisé pour REST APIs.
`$context.endpointType`	Type de point de terminaison de l’API.
`$context.integration.error`	Message d’erreur renvoyé à partir d’une intégration.
`$context.integration.integrationStatus`	Pour l'intégration du proxy Lambda, le code d'état est renvoyé par le code de fonction Lambda principal AWS Lambda, et non par le code de fonction Lambda principal.
`$context.integration.latency`	Latence d’intégration en millisecondes (ms). Équivalent à `$context.integrationLatency`.
`$context.integration.requestId`	ID de demande du AWS point de terminaison. Équivalent à `$context.awsEndpointRequestId`.
`$context.integration.status`	Code de statut renvoyé à partir d’une intégration. Pour les intégrations de proxy Lambda, code de statut que votre code de fonction Lambda renvoie.
`$context.integrationLatency`	Latence d’intégration en millisecondes (ms).
`$context.integrationStatus`	Pour l'intégration du proxy Lambda, ce paramètre représente le code d'état renvoyé par le code de fonction Lambda principal AWS Lambda, et non par le code de fonction Lambda principal.
`$context.responseLatency`	Latence de la réponse en millisecondes (ms).
`$context.responseLength`	La longueur de la charge utile de la réponse en octets.
`$context.status`	Statut de la réponse de la méthode.
`$context.waf.error`	Le message d'erreur renvoyé par AWS WAF.
`$context.waf.latency`	La AWS WAF latence en ms.
`$context.waf.status`	Le code d'état renvoyé par AWS WAF.
`$context.xrayTraceId`	ID du suivi X-Ray. Pour de plus amples informations, veuillez consulter Configuration AWS X-Ray avec API Gateway REST APIs.

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 les fonctions suivantes :

Variable et fonction	Description
`$input.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`.
`$input.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 JSONPathou 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 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). 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 JSONPathou JSONPath pour Java.

Exemples de modèles de variable `$input`

Les exemples suivants montrent comment utiliser les variables $input 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 à API Gateway pour essayer ces exemples.

Exemple de modèle de mappage de paramètres

L’exemple suivant transmet tous les paramètres de demande, y compris 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
  }
}

Pour une demande qui inclut les paramètres d’entrée suivants :

Paramètre de chemin nommé myparam
Paramètres des chaînes de demande querystring1=value1,value2&querystring2=value3
En-têtes "header1" : "value1", "header2" : "value2", "header3" : "value3".

Le résultat de ce modèle de mappage doit ressembler à ce qui suit :


{
  "params" : {
        "path" : {
            "path" : "myparam"
                }
    ,        "querystring" : {
            "querystring1" : "value1,value2"
      ,            "querystring2" : "value3"
                }
    ,        "header" : {
            "header3" : "value3"
      ,            "header2" : "value2"
      ,            "header1" : "value1"
                }
          }
}

Exemple de modèle de mappage JSON

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 pouvez également obtenir le paramètre et les ddonnées utiles, ou une sous-section des données utiles. Les trois exemples suivants illustrent la marche à suivre.

L’exemple suivant utilise un modèle de mappage pour obtenir une sous-section des données utiles. Cet exemple permet d’obtenir le paramètre d’entrée name, puis l’intégralité du corps POST :


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

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

JSONPath exemple d'expression

L'exemple suivant montre comment transmettre une JSONPath expression à la json() méthode. Vous pouvez également lire une sous-section de l’objet du corps de votre demande en utilisant un point, ., pour spécifier une propriété :


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

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 de demande et de réponse

L’exemple suivant utilise $input.params(), $input.path() et $input.json() pour une ressource dont le chemin est /things/{id} :


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

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

Pour plus d’exemples de mappage, consultez Modèles de mappage pour REST APIs.

`$stageVariables`

Les variables d'étape peuvent être utilisées dans le mappage de paramètres et les modèles de mappage, ainsi que comme espaces réservés ARNs et URLs utilisés 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.

Syntaxe	Description
`$stageVariables.<variable_name>`, `$stageVariables['<variable_name>']` ou `${stageVariables['<variable_name>']}`	`<variable_name>`représente le nom d'une 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()`	Échape les caractères d'une chaîne en utilisant les règles relatives aux JavaScript chaînes. 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 : `"input" : "$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.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Comportements de transfert direct

Réponses de passerelle

Sur cette page

Sélectionner vos préférences de cookies

Personnaliser les préférences de cookies

Essentiels

Performances

Fonctionnels

Publicitaires

Impossible d'enregistrer les préférences concernant les cookies

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

Rubriques

Note

`$context`Variables pour les modèles de données, les autorisateurs, les modèles de mappage et la journalisation des CloudWatch accès

Note

Note

Exemple de modèle de variable `$context`

Note

Variables `$context` pour la journalisation des accès uniquement

Variables `$input`

Exemples de modèles de variable `$input`

Exemple de modèle de mappage de paramètres

Exemple de modèle de mappage JSON

JSONPath exemple d'expression

Exemple de demande et de réponse

`$stageVariables`

Variables `$util`

Note

Note

Sur cette page

Related resources

Cette page vous a-t-elle été utile ?

Related resources

Rubrique suivante :

Rubrique précédente :

Avez-vous besoin d’aide ?