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 WebSocket APIs dans API Gateway Dans API Gateway, la demande de méthode d'une WebSocket API peut prendre une charge utile dans un format différent de la charge utile de la demande d'intégration correspondante, comme l'exige le backend. De même, le serveur principal peut renvoyer une charge utile de réponse d’intégration différente de la charge utile de réponse de méthode attendue par le serveur frontal. API Gateway vous permet d’utiliser les transformations de modèles de mappage pour mapper les données utiles d’une demande de méthode à la demande d’intégration correspondante, et d’une réponse d’intégration à la réponse de méthode correspondante. Vous allez créer un modèle de mappage et spécifier une expression de sélection de modèle afin de déterminer le modèle à utiliser pour effectuer les transformations de données nécessaires. Vous pouvez utiliser des mappages de données pour mapper des données d’une [demande de routage](api-gateway-basic-concept.md#apigateway-definition-route-request) à une intégration backend. Pour en savoir plus, consultez la section [Configurer le mappage des données pour WebSocket APIs dans API Gateway](websocket-api-data-mapping.md). ## Modèles et modèles de mappage [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é à la charge utile à l'aide d'JSONPath expressions.](https://goessner.net/articles/JsonPath/) Pour plus d’informations sur les modèles de mappage API Gateway, consultez [Transformations de modèles de mappage pour REST APIs dans API Gateway](models-mappings.md). La charge utile peut comporter un *modèle de données* en fonction du [schéma JSON version 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04). Vous n’avez pas besoin de définir un modèle pour créer un modèle de mappage. Toutefois, un modèle peut vous aider à créer un modèle de mappage, car API Gateway génère un plan de modèle en fonction du modèle fourni. Pour plus d’informations sur les modèles API Gateway, consultez [Modèles de données pour REST APIs](models-mappings-models.md). ## Expressions de sélection du modèle Pour transformer une charge utile à l'aide d'un modèle de mappage, vous devez spécifier une expression de sélection de modèle d' WebSocket API dans une [demande d'intégration](apigateway-websocket-api-integration-requests.md) ou une [réponse d'intégration](apigateway-websocket-api-integration-responses.md). Cette expression est évaluée pour déterminer le modèle d’entrée ou de sortie (le cas échéant) à utiliser pour transformer le corps de la demande en corps de demande d’intégration (via un modèle d’entrée) ou le corps de la réponse au corps de la réponse de routage (via un modèle de sortie). `Integration.TemplateSelectionExpression` prend en charge `${request.body.jsonPath}` et les valeurs statiques. `IntegrationResponse.TemplateSelectionExpression` prend en charge `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}` et des valeurs statiques. ## Expressions de sélection de la réponse d’intégration Lorsque vous [configurez une réponse d'intégration](apigateway-websocket-api-integration-responses.md) pour une WebSocket API, vous pouvez éventuellement spécifier une expression de sélection de réponse d'intégration. Cette expression détermine quelle `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html)` doit être sélectionnée lorsqu’une intégration est renvoyée. La valeur de cette expression est actuellement restreinte par API Gateway, comme défini ci-dessous. Gardez à l’esprit que cette expression est uniquement pertinente pour des *intégrations autres que de proxy*. Une intégration de proxy transmet simplement la charge utile de la réponse à l’appelant sans modélisation ni modification. Contrairement aux autres expressions de sélection précédentes, cette expression prend actuellement en charge un format de *correspondance de modèle*. L’expression doit être encapsulée avec des barres obliques. Actuellement, la valeur est fixée en fonction de l’élément `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)`: + Pour les intégrations basées sur Lambda, la valeur est `$integration.response.body.errorMessage`. + Pour les intégrations `HTTP` et `MOCK`, la valeur est `$integration.response.statuscode`. + Pour `HTTP_PROXY` et `AWS_PROXY`, l’expression n’est pas utilisée, car vous demandez que la charge utile soit transmise à l’appelant. # Configurer le mappage des données pour WebSocket APIs dans API Gateway Le *mappage de données* vous permet de mapper des données d’une [demande de routage](api-gateway-basic-concept.md#apigateway-definition-route-request) vers une intégration backend. **Note** Le mappage de données pour WebSocket APIs n'est pas pris en charge dans le AWS Management Console. Vous devez utiliser le AWS CLI AWS CloudFormation, ou un SDK pour configurer le mappage des données. **Topics** + [Mappage des données de demande de routage à des paramètres de demande d’intégration](#websocket-mapping-request-parameters) + [Exemples](#websocket-data-mapping-examples) ## Mappage des données de demande de routage à des paramètres de demande d’intégration Les paramètres de demande d’intégration peuvent être mappés à partir de n’importe quels paramètres de demande de routage défini, du corps de la demande, des variables [`context` ou ](api-gateway-mapping-template-reference.md#context-variable-reference) [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference), ainsi que des valeurs statiques. Le tableau suivant présente les expressions de mappage des données des demandes d’intégration. Dans le tableau, *`PARAM_NAME`* est le nom d’un paramètre de demande de routage du type de paramètre donné. Elle doit correspondre à l'expression régulière`'^[a-zA-Z0-9._$-]+$]'`. *JSONPath\$1EXPRESSION*est une JSONPath expression pour un champ JSON du corps de la requête. | Source de données mappée | Expression de mappage | | --- | --- | | Chaîne de requête de demande (prise en charge uniquement pour le routage \$1connect) | route.request.querystring.PARAM\$1NAME | | En-tête de demande (prise en charge uniquement pour le routage \$1connect) | route.request.header.PARAM\$1NAME | | Chaîne de demande à plusieurs valeurs (prise en charge uniquement pour le routage \$1connect) | route.request.multivaluequerystring.PARAM\$1NAME | | En-tête de demande à plusieurs valeurs (prise en charge uniquement pour le routage \$1connect) | route.request.multivalueheader.PARAM\$1NAME | | Corps de la demande | route.request.body.JSONPath\$1EXPRESSION | | Variables d’étape | stageVariables.VARIABLE\$1NAME | | Variables de contexte | context.VARIABLE\$1NAME qui doit être l’une des [variables de contexte prises en charge](api-gateway-mapping-template-reference.md#context-variable-reference). | | Valeur statique | 'STATIC\$1VALUE'. STATIC\$1VALUEIl s'agit d'une chaîne littérale qui doit être placée entre guillemets simples. | Lorsque vous créez un mappage de données, AWS CLI assurez-vous de suivre le format correct pour utiliser des littéraux avec des chaînes dans le AWS CLI. Pour plus d’informations, consultez [Using quotation marks and literals with strings in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html) dans le *Guide d’utilisateur AWS Command Line Interface *. ## Exemples Les AWS CLI exemples suivants configurent les mappages de données. Pour un exemple CloudFormation de modèle, voir [samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip). ### Mapper ConnectionID d’un client à un en-tête dans une demande d’intégration La commande [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) suivante mappe l’`connectionId` d’un client à un en-tête `connectionId` de la demande adressée à une intégration backend : ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.connectionId'='context.connectionId' ``` ### Mapper un paramètre de chaîne de demande à un en-tête dans une demande d’intégration L’exemple suivant mappe un paramètre de chaîne de requête `authToken` à un en-tête `authToken` de la demande d’intégration. 1. Utilisez la commande [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) suivante pour ajouter le paramètre de chaîne de requête `authToken` aux paramètres de demande de la route. ``` aws apigatewayv2 update-route --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameters '{"route.request.querystring.authToken": {"Required": false}}' ``` 1. Utilisez la commande [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) suivante pour mapper le paramètre de chaîne de requête à l’en-tête `authToken` de la demande adressée à l’intégration backend. ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken' ``` 1. (Facultatif) Si nécessaire, utilisez ce qui suit [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html)pour supprimer le paramètre de chaîne de `authToken` requête des paramètres de demande de l'itinéraire. ``` aws apigatewayv2 delete-route-request-parameter \ --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameter-key 'route.request.querystring.authToken' ``` # WebSocket Référence du modèle de mappage d'API pour API Gateway Cette section résume l'ensemble des variables actuellement prises en charge WebSocket APIs dans API Gateway. | Paramètre | Description | | --- | --- | | \$1context.connectionId | ID unique pour la connexion qui peut être utilisé pour effectuer un rappel au client. | | \$1context.connectedAt | Temps de connexion au format [Epoch](https://en.wikipedia.org/wiki/Unix_time). | | \$1context.domainName | Nom de domaine pour l' WebSocket API. Ce nom peut être utilisé pour effectuer un rappel au client (au lieu d’une valeur codée en dur). | | \$1context.eventType | Type d’événement : `CONNECT`, `MESSAGE` ou `DISCONNECT`. | | \$1context.messageId | ID côté serveur unique pour un message. Uniquement disponible lorsque `$context.eventType` est défini sur `MESSAGE`. | | \$1context.routeKey | Clé de routage sélectionnée. | | \$1context.requestId | Identique à `$context.extendedRequestId`. | | \$1context.extendedRequestId | ID généré automatiquement pour l’appel d’API, qui contient d’autres informations utiles pour le débogage et le dépannage. | | \$1context.apiId | Identifiant qu’API Gateway attribue à votre API. | | \$1context.authorizer.principalId | Identification de l’utilisateur principal associée au jeton envoyé par le client et retourné par une fonction Lambda du mécanisme d’autorisation Lambda API Gateway (anciennement appelé mécanisme d’autorisation personnalisée). | | \$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"`. | | \$1context.error.messageString | Valeur entre guillemets de \$1context.error.message, à savoir "\$1context.error.message". | | \$1context.error.validationErrorString | Chaîne contenant un message d’erreur de validation détaillé. | | \$1context.identity.accountId | L'ID de AWS compte associé à la demande. | | \$1context.identity.apiKey | Clé du propriétaire d’API associée à la demande d’API activée par clé. | | \$1context.identity.apiKeyId | ID de clé du propriétaire d’API associée à la demande d’API activée par clé | | \$1context.identity.caller | Identifiant principal de l’appelant effectuant la demande. | | \$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.sourceIp | Adresse IP source de la connexion TCP envoyant la demande au point de terminaison de l’API Gateway. | | \$1context.identity.user | Identifiant principal de l’utilisateur effectuant la demande. | | \$1context.identity.userAgent | Agent utilisateur de l’appelant de l’API. | | \$1context.identity.userArn | ARN (Amazon Resource Name) de l’utilisateur identifié après l’authentification. | | \$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.stage | Étape de déploiement de l’appel d’API (par exemple, bêta ou production). | | \$1context.status | Statut de la réponse. | | \$1input.body | Renvoie la charge utile brute sous forme de chaîne. | | \$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.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').count()` renvoie `"3"`. Pour plus d'informations sur JSONPath, voir [JSONPath](http://goessner.net/articles/JsonPath/)ou [JSONPath pour Java](https://github.com/jayway/JsonPath). | | \$1stageVariables. | **représente le nom d'une variable d'étape. | | \$1stageVariables[''] | **représente n'importe quel nom de variable d'étape. | | \$1\$1stageVariables['']\$1 | **représente n'importe quel nom de variable d'étape. | | \$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 : 
 $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. |