Configurer une demande WebSocket API d'intégration 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 APIsprennent 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, reportez-vous IntegrationTypeà la section API Gateway V2 RESTAPI.

• 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

Configurer une demande d' WebSocket APIintégration à l'aide de la console API Gateway

Pour ajouter une demande d'intégration à un itinéraire à WebSocket API l'aide de la console API Gateway

1. Connectez-vous à la console API Gateway, choisissez leAPI, 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 API vous souhaitez ê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

   • Choisissez HTTPAPIsi vous souhaitez être intégré à un point de HTTP terminaison existant. Pour de plus amples informations, veuillez consulter Intégrations HTTP pour les API REST dans API Gateway.

   • Choisissez Mock si vous souhaitez générer des API réponses directement depuis API Gateway, sans avoir besoin d'un backend d'intégration. Pour de plus amples informations, veuillez consulter Intégrations fictives pour les API REST dans API Gateway.

   • Choisissez AWS un service si API vous souhaitez être intégré à un AWS service.

   • Choisissez VPCle lien si API vous souhaitez utiliser un VpcLink comme point de terminaison d'intégration privé. Pour de plus amples informations, veuillez consulter Intégrations privées pour REST APIs in Gateway API.

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, entrez le nom 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 le souhaitez HTTP, suivez les instructions de l'étape 4 deConfiguration 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 choisi VPCle lien, procédez comme suit :

   1. Pour l'intégration du VPC proxy, cochez la case si vous souhaitez que vos demandes soient transmises par proxy à votre point VPCLink de terminaison.

   2. Pour la HTTPméthode, choisissez le type de HTTP méthode qui correspond le mieux à la méthode du HTTP backend.

   3. Dans la liste déroulante des VPCliens, sélectionnez un VPC lien. 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'vpcLinkIdétape après l'APIavoir déployée sur une étape et définir sa valeur sur l'ID duVpcLink.

   4. Pour Endpoint URL, entrez URL le HTTP backend que vous souhaitez que cette intégration utilise.

   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 que 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 un en WebSocket API 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 indiqué 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 WebSocket APIs

Dans le cadre de l'intégration du proxy Lambda, API Gateway mappe l'intégralité de la demande du client au event paramètre d'entrée de la fonction Lambda principale. 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 que 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
  }