# Integrações para APIs de WebSocket no API Gateway
Após a configuração de uma rota de API, você deve integrá-la a um endpoint no backend. Um endpoint de backend também é conhecido como endpoint de integração e pode ser uma função do Lambda, um endpoint HTTP ou uma ação de serviço da AWS. A integração da API tem uma solicitação e uma resposta de integração.
Nesta seção, você pode aprender como configurar solicitações e respostas de integração para sua API WebSocket.
**Topics**
+ [Configurar uma solicitação de integração da API de WebSocket no API Gateway](apigateway-websocket-api-integration-requests.md)
+ [Configurar uma resposta de integração da API de WebSocket no API Gateway](apigateway-websocket-api-integration-responses.md)
# 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](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
**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
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
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
}
```
------
# Configurar uma resposta de integração da API de WebSocket no API Gateway
A seção a seguir oferece uma breve visão geral das respostas de integração da API de WebSocket e como configurar uma resposta de integração de uma API de WebSocket.
**Topics**
+ [Visão geral das respostas de integração](#apigateway-websocket-api-integration-response-overview)
+ [Respostas de integração para comunicação bidirecional](#apigateway-websocket-api-integration-response-for-two-way-communication)
+ [Configurar uma resposta de integração usando o console do API Gateway](#apigateway-websocket-api-integration-response-using-console)
+ [Configurar uma resposta de integração usando a AWS CLI](#apigateway-websocket-api-integration-response-using-awscli)
## Visão geral das respostas de integração
A resposta de integração do API Gateway é uma maneira de modelar e manipular a resposta de um serviço de backend. Existem algumas diferenças na configuração de uma resposta de integração entre uma API REST e uma API WebSocket, mas, conceitualmente, o comportamento é o mesmo.
As rotas do WebSocket podem ser configuradas para comunicação bidirecional ou unidirecional.
+ Quando uma rota está configurada para comunicação bidirecional, uma resposta de integração permite que você configure as transformações na carga útil da mensagem retornada, semelhante às respostas de integração para APIs REST.
+ Se uma rota está configurada para comunicação unidirecional, independentemente de qualquer configuração da resposta de integração, nenhuma resposta será retornada pelo canal do WebSocket após o processamento da mensagem.
O API Gateway não transmitirá a resposta de back-end para a resposta de rota, a menos que você configure uma resposta de rota. Para saber mais sobre como configurar uma resposta de rota, consulte [Configurar respostas de rotas para APIs de WebSocket no API Gateway](apigateway-websocket-api-route-response.md).
## Respostas de integração para comunicação bidirecional
As integrações podem ser divididas em integrações de *proxy* e *não proxy*.
**Importante**
Para *integrações de proxy*, o API Gateway transmite automaticamente a saída de backend para o autor da chamada como a carga completa. Não há uma resposta de integração.
Para *integrações não proxy*, você deve configurar ao menos uma resposta de integração:
+ Idealmente, uma de suas respostas de integração deve agir como um genérico quando nenhuma escolha explícita puder ser feita. Este caso padrão é representado pela configuração de uma chave de resposta de integração `$default`.
+ Em todos os outros casos, a chave de resposta de integração funciona como uma expressão regular. É necessário que siga um formato de `"/expression/"`.
Para integrações HTTP não proxy:
+ O API Gateway tentará corresponder o código de status HTTP da resposta do backend. A chave de resposta de integração funcionará como uma expressão regular neste caso. Se não for possível encontrar uma correspondência, `$default` é escolhido como a resposta de integração.
+ A expressão de seleção de modelo, conforme descrito acima, funciona de forma idêntica. Por exemplo:
+ `/2\d\d/`: Recebe e transforma respostas bem-sucedidas
+ `/4\d\d/`: Recebe e transforma erros de solicitação incorreta
+ `$default`: Recebe e transforma todas as respostas inesperadas
Para ter 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 resposta de integração usando o console do API Gateway
Como configurar uma resposta de integração de rotas para uma API WebSocket usando o console do API Gateway:
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Selecione sua API de WebSocket e rota.
1. Selecione a guia **Solicitação de integração** e, na seção **Configurações de resposta de integração**, selecione **Criar resposta de integração**.
1. Em **Chave de resposta**, insira um valor que será encontrado na chave de resposta na mensagem de saída após a avaliação da expressão de seleção de resposta. Por exemplo, é possível inserir **/4\$1d\$1d/** para receber e transformar erros de solicitação inválida ou inserir **\$1default** para receber e transformar todas as respostas que correspondam à expressão de seleção do modelo.
1. Em **Expressão de seleção de modelos**, insira uma expressão de seleção para avaliar a mensagem de saída.
1. Selecione **Criar resposta**.
1. Você também pode definir um modelo de mapeamento para configurar as transformações da carga útil da mensagem retornada. Selecione **Criar modelo**.
1. Insira um nome de chave. Se você estiver selecionando a expressão de seleção de modelo padrão, insira **\$1\$1default**.
1. Em **Modelo de resposta**, insira o modelo de mapeamento no editor de código.
1. Selecione **Criar modelo**.
1. Selecione **Implantar API** para implantar a API.
Use o comando [ wscat](https://www.npmjs.com/package/wscat) a seguir para se conectar à sua API. Para obter mais informações sobre o `wscat`, consulte [Use `wscat` para se conectar a uma API do WebSocket e enviar mensagens a ela](apigateway-how-to-call-websocket-api-wscat.md).
```
wscat -c wss://api-id.execute-api.us-east-2.amazonaws.com/test
```
Quando você chamar sua rota, a carga útil da mensagem retornada deverá ser exibida.
## Configurar uma resposta de integração usando a AWS CLI
O comando [create-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration-response.html) indicado abaixo cria uma resposta de integração `$default`:
```
aws apigatewayv2 create-integration-response \
--api-id vaz7da96z6 \
--integration-id a1b2c3 \
--integration-response-key '$default'
```