Configuration d'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 au serveur principal

• Spécifier le point de terminaison du backend à appeler. WebSocket Les API 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 IntegrationTypel'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.

2. Sous Routes, choisissez la route.

3. Choisissez l'onglet Demande d'intégration, puis dans la section Paramètres de la demande d'intégration, choisissez Modifier.

4. 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 à un point de terminaison HTTP existant. Pour de plus amples informations, veuillez consulter Configuration des intégrations HTTP dans API Gateway.

   • 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 Configuration des intégrations fictives dans API Gateway.

   • 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 Configuration des intégrations privées API Gateway.

5. 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 ou Intégration proxy Lambda entre comptes.

   2. 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.

   3. 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.

6. 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.

7. Si vous avez sélectionné Mock (Fictif), passez à l'étape Request Templates (Modèles de demande).

8. 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.

9. 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.

   2. Dans le champ HTTP method, sélectionnez le type de méthode HTTP qui correspond le mieux au service backend HTTP.

   3. Dans la liste déroulante Lien VPC, sélectionnez un lien VPC. Vous pouvez sélectionner [Use Stage Variables] et entrer ${stageVariables.vpcLinkId} 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 à une étape et définir sa valeur sur l'ID du VpcLink.

   4. Pour URL du point de terminaison, entrez l'URL du back-end HTTP que cette intégration doit utiliser.

   5. 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.

10. Sélectionnez Enregistrer les modifications.

11. 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.

    2. 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.

    3. 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.

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

2. Exécutez la commande create-integration, comme illustré dans l'exemple suivant :

   aws apigatewayv2 --region us-east-1 create-integration --api-id aabbccddee --cli-input-json file://integration-params.json

Cet exemple renvoie l'exemple de sortie suivant :

{
    "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 AWS CLI en utilisant l'exemple suivant :

1. Créez une fonction Lambda dans la console Lambda et attribuez-lui un rôle d'exécution Lambda de base.

2. Exécutez la commande create-integration, comme dans l'exemple suivant :

   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

Cet exemple renvoie l'exemple de sortie suivant :

{
    "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 les API WebSocket

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 $connect route et de l'événement d'entrée de la $disconnect route qu'API Gateway envoie à une intégration de proxy Lambda.

Input from the $connect 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 $disconnect 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
  }