Configurazione di una richiesta di integrazione WebSocket API in API Gateway

La configurazione di una richiesta di integrazione comporta le seguenti operazioni:

• Selezione di una chiave di instradamento da integrare nel back-end.

• Specificazione dell'endpoint di backend da richiamare. WebSocket Le API supportano i seguenti tipi di integrazione:

  • AWS_PROXY

  • AWS

  • HTTP_PROXY

  • HTTP

  • MOCK

  Per ulteriori informazioni sui tipi di integrazione, consulta IntegrationTypel'API REST di API Gateway V2.

• Configurazione della modalità di trasformazione dei dati della richiesta di instradamento, se necessario, in dati di richiesta di integrazione specificando uno o più modelli di richiesta.

Configurare una richiesta di integrazione WebSocket API utilizzando la console API Gateway

Per aggiungere una richiesta di integrazione a un percorso in un' WebSocket API utilizzando la console API Gateway

1. Accedere alla console API Gateway, scegliere l'API e selezionare Routes (Route).

2. In Routes (Route), scegliere la route.

3. Scegli la scheda Richiesta di integrazione, quindi seleziona Modifica nella sezione Impostazioni della richiesta di integrazione.

4. Per Tipo di integrazione scegli una delle seguenti opzioni:

   • Scegli la funzione Lambda solo se la tua API sarà integrata con una AWS Lambda funzione che hai già creato in questo account o in un altro account.

     Per creare una nuova funzione Lambda in AWS Lambda, impostare un'autorizzazione di risorsa sulla funzione Lambda o eseguire qualsiasi altra azione del servizio Lambda, scegli invece Service.AWS

   • Scegliere HTTP se l'API verrà integrata con un endpoint HTTP esistente. Per ulteriori informazioni, consulta Configurazione di integrazioni HTTP in API Gateway.

   • Scegliere Mock (Fittizio) se si desidera generare le risposte API direttamente da API Gateway, senza la necessità di un back-end di integrazione. Per ulteriori informazioni, consulta Configurazione di integrazioni HTTP fittizie in API Gateway.

   • Scegli AWS service se la tua API sarà integrata con un servizio. AWS

   • Scegli Collegamento VPC se l'API utilizzerà un VpcLink come endpoint di integrazione privato. Per ulteriori informazioni, consulta Configurazione delle integrazioni private di API Gateway.

5. Se scegli Funzione Lambda procedi come segue:

   1. Per Utilizza integrazione proxy Lambda seleziona la casella di controllo desiderata per utilizzare l'integrazione proxy Lambda o l'integrazione proxy Lambda tra più account.

   2. Per Funzione Lambda specifica la funzione in uno dei modi seguenti:

      • Se la funzione Lambda si trova nello stesso account, immetti il nome della funzione e quindi seleziona la funzione dall'elenco a discesa.

        Nota

        Il nome della funzione può facoltativamente includere l'alias o la specifica della versione, come in HelloWorld, HelloWorld:1 o HelloWorld:alpha.

      • Se la funzione si trova in un account diverso, immettere l'ARN per la funzione.

   3. Per utilizzare il valore di timeout predefinito di 29 secondi, mantieni attiva l'opzione Timeout predefinito. Per impostare un timeout personalizzato, scegli Timeout predefinito e immetti un valore di timeout compreso tra 50 e 29000 millisecondi.

6. Se si sceglie HTTP, seguire le istruzioni nella fase 4 di Configurazione di una richiesta di integrazione API tramite la console API Gateway.

7. Se si sceglie Mock (Fittizio), andare alla fase Request Templates (Modelli di richiesta).

8. Se scegli Servizio AWS segui le istruzioni della fase 6 in Configurazione di una richiesta di integrazione API tramite la console API Gateway.

9. Se scegli Collegamento VPC procedi come segue:

   1. Per Integrazione proxy VPC seleziona la casella di controllo se desideri eseguire il proxy delle richieste sull'endpoint di VPCLink.

   2. Per HTTP method (Metodo HTTP) scegliere il tipo di metodo HTTP che corrisponde maggiormente al metodo nel back-end HTTP.

   3. Dall'elenco a discesa Collegamento VPC seleziona un collegamento VPC. È possibile selezionare [Use Stage Variables] e inserire ${stageVariables.vpcLinkId} nella casella di testo sotto l'elenco.

      È possibile definire la variabile di fase vpcLinkId dopo l'implementazione dell'API in una fase e l'impostazione del suo valore sull'ID del VpcLink.

   4. In Endpoint URL (URL endpoint), immettere l'URL del back-end HTTP che l'integrazione deve utilizzare.

   5. Per utilizzare il valore di timeout predefinito di 29 secondi, mantieni attiva l'opzione Timeout predefinito. Per impostare un timeout personalizzato, scegli Timeout predefinito e immetti un valore di timeout compreso tra 50 e 29000 millisecondi.

10. Seleziona Salvataggio delle modifiche.

11. In Modelli di richiesta procedi come segue:

    1. Per immettere un'Espressione di selezione del modello scegli Modifica in Modelli di richiesta.

    2. Immetti un'Espressione di selezione del modello. Specifica un'espressione che viene ricercata da Gateway API nel payload del messaggio. Se viene trovata, viene valutata e il risultato è un valore chiave del modello che viene utilizzato per selezionare il modello di mappatura dei dati che deve essere applicato ai dati nel payload del messaggio. Il modello di mappatura dei dati viene creato nel passaggio successivo. Scegli Modifica per salvare le modifiche.

    3. Scegli Crea modello per creare il modello di mappatura dei dati. Per Chiave del modello immetti il valore della chiave del modello utilizzato per selezionare il modello di mappatura dei dati da applicare ai dati nel payload del messaggio. Quindi, specifica un modello di mappatura. Scegli Crea modello.

       Per ulteriori informazioni sulle espressioni di selezione del modello, consulta Espressioni di selezione del modello.

Imposta una richiesta di integrazione utilizzando il AWS CLI

È possibile impostare una richiesta di integrazione per un percorso in un' WebSocket API utilizzando AWS CLI come illustrato nell'esempio seguente, che crea un'integrazione fittizia:

1. Crea un file denominato integration-params.json, con i seguenti contenuti:

   {"PassthroughBehavior": "WHEN_NO_MATCH", "TimeoutInMillis": 29000, "ConnectionType": "INTERNET", "RequestTemplates": {"application/json": "{\"statusCode\":200}"}, "IntegrationType": "MOCK"}

2. Eseguite il comando create-integration come mostrato nell'esempio seguente:

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

Di seguito è riportato un output di esempio:

{
    "PassthroughBehavior": "WHEN_NO_MATCH",
    "TimeoutInMillis": 29000,
    "ConnectionType": "INTERNET",
    "IntegrationResponseSelectionExpression": "${response.statuscode}",
    "RequestTemplates": {
        "application/json": "{\"statusCode\":200}"
    },
    "IntegrationId": "0abcdef",
    "IntegrationType": "MOCK"
}

In alternativa, è possibile impostare una richiesta di integrazione per un'integrazione proxy utilizzando AWS CLI come illustrato nell'esempio seguente:

1. Creare una funzione Lambda nella console Lambda e assegnarle un ruolo di esecuzione Lambda di base.

2. Eseguite il comando create-integration come nell'esempio seguente:

   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

Di seguito è riportato un output di esempio:

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

Formato di input di una funzione Lambda per l'integrazione del proxy per le API WebSocket

Con l'integrazione proxy Lambda, API Gateway mappa l'intera richiesta client al parametro di input event della funzione Lambda di back-end. L'esempio seguente mostra la struttura dell'evento di input dalla $connect route e dell'evento di input dalla $disconnect route che API Gateway invia a un'integrazione 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
  }