Didacticiel : création d’une API WebSocket avec une intégration AWS

Pour créer une pile AWS CloudFormation

1. Ouvrez la console AWS CloudFormation, à l’adresse https://console.aws.amazon.com/cloudformation.

2. Choisissez Créer une pile, puis choisissez Avec de nouvelles ressources (standard).

3. Dans Spécifier le modèle, choisissez Charger un modèle de fichier.

4. Sélectionnez le modèle que vous avez téléchargé.

5. Choisissez Suivant.

6. Pour Nom de la pile, saisissez websocket-step-functions-tutorial, puis choisissez Suivant.

7. Pour Configurer les options de pile, choisissez Suivant.

8. Pour Capacités, sachez que AWS CloudFormation peut créer des ressources IAM dans votre compte.

9. Sélectionnez Envoyer.

Pour créer une API WebSocket

1. Connectez-vous à la console API Gateway à l’adresse : https://console.aws.amazon.com/apigateway.

2. Sélectionnez Create API (Créer une API). Ensuite, sous WebSocket API (API WebSocket), choisissez Build (Créer).

3. Sous API name (Nom de l’API), saisissez websocket-step-functions-tutorial.

4. Pour Route selection expression (Expression de sélection de route), entrez request.body.action.

   Expression de sélection de route pour déterminer la route à appeler lorsqu’un client envoie un message.

5. Choisissez Suivant.

6. Pour Routages prédéfinis, choisissez Ajouter $connect, Ajouter $disconnect et Ajouter $default.

   Les routes $connect et $disconnect sont des itinéraires spéciaux qu’API Gateway appelle automatiquement lorsqu’un client se connecte à une API ou se déconnecte de celle-ci. API Gateway invoque la route $default lorsqu’aucune autre route ne correspond à une demande. Vous devez créer une route personnalisée pour vous connecter à Step Functions après avoir créé votre API.

7. Choisissez Suivant.

8. Pour Intégration de $connect, procédez comme suit :

   1. Pour Type d’intégration, choisissez Lambda.

   2. Pour Fonction Lambda, choisissez la fonction Lambda $connect que vous avez créée avec AWS CloudFormation à l’étape 1. Le nom de la fonction Lambda doit commencer par websocket-step.

9. Pour Intégration de $disconnect, procédez comme suit :

   1. Pour Type d’intégration, choisissez Lambda.

   2. Pour Fonction Lambda, choisissez la fonction Lambda $disconnect que vous avez créée avec AWS CloudFormation à l’étape 1. Le nom de la fonction Lambda doit commencer par websocket-step.

10. Pour Intégration de $default, choisissez Mock.

    Dans une intégration simulée, API Gateway gère la réponse de routage sans backend d’intégration.

11. Choisissez Suivant.

12. Passez en revue l’étape créée par API Gateway pour vous. Par défaut, API Gateway crée une étape nommée production et déploie automatiquement votre API dans cette étape. Choisissez Suivant.

13. Choisissez Create and deploy (Créer et déployer).

Pour créer un mécanisme d’autorisation Lambda

1. Connectez-vous à la console API Gateway à l’adresse : https://console.aws.amazon.com/apigateway.

2. Dans le panneau de navigation principal, choisissez Mécanismes d’autorisation.

3. Choisissez Créer un mécanisme d’autorisation.

4. Pour Nom du mécanisme d’autorisation, saisissez LambdaAuthorizer.

5. Pour ARN du mécanisme d’autorisation, saisissez le nom du mécanisme d’autorisation créé par le modèle AWS CloudFormation. Son nom doit commencer par websocket-step-functions-tutorial-AuthorizerHandler.

   Note

   Nous vous recommandons de ne pas utiliser cet exemple de mécanisme d’autorisation pour vos API de production.

6. Pour Type de source d’identité, choisissez En-tête. Pour Key (Clé), saisissez Authorization.

7. Choisissez Créer un mécanisme d’autorisation.

Pour attacher un mécanisme d’autorisation à la route $connect

1. Dans le volet de navigation principal, sélectionnez Routes.

2. Choisissez la route $connect.

3. Dans la section Paramètres de requête de routage, choisissez Modifier.

4. Pour Autorisation, sélectionnez le menu déroulant, puis votre mécanisme d’autorisation de requête.

5. Sélectionnez Enregistrer les modifications.

Pour créer une intégration simulée

1. Connectez-vous à la console API Gateway à l’adresse : https://console.aws.amazon.com/apigateway.

2. Choisissez la route $default, puis l’onglet Requête d’intégration.

3. Pour Modèles de requête, choisissez Modifier.

4. Pour Expression de sélection de modèle, saisissez 200, puis choisissez Modifier.

5. Dans l’onglet Requête d’intégration, pour Modèles de requête, choisissez Créer un modèle.

6. Pour Clé de modèle, saisissez 200.

7. Pour Générer un modèle, saisissez le modèle de mappage suivant :

   {"statusCode": 200}

   Sélectionnez Create template (Créer un modèle).

   Le résultat doit avoir l’aspect suivant :

   

8. Dans le volet Route $default, choisissez Activer la communication bidirectionnelle.

9. Choisissez l’onglet Réponse d’intégration, puis sélectionnez Créer une réponse d’intégration.

10. Pour Clé de réponse, saisissez $default.

11. Pour Expression de sélection de modèle, saisissez 200.

12. Choisissez Créer une réponse.

13. Sous Modèles de réponse, choisissez Créer un modèle.

14. Pour Clé de modèle, saisissez 200.

15. Pour Modèle de réponse, saisissez le modèle de mappage suivant :

    {"Use the sendmessage route to send a message. Connection ID: $context.connectionId"}

16. Sélectionnez Create template (Créer un modèle).

    Le résultat doit avoir l’aspect suivant :

    

Pour créer une intégration sans proxy

1. Connectez-vous à la console API Gateway à l’adresse : https://console.aws.amazon.com/apigateway.

2. Choisissez Create Route (Créer un itinéraire).

3. Pour Route key (Clé de route), entrez sendmessage.

4. Pour Type d’intégration, choisissez Service AWS.

5. Pour Région AWS, saisissez la région dans laquelle vous avez déployé votre modèle AWS CloudFormation.

6. Pour Service AWS, choisissez Step Functions.

7. Dans le champ HTTP Method, sélectionnez POST.

8. Pour Nom de l’action, saisissez StartExecution.

9. Pour Rôle d’exécution, saisissez le rôle d’exécution créé par le modèle AWS CloudFormation. Le nom doit être WebsocketTutorialApiRole.

10. Choisissez Create Route (Créer un itinéraire).

Pour créer un modèle de mappage

1. Choisissez la route sendmessage, puis l’onglet Requête d’intégration.

2. Dans la section Modèles de requête, choisissez Modifier.

3. Pour Expression de sélection de modèle, saisissez \$default.

4. Choisissez Modifier.

5. Dans la section Modèles de requête, choisissez Créer un modèle.

6. Pour Clé de modèle, saisissez \$default.

7. Pour Générer un modèle, saisissez le modèle de mappage suivant :

   #set($domain = "$context.domainName")
   #set($stage = "$context.stage")
   #set($body = $input.json('$'))
   #set($getMessage = $util.parseJson($body))
   #set($mymessage = $getMessage.message)
   {
   "input": "{\"domain\": \"$domain\", \"stage\": \"$stage\", \"message\": \"$mymessage\"}",
   "stateMachineArn": "arn:aws:states:us-east-2:123456789012:stateMachine:WebSocket-Tutorial-StateMachine"
   }

   Remplacez stateMachineArn par l’ARN de la machine d’état créé par AWS CloudFormation.

   Le modèle de mappage :

   • Crée la variable $domain à l’aide de la variable contextuelle domainName.

   • Crée la variable $stage à l’aide de la variable contextuelle stage.

     Les variables $domain et $stage sont nécessaires pour créer une URL de rappel.

   • Prend le message JSON sendmessage entrant et en extrait la propriété message.

   • Crée l’entrée pour la machine d’état. L’entrée correspond au domaine et à l’étape de l’API WebSocket et au message de la route sendmessage.

8. Sélectionnez Create template (Créer un modèle).

   

Pour déployer votre API

1. Connectez-vous à la console API Gateway à l’adresse : https://console.aws.amazon.com/apigateway.

2. Dans le volet de navigation principal, sélectionnez Routes.

3. Sélectionnez Deploy API (Déployer une API).

4. Pour Étape, sélectionnez production.

5. (Facultatif) Pour Description du déploiement, saisissez une description.

6. Choisissez Deploy (Déployer).

Pour obtenir l’URL d’invocation de votre API

1. Choisissez votre API.

2. Choisissez Stages (Étapes), puis production.

3. Notez l’URL WebSocket de votre API. L’URL doit ressembler à wss://abcdef123.execute-api.us-east-2.amazonaws.com/production.

Pour tester la connexion à votre API

1. Utilisez la commande suivante pour vous connecter à votre API. Tout d’abord, vous allez tester la connexion en invoquant le chemin /ping.

   wscat -c wss://abcdef123.execute-api.us-east-2.amazonaws.com/production -H "Authorization: Allow" --slash -P

   Connected (press CTRL+C to quit)

2. Saisissez la commande suivante pour effectuer un ping du cadre de contrôle. Vous pouvez utiliser un cadre de contrôle pour le keepalive côté client.

   /ping

   Le résultat doit avoir l’aspect suivant :

   < Received pong (data: "")

Pour tester votre API

1. Ouvrez un nouveau terminal et exécutez à nouveau la commande wscat avec les paramètres suivants.

   wscat -c wss://abcdef123.execute-api.us-east-2.amazonaws.com/production -H "Authorization: Allow"

   Connected (press CTRL+C to quit)

2. API Gateway détermine la route à invoquer en fonction de l’expression de sélection de requête de routage de votre API. L’expression de sélection de route de votre API est $request.body.action. Par conséquent, API Gateway appelle la route sendmessage lorsque vous envoyez le message suivant :

   {"action": "sendmessage", "message": "hello, from Step Functions!"}

   La machine d’état Step Functions associée à la route invoque une fonction Lambda avec le message et l’URL de rappel. La fonction Lambda appelle l’API API Gateway Management et envoie le message à tous les clients connectés. Tous les clients reçoivent le message suivant :

   < hello, from Step Functions!

Pour vous déconnecter de votre API

• Pour vous déconnecter de votre API, appuyez sur CTRL+C.

  Lorsqu’un client se déconnecte de votre API, API Gateway invoque la route $disconnect de votre API. L’intégration Lambda pour la route $disconnect de votre API supprime l’ID de connexion de DynamoDB.

Pour supprimer une API WebSocket

1. Connectez-vous à la console API Gateway à l’adresse : https://console.aws.amazon.com/apigateway.

2. Sur la page API, sélectionnez votre websocket-api.

3. Choisissez Actions, choisissez Supprimer, puis confirmez votre choix.

Pour supprimer une pile AWS CloudFormation

1. Ouvrez la console AWS CloudFormation, à l’adresse https://console.aws.amazon.com/cloudformation.

2. Sélectionnez votre pile AWS CloudFormation.

3. Choisissez Supprimer, puis confirmez votre choix.