# Configurar uma solicitação de integração da API de WebSocket no API Gateway
<a name="apigateway-websocket-api-integration-requests"></a>

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](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-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
<a name="apigateway-websocket-api-integration-request-using-console"></a>

**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)**.

1. Em **Rotas**, selecione a rota.

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

1. 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 função do Lambda no AWS Lambda, definir uma permissão do recurso 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 obter mais informações, consulte [Integrações de HTTP para APIs REST no API Gateway](setup-http-integrations.md).
   + Escolha **Mock (Simulação)** se deseja gerar respostas de API diretamente do API Gateway, sem a necessidade de um backend de integração. Para obter mais informações, consulte [Simular integrações para APIs REST no API Gateway](how-to-mock-integration.md).
   + 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 obter mais informações, consulte [Configurar uma integração privada](set-up-private-integration.md).

1. 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](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy) ou a [Integração de proxy do Lambda entre contas](apigateway-cross-account-lambda-integrations.md).

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

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

1. 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](how-to-method-settings-console.md).

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

1. 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](how-to-method-settings-console.md).

1. 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`.

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

   1. Na lista suspensa **Link de VPC**, selecione um link de VPC. Você pode selecionar `[Use Stage Variables]` e inserir **\$1\$1stageVariables.vpcLinkId\$1** 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`.

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

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

1. Escolha **Salvar alterações**.

1. 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**.

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

   1. 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](websocket-api-data-transformations.md#apigateway-websocket-api-template-selection-expressions).

## Configurar uma solicitação de integração usando a AWS CLI
<a name="apigateway-websocket-api-integration-request-using-awscli"></a>

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

1. Use o comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo para criar a integração simulada.

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

   A saída será exibida da seguinte forma:

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

Também é possível configurar uma solicitação de integração para uma integração de proxy usando a AWS CLI.

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

1. Use o comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo para criar a integração.

   ```
   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 saída será exibida da seguinte forma:

```
{
    "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
<a name="api-gateway-simple-proxy-for-lambda-input-format-websocket"></a>

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 \$1connect 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 \$1disconnect 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
  }
```

------