Configurar uma solicitação de integração da API de WebSocket no API Gateway

A configuração de uma solicitação de integração envolve o seguinte:

• Escolher uma chave de roteamento a ser integrada ao backend.

• Especificar o endpoint de back-end a ser invocado. As APIs do WebSocket são compatíveis com os seguintes tipos de integração:

  • AWS_PROXY

  • AWS

  • HTTP_PROXY

  • HTTP

  • MOCK

  Para obter mais informações sobre tipos de integração, consulte IntegrationType na API REST do API Gateway V2.

• Configurar como transformar os dados da solicitação de rota, se necessário, para os dados da solicitação de integração, especificando um ou mais modelos de solicitação.

Configurar uma solicitação de integração de API WebSocket usando o console do API Gateway

Como adicionar uma solicitação de integração para uma rota em uma API WebSocket usando o console do API Gateway

1. Inicie uma sessão no console do API Gateway, escolha a API e selecione Routes (Rotas).

2. Em Rotas, selecione a rota.

3. Escolha a guia Solicitação de integração e, na seção Configurações de solicitação de integração, selecione Editar.

4. Em Tipo de integração, selecione uma das seguintes opções:

   • Selecione Função do Lambda somente se a API for integrada a uma função do AWS Lambda que você já criou nesta ou em outra conta.

     Para criar uma nova função do Lambda no AWS Lambda, definir uma permissão de recursos na função do Lambda ou executar qualquer outra ação de serviço do Lambda, escolha Serviço da AWS.

   • Escolha HTTP se a sua API for integrada a um endpoint HTTP existente. Para ter mais informações, consulte Integrações de HTTP para APIs REST no API Gateway.

   • Escolha Mock (Simulação) se deseja gerar respostas de API diretamente do API Gateway, sem a necessidade de um backend de integração. Para ter mais informações, consulte Simular integrações para APIs REST no API Gateway.

   • Selecione Serviço da AWS se a API for integrada a um serviço da AWS.

   • Selecione Link de VPC se a API utilizar VpcLink como um endpoint de integração privada. Para ter mais informações, consulte Integrações privadas para APIs REST no API Gateway.

5. Se você escolheu Função do Lambda, faça o seguinte:

   1. Em Usar a integração de proxy do Lambda, marque a caixa de seleção se você pretende usar a Integração de proxy do Lambda ou a Integração de proxy do Lambda entre contas.

   2. Em Função do Lambda, especifique a função de uma das seguintes formas:

      • Se a função do Lambda estiver na mesma conta, insira o nome da função e selecione-a na lista suspensa.

        nota

        O nome da função pode, opcionalmente, incluir seu alias ou sua especificação de versão, como em HelloWorld, HelloWorld:1 ou HelloWorld:alpha.

      • Se a função estiver em uma conta diferente, insira o ARN da função.

   3. Para usar o valor de tempo limite padrão de 29 segundos, deixe a opção Tempo limite padrão ativada. Para definir um tempo limite personalizado, selecione Tempo limite padrão e insira um valor de tempo limite entre 50 e 29000 milissegundos.

6. Se você escolher HTTP, siga as instruções na etapa 4 de Configurar uma solicitação de integração de API usando o console do API Gateway.

7. Se você escolheu Simulação, prossiga para a etapa de Modelos de solicitação.

8. Se você escolheu Serviço da AWS, siga as instruções na etapa 6 de Configurar uma solicitação de integração de API usando o console do API Gateway.

9. Se você escolheu Link de VPC, faça o seguinte:

   1. Em Usar a integração de proxy, marque a caixa de seleção se desejar que as solicitações sejam encaminhadas por proxy ao endpoint do VPCLink.

   2. Em HTTP method (Método HTTP), escolha o tipo de método HTTP mais parecido com o método no backend HTTP.

   3. Na lista suspensa Link de VPC, selecione um link de VPC. Você pode selecionar [Use Stage Variables] e inserir ${stageVariables.vpcLinkId} na caixa de texto abaixo da lista.

      É possível definir a variável do estágio vpcLinkId depois de implantar a API em um estágio e definir o valor como o ID do VpcLink.

   4. Em Endpoint URL (URL de endpoint), insira o URL do backend HTTP que você deseja que essa integração use.

   5. Para usar o valor de tempo limite padrão de 29 segundos, deixe a opção Tempo limite padrão ativada. Para definir um tempo limite personalizado, selecione Tempo limite padrão e insira um valor de tempo limite entre 50 e 29000 milissegundos.

10. Escolha Salvar alterações.

11. Em Modelos de solicitação, faça o seguinte:

    1. Em Expressão de seleção de modelos, em Modelos de solicitação, selecione Editar.

    2. Insira uma Expressão de seleção de modelos. Use uma expressão que o API Gateway procura na carga útil de mensagens. Ela será avaliada se for encontrada, e o resultado é um valor de chave de modelo que é utilizado para selecionar o modelo de mapeamento de dados a ser aplicado aos dados na carga da mensagem. Você criará o modelo de mapeamento de dados na próxima etapa. Selecione Editar para salvar as alterações.

    3. Selecione Criar modelo para criar o modelo de mapeamento de dados. Em Chave de modelo, insira o valor de chave de modelo que é utilizado para selecionar o modelo de mapeamento de dados a ser aplicado aos dados na carga útil de mensagens. Depois, insira um modelo de mapeamento. Selecione Criar modelo.

       Para obter mais informações sobre expressões de seleção de modelo, consulte Expressões de seleção de modelo.

Configurar uma solicitação de integração usando a AWS CLI

Você pode configurar uma solicitação de integração para uma rota em uma API WebSocket usando a AWS CLI como no exemplo a seguir, que cria uma integração simulada:

1. Crie um arquivo denominado integration-params.json com o seguinte conteúdo:

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

2. Execute o comando create-integration conforme mostrado no seguinte exemplo:

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

A seguir está a saída de amostra para este exemplo:

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

Como alternativa, você pode configurar uma solicitação de integração para uma integração de proxy usando a AWS CLI, conforme mostrado no exemplo a seguir:

1. Crie uma função do Lambda no console do Lambda e forneça uma função de execução básica do Lambda.

2. Execute o comando create-integration conforme mostrado no seguinte exemplo:

   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

A seguir está a saída de amostra para este exemplo:

{
    "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 de entrada de uma função do Lambda para integração de proxy de APIs de WebSocket

Com a integração de proxy do Lambda, o API Gateway mapeia toda a solicitação do cliente para o parâmetro event de entrada da função do Lambda de back-end. O seguinte exemplo mostra a estrutura do evento de entrada da rota $connect e o evento de entrada da rota $disconnect que o API Gateway envia para uma integração de proxy do 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
  }