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. # Développez WebSocket APIs dans API Gateway Cette section fournit des détails sur les fonctionnalités d'API Gateway dont vous avez besoin pour développer votre API Gateway APIs. Au fur et à mesure que vous développez votre API API Gateway, vous décidez d’un certain nombre de caractéristiques de votre API. Ces caractéristiques dépendent du cas d’utilisation de votre API. Par exemple, vous pourriez vouloir autoriser uniquement certains clients à appeler votre API ou qu’elle soit disponible pour tout le monde. Vous pouvez souhaiter utiliser un appel d’API pour exécuter une fonction Lambda, créer une requête de base de données ou appeler une application. **Topics** + [Création WebSocket APIs dans API Gateway](apigateway-websocket-api-create-empty-api.md) + [Types d’adresses IP pour les API WebSocket dans API Gateway](websocket-api-ip-address-type.md) + [Création de routes pour WebSocket APIs in API Gateway](websocket-api-develop-routes.md) + [Contrôler et gérer l'accès WebSocket APIs à API Gateway](apigateway-websocket-api-control-access.md) + [Intégrations pour WebSocket APIs in API Gateway](apigateway-websocket-api-integrations.md) + [Demande de validation pour WebSocket APIs in API Gateway](websocket-api-request-validation.md) + [Transformations de données pour WebSocket APIs dans API Gateway](websocket-api-data-transformations.md) + [Types de supports binaires pour les API WebSocket dans API Gateway](websocket-api-develop-binary-media-types.md) + [Invoquer WebSocket APIs](apigateway-how-to-call-websocket-api.md) # Création WebSocket APIs dans API Gateway Vous pouvez créer une WebSocket API dans la console API Gateway, à l'aide de la commande AWS CLI [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) ou à l'aide de la `CreateApi` commande d'un AWS SDK. Les procédures suivantes montrent comment créer une nouvelle WebSocket API. **Note** WebSocket APIs ne supporte que TLS 1.2 et TLS 1.3. Les versions antérieures de TLS ne sont pas prises en charge. ## Création d'une WebSocket API à l'aide de AWS CLI commandes La commande [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) suivante crée une API avec l’expression de sélection de route `$request.body.action` : ``` aws apigatewayv2 --region us-east-1 create-api --name "myWebSocketApi3" --protocol-type WEBSOCKET --route-selection-expression '$request.body.action' ``` Le résultat se présente comme suit : ``` { "ApiKeySelectionExpression": "$request.header.x-api-key", "Name": "myWebSocketApi3", "CreatedDate": "2018-11-15T06:23:51Z", "ProtocolType": "WEBSOCKET", "RouteSelectionExpression": "'$request.body.action'", "ApiId": "aabbccddee" } ``` ## Création d'une WebSocket API à l'aide de la console API Gateway Vous pouvez créer une WebSocket API dans la console en choisissant le WebSocket protocole et en lui attribuant un nom. **Important** Une fois l’API créée, vous ne pouvez pas modifier le protocole que vous avez choisi. Il n'existe aucun moyen de convertir une WebSocket API en API REST ou vice versa. **Pour créer une WebSocket API à l'aide de la console API Gateway** 1. Connectez-vous à la console API Gateway et choisissez **Create API (Créer une API)**. 1. Sous **WebSocket API**, choisissez **Build**. Seuls les points de terminaison régionaux sont pris en charge. 1. Pour **Nom de l’API**, saisissez le nom de votre API. 1. Pour **Expression de sélection de routage**, saisissez une valeur. Par exemple, `$request.body.action`. Pour plus d’informations sur les expressions de sélection de la route, consultez la section [Expressions de sélection de la route](websocket-api-develop-routes.md#apigateway-websocket-api-route-selection-expressions). 1. Effectuez l’une des actions suivantes : + Choisissez **Créer une API vide** pour créer une API sans routes. + Choisissez **Suivant** pour joindre des routes à votre API. Vous pouvez joindre des routes après avoir créé votre API. # Types d’adresses IP pour les API WebSocket dans API Gateway Lorsque vous créez une API, vous spécifiez le type d’adresses IP qui peut invoquer votre API. Vous avez le choix entre IPv4 (pour autoriser les adresses IPv4 à invoquer votre API) et Dualstack (pour autoriser les adresses IPv4 et IPv6 à invoquer votre API). Nous vous recommandons de définir le type d’adresse IP sur Dualstack pour éviter l’épuisement de l’espace IP ou renforcer votre niveau de sécurité. Pour plus d’informations sur les avantages d’un type d’adresse IP à double pile, consultez [IPv6 sur AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html). ## Considérations relatives aux types d’adresses IP Les considérations suivantes peuvent avoir une incidence sur votre utilisation des types d’adresses IP : + Le type d’adresses IP par défaut pour toutes les API WebSocket est IPv4. + Si vous remplacez le type d’adresse IP IPv4 d’une API existante par un type d’adresse IP à double pile, vérifiez que toutes les stratégies d’accès à vos API ont été mises à jour pour prendre en compte les appels IPv6. La modification du type d’adresse IP prend effet immédiatement. + Votre API peut être mappée à un nom de domaine personnalisé présentant un type d’adresse IP différent de celui de votre API. La désactivation du point de terminaison de votre API par défaut peut avoir une incidence sur la manière dont les appelants peuvent invoquer votre API. ## Modification du type d’adresse IP d’une API WebSocket Vous pouvez modifier le type d’adresse IP en mettant à jour la configuration de l’API. Vous pouvez mettre à jour la configuration de l’API à l’aide de la AWS Management Console, de l’AWS CLI, d’CloudFormation ou d’un kit SDK AWS. Si vous modifiez le type d’adresse IP de l’API, vous n’avez pas besoin de redéployer votre API pour que les modifications prennent effet. ------ #### [ AWS Management Console ] **Pour modifier le type d’adresse IP d’une API WebSocket** 1. Connectez-vous à la console API Gateway à l’adresse : [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choisissez une API WebSocket. 1. Choisissez **Paramètres de l’API**, puis **Modifier**. 1. Pour Type d’adresse IP, choisissez **IPv4** ou **Dualstack**. 1. Choisissez **Save (Enregistrer)**. La modification de la configuration de votre API prend effet immédiatement. ------ #### [ AWS CLI ] La commande [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) suivante met à jour une API pour qu’elle possède le type d’adresse IP Dualstack : ``` aws apigatewayv2 update-api \ --api-id abcd1234 \ --ip-address-type dualstack ``` Le résultat se présente comme suit : ``` { "ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com", "ApiId": "abcd1234", "ApiKeySelectionExpression": "$request.header.x-api-key", "CreatedDate": "2025-02-04T22:20:20+00:00", "DisableExecuteApiEndpoint": false, "Name": "My-WebSocket-API", "ProtocolType": "WEBSOCKET", "RouteSelectionExpression": "$request.method $request.path", "Tags": {}, "NotificationUris": [], "IpAddressType": "dualstack" } ``` ------ # Création de routes pour WebSocket APIs in API Gateway Dans votre WebSocket API, les messages JSON entrants sont dirigés vers les intégrations du backend en fonction des routes que vous configurez. (Les messages non JSON sont dirigés vers une route `$default` que vous configurez.) Une *route* comprend une *clé de routage*, qui correspond à la valeur attendue une fois qu’une *expression de sélection de la route* est évaluée. L’attribut `routeSelectionExpression` est défini au niveau de l’API. Il spécifie une propriété JSON attendue dans la charge utile du message. Pour plus d’informations sur les expressions de sélection de la route, consultez la section [Expressions de sélection de la route](#apigateway-websocket-api-route-selection-expressions). Par exemple, si vos messages JSON contiennent une propriété `action` et que vous souhaitez effectuer différentes actions en fonction de cette propriété, votre expression de sélection de la route peut être `${request.body.action}`. Votre table de routage spécifie l'action à exécuter en mettant en correspondance la valeur de la propriété `action` avec les valeurs des clés de routage personnalisées que vous avez définies dans la table. Trois routes prédéfinies peuvent être utilisées : `$connect`, `$disconnect` et `$default`. De plus, vous pouvez créer des routes personnalisées. + API Gateway appelle la `$connect` route lorsqu'une connexion persistante entre le client et une WebSocket API est initiée. + API Gateway appelle la route `$disconnect` lorsque le client ou le serveur se déconnecte de l’API. + API Gateway appelle une route personnalisée après évaluation de l’expression de sélection de la route par rapport au message si une route correspondante est trouvée ; la correspondance détermine l’intégration appelée. + API Gateway appelle la route `$default` si l’expression de sélection de la route ne peut pas être évaluée par rapport au message ou si aucune route correspondante n’est trouvée. ## Expressions de sélection de la route Une *expression de sélection de la route* est évaluée lorsque le service sélectionne la route que doit suivre un message entrant. Le service utilise la route dont la clé `routeKey` correspond exactement à la valeur évaluée. Si aucune clé ne correspond et qu’une route avec la clé `$default` existe, celle-ci est sélectionnée. Si aucune route ne correspond à la valeur évaluée et qu’il n’y a pas de route `$default`, le service renvoie une erreur. Pour WebSocket based APIs, l'expression doit être de la forme`$request.body.{path_to_body_element}`. Par exemple, supposons que vous envoyiez le message JSON suivant : ``` { "service" : "chat", "action" : "join", "data" : { "room" : "room1234" } } ``` Vous pouvez sélectionner le comportement de votre API en fonction de la propriété `action`. Dans ce cas, vous pouvez définir l’expression de sélection de la route suivante : ``` $request.body.action ``` Dans cet exemple, il `request.body` fait référence à la charge utile JSON de votre message et `.action` est une [JSONPath](https://goessner.net/articles/JsonPath/)expression. Vous pouvez utiliser n’importe quelle expression de chemin JSON après `request.body`, mais n’oubliez pas que le résultat sera obtenu à l’aide de stringify. Par exemple, si votre JSONPath expression renvoie un tableau de deux éléments, celui-ci sera présenté sous forme de chaîne`"[item1, item2]"`. C’est la raison pour laquelle il est recommandé d’utiliser une expression qui correspond à une valeur plutôt qu’à un tableau ou un objet. Vous pouvez utiliser simplement une valeur statique ou plusieurs variables. Le tableau suivant montre des exemples et leurs résultats évalués par rapport à la charge utile précédente. | Expression | Résultat évalué | Description | | --- | --- | --- | | \$1request.body.action | join | Variable désencapsulée | | \$1\$1request.body.action\$1 | join | Variable encapsulée | | \$1\$1request.body.service\$1/\$1\$1request.body.action\$1 | chat/join | Plusieurs variables avec des valeurs statiques | | \$1\$1request.body.action\$1-\$1\$1request.body.invalidPath\$1 | join- | Si le n' JSONPath est pas trouvé, la variable est résolue sous la forme « ». | | action | action | Valeur statique | | \$1\$1default | \$1default | Valeur statique | Le résultat évalué est utilisé pour trouver une route. S’il existe une route avec une clé de routage correspondante, elle est sélectionnée pour traiter le message. Si aucune route correspondante n’existe, API Gateway tente de trouver la route `$default`, si elle est disponible. Si la route `$default` n’est pas définie, API Gateway renvoie une erreur. ## Configuration de routes pour une WebSocket API dans API Gateway Lorsque vous créez une nouvelle WebSocket API pour la première fois, il existe trois itinéraires prédéfinis : `$connect``$disconnect`, et`$default`. Vous pouvez les créer à l'aide de la console, de l'API ou AWS CLI. Si vous le souhaitez, vous pouvez créer des routes personnalisées. Pour plus d’informations, consultez [Vue d'ensemble de WebSocket APIs in API Gateway](apigateway-websocket-api-overview.md). **Note** Dans l’interface de ligne de commande, vous pouvez créer des routes avant ou après avoir créé des intégrations, et réutiliser la même intégration pour plusieurs routes. ### Création d’une route à l’aide de la console API Gateway **Pour créer une route à l’aide de la console API Gateway** 1. Connectez-vous à la console API Gateway et choisissez l’API, puis choisissez **Routes**. 1. Choisissez **Créer une route**. 1. Pour **Clé de route**, entrez le nom de la clé de route. Vous pouvez créer les routes prédéfinies (`$connect`, `$disconnect` et `$default`) ou une route personnalisée. **Note** Lorsque vous créez une route personnalisée, n’utilisez pas le préfixe `$` dans le nom de la clé de routage. Ce préfixe est réservé aux routes prédéfinies. 1. Sélectionnez et configurez le type d’intégration pour la route. Pour de plus amples informations, veuillez consulter [Configuration d'une demande d'intégration d' WebSocket API à l'aide de la console API Gateway](apigateway-websocket-api-integration-requests.md#apigateway-websocket-api-integration-request-using-console). ### Créez un itinéraire à l'aide du AWS CLI La commande [create-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route.html) suivante crée une route : ``` aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default ``` Le résultat se présente comme suit : ``` { "ApiKeyRequired": false, "AuthorizationType": "NONE", "RouteKey": "$default", "RouteId": "1122334" } ``` ### Spécification des paramètres de requête de routage pour `$connect` Lorsque vous configurez la route `$connect` pour votre API, les paramètres facultatifs suivants sont disponibles pour activer les autorisations pour votre API. Pour plus d’informations, consultez [Route `$connect`](apigateway-websocket-api-route-keys-connect-disconnect.md#apigateway-websocket-api-routes-about-connect). + **Authorization (Autorisation)** : Si aucune autorisation n’est nécessaire, vous pouvez spécifier `NONE`. Sinon, vous pouvez spécifier : + `AWS_IAM`pour utiliser des politiques AWS IAM standard afin de contrôler l'accès à votre API. + `CUSTOM` pour implémenter l’autorisation pour une API en spécifiant une fonction de mécanisme d’autorisation Lambda que vous avez créée précédemment. L'autorisateur peut résider dans votre propre AWS compte ou sur un autre AWS compte. Pour plus d’informations sur les mécanismes d’autorisation Lambda, consultez [Utilisation des mécanismes d’autorisation Lambda API Gateway](apigateway-use-lambda-authorizer.md). **Note** Dans la console API Gateway, le paramètre `CUSTOM` est visible uniquement une fois que vous avez configuré une fonction de mécanisme d’autorisation, comme décrit dans [Configuration d’un mécanisme d’autorisation Lambda (console)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console). **Important** Le paramètre **Authorization (Autorisation)** est appliqué à l’ensemble de l’API, et pas uniquement à la route `$connect`. La route `$connect` protège les autres routes, car elle est appelée sur chaque connexion. + **Clé d’API obligatoire** : si vous le souhaitez, vous pouvez exiger une clé d’API pour une route `$connect` de l’API. Vous pouvez utiliser des clés d'API ainsi que des plans d'utilisation pour contrôler et suivre l'accès à votre APIs. 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). ### Configuration de la demande de route `$connect` à l’aide de la console API Gateway Pour configurer la demande de `$connect` route pour une WebSocket API à l'aide de la console API Gateway, procédez comme suit : 1. Connectez-vous à la console API Gateway et choisissez l’API, puis choisissez **Routes**. 1. Sous **Routes**, choisissez `$connect` ou créez une route `$connect` en suivant [Création d’une route à l’aide de la console API Gateway](#apigateway-websocket-api-route-using-console). 1. Dans la section **Paramètres de requête de routage**, choisissez **Modifier**. 1. Pour **Autorisation**, sélectionnez un type d’autorisation. 1. Pour demander une API pour la route `$connect`, sélectionnez **Exiger une clé d’API**. 1. Sélectionnez **Enregistrer les modifications**. # Configuration des réponses d'itinéraire pour WebSocket APIs dans API Gateway WebSocket les itinéraires peuvent être configurés pour une communication bidirectionnelle ou unidirectionnelle. API Gateway ne transmet pas la réponse du backend à la réponse de routage, sauf si vous avez configuré une réponse de routage. **Note** Vous ne pouvez définir la réponse de l'`$default`itinéraire que pour WebSocket APIs. Vous pouvez utiliser une réponse d’intégration pour manipuler la réponse d’un service backend. Pour de plus amples informations, veuillez consulter [Présentation des réponses d’intégration](apigateway-websocket-api-integration-responses.md#apigateway-websocket-api-integration-response-overview). Vous pouvez configurer les réponses d'itinéraire et les expressions de sélection des réponses à l'aide de la console API Gateway AWS CLI ou d'un AWS SDK. Pour plus d’informations sur les expressions de sélection de la réponse de routage, consultez la section [Expressions de sélection de la réponse de routage](apigateway-websocket-api-selection-expressions.md#apigateway-websocket-api-route-response-selection-expressions). **Topics** + [Configuration d’une réponse de routage à l’aide de la console API Gateway](#apigateway-websocket-api-route-response-using-console) + [Configurez une réponse d'itinéraire à l'aide du AWS CLI](#apigateway-websocket-api-route-response-using-awscli) ## Configuration d’une réponse de routage à l’aide de la console API Gateway Après avoir créé une WebSocket API et attaché une fonction Lambda proxy à la route par défaut, vous pouvez configurer la réponse de route à l'aide de la console API Gateway : 1. Connectez-vous à la console API Gateway, choisissez une WebSocket API avec une intégration de la fonction Lambda par proxy sur la `$default` route. 1. Sous **Routes** (Routes), choisissez la route `$default`. 1. Choisissez **Activer la communication bidirectionnelle**. 1. Sélectionnez **Deploy API (Déployer une API)**. 1. Déployez votre API dans une étape. Utilisez la commande [wscat](https://www.npmjs.com/package/wscat) suivante pour vous connecter à votre API. Pour plus d’informations sur `wscat`, consultez [`wscat`À utiliser pour se connecter à une WebSocket API et y envoyer des messages](apigateway-how-to-call-websocket-api-wscat.md). ``` wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test ``` Appuyez sur la touche Entrée pour appeler la route par défaut. Le corps de votre fonction Lambda vous est renvoyé. ## Configurez une réponse d'itinéraire à l'aide du AWS CLI La [create-route-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route-response.html)commande suivante crée une réponse d'itinéraire pour l'`$default`itinéraire. Vous pouvez identifier l’ID de l’API et l’ID du routage à l’aide des commandes [get-apis](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-apis.html) et [get-routes](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-routes.html). ``` aws apigatewayv2 create-route-response \ --api-id aabbccddee \ --route-id 1122334 \ --route-response-key '$default' ``` Le résultat se présente comme suit : ``` { "RouteResponseId": "abcdef", "RouteResponseKey": "$default" } ``` # Configurer un `$connect` itinéraire qui nécessite un WebSocket sous-protocole Les clients peuvent utiliser `Sec-WebSocket-Protocol` ce champ pour demander un [WebSocket sous-protocole](https://datatracker.ietf.org/doc/html/rfc6455#page-12) lors de la connexion à votre WebSocket API. Vous pouvez configurer une intégration pour la route `$connect` afin d’autoriser les connexions uniquement si un client demande un sous-protocole pris en charge par votre API. L’exemple de fonction Lambda suivant renvoie l’en-tête `Sec-WebSocket-Protocol` aux clients. La fonction établit une connexion à votre API uniquement si le client spécifie le sous-protocole `myprotocol`. Pour un CloudFormation modèle qui crée cet exemple d'intégration d'API et de proxy Lambda, consultez. [samples/ws-subprotocol.zip](samples/ws-subprotocol.zip) ``` export const handler = async (event) => { if (event.headers != undefined) { const headers = toLowerCaseProperties(event.headers); if (headers['sec-websocket-protocol'] != undefined) { const subprotocolHeader = headers['sec-websocket-protocol']; const subprotocols = subprotocolHeader.split(','); if (subprotocols.indexOf('myprotocol') >= 0) { const response = { statusCode: 200, headers: { "Sec-WebSocket-Protocol" : "myprotocol" } }; return response; } } } const response = { statusCode: 400 }; return response; }; function toLowerCaseProperties(obj) { var wrapper = {}; for (var key in obj) { wrapper[key.toLowerCase()] = obj[key]; } return wrapper; } ``` Vous pouvez utiliser [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat) pour vérifier que votre API autorise les connexions uniquement si un client demande un sous-protocole pris en charge par votre API. Les commandes suivantes utilisent l’indicateur `-s` pour spécifier des sous-protocoles pendant la connexion. La commande suivante tente une connexion avec un sous-protocole non pris en charge. Étant donné que le client a spécifié le sous-protocole `chat1`, l’intégration Lambda renvoie une erreur 400 et la connexion échoue. ``` wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1 error: Unexpected server response: 400 ``` La commande suivante inclut un sous-protocole pris en charge dans la demande de connexion. L’intégration Lambda permet la connexion. ``` wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1,myprotocol connected (press CTRL+C to quit) ``` Pour en savoir plus sur l'invocation WebSocket APIs, consultez[Invoquer WebSocket APIs](apigateway-how-to-call-websocket-api.md). # Contrôler et gérer l'accès WebSocket APIs à API Gateway API Gateway prend en charge plusieurs mécanismes de contrôle et de gestion de l'accès à votre WebSocket API. Les mécanismes suivants peuvent être utilisés pour l’authentification et l’autorisation : + Les **rôles et politiques AWS IAM standard** offrent des contrôles d'accès flexibles et robustes. Vous pouvez utiliser les rôles et les politiques IAM pour contrôler qui peut les créer et les gérer APIs, ainsi que les personnes habilitées à les invoquer. Pour de plus amples informations, veuillez consulter [Contrôler l'accès à l' WebSocket APIs aide d'une autorisation IAM](apigateway-websocket-control-access-iam.md). + Les **balises IAM** peuvent être utilisées avec des politiques IAM pour contrôler l’accès. Pour de plus amples informations, veuillez consulter [Utilisation de balises pour contrôler l’accès aux ressources API REST API Gateway](apigateway-tagging-iam-policy.md). + **Les autorisateurs Lambda sont des** fonctions Lambda qui contrôlent l'accès à. APIs Pour de plus amples informations, veuillez consulter [Contrôlez l'accès à l' WebSocket APIs aide des AWS Lambda autorisateurs REQUEST](apigateway-websocket-api-lambda-auth.md). Pour améliorer votre niveau de sécurité, nous vous recommandons de configurer un autorisateur pour l'`$connect`itinéraire sur tous vos WebSocket APIs itinéraires. Vous devrez peut-être le faire pour vous conformer aux différents cadres de conformité. Pour plus d’informations, consultez [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) dans le *Guide de l’utilisateur AWS Security Hub *. **Topics** + [Contrôler l'accès à l' WebSocket APIs aide d'une autorisation IAM](apigateway-websocket-control-access-iam.md) + [Contrôlez l'accès à l' WebSocket APIs aide des AWS Lambda autorisateurs REQUEST](apigateway-websocket-api-lambda-auth.md) # Contrôler l'accès à l' WebSocket APIs aide d'une autorisation IAM L'autorisation IAM dans WebSocket APIs est similaire à celle pour [REST APIs](api-gateway-control-access-using-iam-policies-to-invoke-api.md), avec les exceptions suivantes : + L’action `execute-api` prend en charge `ManageConnections` en plus des actions existantes (`Invoke`, `InvalidateCache`). `ManageConnections` contrôle l’accès à l’API @connections. + WebSocket les routes utilisent un format d'ARN différent : ``` arn:aws:execute-api:region:account-id:api-id/stage-name/route-key ``` + L'`@connections`API utilise le même format ARN que REST APIs : ``` arn:aws:execute-api:region:account-id:api-id/stage-name/POST/@connections ``` **Important** Lorsque vous utilisez [Autorisation IAM](#apigateway-websocket-control-access-iam), vous devez signer les requêtes avec [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). Par exemple, vous pouvez configurer la politique suivante pour le client. Cet exemple autorise tout le monde à envoyer un message (`Invoke`) pour toutes les routes, sauf pour une route secrète de l’étape `prod`, et empêche tout le monde de renvoyer un message aux clients connectés (`ManageConnections`) pour toutes les étapes. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111122223333:api-id/prod/*" ] }, { "Effect": "Deny", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111122223333:api-id/prod/secret" ] }, { "Effect": "Deny", "Action": [ "execute-api:ManageConnections" ], "Resource": [ "arn:aws:execute-api:us-east-1:111122223333:api-id/*" ] } ] } ``` ------ # Contrôlez l'accès à l' WebSocket APIs aide des AWS Lambda autorisateurs REQUEST Une fonction d'autorisation Lambda dans WebSocket APIs est similaire à celle de [REST APIs](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create), avec les exceptions suivantes : + Vous pouvez uniquement utiliser une fonction de mécanisme d’autorisation Lambda pour la route `$connect`. + Vous ne pouvez pas utiliser de variables de chemin (`event.pathParameters`), car le chemin d’accès est fixe. + `event.methodArn` est différent de son équivalent de l’API REST, car il ne possède pas de méthode HTTP. Dans le cas de `$connect`, `methodArn` se termine par `"$connect"` : ``` arn:aws:execute-api:region:account-id:api-id/stage-name/$connect ``` + Les variables de contexte `event.requestContext` sont différentes de celles de REST APIs. L'exemple suivant montre une entrée dans un `REQUEST` autorisateur pour une WebSocket API : ``` { "type": "REQUEST", "methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/default/$connect", "headers": { "Connection": "upgrade", "content-length": "0", "HeaderAuth1": "headerValue1", "Host": "abcdef123.execute-api.us-east-1.amazonaws.com", "Sec-WebSocket-Extensions": "permessage-deflate; client_max_window_bits", "Sec-WebSocket-Key": "...", "Sec-WebSocket-Version": "13", "Upgrade": "websocket", "X-Amzn-Trace-Id": "...", "X-Forwarded-For": "...", "X-Forwarded-Port": "443", "X-Forwarded-Proto": "https" }, "multiValueHeaders": { "Connection": [ "upgrade" ], "content-length": [ "0" ], "HeaderAuth1": [ "headerValue1" ], "Host": [ "abcdef123.execute-api.us-east-1.amazonaws.com" ], "Sec-WebSocket-Extensions": [ "permessage-deflate; client_max_window_bits" ], "Sec-WebSocket-Key": [ "..." ], "Sec-WebSocket-Version": [ "13" ], "Upgrade": [ "websocket" ], "X-Amzn-Trace-Id": [ "..." ], "X-Forwarded-For": [ "..." ], "X-Forwarded-Port": [ "443" ], "X-Forwarded-Proto": [ "https" ] }, "queryStringParameters": { "QueryString1": "queryValue1" }, "multiValueQueryStringParameters": { "QueryString1": [ "queryValue1" ] }, "stageVariables": {}, "requestContext": { "routeKey": "$connect", "eventType": "CONNECT", "extendedRequestId": "...", "requestTime": "19/Jan/2023:21:13:26 +0000", "messageDirection": "IN", "stage": "default", "connectedAt": 1674162806344, "requestTimeEpoch": 1674162806345, "identity": { "sourceIp": "..." }, "requestId": "...", "domainName": "abcdef123.execute-api.us-east-1.amazonaws.com", "connectionId": "...", "apiId": "abcdef123" } } ``` L'exemple de fonction d'autorisation Lambda suivant est une WebSocket version de la fonction d'autorisation Lambda pour REST dans : APIs [Exemples supplémentaires de fonctions de mécanisme d’autorisation Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create) ------ #### [ Node.js ] ``` // A simple REQUEST authorizer example to demonstrate how to use request // parameters to allow or deny a request. In this example, a request is // authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter // in the request context match the specified values of // of 'headerValue1' and 'queryValue1' respectively. export const handler = function(event, context, callback) { console.log('Received event:', JSON.stringify(event, null, 2)); // Retrieve request parameters from the Lambda function input: var headers = event.headers; var queryStringParameters = event.queryStringParameters; var stageVariables = event.stageVariables; var requestContext = event.requestContext; // Parse the input for the parameter values var tmp = event.methodArn.split(':'); var apiGatewayArnTmp = tmp[5].split('/'); var awsAccountId = tmp[4]; var region = tmp[3]; var ApiId = apiGatewayArnTmp[0]; var stage = apiGatewayArnTmp[1]; var route = apiGatewayArnTmp[2]; // Perform authorization to return the Allow policy for correct parameters and // the 'Unauthorized' error, otherwise. var authResponse = {}; var condition = {}; condition.IpAddress = {}; if (headers.HeaderAuth1 === "headerValue1" && queryStringParameters.QueryString1 === "queryValue1") { callback(null, generateAllow('me', event.methodArn)); } else { callback(null, generateDeny('me', event.methodArn)); } } // Helper function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { // Required output: var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17 '; // default version policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; // default action statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; } var generateAllow = function(principalId, resource) { return generatePolicy(principalId, 'Allow', resource); } var generateDeny = function(principalId, resource) { return generatePolicy(principalId, 'Deny', resource); } ``` ------ #### [ Python ] ``` # A simple REQUEST authorizer example to demonstrate how to use request # parameters to allow or deny a request. In this example, a request is # authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter # in the request context match the specified values of # of 'headerValue1' and 'queryValue1' respectively. import json def lambda_handler(event, context): print(event) # Retrieve request parameters from the Lambda function input: headers = event['headers'] queryStringParameters = event['queryStringParameters'] stageVariables = event['stageVariables'] requestContext = event['requestContext'] # Parse the input for the parameter values tmp = event['methodArn'].split(':') apiGatewayArnTmp = tmp[5].split('/') awsAccountId = tmp[4] region = tmp[3] ApiId = apiGatewayArnTmp[0] stage = apiGatewayArnTmp[1] route = apiGatewayArnTmp[2] # Perform authorization to return the Allow policy for correct parameters # and the 'Unauthorized' error, otherwise. authResponse = {} condition = {} condition['IpAddress'] = {} if (headers['HeaderAuth1'] == "headerValue1" and queryStringParameters["QueryString1"] == "queryValue1"): response = generateAllow('me', event['methodArn']) print('authorized') return json.loads(response) else: response = generateDeny('me', event['methodArn']) print('unauthorized') return json.loads(response) # Help function to generate IAM policy def generatePolicy(principalId, effect, resource): authResponse = {} authResponse['principalId'] = principalId if (effect and resource): policyDocument = {} policyDocument['Version'] = '2012-10-17 ' policyDocument['Statement'] = [] statementOne = {} statementOne['Action'] = 'execute-api:Invoke' statementOne['Effect'] = effect statementOne['Resource'] = resource policyDocument['Statement'] = [statementOne] authResponse['policyDocument'] = policyDocument authResponse['context'] = { "stringKey": "stringval", "numberKey": 123, "booleanKey": True } authResponse_JSON = json.dumps(authResponse) return authResponse_JSON def generateAllow(principalId, resource): return generatePolicy(principalId, 'Allow', resource) def generateDeny(principalId, resource): return generatePolicy(principalId, 'Deny', resource) ``` ------ [Pour configurer la fonction Lambda précédente en tant que fonction d'`REQUEST`autorisation pour une WebSocket API, suivez la même procédure que pour REST. APIs](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console) Pour configurer la route `$connect` afin qu’elle utilise ce mécanisme d’autorisation Lambda dans la console, sélectionnez ou créez la route `$connect`. Dans la section **Paramètres de la demande de route**, choisissez **Modifier**. Sélectionnez votre mécanisme d’autorisation dans le menu déroulant **Autorisation**, puis choisissez **Enregistrer les modifications**. Pour tester le mécanisme d’autorisation, vous devez créer une nouvelle connexion. La modification du mécanisme d’autorisation dans `$connect` n’affecte pas le client déjà connecté. Lorsque vous vous connectez à votre WebSocket API, vous devez fournir des valeurs pour toutes les sources d'identité configurées. Par exemple, vous pouvez vous connecter en envoyant une chaîne de requête et un en-tête en utilisant `wscat` comme dans l’exemple suivant : ``` wscat -c 'wss://myapi.execute-api.us-east-1.amazonaws.com/beta?QueryString1=queryValue1' -H HeaderAuth1:headerValue1 ``` Si vous tentez de vous connecter sans valeur d’identité valide, vous recevrez une réponse `401` : ``` wscat -c wss://myapi.execute-api.us-east-1.amazonaws.com/beta error: Unexpected server response: 401 ``` # Intégrations pour WebSocket APIs in API Gateway Après avoir configuré une route d’API, vous devez l’intégrer avec un point de terminaison dans le serveur principal. Un point de terminaison principal est également appelé point de terminaison d'intégration et peut être une fonction Lambda, un point de terminaison HTTP ou AWS une action de service. L’intégration de l’API a une demande d’intégration et une réponse d’intégration. Dans cette section, vous découvrirez comment configurer les demandes d'intégration et les réponses d'intégration pour votre WebSocket API. **Topics** + [Configurer une demande d'intégration d' WebSocket API dans API Gateway](apigateway-websocket-api-integration-requests.md) + [Configurer une réponse d'intégration d' WebSocket API dans API Gateway](apigateway-websocket-api-integration-responses.md) # Configurer une demande d'intégration d' WebSocket API dans API Gateway La configuration d’une demande d’intégration comprend les opérations suivantes : + La sélection d’une clé de routage à intégrer avec le serveur principal. + Spécifier le point de terminaison du backend à appeler. WebSocket APIs prennent en charge les types d'intégration suivants : + `AWS_PROXY` + `AWS` + `HTTP_PROXY` + `HTTP` + `MOCK` Pour plus d'informations sur les types d'intégration, consultez [IntegrationType](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)l'API REST API Gateway V2. + La configuration de la transformation des données de la demande de routage, si nécessaire, en données de demande d’intégration en spécifiant un ou plusieurs modèles de demande. ## Configuration d'une demande d'intégration d' WebSocket API à l'aide de la console API Gateway **Pour ajouter une demande d'intégration à un itinéraire dans une WebSocket API à l'aide de la console API Gateway** 1. Connectez-vous à la console API Gateway et choisissez l’API, puis choisissez **Routes**. 1. Sous **Routes**, choisissez la route. 1. Choisissez l’onglet **Demande d’intégration**, puis dans la section **Paramètres de la demande d’intégration**, choisissez **Modifier**. 1. Pour **Type d’intégration**, sélectionnez l’une des valeurs suivantes : + Choisissez la **fonction Lambda** uniquement si votre API doit être intégrée à une AWS Lambda fonction que vous avez déjà créée dans ce compte ou dans un autre compte. **Pour créer une nouvelle fonction Lambda dans AWS Lambda, pour définir une autorisation de ressource sur la fonction Lambda ou pour effectuer toute autre action de service Lambda, choisissez plutôt Service.AWS ** + Sélectionnez **HTTP** si votre API doit être intégrée avec un point de terminaison HTTP existant. Pour de plus amples informations, veuillez consulter [Intégrations HTTP pour REST APIs dans API Gateway](setup-http-integrations.md). + Choisissez **Mock** si vous souhaitez générer des réponses d’API directement depuis API Gateway, sans recourir à un backend d’intégration. Pour de plus amples informations, veuillez consulter [Intégrations fictives pour REST APIs dans API Gateway](how-to-mock-integration.md). + Choisissez **AWS un service** si votre API doit être intégrée à un AWS service. + Choisissez **Lien VPC** si votre API doit utiliser un `VpcLink` en tant que point de terminaison d’intégration privé. Pour de plus amples informations, veuillez consulter [Configurez une intégration privée](set-up-private-integration.md). 1. Si vous avez sélectionné **Fonction Lambda**, procédez comme suit : 1. Pour **Utiliser une intégration proxy Lambda**, cochez la case si vous avez l’intention d’utiliser [Intégration proxy Lambda](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy) ou [Intégration proxy Lambda entre comptes](apigateway-cross-account-lambda-integrations.md). 1. Pour **Fonction Lambda**, spécifiez la fonction de l’une des manières suivantes : + Si votre Fonction Lambda se trouve dans le même compte, entrez le nom de la fonction, puis sélectionnez la fonction dans la liste déroulante. **Note** Le nom de la fonction peut éventuellement inclure son alias ou sa spécification de version, comme dans `HelloWorld`, `HelloWorld:1` ou `HelloWorld:alpha`. + Si la fonction se trouve dans un autre compte, tapez l’ARN de la fonction. 1. Pour utiliser la valeur de délai d'expiration par défaut de 29 secondes, gardez **Délai d'expiration** activé. Pour définir un délai d'expiration personnalisé, choisissez **Délai d'expiration** et entrez une valeur de délai d'expiration comprise entre `50` et `29000` millisecondes. 1. Si vous avez sélectionné **HTTP**, suivez les instructions de l’étape 4 de la section [Configuration d’une demande d’intégration d’API à l’aide de la console API Gateway](how-to-method-settings-console.md). 1. Si vous avez sélectionné **Mock (Fictif)**, passez à l’étape **Request Templates (Modèles de demande)**. 1. Si vous avez choisi **Service AWS **, suivez les instructions de l’étape 6 de [Configuration d’une demande d’intégration d’API à l’aide de la console API Gateway](how-to-method-settings-console.md). 1. Si vous avez sélectionné **Lien VPC**, procédez comme suit : 1. Pour **Intégration proxy au VPC**, sélectionnez la case à cocher si vous souhaitez que vos demandes soient traitées par proxy vers le point de terminaison de votre `VPCLink`. 1. Dans le champ **Méthode HTTP**, sélectionnez le type de méthode HTTP qui correspond le mieux au service backend HTTP. 1. Dans la liste déroulante **Lien VPC**, sélectionnez un lien VPC. Vous pouvez sélectionner `[Use Stage Variables]` et entrer **\$1\$1stageVariables.vpcLinkId\$1** dans la zone de texte en dessous de la liste. Vous pouvez définir la variable d’étape `vpcLinkId` après le déploiement de l’API dans une étape et définir sa valeur sur l’ID du `VpcLink`. 1. Pour **URL du point de terminaison**, entrez l’URL du back-end HTTP que cette intégration doit utiliser. 1. Pour utiliser la valeur de délai d'expiration par défaut de 29 secondes, gardez **Délai d'expiration** activé. Pour définir un délai d'expiration personnalisé, choisissez **Délai d'expiration** et entrez une valeur de délai d'expiration comprise entre `50` et `29000` millisecondes. 1. Sélectionnez **Enregistrer les modifications**. 1. Sous **Modèles de demande**, procédez comme suit : 1. Pour entrer une **Expression de sélection de modèle**, sous **Modèles de demande**, choisissez **Modifier**. 1. Entrez une **Expression de sélection de modèle**. Utilisez une expression qu’API Gateway recherche dans la charge utile du message. S’il la trouve, il l’évalue, et le résultat est une valeur de clé de modèle qui est utilisée pour sélectionner le modèle de mappage de données à appliquer aux données dans la charge utile du message. Vous créez le modèle de mappage de données à la prochaine étape. Choisissez **Modifier** pour enregistrer vos modifications. 1. Choisissez **Créer un modèle** pour créer le modèle de mappage de données. Pour **Clé de modèle**, entrez une valeur de clé de modèle qui est utilisée pour sélectionner le modèle de mappage de données à appliquer aux données dans la charge utile du message. Entrez ensuite un modèle de mappage. Sélectionnez **Create template (Créer un modèle)**. Pour plus d’informations sur les expressions de sélection du modèle, consultez la section [Expressions de sélection du modèle](websocket-api-data-transformations.md#apigateway-websocket-api-template-selection-expressions). ## Configurez une demande d'intégration à l'aide du AWS CLI Vous pouvez configurer une demande d'intégration pour un itinéraire dans une WebSocket API en utilisant l' AWS CLI exemple suivant, qui crée une intégration fictive : 1. Créez un fichier nommé `integration-params.json`, avec le contenu suivant : ``` {"PassthroughBehavior": "WHEN_NO_MATCH", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "RequestTemplates": {"application/json": "{\"statusCode\":200}"}, "IntegrationType": "MOCK"} ``` 1. Utilisez la commande [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) suivante pour créer l’intégration simulée. ``` aws apigatewayv2 --region us-east-1 create-integration --api-id aabbccddee --cli-input-json file://integration-params.json ``` Le résultat se présente comme suit : ``` { "PassthroughBehavior": "WHEN_NO_MATCH", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "IntegrationResponseSelectionExpression": "${response.statuscode}", "RequestTemplates": { "application/json": "{\"statusCode\":200}" }, "IntegrationId": "0abcdef", "IntegrationType": "MOCK" } ``` Vous pouvez également configurer une demande d'intégration pour une intégration par proxy en utilisant le AWS CLI. 1. Créez une fonction Lambda dans la console Lambda et attribuez-lui un rôle d’exécution Lambda de base. 1. Utilisez la commande [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) suivante pour créer l’intégration. ``` aws apigatewayv2 create-integration --api-id aabbccddee --integration-type AWS_PROXY --integration-method POST --integration-uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations ``` Le résultat se présente comme suit : ``` { "PassthroughBehavior": "WHEN_NO_MATCH", "IntegrationMethod": "POST", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "IntegrationUri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:simpleproxy-echo-e2e/invocations", "IntegrationId": "abcdefg", "IntegrationType": "AWS_PROXY" } ``` ## Format d'entrée d'une fonction Lambda pour l'intégration de proxy pour WebSocket APIs Avec l’intégration de proxy Lambda, API Gateway mappe l’intégralité de la demande du client avec le paramètre `event` en entrée de la fonction Lambda du backend. L’exemple suivant montre la structure de l’événement d’entrée de la route `$connect` et de l’événement d’entrée de la route `$disconnect` qu’API Gateway envoie à une intégration de proxy Lambda. ------ #### [ Input from the \$1connect route ] ``` { headers: { Host: 'abcd123.execute-api.us-east-1.amazonaws.com', 'Sec-WebSocket-Extensions': 'permessage-deflate; client_max_window_bits', 'Sec-WebSocket-Key': '...', 'Sec-WebSocket-Version': '13', 'X-Amzn-Trace-Id': '...', 'X-Forwarded-For': '192.0.2.1', 'X-Forwarded-Port': '443', 'X-Forwarded-Proto': 'https' }, multiValueHeaders: { Host: [ 'abcd123.execute-api.us-east-1.amazonaws.com' ], 'Sec-WebSocket-Extensions': [ 'permessage-deflate; client_max_window_bits' ], 'Sec-WebSocket-Key': [ '...' ], 'Sec-WebSocket-Version': [ '13' ], 'X-Amzn-Trace-Id': [ '...' ], 'X-Forwarded-For': [ '192.0.2.1' ], 'X-Forwarded-Port': [ '443' ], 'X-Forwarded-Proto': [ 'https' ] }, requestContext: { routeKey: '$connect', eventType: 'CONNECT', extendedRequestId: 'ABCD1234=', requestTime: '09/Feb/2024:18:11:43 +0000', messageDirection: 'IN', stage: 'prod', connectedAt: 1707502303419, requestTimeEpoch: 1707502303420, identity: { sourceIp: '192.0.2.1' }, requestId: 'ABCD1234=', domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com', connectionId: 'AAAA1234=', apiId: 'abcd1234' }, isBase64Encoded: false } ``` ------ #### [ Input from the \$1disconnect route ] ``` { headers: { Host: 'abcd1234.execute-api.us-east-1.amazonaws.com', 'x-api-key': '', 'X-Forwarded-For': '', 'x-restapi': '' }, multiValueHeaders: { Host: [ 'abcd1234.execute-api.us-east-1.amazonaws.com' ], 'x-api-key': [ '' ], 'X-Forwarded-For': [ '' ], 'x-restapi': [ '' ] }, requestContext: { routeKey: '$disconnect', disconnectStatusCode: 1005, eventType: 'DISCONNECT', extendedRequestId: 'ABCD1234=', requestTime: '09/Feb/2024:18:23:28 +0000', messageDirection: 'IN', disconnectReason: 'Client-side close frame status not set', stage: 'prod', connectedAt: 1707503007396, requestTimeEpoch: 1707503008941, identity: { sourceIp: '192.0.2.1' }, requestId: 'ABCD1234=', domainName: 'abcd1234.execute-api.us-east-1.amazonaws.com', connectionId: 'AAAA1234=', apiId: 'abcd1234' }, isBase64Encoded: false } ``` ------ # Configurer une réponse d'intégration d' WebSocket API dans API Gateway La section suivante fournit un bref aperçu des réponses d'intégration pour une WebSocket API et explique comment configurer une réponse d'intégration pour une WebSocket API. **Topics** + [Présentation des réponses d’intégration](#apigateway-websocket-api-integration-response-overview) + [Réponses d’intégration pour une communication bidirectionnelle](#apigateway-websocket-api-integration-response-for-two-way-communication) + [Configuration d’une réponse d’intégration à l’aide de la console API Gateway](#apigateway-websocket-api-integration-response-using-console) + [Configurez une réponse d'intégration à l'aide du AWS CLI](#apigateway-websocket-api-integration-response-using-awscli) ## Présentation des réponses d’intégration La réponse d’intégration d’API Gateway permet de modéliser et de manipuler la réponse reçue d’un service backend. Il existe certaines différences entre la configuration d'une API REST et une réponse d'intégration d' WebSocket API, mais le comportement est conceptuellement le même. WebSocket les itinéraires peuvent être configurés pour une communication bidirectionnelle ou unidirectionnelle. + Lorsqu'un itinéraire est configuré pour une communication bidirectionnelle, une réponse d'intégration vous permet de configurer des transformations sur la charge utile du message renvoyé, de la même manière que les réponses d'intégration pour REST. APIs + Si un itinéraire est configuré pour une communication unidirectionnelle, quelle que soit la configuration de réponse d'intégration, aucune réponse ne sera renvoyée sur le WebSocket canal une fois le message traité. API Gateway ne transmet pas la réponse du backend à la réponse de routage, sauf si vous avez configuré une réponse de routage. Pour en savoir plus sur la configuration d’une réponse de routage, consultez [Configuration des réponses d'itinéraire pour WebSocket APIs dans API Gateway](apigateway-websocket-api-route-response.md). ## Réponses d’intégration pour une communication bidirectionnelle Les intégrations peuvent être divisées en intégrations de *proxy* et *autres que de proxy*. **Important** Pour les *intégrations de proxy*, API Gateway transmet automatiquement la sortie du backend à l’appelant en tant que charge utile complète. Il n’y a pas de réponse d’intégration. Pour les *intégrations autres que de proxy*, vous devez configurer au moins une réponse d’intégration : + Idéalement, une de vos réponses d’intégration doit servir de fourre-tout lorsqu’aucun choix explicite ne peut être effectué. Ce cas par défaut est représenté en définissant une clé de réponse d’intégration `$default`. + Dans tous les autres cas, la clé de réponse d’intégration fonctionne en tant qu’expression régulière. Elle doit suivre le format `"/expression/"`. Pour les intégrations HTTP autres que de proxy : + API Gateway tente de mettre en correspondance le code de statut HTTP de la réponse du backend. Dans ce cas, la clé de réponse d’intégration fonctionne en tant qu’expression régulière. Si aucune correspondance n’est trouvée, `$default` est choisi en tant que réponse d’intégration. + L’expression de sélection du modèle décrite ci-dessus fonctionne de manière identique. Exemples : + `/2\d\d/` : reçoit et transforme les réponses fructueuses + `/4\d\d/` : reçoit et transforme les erreurs de demande incorrecte + `$default` : reçoit et transforme toutes les réponses inattendues Pour en savoir plus sur les expressions de sélection de modèle, consultez [Expressions de sélection du modèle](websocket-api-data-transformations.md#apigateway-websocket-api-template-selection-expressions). ## Configuration d’une réponse d’intégration à l’aide de la console API Gateway Pour configurer une réponse d'intégration d'itinéraires pour une WebSocket API à l'aide de la console API Gateway : 1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Choisissez votre WebSocket API et votre itinéraire. 1. Choisissez l’onglet **Demande d’intégration**, puis dans la section **Paramètres de la réponse d’intégration**, choisissez **Créer une réponse d’intégration**. 1. Pour **Clé de réponse**, saisissez une valeur qui sera trouvée dans la clé de réponse trouvée dans le message sortant après avoir évalué l’expression de sélection de réponse. Par exemple, vous pouvez entrer **/4\$1d\$1d/** pour recevoir et transformer les erreurs de mauvaise demande ou entrer **\$1default** pour recevoir et transformer toutes les réponses qui correspondent à l’expression de sélection du modèle. 1. Pour **Expression de sélection du modèle**, entrez une expression de sélection pour évaluer le message sortant. 1. Choisissez **Créer une réponse**. 1. Vous pouvez également définir un modèle de mappage pour configurer les transformations de votre charge utile de message renvoyé. Sélectionnez **Create template (Créer un modèle)**. 1. Saisissez un nom de clé. Si vous choisissez l’expression de sélection de modèle par défaut, saisissez **\$1\$1default**. 1. Pour **Modèle de réponse**, entrez votre modèle de mappage dans l’éditeur de code. 1. Sélectionnez **Create template (Créer un modèle)**. 1. Choisissez **Déployer l’API** pour déployer votre API. Utilisez la commande [wscat](https://www.npmjs.com/package/wscat) suivante pour vous connecter à votre API. Pour plus d’informations sur `wscat`, consultez [`wscat`À utiliser pour se connecter à une WebSocket API et y envoyer des messages](apigateway-how-to-call-websocket-api-wscat.md). ``` wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test ``` Lorsque vous appelez votre route, la charge utile de message renvoyé est renvoyée. ## Configurez une réponse d'intégration à l'aide du AWS CLI La [create-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration-response.html)commande suivante crée une réponse `$default` d'intégration : ``` aws apigatewayv2 create-integration-response \ --api-id vaz7da96z6 \ --integration-id a1b2c3 \ --integration-response-key '$default' ``` # Demande de validation pour WebSocket APIs in API Gateway Vous pouvez configurer API Gateway afin qu’il exécute la validation d’une requête de routage avant de continuer avec la demande d’intégration. Si la validation échoue, API Gateway échoue à la demande sans appeler votre backend, envoie une réponse de passerelle « Bad request body » au client et publie les résultats de la validation dans les CloudWatch journaux. L’utilisation de la validation de cette façon réduit les appels inutiles vers votre back-end d’API. ## Expressions de sélection du modèle Vous pouvez utiliser une expression de sélection de modèle pour valider dynamiquement les requêtes au sein d’une même route. La validation du modèle se produit si vous fournissez une expression de sélection de modèle pour les intégrations proxy ou autres que de proxy. Vous devrez peut-être définir le modèle `$default` comme solution de secours si aucun modèle correspondant n’est trouvé. S’il n’y a pas de modèle correspondant et que `$default` n’est pas défini, la validation échoue. L’expression de sélection ressemble à `Route.ModelSelectionExpression` et évalue à la clé pour `Route.RequestModels`. Lorsque vous définissez un itinéraire pour une WebSocket API, vous pouvez éventuellement spécifier une *expression de sélection de modèle*. Cette expression est évaluée pour sélectionner le modèle à utiliser pour la validation du corps lors de la réception d’une requête. L’expression correspond à l’une des entrées de l’élément d’une route [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels). Un modèle est exprimé sous forme de [schéma JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) et décrit la structure des données du corps de la requête. La nature de ces expressions de sélection vous permet de choisir de manière dynamique le modèle à utiliser pour la validation lors de l’exécution pour une route particulière. Pour plus d’informations sur la création d’un modèle, consultez la section [Modèles de données pour REST APIs](models-mappings-models.md). ## Configuration de la validation des requêtes à l’aide de la console API Gateway L’exemple suivant vous montre comment configurer une validation des demandes sur une route. Vous devez d’abord créer un modèle, puis une route. Ensuite, vous devez configurer la validation des demandes sur la route que vous venez de créer. Enfin, vous devez déployer et tester votre API. Pour terminer ce didacticiel, vous avez besoin d'une WebSocket API `$request.body.action` servant d'expression de sélection d'itinéraire et d'un point de terminaison d'intégration pour votre nouvel itinéraire. Vous avez également besoin de `wscat` pour vous connecter à votre API. Pour de plus amples informations, veuillez consulter [`wscat`À utiliser pour se connecter à une WebSocket API et y envoyer des messages](apigateway-how-to-call-websocket-api-wscat.md). **Pour créer un modèle** 1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Choisissez une WebSocket API. 1. Dans le volet de navigation principal, choisissez **Modèles**. 1. Sélectionnez **Créer un modèle**. 1. Pour **Nom**, saisissez **emailModel**. 1. Pour **Type de contenu**, entrez **application/json**. 1. Pour **Schéma du modèle**, saisissez le modèle qui suit : ``` { "$schema": "http://json-schema.org/draft-04/schema#", "type" : "object", "required" : [ "address"], "properties" : { "address": { "type": "string" } } } ``` Ce modèle nécessite que la requête contienne une adresse e-mail. 1. Choisissez **Enregistrer**. Au cours de cette étape, vous allez créer un itinéraire pour votre WebSocket API. **Pour créer une route** 1. Dans le volet de navigation principal, sélectionnez **Routes**. 1. Choisissez **Create Route (Créer un itinéraire)**. 1. Pour **Route key (Clé de route)**, entrez **sendMessage**. 1. Choisissez un type d’intégration et spécifiez un point de terminaison d’intégration. Pour plus d’informations, consultez [Intégrations pour WebSocket APIs in API Gateway](apigateway-websocket-api-integrations.md). 1. Choisissez **Create Route (Créer un itinéraire)**. Au cours de cette étape, vous allez configurer la validation des demandes pour la route `sendMessage`. **Pour configurer une validation des demandes** 1. Dans l’onglet **Requête de routage**, sous **Paramètres de requête de routage**, choisissez **Modifier**. 1. Pour **Expression de sélection de modèle**, saisissez **\$1\$1request.body.messageType\$1**. API Gateway utilise la propriété `messageType` pour valider la requête entrante. 1. Choisissez **Ajouter un modèle de requête**. 1. Pour **Clé de modèle**, saisissez **email**. 1. Pour **Modèle**, choisissez **emailModel**. API Gateway valide les messages entrants avec la propriété `messageType` définie sur `email` pour ce modèle. **Note** Si API Gateway ne parvient pas à faire correspondre l’expression de sélection du modèle à une clé de modèle, le modèle `$default` est sélectionné. S’il n’y a pas de modèle `$default`, la validation échoue. Pour la production APIs, nous vous recommandons de créer un `$default` modèle. 1. Sélectionnez **Enregistrer les modifications**. Au cours de cette étape, vous allez déployer et tester votre API. **Pour déployer et tester votre API** 1. Sélectionnez **Deploy API (Déployer une API)**. 1. Choisissez l’étape souhaitée dans la liste déroulante ou saisissez le nom d’une nouvelle étape. 1. Choisissez **Déployer**. 1. Dans le volet de navigation principal, choisissez **Étapes**. 1. Copiez l' WebSocket URL de votre API. L’URL doit ressembler à `wss://abcdef123.execute-api.us-east-2.amazonaws.com/production`. 1. Ouvrez un nouveau terminal et exécutez la commande **wscat** avec les paramètres suivants. ``` wscat -c wss://abcdef123.execute-api.us-west-2.amazonaws.com/production ``` ``` Connected (press CTRL+C to quit) ``` 1. Utilisez la commande suivante pour tester votre API. ``` {"action": "sendMessage", "messageType": "email"} ``` ``` {"message": "Invalid request body", "connectionId":"ABCD1=234", "requestId":"EFGH="} ``` API Gateway rejettera la requête. Utilisez la commande suivante pour envoyer une demande valide à votre API. ``` {"action": "sendMessage", "messageType": "email", "address": "mary_major@example.com"} ``` # 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. | # Types de supports binaires pour les API WebSocket dans API Gateway Les API WebSocket d’API Gateway ne prennent actuellement pas en charge les trames binaires dans les charges utiles des messages entrants. Si une application client envoie une trame binaire, API Gateway la rejette et déconnecte le client avec le code 1003. Il existe une solution pour contourner ce comportement. Si le client envoie des données binaires encodées au format texte (par exemple, base64) en tant que trame de texte, vous pouvez définir la propriété `contentHandlingStrategy` de l’intégration sur `CONVERT_TO_BINARY` pour convertir la charge utile de la chaîne encodée en base64 au format binaire. Pour renvoyer une réponse de routage pour une charge utile binaire dans des intégrations autres que de proxy, vous pouvez définir la propriété `contentHandlingStrategy` de la réponse d’intégration sur `CONVERT_TO_TEXT` pour convertir la charge utile du format binaire en chaîne encodée en base64. # Invoquer WebSocket APIs Une fois que vous avez déployé votre WebSocket API, les applications clientes peuvent s'y connecter et lui envoyer des messages, et votre service principal peut envoyer des messages aux applications clientes connectées : + Vous pouvez l'utiliser `wscat` pour vous connecter à votre WebSocket API et lui envoyer des messages afin de simuler le comportement du client. Voir [`wscat`À utiliser pour se connecter à une WebSocket API et y envoyer des messages](apigateway-how-to-call-websocket-api-wscat.md). + Vous pouvez utiliser l’API @connections à partir de votre service backend pour envoyer un message de rappel à un client connecté, obtenir des informations de connexion ou déconnecter le client. Voir [Utilisation des commandes `@connections` dans votre service backend](apigateway-how-to-call-websocket-api-connections.md). + Une application cliente peut utiliser sa propre WebSocket bibliothèque pour appeler votre WebSocket API. # `wscat`À utiliser pour se connecter à une WebSocket API et y envoyer des messages Cet `[wscat](https://www.npmjs.com/package/wscat)` utilitaire est un outil pratique pour tester une WebSocket API que vous avez créée et déployée dans API Gateway. Vous pouvez installer et utiliser `wscat` comme suit : 1. Téléchargez `wscat` depuis [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat). 1. Installez `wscat` en exécutant les commandes suivantes. ``` npm install -g wscat ``` 1. Pour vous connecter à votre API, exécutez la commande `wscat` comme illustré dans l’exemple suivant. Notez que cet exemple part du principe que le paramètre `Authorization` est défini sur `NONE`. ``` wscat -c wss://aabbccddee.execute-api.us-east-1.amazonaws.com/test/ ``` Vous devez remplacer `aabbccddee` par l’ID réel de l’API qui est affiché dans la console API Gateway ou renvoyé par la commande [https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) de l’ AWS CLI . En outre, si votre API se trouve dans une région autre que `us-east-1`, vous devez remplacer la région par la région correcte. 1. Pour tester votre API, entrez un message tel que le suivant une fois connecté : ``` {"{jsonpath-expression}":"{route-key}"} ``` où *\$1jsonpath-expression\$1* est une JSONPath expression et *\$1route-key\$1* une clé de route pour l'API. Par exemple : ``` {"action":"action1"} {"message":"test response body"} ``` Pour plus d'informations sur JSONPath, voir [JSONPath](https://goessner.net/articles/JsonPath/)ou [JSONPath pour Java](https://github.com/json-path/JsonPath). 1. Pour vous déconnecter de votre API, entrez `ctrl-C`. # Utilisation des commandes `@connections` dans votre service backend Votre service principal peut utiliser les requêtes HTTP de WebSocket connexion suivantes pour envoyer un message de rappel à un client connecté, obtenir des informations de connexion ou déconnecter le client. **Important** Ces demandes utilisent l’[autorisation IAM](apigateway-websocket-control-access-iam.md). Vous devez donc les signer avec [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). Pour ce faire, vous pouvez utiliser l’API de gestion API Gateway. Pour de plus amples informations, veuillez consulter [ApiGatewayManagementApi](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigatewaymanagementapi.html). Dans la commande suivante, vous devez le `{api-id}` remplacer par l'identifiant d'API réel, qui est affiché dans la console API Gateway ou renvoyé par la commande AWS CLI [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html). Vous devez établir la connexion avant d’utiliser cette commande. Pour envoyer un message de rappel au client, utilisez : ``` POST https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id} ``` Vous pouvez tester cette demande en utilisant `[Postman](https://www.postman.com/)` ou en appelant `[awscurl](https://github.com/okigan/awscurl)` comme dans l’exemple suivant : ``` awscurl --service execute-api -X POST -d "hello world" https://{prefix}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id} ``` Vous avez besoin de coder la commande en URL comme dans l’exemple suivant : ``` awscurl --service execute-api -X POST -d "hello world" https://aabbccddee.execute-api.us-east-1.amazonaws.com/prod/%40connections/R0oXAdfD0kwCH6w%3D ``` Pour obtenir le dernier état de connexion du client, utilisez : ``` GET https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id} ``` Pour déconnecter le client, utilisez : ``` DELETE https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id} ``` Vous pouvez générer dynamiquement une URL de rappel en utilisant les variables `$context` dans votre intégration. Par exemple, si vous utilisez l’intégration de proxy Lambda avec une fonction Lambda `Node.js`, vous pouvez générer l’URL et envoyer un message à un client connecté comme suit : ``` import { ApiGatewayManagementApiClient, PostToConnectionCommand, } from "@aws-sdk/client-apigatewaymanagementapi"; export const handler = async (event) => { const domain = event.requestContext.domainName; const stage = event.requestContext.stage; const connectionId = event.requestContext.connectionId; const callbackUrl = `https://${domain}/${stage}`; const client = new ApiGatewayManagementApiClient({ endpoint: callbackUrl }); const requestParams = { ConnectionId: connectionId, Data: "Hello!", }; const command = new PostToConnectionCommand(requestParams); try { await client.send(command); } catch (error) { console.log(error); } return { statusCode: 200, }; }; ``` Si vous utilisez un nom de domaine personnalisé pour votre WebSocket API, supprimez la `stage` variable de votre code de fonction. Lorsque vous envoyez un message de rappel, votre fonction Lambda doit être autorisée à appeler l’API de gestion d’API Gateway. Vous pouvez recevoir un message d’erreur contenant `GoneException` si vous publiez un message avant l’établissement de la connexion ou après la déconnexion du client.