` e valores estáticos.
No protocolo HTTP, em que solicitações e respostas são enviadas de forma síncrona, a comunicação é essencialmente unidirecional. No protocolo WebSocket, a comunicação é bidirecional. As respostas são assíncronas e não são necessariamente recebidas pelo cliente na mesma ordem em que as mensagens do cliente foram enviadas. Além disso, o backend pode enviar mensagens ao cliente.
**nota**
Para uma rota que é configurada para utilizar a integração `AWS_PROXY` ou `LAMBDA_PROXY`, a comunicação é unidirecional, e o API Gateway não transmitirá automaticamente a resposta de backend para a resposta de rota. Por exemplo, no caso da integração `LAMBDA_PROXY`, o corpo retornado pela função do Lambda não será retornado ao cliente. Se deseja que o cliente receba respostas de integração, você deve definir uma resposta de rota para possibilitar a comunicação bidirecional.
# Expressões de seleção do WebSocket
O API Gateway usa expressões de seleção como uma maneira de avaliar o contexto de solicitação e resposta e produzir uma chave. A chave é utilizar para selecionar a partir de um conjunto de valores possíveis, normalmente fornecidos por você, que é o desenvolvedor da API. O conjunto exato de variáveis compatíveis varia de acordo com a expressão específica. Cada expressão é discutir a seguir com mais detalhes.
Para todas as expressões, o idioma segue o mesmo conjunto de regras:
+ Uma variável é prefixada com `"$"`.
+ As chaves podem ser usadas para definir explicitamente os limites da variável, por exempl., `"${request.body.version}-beta"`.
+ Várias variáveis são compatíveis, mas a avaliação ocorre somente uma vez (sem avaliação recursiva).
+ Um cifrão (`$`) pode ser recuado com `"\"`. Isso é mais útil ao definir uma expressão que mapeia para a chave reservada `$default`, por exemplo, `"\$default"`.
+ Em alguns casos, um formato padrão é obrigatório. Nesse caso, a expressão deve ser encapsulada com barras (`"/"`), por exemplo, `"/2\d\d/"` para corresponder aos códigos de status `2XX`.
**Topics**
+ [Expressões de seleção de resposta de rotas](#apigateway-websocket-api-route-response-selection-expressions)
+ [Expressões de seleção de chave da API](#apigateway-websocket-api-apikey-selection-expressions)
+ [Expressões de seleção de mapeamento da API](#apigateway-websocket-api-mapping-selection-expressions)
+ [Resumo da expressão de seleção do WebSocket](#apigateway-websocket-api-selection-expression-table)
## Expressões de seleção de resposta de rotas
Uma [resposta de rota](apigateway-websocket-api-route-response.md) é utilizada para modelar uma resposta do backend para o cliente. Para APIs WebSocket, uma resposta de rota é opcional. Quando definida, emite sinais para o API Gateway de que deve retornar uma resposta a um cliente após o recebimento de uma mensagem WebSocket.
A avaliação da *expressão de seleção de resposta de rotas* produz uma chave de resposta de rotas. Por fim, essa chave será usada para escolher um dos [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html) associados à API. No entanto, a única chave atualmente compatível é `$default`.
## Expressões de seleção de chave da API
Esta expressão é avaliada quando o serviço determina que uma dada solicitação deve continuar somente se o cliente fornecer uma [chave de API](api-gateway-basic-concept.md#apigateway-definition-api-key) válida.
Atualmente, os únicos dois valores compatíveis são `$request.header.x-api-key` e `$context.authorizer.usageIdentifierKey`.
## Expressões de seleção de mapeamento da API
Esta expressão é avaliada para determinar qual estágio de API é selecionado quando uma solicitação é feita por meio de um domínio personalizado.
Atualmente, o único valor compatível é `$request.basepath`.
## Resumo da expressão de seleção do WebSocket
A tabela a seguir resume os casos de uso para expressões de seleção em APIs WebSocket:
| Expressão de seleção | Avalia chave para | Observações | Exemplo de caso de uso |
| --- | --- | --- | --- |
| Api.RouteSelectionExpression | Route.RouteKey | \$1default é compatível como uma rota genérica. | Roteie mensagens WebSocket com base no contexto de uma solicitação do cliente. |
| Route.ModelSelectionExpression | Chave para Route.RequestModels | Opcional. Se fornecida para integração não proxy, a validação do modelo ocorre. `$default` é compatível como um genérico. | Execute a validação de solicitação dinamicamente na mesma rota. |
| Integration.TemplateSelectionExpression | Chave para Integration.RequestTemplates | Opcional. Pode ser fornecida para integração não proxy visando manipular as cargas de entrada. `${request.body.jsonPath}` e valores estáticos são compatíveis. `$default` é compatível como um genérico. | Manipular a solicitação do autor da chamada nas propriedades dinâmicas da solicitação. |
| Integration.IntegrationResponseSelectionExpression | IntegrationResponse.IntegrationResponseKey | Opcional. Pode ser fornecida para integração não proxy. Funciona como uma correspondência de padrão para mensagens de erro (do Lambda) ou códigos de status (de integrações HTTP). `$default` é necessário para integrações não proxy visando atuar como um genérico para respostas bem-sucedidas. | Manipular a resposta do backend. Escolha a ação que deve ocorrer com base na resposta dinâmica do backend (por exemplo, manipular determinados erros de forma distinta). |
| IntegrationResponse.TemplateSelectionExpression | Chave para IntegrationResponse.ResponseTemplates | Opcional. Pode ser fornecida para integração não proxy. O padrão \$1 é compatível. | Em alguns casos, uma propriedade dinâmica da resposta pode ditar transformações diferentes na mesma rota e integração associada. `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}`, e valores estáticos são compatíveis. `$default` é compatível como um genérico. |
| Route.RouteResponseSelectionExpression | RouteResponse.RouteResponseKey | Deve ser fornecido para iniciar a comunicação bidirecional para uma rota do WebSocket. Atualmente, este valor é restrito apenas ao `$default`. | |
| RouteResponse.ModelSelectionExpression | Chave para RouteResponse.RequestModels | Atualmente incompatível. | |
# Desenvolver APIs de WebSocket no API Gateway
Esta seção fornece detalhes sobre os recursos necessários do API Gateway durante o desenvolvimento de suas APIs do API Gateway.
Ao desenvolver a API do API Gateway, você decidirá uma série de características da API. Essas características dependem do caso de uso da sua API. Por exemplo, talvez você queira permitir que somente determinados clientes chamem sua API ou talvez queira disponibilizá-las a todos. É recomendável que uma chamada de API execute uma função do Lambda, faça uma consulta de banco de dados ou chame uma aplicação.
**Topics**
+ [Criar APIs de WebSocket no API Gateway](apigateway-websocket-api-create-empty-api.md)
+ [Tipos de endereço IP para APIs de WebSocket no API Gateway](websocket-api-ip-address-type.md)
+ [Criar rotas para APIs de WebSocket no API Gateway](websocket-api-develop-routes.md)
+ [Controlar e gerenciar o acesso a APIs de WebSocket no API Gateway](apigateway-websocket-api-control-access.md)
+ [Integrações para APIs de WebSocket no API Gateway](apigateway-websocket-api-integrations.md)
+ [Solicitar validação para APIs de WebSocket no API Gateway](websocket-api-request-validation.md)
+ [Transformações de dados para APIs de WebSocket no API Gateway](websocket-api-data-transformations.md)
+ [Tipos de mídia binários para APIs de WebSocket no API Gateway](websocket-api-develop-binary-media-types.md)
+ [Invocar APIs de WebSocket](apigateway-how-to-call-websocket-api.md)
# Criar APIs de WebSocket no API Gateway
Você pode criar uma API de WebSocket no console do API Gateway usando o comando [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) da AWS CLI ou usando o comando `CreateApi` em um AWS SDK. Os procedimentos a seguir mostram como criar uma nova API WebSocket.
**nota**
APIs de WebSocket são compatíveis somente com TLS 1.2 e TLS 1.3. Versões anteriores do TLS não são compatíveis.
## Criar uma API WebSocket usando comandos da AWS CLI
O comando [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) indicado abaixo cria uma API com a expressão de seleção de rota `$request.body.action`:
```
aws apigatewayv2 --region us-east-1 create-api --name "myWebSocketApi3" --protocol-type WEBSOCKET --route-selection-expression '$request.body.action'
```
A saída será exibida como a seguir:
```
{
"ApiKeySelectionExpression": "$request.header.x-api-key",
"Name": "myWebSocketApi3",
"CreatedDate": "2018-11-15T06:23:51Z",
"ProtocolType": "WEBSOCKET",
"RouteSelectionExpression": "'$request.body.action'",
"ApiId": "aabbccddee"
}
```
## Criar uma API WebSocket usando o console do API Gateway
Você pode criar uma API WebSocket no console ao selecionar o protocolo WebSocket e atribuir um nome à API.
**Importante**
Depois de criar a API, você não pode alterar o protocolo escolhido. Não é possível converter uma API WebSocket em uma API REST ou vice-versa.
**Como criar uma API WebSocket usando o console do API Gateway**
1. Inicie uma sessão no console do API Gateway e escolha **Create API (Criar API)**.
1. Em **WebSocket API (API WebSocket)**, escolha **Build (Criar)**. Somente endpoints regionais são aceitos.
1. Em **Nome da API**, insira o nome da API.
1. Em **Expressão de seleção de rotas**, insira um valor. Por exemplo, `$request.body.action`.
Para obter mais informações sobre expressões de seleção de rota, consulte [Expressões de seleção de rota](websocket-api-develop-routes.md#apigateway-websocket-api-route-selection-expressions).
1. Execute um destes procedimentos:
+ Selecione **Criar API em branco** para criar uma API sem rotas.
+ Selecione **Próximo** para anexar rotas à API.
É possível anexar rotas depois de criar a API.
# Tipos de endereço IP para APIs de WebSocket no API Gateway
Ao criar uma API, você especifica o tipo de endereços IP que podem invocar sua API. É possível escolher IPv4 para resolver endereços IPv4 e invocar sua API ou escolher pilha dupla para permitir que endereços IPv4 e IPv6 invoquem sua API. Recomendamos que você defina o tipo de endereço IP como pilha dupla para aliviar o esgotamento do espaço IP ou para seu procedimento de segurança. Para ter mais informações sobre os benefícios de um tipo de endereço IP de pilha dupla, consulte [IPv6 na AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considerações sobre tipos de endereço IP
As seguintes considerações podem afetar o uso de tipos de endereço IP:
+ O tipo de endereço IP padrão para todas as APIs de WebSocket é IPv4.
+ Se você alterar o tipo de endereço IP de uma API existente de IPv4 para pilha dupla, confirme se todas as políticas que controlam o acesso às suas APIs foram atualizadas para considerar as chamadas IPv6. Quando você altera o tipo de endereço IP, a alteração entra em vigor imediatamente.
+ Sua API pode ser associada a um nome de domínio personalizado com um tipo de endereço IP diferente do da sua API. Se você desabilitar seu endpoint de API padrão, isso poderá afetar como os chamadores podem invocar sua API.
## Alterar o tipo de endereço IP de uma API de WebSocket
É possível alterar o tipo de endereço IP atualizando a configuração da API. É possível atualizar a configuração da API usando o Console de gerenciamento da AWS, a AWS CLI, o CloudFormation ou um SDK da AWS. Se você alterar o tipo de endereço IP da API, não poderá reimplantá-la para que as alterações entrem em vigor.
------
#### [ Console de gerenciamento da AWS ]
**Como alterar o tipo de endereço IP de uma API de WebSocket**
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha uma API de WebSocket.
1. Selecione **Configurações da API** e, depois, escolha **Editar**.
1. Em Tipo de endereço IP, escolha **IPv4** ou **Pilha dupla**.
1. Escolha **Salvar**.
A alteração na configuração da sua API entrará em vigor imediatamente.
------
#### [ AWS CLI ]
O comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) a seguir atualiza uma API para ter um tipo de endereço IP de pilha dupla:
```
aws apigatewayv2 update-api \
--api-id abcd1234 \
--ip-address-type dualstack
```
A saída será exibida da seguinte forma:
```
{
"ApiEndpoint": "https://abcd1234.execute-api.us-east-1.amazonaws.com",
"ApiId": "abcd1234",
"ApiKeySelectionExpression": "$request.header.x-api-key",
"CreatedDate": "2025-02-04T22:20:20+00:00",
"DisableExecuteApiEndpoint": false,
"Name": "My-WebSocket-API",
"ProtocolType": "WEBSOCKET",
"RouteSelectionExpression": "$request.method $request.path",
"Tags": {},
"NotificationUris": [],
"IpAddressType": "dualstack"
}
```
------
# Criar rotas para APIs de WebSocket no API Gateway
Na sua API WebSocket, mensagens JSON de entrada são direcionadas para integrações de backend com base nas rotas que você configurar. (Mensagens que não apresentam o formato JSON são direcionadas para a rota `$default` que você configurar).
Uma *rota* inclui uma *chave de roteamento*, que é o valor esperado quando uma *expressão de seleção de rotas* é avaliada. O `routeSelectionExpression` é um atributo definido em nível de API. Ele especifica uma propriedade JSON que deve estar presente na carga da mensagem. Para obter mais informações sobre expressões de seleção de rota, consulte [Expressões de seleção de rota](#apigateway-websocket-api-route-selection-expressions).
Por exemplo, se as suas mensagens JSON contiverem uma propriedade `action` e você desejar executar ações diferentes de acordo com essa propriedade, sua expressão de seleção de rotas poderá ser `${request.body.action}`. A tabela de roteamento deve especificar qual ação executar ao corresponder o valor da propriedade `action` com os valores de chave de rotas personalizada que você definiu na tabela.
Há três rotas predefinidas que podem ser usadas: `$connect`, `$disconnect` e `$default`. Além disso, você pode criar rotas personalizadas.
+ O API Gateway chama a rota `$connect` quando uma conexão persistente entre o cliente e uma API WebSocket está sendo iniciada.
+ O API Gateway chama a rota `$disconnect` quando o cliente ou o servidor é desconectado da API.
+ O API Gateway chama uma rota personalizada após a avaliação da expressão de seleção de rotas personalizada em relação à mensagem caso uma rota correspondente seja encontrada; a correspondência determina qual integração é invocada.
+ O API Gateway chamará a rota `$default` se a expressão de seleção de rotas não puder ser avaliada em relação à mensagem ou se nenhuma rota correspondente for encontrada.
## Expressões de seleção de rota
Uma *expressão de seleção de rota* é avaliada quando o serviço está selecionando a rota para seguir para uma mensagem recebida. O serviço usa a rota cuja `routeKey` corresponde exatamente ao valor avaliado. Se não existir nenhuma correspondência e uma rota com a chave `$default` existir, essa rota será selecionada. Se nenhuma rota corresponder ao valor avaliado e não existir uma rota `$default`, o serviço retornará uma mensagem de erro. Para APIs com base em WebSocket, a expressão deve ser da forma `$request.body.{path_to_body_element}`.
Por exemplo, suponha que você está enviando a seguinte mensagem JSON:
```
{
"service" : "chat",
"action" : "join",
"data" : {
"room" : "room1234"
}
}
```
Você pode selecionar o comportamento da API com base na propriedade `action`. Nesse caso, você pode definir a seguinte expressão de seleção de rotas:
```
$request.body.action
```
Neste exemplo, `request.body` refere-se à carga JSON da sua mensagem, e `.action` é uma expressão [JSONPath](https://goessner.net/articles/JsonPath/). Você pode usar qualquer expressão de caminho JSON após `request.body`, mas lembre-se de que o resultado será transformado em string. Por exemplo, se a expressão JSONPath retorna uma matriz de dois elementos, que serão apresentadas como a string `"[item1, item2]"`. Por esse motivo, é uma boa prática ter sua expressão avaliada como um valor e não uma matriz ou um objeto.
Você pode simplesmente usar um valor estático, ou utilizar várias variáveis. A tabela a seguir mostra exemplos e seus resultados avaliados em relação à carga anterior.
| Expressão | Resultado avaliado | Descrição |
| --- | --- | --- |
| \$1request.body.action | join | Uma variável desempacotada |
| \$1\$1request.body.action\$1 | join | Uma variável empacotada |
| \$1\$1request.body.service\$1/\$1\$1request.body.action\$1 | chat/join | Várias variáveis com valores estáticos |
| \$1\$1request.body.action\$1-\$1\$1request.body.invalidPath\$1 | join- | Se o JSONPath não for encontrado, a variável será resolvida como "". |
| action | action | Valor estático |
| \$1\$1default | \$1default | Valor estático |
O resultado avaliado é usado para encontrar uma rota. Se houver uma rota com uma chave de rota correspondente, a rota será selecionada para processar a mensagem. Se nenhuma rota correspondente for encontrada, o API Gateway tentará encontrar a rota `$default`, se disponível. Se a rota `$default` não estiver definida, o API Gateway retornará um erro.
## Configurar rotas para uma API WebSocket no API Gateway
Ao criar uma nova API WebSocket pela primeira vez, há três rotas predefinidas: `$connect`, `$disconnect` e `$default`. É possível criá-las ao utilizar o console, a API ou a AWS CLI. Se desejado, você pode criar rotas personalizadas. Para obter mais informações, consulte [Visão geral das APIs de WebSocket no API Gateway](apigateway-websocket-api-overview.md).
**nota**
Na CLI, você pode criar rotas antes ou depois de gerar integrações, sendo possível reutilizar a mesma integração para várias rotas.
### Criar uma rota usando o console do API Gateway
**Como criar uma rota usando o console do API Gateway**
1. Inicie uma sessão no console do API Gateway, escolha a API e selecione **Routes (Rotas)**.
1. Selecione **Criar rota**.
1. Em **Chave de rota**, insira o nome da chave de rota. É possível criar as rotas predefinidas (`$connect`, `$disconnect` e`$default`) ou uma rota personalizada.
**nota**
Ao criar uma rota personalizada, não use o prefixo `$` no nome da chave de rota. Este prefixo está reservado para rotas predefinidas.
1. Selecione e configure o tipo de integração para a rota. Para obter mais informações, consulte [Configurar uma solicitação de integração de API WebSocket usando o console do API Gateway](apigateway-websocket-api-integration-requests.md#apigateway-websocket-api-integration-request-using-console).
### Criar uma rota usando a AWS CLI
O comando [create-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route.html) indicado abaixo cria uma rota:
```
aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default
```
A saída será exibida da seguinte forma:
```
{
"ApiKeyRequired": false,
"AuthorizationType": "NONE",
"RouteKey": "$default",
"RouteId": "1122334"
}
```
### Especificar as configurações de solicitação de rota para `$connect`
Quando você configurar a rota `$connect` para a sua API, as configurações opcionais a seguir serão disponibilizadas para habilitar a autorização para sua API. Para obter mais informações, consulte [A rota `$connect`](apigateway-websocket-api-route-keys-connect-disconnect.md#apigateway-websocket-api-routes-about-connect).
+ **Autorização**: Se a autorização não for necessária, você pode especificar `NONE`. Caso contrário, especifique:
+ `AWS_IAM` para utilizar políticas padrão do AWS IAM para controlar o acesso à sua API.
+ `CUSTOM` para implementar a autorização para uma API especificando uma função de autorizador do Lambda criada anteriormente. O autorizador pode residir em sua própria conta da AWS ou em outra conta da AWS. Para obter mais informações sobre autorizadores do Lambda, consulte [Usar os autorizadores do API Gateway Lambda](apigateway-use-lambda-authorizer.md).
**nota**
No console do API Gateway, a configuração `CUSTOM` é visível somente após a configuração de uma função do autorizador, conforme descrito em [Configurar um autorizador do Lambda (console)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console).
**Importante**
A configuração de **Autorização** é aplicada à API completa, e não apenas à rota `$connect`. A rota `$connect` protege as outras rotas, visto que é chamada em cada conexão.
+ **Chave de API obrigatória**: opcionalmente, você pode exigir uma chave de API para uma rota `$connect` da API. Você pode usar chaves da API com planos de uso para controlar e rastrear o acesso às APIs. Para obter mais informações, consulte [Usar planos e chaves de API para APIs REST no APIs Gateway](api-gateway-api-usage-plans.md).
### Configurar a solicitação de rota `$connect` usando o console do API Gateway
Para configurar uma solicitação de rota `$connect` para 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 `$connect` ou crie uma rota `$connect` seguindo [Criar uma rota usando o console do API Gateway](#apigateway-websocket-api-route-using-console).
1. Na seção **Configurações de solicitação de rota**, selecione **Editar**.
1. Em **Autorização**, selecione um tipo de autorizador.
1. Para exigir uma API para a rota `$connect`, selecione **Exigir chave de API**.
1. Escolha **Salvar alterações**.
# Configurar respostas de rotas para APIs de WebSocket no API Gateway
As rotas do WebSocket podem ser configuradas para comunicação bidirecional ou unidirecional. 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.
**nota**
Você só pode definir a resposta de rota `$default` para as APIs do WebSocket. É possível usar uma resposta de integração para manipular a resposta de um serviço de back-end. Para obter mais informações, consulte [Visão geral das respostas de integração](apigateway-websocket-api-integration-responses.md#apigateway-websocket-api-integration-response-overview).
É possível configurar respostas de rota e expressões de seleção de resposta usando o console do API Gateway ou a AWS CLI ou um SDK da AWS.
Para obter mais informações sobre expressões de seleção de respostas de rota, consulte [Expressões de seleção de resposta de rotas](apigateway-websocket-api-selection-expressions.md#apigateway-websocket-api-route-response-selection-expressions).
**Topics**
+ [Configurar uma resposta de rota usando o console do API Gateway](#apigateway-websocket-api-route-response-using-console)
+ [Configurar uma resposta de rota usando a AWS CLI](#apigateway-websocket-api-route-response-using-awscli)
## Configurar uma resposta de rota usando o console do API Gateway
Depois de criar uma API de WebSocket e anexar uma função proxy do Lambda à rota padrão, você pode configurar a resposta da rota usando o console do API Gateway:
1. Faça login no console do API Gateway e selecione uma API do WebSocket com uma integração de função proxy do Lambda na rota `$default`.
1. Em **Routes** (Rotas), selecione a rota `$default`.
1. Selecione **Habilitar comunicação bidirecional**.
1. Escolha **Implantar API**.
1. Implante a API em um estágio.
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
```
Pressione o botão enter para chamar a rota padrão. O corpo de sua função do Lambda deve retornar.
## Configurar uma resposta de rota usando a AWS CLI
O comando [create-route-response](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-route-response.html) a seguir cria uma resposta de rota para a rota `$default`. Você pode identificar o ID da API e o ID da rota usando os comandos [get-apis](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-apis.html) e [get-routes](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-routes.html).
```
aws apigatewayv2 create-route-response \
--api-id aabbccddee \
--route-id 1122334 \
--route-response-key '$default'
```
A saída será exibida da seguinte forma:
```
{
"RouteResponseId": "abcdef",
"RouteResponseKey": "$default"
}
```
# Configurar uma rota `$connect` que requer um subprotocolo de WebSocket
Os clientes podem usar o campo `Sec-WebSocket-Protocol` para solicitar um [subprotocolo WebSocket](https://datatracker.ietf.org/doc/html/rfc6455#page-12) durante a conexão com sua API WebSocket. É possível configurar uma integração para a rota `$connect` para permitir conexões somente se um cliente solicitar um subprotocolo compatível com sua API.
A função demonstrativa do Lambda a seguir retorna o cabeçalho `Sec-WebSocket-Protocol` aos clientes. A função só estabelecerá uma conexão com sua API se o cliente especificar o subprotocolo `myprotocol`.
Para obter um modelo do CloudFormation que cria essa API de exemplo e integração de proxy do Lambda, consulte [samples/ws-subprotocol.zip](samples/ws-subprotocol.zip).
```
export const handler = async (event) => {
if (event.headers != undefined) {
const headers = toLowerCaseProperties(event.headers);
if (headers['sec-websocket-protocol'] != undefined) {
const subprotocolHeader = headers['sec-websocket-protocol'];
const subprotocols = subprotocolHeader.split(',');
if (subprotocols.indexOf('myprotocol') >= 0) {
const response = {
statusCode: 200,
headers: {
"Sec-WebSocket-Protocol" : "myprotocol"
}
};
return response;
}
}
}
const response = {
statusCode: 400
};
return response;
};
function toLowerCaseProperties(obj) {
var wrapper = {};
for (var key in obj) {
wrapper[key.toLowerCase()] = obj[key];
}
return wrapper;
}
```
Você só poderá usar [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat) para testar se sua API permite conexões se um cliente solicitar um subprotocolo compatível com sua API. Os comandos a seguir usam o sinalizador `-s` para especificar subprotocolos durante a conexão.
O comando a seguir tenta uma conexão com um subprotocolo incompatível. Como o cliente especificou o subprotocolo `chat1`, a integração do Lambda retorna um erro 400 e a conexão não obtém êxito.
```
wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1
error: Unexpected server response: 400
```
O comando a seguir inclui um subprotocolo compatível na solicitação de conexão. A integração do Lambda permite a conexão.
```
wscat -c wss://api-id.execute-api.region.amazonaws.com/beta -s chat1,myprotocol
connected (press CTRL+C to quit)
```
Para saber mais sobre como invocar APIs WebSocket, consulte [Invocar APIs de WebSocket](apigateway-how-to-call-websocket-api.md).
# Controlar e gerenciar o acesso a APIs de WebSocket no API Gateway
O API Gateway é compatível com vários mecanismos para controlar e gerenciar o acesso à sua API WebSocket.
Os mecanismos a seguir podem ser usados para autenticação e autorização:
+ As **funções e políticas padrão do AWS IAM** oferecem controles de acesso flexíveis e robustos. É possível usar as funções e políticas do IAM para controlar quem pode criar e gerenciar suas APIs, bem como quem pode chamá-las. Para obter mais informações, consulte [Controlar o acesso a APIs de WebSocket com autorização do IAM](apigateway-websocket-control-access-iam.md).
+ As **tags do IAM** podem ser usadas com as políticas do IAM para controlar o acesso. Para obter mais informações, consulte [Usar tags para controlar o acesso aos recursos da API REST do API Gateway](apigateway-tagging-iam-policy.md).
+ **Autorizadores do Lambda** são funções do Lambda que controlam o acesso a APIs. Para obter mais informações, consulte [Controlar o acesso a APIs de WebSocket com autorizadores REQUEST do AWS Lambda](apigateway-websocket-api-lambda-auth.md).
Para melhorar seu procedimento de segurança, recomendamos configurar um autorizador para a rota `$connect` em todas as suas APIs de WebSocket. Você pode precisar fazer isso para cumprir vários requisitos de conformidade. Para ter mais informações, consulte [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) no *Guia do usuário do AWS Security Hub*.
**Topics**
+ [Controlar o acesso a APIs de WebSocket com autorização do IAM](apigateway-websocket-control-access-iam.md)
+ [Controlar o acesso a APIs de WebSocket com autorizadores REQUEST do AWS Lambda](apigateway-websocket-api-lambda-auth.md)
# Controlar o acesso a APIs de WebSocket com autorização do IAM
A autorização do IAM em APIs WebSocket é semelhante à utilizada para [APIs REST](api-gateway-control-access-using-iam-policies-to-invoke-api.md), com as seguintes exceções:
+ A ação `execute-api` oferece suporte a `ManageConnections`, além de ações existentes (`Invoke`, `InvalidateCache`). `ManageConnections` controla o acesso à API @connections.
+ As rotas do WebSocket utilizam um formato diferente de ARN:
```
arn:aws:execute-api:region:account-id:api-id/stage-name/route-key
```
+ A API `@connections` utiliza o mesmo formato de ARN presente nas APIs REST:
```
arn:aws:execute-api:region:account-id:api-id/stage-name/POST/@connections
```
**Importante**
Ao usar a [Autorização do IAM](#apigateway-websocket-control-access-iam), é necessário assinar solicitações com o [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html).
Por exemplo, você pode configurar a política a seguir ao cliente: Este exemplo permite que todas as pessoas enviem uma mensagem (`Invoke`) a todas as rotas, exceto para uma rota secreta no estágio `prod`, além de impedir que qualquer pessoa envie uma mensagem aos clientes conectados (`ManageConnections`) para todos os estágios.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/prod/*"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/prod/secret"
]
},
{
"Effect": "Deny",
"Action": [
"execute-api:ManageConnections"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111122223333:api-id/*"
]
}
]
}
```
------
# Controlar o acesso a APIs de WebSocket com autorizadores REQUEST do AWS Lambda
Uma função do autorizador do Lambda em APIs WebSocket é semelhante à utilizada para [APIs REST](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create), com as seguintes exceções:
+ Você só pode usar uma função de autorizador do Lambda para a rota `$connect`.
+ Você não pode utilizar variáveis de caminho (`event.pathParameters`), afinal, o caminho é fixo.
+ `event.methodArn` é diferente de sua API REST equivalente, visto que não possui um método HTTP. No caso de `$connect`, `methodArn` termina com `"$connect"`:
```
arn:aws:execute-api:region:account-id:api-id/stage-name/$connect
```
+ As variáveis de contexto em `event.requestContext` são diferentes das utilizadas para APIs REST.
O exemplo a seguir mostra uma entrada para um autorizador `REQUEST` de uma API de WebSocket:
```
{
"type": "REQUEST",
"methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/default/$connect",
"headers": {
"Connection": "upgrade",
"content-length": "0",
"HeaderAuth1": "headerValue1",
"Host": "abcdef123.execute-api.us-east-1.amazonaws.com",
"Sec-WebSocket-Extensions": "permessage-deflate; client_max_window_bits",
"Sec-WebSocket-Key": "...",
"Sec-WebSocket-Version": "13",
"Upgrade": "websocket",
"X-Amzn-Trace-Id": "...",
"X-Forwarded-For": "...",
"X-Forwarded-Port": "443",
"X-Forwarded-Proto": "https"
},
"multiValueHeaders": {
"Connection": [
"upgrade"
],
"content-length": [
"0"
],
"HeaderAuth1": [
"headerValue1"
],
"Host": [
"abcdef123.execute-api.us-east-1.amazonaws.com"
],
"Sec-WebSocket-Extensions": [
"permessage-deflate; client_max_window_bits"
],
"Sec-WebSocket-Key": [
"..."
],
"Sec-WebSocket-Version": [
"13"
],
"Upgrade": [
"websocket"
],
"X-Amzn-Trace-Id": [
"..."
],
"X-Forwarded-For": [
"..."
],
"X-Forwarded-Port": [
"443"
],
"X-Forwarded-Proto": [
"https"
]
},
"queryStringParameters": {
"QueryString1": "queryValue1"
},
"multiValueQueryStringParameters": {
"QueryString1": [
"queryValue1"
]
},
"stageVariables": {},
"requestContext": {
"routeKey": "$connect",
"eventType": "CONNECT",
"extendedRequestId": "...",
"requestTime": "19/Jan/2023:21:13:26 +0000",
"messageDirection": "IN",
"stage": "default",
"connectedAt": 1674162806344,
"requestTimeEpoch": 1674162806345,
"identity": {
"sourceIp": "..."
},
"requestId": "...",
"domainName": "abcdef123.execute-api.us-east-1.amazonaws.com",
"connectionId": "...",
"apiId": "abcdef123"
}
}
```
A função demonstrativa do autorizador do Lambda a seguir é uma versão WebSocket da função do autorizador do Lambda para APIs REST em [Exemplos adicionais de funções do autorizador do Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-lambda-function-create):
------
#### [ Node.js ]
```
// A simple REQUEST authorizer example to demonstrate how to use request
// parameters to allow or deny a request. In this example, a request is
// authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter
// in the request context match the specified values of
// of 'headerValue1' and 'queryValue1' respectively.
export const handler = function(event, context, callback) {
console.log('Received event:', JSON.stringify(event, null, 2));
// Retrieve request parameters from the Lambda function input:
var headers = event.headers;
var queryStringParameters = event.queryStringParameters;
var stageVariables = event.stageVariables;
var requestContext = event.requestContext;
// Parse the input for the parameter values
var tmp = event.methodArn.split(':');
var apiGatewayArnTmp = tmp[5].split('/');
var awsAccountId = tmp[4];
var region = tmp[3];
var ApiId = apiGatewayArnTmp[0];
var stage = apiGatewayArnTmp[1];
var route = apiGatewayArnTmp[2];
// Perform authorization to return the Allow policy for correct parameters and
// the 'Unauthorized' error, otherwise.
var authResponse = {};
var condition = {};
condition.IpAddress = {};
if (headers.HeaderAuth1 === "headerValue1"
&& queryStringParameters.QueryString1 === "queryValue1") {
callback(null, generateAllow('me', event.methodArn));
} else {
callback(null, generateDeny('me', event.methodArn));
}
}
// Helper function to generate an IAM policy
var generatePolicy = function(principalId, effect, resource) {
// Required output:
var authResponse = {};
authResponse.principalId = principalId;
if (effect && resource) {
var policyDocument = {};
policyDocument.Version = '2012-10-17 '; // default version
policyDocument.Statement = [];
var statementOne = {};
statementOne.Action = 'execute-api:Invoke'; // default action
statementOne.Effect = effect;
statementOne.Resource = resource;
policyDocument.Statement[0] = statementOne;
authResponse.policyDocument = policyDocument;
}
// Optional output with custom properties of the String, Number or Boolean type.
authResponse.context = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": true
};
return authResponse;
}
var generateAllow = function(principalId, resource) {
return generatePolicy(principalId, 'Allow', resource);
}
var generateDeny = function(principalId, resource) {
return generatePolicy(principalId, 'Deny', resource);
}
```
------
#### [ Python ]
```
# A simple REQUEST authorizer example to demonstrate how to use request
# parameters to allow or deny a request. In this example, a request is
# authorized if the client-supplied HeaderAuth1 header and QueryString1 query parameter
# in the request context match the specified values of
# of 'headerValue1' and 'queryValue1' respectively.
import json
def lambda_handler(event, context):
print(event)
# Retrieve request parameters from the Lambda function input:
headers = event['headers']
queryStringParameters = event['queryStringParameters']
stageVariables = event['stageVariables']
requestContext = event['requestContext']
# Parse the input for the parameter values
tmp = event['methodArn'].split(':')
apiGatewayArnTmp = tmp[5].split('/')
awsAccountId = tmp[4]
region = tmp[3]
ApiId = apiGatewayArnTmp[0]
stage = apiGatewayArnTmp[1]
route = apiGatewayArnTmp[2]
# Perform authorization to return the Allow policy for correct parameters
# and the 'Unauthorized' error, otherwise.
authResponse = {}
condition = {}
condition['IpAddress'] = {}
if (headers['HeaderAuth1'] ==
"headerValue1" and queryStringParameters["QueryString1"] == "queryValue1"):
response = generateAllow('me', event['methodArn'])
print('authorized')
return json.loads(response)
else:
response = generateDeny('me', event['methodArn'])
print('unauthorized')
return json.loads(response)
# Help function to generate IAM policy
def generatePolicy(principalId, effect, resource):
authResponse = {}
authResponse['principalId'] = principalId
if (effect and resource):
policyDocument = {}
policyDocument['Version'] = '2012-10-17 '
policyDocument['Statement'] = []
statementOne = {}
statementOne['Action'] = 'execute-api:Invoke'
statementOne['Effect'] = effect
statementOne['Resource'] = resource
policyDocument['Statement'] = [statementOne]
authResponse['policyDocument'] = policyDocument
authResponse['context'] = {
"stringKey": "stringval",
"numberKey": 123,
"booleanKey": True
}
authResponse_JSON = json.dumps(authResponse)
return authResponse_JSON
def generateAllow(principalId, resource):
return generatePolicy(principalId, 'Allow', resource)
def generateDeny(principalId, resource):
return generatePolicy(principalId, 'Deny', resource)
```
------
Para configurar a função anterior do Lambda como uma função do autorizador `REQUEST` para uma API WebSocket, siga o mesmo procedimento para [APIs REST](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-with-console).
Para configurar a rota `$connect` a fim de esse autorizador do Lambda no console, selecione ou crie a rota `$connect`. Na seção **Configurações de solicitação de rota**, selecione **Editar**. Selecione o autorizador no menu suspenso **Autorização** e escolha **Salvar alterações**.
Para testar o autorizador, é necessário uma conexão. O autorizador da alteração no `$connect` não afeta o cliente já conectado. Quando você se conectar à API WebSocket, será necessário fornecer valores para todas as origens de identidade configuradas. Por exemplo, você pode se conectar ao enviar uma string de consulta e cabeçalho validos usando `wscat` como no exemplo a seguir:
```
wscat -c 'wss://myapi.execute-api.us-east-1.amazonaws.com/beta?QueryString1=queryValue1' -H HeaderAuth1:headerValue1
```
Ao tentar se conectar sem um valor de identidade válido, você receberá uma resposta `401`:
```
wscat -c wss://myapi.execute-api.us-east-1.amazonaws.com/beta
error: Unexpected server response: 401
```
# 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 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 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. Inicie uma sessão 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'
```
# Solicitar validação para APIs de WebSocket no API Gateway
É possível configurar o API Gateway para realizar a validação em uma solicitação de rota antes de prosseguir com a solicitação de integração. Se a validação falhar, o API Gateway falhará na solicitação sem chamar seu backend, enviará uma resposta de gateway “Corpo de solicitação incorreto” ao cliente e publicará os resultados da validação no CloudWatch Logs. Usar a validação dessa forma reduz chamadas desnecessárias para o backend da API.
## Expressões de seleção de modelo
Você pode usar uma expressão de seleção de modelo para validar solicitações dinamicamente dentro da mesma rota. A validação de modelos ocorrerá se você fornecer uma expressão de seleção de modelo para integrações proxy ou não proxy. Talvez seja necessário definir o modelo `$default` como um fallback quando nenhum modelo correspondente for encontrado. Se não houver nenhum modelo correspondente e `$default` não estiver definido, a validação falhará. A expressão de seleção é semelhante a `Route.ModelSelectionExpression` e é avaliada como a chave de `Route.RequestModels`.
Ao definir uma rota para uma API de WebSocket, é possível especificar, opcionalmente, uma *expressão de seleção de modelo*. Esta expressão é avaliada para selecionar o modelo a ser usado para a validação do corpo quando uma solicitação é recebida. A expressão é avaliada como uma das entradas em de uma rota [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes.html#apis-apiid-routes-prop-route-requestmodels).
Um modelo é expresso como um [esquema JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) e descreve a estrutura de dados do corpo da solicitação. A natureza dessa expressão de seleção permite que você escolha dinamicamente o modelo para validar com base no tempo de execução para uma rota específica. Para obter informações sobre como criar um modelo, consulte [Modelos de dados para APIs REST](models-mappings-models.md).
## Configurar a validação de solicitação usando o console do API Gateway
O seguinte exemplo mostra como configurar a validação da solicitação em uma rota.
Primeiro, crie um modelo e depois crie uma rota. Em seguida, configure a validação da solicitação na rota criada. Por fim, implante e teste a API. Para concluir este tutorial, você precisa de uma API de WebSocket com `$request.body.action` como a expressão de seleção de rota e um endpoint de integração para sua nova rota.
Você também precisa que o `wscat` se conecte à sua API. Para obter mais informações, consulte [Use `wscat` para se conectar a uma API do WebSocket e enviar mensagens a ela](apigateway-how-to-call-websocket-api-wscat.md).
**Como criar um modelo**
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha uma API de WebSocket.
1. No painel de navegação principal, selecione **Modelos**.
1. Escolha **Criar modelo**.
1. Em **Nome**, digite **emailModel**.
1. Em **Tipo de conteúdo**, insira **application/json**.
1. Em **Esquema do modelo**, insira o seguinte modelo:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type" : "object",
"required" : [ "address"],
"properties" : {
"address": {
"type": "string"
}
}
}
```
Este modelo exige que a solicitação contenha um endereço de e-mail.
1. Escolha **Salvar**.
Nesta etapa, você cria uma rota para a API de WebSocket.
**Para criar uma rota**
1. No painel de navegação principal, selecione **Rotas**.
1. Escolha **Create route (Criar rota)**.
1. Em **Route key** (Chave de rota), insira **sendMessage**.
1. Escolha um tipo de integração e especifique um endpoint de integração. Para obter mais informações, consulte [Integrações para APIs de WebSocket no API Gateway](apigateway-websocket-api-integrations.md).
1. Escolha **Create route (Criar rota)**.
Nesta etapa, você configura a validação da solicitação para a rota `sendMessage`.
**Para configurar a validação da solicitação**
1. Na guia **Solicitação de rota**, em **Configurações de solicitação de rota**, escolha **Editar**.
1. Em **Expressão de seleção de modelos**, insira **\$1\$1request.body.messageType\$1**.
O API Gateway usa a propriedade `messageType` para validar a solicitação de entrada.
1. Escolha **Adicionar modelo de solicitação**.
1. Em **Chave do modelo**, insira **email**.
1. Em **Modelo**, escolha **emailModel**.
O API Gateway valida as mensagens de entrada com a propriedade `messageType` definida como `email` em relação a este modelo.
**nota**
Se o API Gateway não combinar a expressão de seleção de modelo com uma chave do modelo, ele selecionará o modelo `$default`. Se não houver nenhum modelo `$default`, a validação falhará. Para APIs de produção, recomendamos que você crie um modelo `$default`.
1. Escolha **Salvar alterações**.
Nesta etapa, você implanta e testa a API.
**Para implantar e testar sua API**
1. Escolha **Implantar API**.
1. Escolha o estágio desejado na lista suspensa ou insira o nome de um novo estágio.
1. Escolha **Implantar**.
1. No painel de navegação principal, selecione **Estágios**.
1. Copie o URL WebSocket da API. O URL deve ser semelhante a `wss://abcdef123.execute-api.us-east-2.amazonaws.com/production`.
1. Abra um novo terminal e execute o comando **wscat** com os parâmetros a seguir.
```
wscat -c wss://abcdef123.execute-api.us-west-2.amazonaws.com/production
```
```
Connected (press CTRL+C to quit)
```
1. Use o comando a seguir para testar a API.
```
{"action": "sendMessage", "messageType": "email"}
```
```
{"message": "Invalid request body", "connectionId":"ABCD1=234", "requestId":"EFGH="}
```
O API Gateway falhará na solicitação.
Use o próximo comando para enviar uma solicitação válida para sua API.
```
{"action": "sendMessage", "messageType": "email", "address": "mary_major@example.com"}
```
# Transformações de dados para APIs de WebSocket no API Gateway
No API Gateway, a solicitação de método de uma API WebSocket pode usar uma carga em um formato diferente da carga da solicitação de integração correspondente, conforme exigido no backend. De maneira semelhante, o backend pode retornar uma carga de resposta de integração diferente da carga da resposta do método, conforme esperado pelo front-end.
O API Gateway permite usar transformações de modelos de mapeamento para mapear a carga útil de uma solicitação de método para a solicitação de integração correspondente ou de uma resposta de integração para a resposta de método correspondente. Você cria um modelo de mapeamento e especifica uma expressão de seleção de modelos para determinar qual deles usar para executar as transformações de dados necessárias.
É possível usar mapeamentos de dados para mapear dados de uma [solicitação de rota](api-gateway-basic-concept.md#apigateway-definition-route-request) para uma integração de backend. Para saber mais, consulte [Configurar o mapeamento de dados para APIs de WebSocket no API Gateway](websocket-api-data-mapping.md).
## Modelos e modelos de mapeamento
Um *modelo de mapeamento* é um script expresso em [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) e aplicado à carga usando [expressões JSONPath](https://goessner.net/articles/JsonPath/). Para obter mais informações sobre modelos de mapeamento do API Gateway, consulte [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md).
A carga pode ter um *modelo de dados* de acordo com o [esquema JSON rascunho 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04). Não é necessário definir um modelo para criar um modelo de mapeamento. No entanto, um modelo pode ajudar você a criar um modelo, porque o API Gateway gera um esquema de modelo com base em um modelo fornecido. Para obter mais informações sobre modelos do API Gateway, consulte [Modelos de dados para APIs REST](models-mappings-models.md).
## Expressões de seleção de modelo
Para transformar uma carga com um modelo de mapeamento, especifique uma expressão de seleção de modelo de API WebSocket em uma [solicitação de integração](apigateway-websocket-api-integration-requests.md) ou [resposta de integração](apigateway-websocket-api-integration-responses.md). Esta expressão é avaliada para determinar o modelo de entrada ou de saída (se houver) a ser utilizado para transformar o corpo da solicitação no corpo da solicitação de integração (por meio de um modelo de entrada) ou o corpo da resposta de integração para o corpo de resposta de rotas (por meio de um modelo de saída).
`Integration.TemplateSelectionExpression` oferece suporte a `${request.body.jsonPath}` e valores estáticos.
`IntegrationResponse.TemplateSelectionExpression` oferece suporte a `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}` e a valores estáticos.
## Expressões de seleção de resposta da integração
Quando você [define uma resposta de integração](apigateway-websocket-api-integration-responses.md) para uma API WebSocket, é possível especificar opcionalmente uma expressão de seleção de resposta da integração. Esta expressão determina qual `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html)` deve ser selecionada quando uma integração retorna. O valor dessa expressão é atualmente restrito pelo API Gateway, conforme definido abaixo. Observe que essa expressão só é relevante para *integrações não proxy*; uma integração de proxy simplesmente transmitirá a carga da resposta de volta para o autor da chamada sem modelagem ou modificação.
Ao contrário de outras expressões de seleção anteriores, essa expressão é atualmente compatível com um formato de *padrão correspondente*. A expressão deve ser encapsulada com barras.
Atualmente, o valor é corrigido dependendo do `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)`:
+ Para integrações baseadas em Lambda, é `$integration.response.body.errorMessage`.
+ Para integrações `HTTP` e `MOCK`, é `$integration.response.statuscode`.
+ Para `HTTP_PROXY` e `AWS_PROXY`, a expressão não é utilizada porque você está solicitando que a carga seja transmitida para o autor da chamada.
# Configurar o mapeamento de dados para APIs de WebSocket no API Gateway
O*mapeamento de dados* permite mapear dados de uma [solicitação de rota](api-gateway-basic-concept.md#apigateway-definition-route-request) para uma integração de backend.
**nota**
O mapeamento de dados para APIs do WebSocket não é suportado no Console de gerenciamento da AWS. É necessário usar a AWS CLI, o AWS CloudFormation, ou um SDK para configurar o mapeamento de dados.
**Topics**
+ [Mapear dados de solicitação de rota para parâmetros de solicitação de integração](#websocket-mapping-request-parameters)
+ [Exemplos](#websocket-data-mapping-examples)
## Mapear dados de solicitação de rota para parâmetros de solicitação de integração
Os parâmetros de solicitação de integração podem ser mapeados a partir de quaisquer parâmetros de solicitação de rota definidos, o corpo da solicitação, as variáveis [`context` ou ](api-gateway-mapping-template-reference.md#context-variable-reference) [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference) e valores estáticos.
A tabela a seguir mostra as expressões de mapeamento de dados da solicitação de integração. Na tabela, *`PARAM_NAME`* é o nome de um parâmetro de solicitação de rota do tipo de parâmetro especificado. Deve corresponder à expressão regular `'^[a-zA-Z0-9._$-]+$]'`. *JSONPath\$1Expression* é uma expressão JSONPath para um campo JSON do corpo da solicitação.
| Fonte de dados mapeada | Expressão de mapeamento |
| --- | --- |
| String de consulta de solicitação (compatível apenas com a rota \$1connect) | route.request.querystring.PARAM\$1NAME |
| Cabeçalho de solicitação (compatível apenas com a rota \$1connect) | route.request.header.PARAM\$1NAME |
| String de consulta de solicitação de vários valores (compatível apenas com a rota \$1connect) | route.request.multivaluequerystring.PARAM\$1NAME |
| Cabeçalho de solicitação de vários valores (compatível apenas com a rota \$1connect) | route.request.multivalueheader.PARAM\$1NAME |
| Corpo da solicitação | route.request.body.JSONPath\$1EXPRESSION |
| Variáveis de estágio | stageVariables.VARIABLE\$1NAME |
| Variáveis de contexto | context.VARIABLE\$1NAME que deve ser uma das [variáveis de contexto com suporte](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valor estático | 'STATIC\$1VALUE'. STATIC\$1VALUE é um literal de string e deve estar entre aspas simples. |
Ao criar um mapeamento de dados, usando a AWS CLI, siga o formato correto para usar literais com strings na AWS CLI. Para ter mais informações, consulte [Usar aspas e literais com strings na AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html) no *Guia do usuário da versão 1 da AWS Command Line Interface*.
## Exemplos
Os exemplos da AWS CLI a seguir configuram mapeamentos de dados. Para obter um modelo demonstrativo do CloudFormation, consulte [samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip).
### Mapear o connectionId de um cliente para um cabeçalho em uma solicitação de integração
O comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) indicado abaixo associa o `connectionId` de um cliente a um cabeçalho `connectionId` na solicitação para uma integração de backend:
```
aws apigatewayv2 update-integration \
--integration-id abc123 \
--api-id a1b2c3d4 \
--request-parameters 'integration.request.header.connectionId'='context.connectionId'
```
### Mapear um parâmetro de string de consulta para um cabeçalho em uma solicitação de integração
O exemplo a seguir associa um parâmetro de string de consulta `authToken` a um cabeçalho `authToken` na solicitação de integração.
1. Use o comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) a seguir para adicionar o parâmetro de string de consulta `authToken` aos parâmetros de solicitação da rota.
```
aws apigatewayv2 update-route --route-id 0abcdef \
--api-id a1b2c3d4 \
--request-parameters '{"route.request.querystring.authToken": {"Required": false}}'
```
1. Use o comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) a seguir para associar o parâmetro de string de consulta ao cabeçalho `authToken` na solicitação para a integração de backend.
```
aws apigatewayv2 update-integration \
--integration-id abc123 \
--api-id a1b2c3d4 \
--request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken'
```
1. (Opcional) Se necessário, use o comando [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html) a seguir para excluir o parâmetro de string de consulta `authToken` dos parâmetros de solicitação da rota.
```
aws apigatewayv2 delete-route-request-parameter \
--route-id 0abcdef \
--api-id a1b2c3d4 \
--request-parameter-key 'route.request.querystring.authToken'
```
# Referência de modelos de mapeamento da API de WebSocket do API Gateway
Esta seção resume o conjunto de variáveis que são atualmente compatíveis com APIs WebSocket no API Gateway.
| Parâmetro | Descrição |
| --- | --- |
| \$1context.connectionId | Um ID exclusivo para a conexão que pode ser utilizado para fazer uma chamada ao cliente. |
| \$1context.connectedAt | O tempo de conexão formatado em [Epoch](https://en.wikipedia.org/wiki/Unix_time). |
| \$1context.domainName | Um nome de domínio para a API WebSocket. É possível utilizá-lo para fazer uma chamada ao cliente (em vez de um valor codificado). |
| \$1context.eventType | O tipo de evento: `CONNECT`, `MESSAGE` ou `DISCONNECT`. |
| \$1context.messageId | Um ID exclusivo do servidor para uma mensagem. Disponível apenas quando o `$context.eventType` é `MESSAGE`. |
| \$1context.routeKey | A chave de roteamento selecionada. |
| \$1context.requestId | Igual a `$context.extendedRequestId`. |
| \$1context.extendedRequestId | Um ID gerado automaticamente para a chamada de API, que contém mais informações úteis para depuração/solução de problemas. |
| \$1context.apiId | O identificador que o API Gateway atribui à sua API. |
| \$1context.authorizer.principalId | A identificação do usuário principal associada ao token enviado pelo cliente e retornada por uma função do Lambda do autorizador do Lambda do API Gateway (anteriormente conhecido como autorizador personalizado). |
| \$1context.authorizer.property | O valor transformado em string do par de chave/valor especificado do mapa `context` retornado de uma função de autorizador do Lambda do API Gateway. Por exemplo, se o autorizador retornar o seguinte mapa `context`: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} chamar `$context.authorizer.key` retornará a string `"value"`, chamar `$context.authorizer.numKey` retornará a string `"1"` e chamar `$context.authorizer.boolKey` retornará a string `"true"`. |
| \$1context.error.messageString | O valor citado de \$1context.error.message, ou seja, "\$1context.error.message". |
| \$1context.error.validationErrorString | Uma string que contém uma mensagem de erro de validação detalhada. |
| \$1context.identity.accountId | O ID da conta da AWS associado à solicitação. |
| \$1context.identity.apiKey | A chave do proprietário da API associada à solicitação de API habilitada por chave. |
| \$1context.identity.apiKeyId | O ID da chave da API associada à solicitação de API habilitada por chave |
| \$1context.identity.caller | O identificador principal do agente de chamada que está fazendo a solicitação. |
| \$1context.identity.cognitoAuthenticationProvider | Uma lista separada por vírgulas de todos os provedores de autenticação do Amazon Cognito usados pelo autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Por exemplo, para uma identidade de um grupo de usuários do Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Consulte informações sobre os provedores de autenticação do Amazon Cognito disponível em [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) no *Guia do desenvolvedor do Amazon Cognito*. |
| \$1context.identity.cognitoAuthenticationType | O tipo de autenticação do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Os valores possíveis incluem `authenticated` para identidades autenticadas e `unauthenticated` para identidades não autenticadas. |
| \$1context.identity.cognitoIdentityId | O ID de identidade do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | O ID do grupo de identidades do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. |
| \$1context.identity.sourceIp | O endereço IP de origem da conexão TCP mais próxima que está fazendo a solicitação para o endpoint do API Gateway. |
| \$1context.identity.user | O identificador principal do usuário que está fazendo a solicitação. |
| \$1context.identity.userAgent | O agente de usuário do autor da chamada da API. |
| \$1context.identity.userArn | O Nome do Recurso Amazon (ARN) do usuário efetivo identificado após a autenticação. |
| \$1context.requestTime | O horário da solicitação [CLF](https://httpd.apache.org/docs/current/logs.html#common) formatado (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | O tempo de solicitação formatado em [Epoch](https://en.wikipedia.org/wiki/Unix_time), em milissegundos. |
| \$1context.stage | O estágio de implantação da chamada de API (por exemplo, Beta ou Prod). |
| \$1context.status | O status da resposta. |
| \$1input.body | Retorna a carga bruta como uma string. |
| \$1input.json(x) | Essa função avalia uma expressão JSONPath e retorna os resultados como uma string JSON. Por exemplo, `$input.json('$.pets')` retornará uma string JSON que representa a estrutura de animais de estimação. Para obter mais informações sobre o JSONPath, consulte [JSONPath](https://goessner.net/articles/JsonPath/) ou [JSONPath para Java](https://github.com/json-path/JsonPath). |
| \$1input.path(x) | Usa uma string de expressão JSONPath (`x`) e retorna uma representação de objeto JSON do resultado. Isso permite que você acesse e manipule elementos da carga nativamente em [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Por exemplo, se a expressão `$input.path('$.pets')` retorna um objeto da seguinte forma: [
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
`$input.path('$.pets').count()` retornaria `"3"`. Para obter mais informações sobre o JSONPath, consulte [JSONPath](http://goessner.net/articles/JsonPath/) ou [JSONPath para Java](https://github.com/jayway/JsonPath). |
| \$1stageVariables. | ** representa um nome de variável de estágio. |
| \$1stageVariables[''] | ** representa qualquer nome de variável de estágio. |
| \$1\$1stageVariables['']\$1 | ** representa qualquer nome de variável de estágio. |
| \$1util.escapeJavaScript() | Escapa os caracteres em uma string usando regras de string JavaScript. Essa função transformará quaisquer aspas simples comuns (`'`) em aspas com escape (`\'`). No entanto, as aspas simples com escape não são válidas no JSON. Portanto, quando a saída dessa função for usada em uma propriedade JSON, você deverá transformar todas aspas simples (`\'`) com escape de volta para aspas simples comuns (`'`). Isso é mostrado no exemplo a seguir: $util.escapeJavaScript(data).replaceAll("\\'","'") |
| \$1util.parseJson() | Usa um JSON "transformado em string" e retorna uma representação de objeto do resultado. Você pode usar o resultado dessa função para acessar e manipular elementos da carga nativamente em Apache VTL (Velocity Template Language). Por exemplo, se tiver a seguinte carga: {"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"} e usar o seguinte modelo de mapeamento #set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
"errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Você receberá a seguinte saída: {
"errorMessageObjKey2ArrVal" : 1
}
|
| \$1util.urlEncode() | Converte uma string no formato "application/x-www-form-urlencoded". |
| \$1util.urlDecode() | Decodifica uma string "application/x-www-form-urlencoded". |
| \$1util.base64Encode() | Codifica os dados em uma string codificada em base64. |
| \$1util.base64Decode() | Decodifica os dados de uma string codificada em base64. |
# Tipos de mídia binários para APIs de WebSocket no API Gateway
As APIs WebSocket do API Gateway não são compatíveis com quadros binários nas cargas de mensagem recebida. Se um aplicativo do cliente enviar um quadro binário, este será rejeitado pelo API Gateway, que desconectará o cliente com o código 1003.
Há uma solução para esse comportamento. Se o cliente envia dados binários codificados em texto (por exemplo, base64) como um quadro de texto, você pode definir a propriedade `contentHandlingStrategy` da integração como `CONVERT_TO_BINARY` para converter a carga de string codificada em base64 em binário.
Para retornar uma resposta de rota para uma carga de binário em integrações não proxy, você pode definir a propriedade `contentHandlingStrategy` da resposta de integração como `CONVERT_TO_TEXT` para converter a carga de binário em string codificada em base64.
# Invocar APIs de WebSocket
Depois de implantar a API WebSocket, as aplicações cliente poderão se conectar para enviar mensagens para ela, e seu serviço de backend poderá enviar mensagens para aplicações cliente conectados:
+ Você pode usar `wscat` para se conectar à sua API WebSocket e enviar mensagens a ela, simulando o comportamento do cliente. Consulte [Use `wscat` para se conectar a uma API do WebSocket e enviar mensagens a ela](apigateway-how-to-call-websocket-api-wscat.md).
+ Você pode usar a API @connections do seu serviço de backend para enviar uma mensagem de retorno a um cliente conectado, obter informações de conexão ou desconectar o cliente. Consulte [Usar os comandos `@connections` em seu serviço de backend](apigateway-how-to-call-websocket-api-connections.md).
+ Um aplicativo do cliente pode usar sua própria biblioteca WebSocket para invocar a API WebSocket.
# Use `wscat` para se conectar a uma API do WebSocket e enviar mensagens a ela
O utilitário `[wscat](https://www.npmjs.com/package/wscat)` é uma ferramenta conveniente para testar uma API WebSocket criada e implantada no API Gateway. Você pode instalar e utilizar `wscat` da seguinte maneira:
1. Faça download de `wscat` em [https://www.npmjs.com/package/wscat](https://www.npmjs.com/package/wscat).
1. Instale o `wscat` executando o seguinte comando.
```
npm install -g wscat
```
1. Para se conectar à sua API, execute o comando `wscat` conforme mostrado no exemplo a seguir. Observe que este exemplo pressupõe que a configuração `Authorization` é `NONE`.
```
wscat -c wss://aabbccddee.execute-api.us-east-1.amazonaws.com/test/
```
É necessário substituir `aabbccddee` pelo ID de API real que é exibido no console do API Gateway ou retornado pelo comando [https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) da AWS CLI.
Além disso, se a sua API estiver em uma região diferente de `us-east-1`, será necessário substituir a região correta.
1. Enquanto estiver conectado, para testar a API, insira uma mensagem como a seguinte:
```
{"{jsonpath-expression}":"{route-key}"}
```
em que *\$1jsonpath-expression\$1* é uma expressão JSONPath e *\$1route-key\$1* é uma chave de roteamento para a API. Por exemplo:
```
{"action":"action1"}
{"message":"test response body"}
```
Para obter mais informações sobre o JSONPath, consulte [JSONPath](https://goessner.net/articles/JsonPath/) ou [JSONPath para Java](https://github.com/json-path/JsonPath).
1. Para desconectar-se da API, insira `ctrl-C`.
# Usar os comandos `@connections` em seu serviço de backend
Seu serviço de backend pode utilizar as solicitações HTTP de conexão WebSocket a seguir para enviar uma mensagem de retorno a um cliente conectado, obter informações de conexão ou desconectar o cliente.
**Importante**
Essas solicitações utilizam a [autorização do IAM](apigateway-websocket-control-access-iam.md), portanto, você deve assiná-las com o [Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). Para fazer isso, você pode usar a API de Gerenciamento do API Gateway. Para obter mais informações, consulte [ApiGatewayManagementApi](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigatewaymanagementapi.html).
No comando a seguir, é necessário substituir `{api-id}` pelo ID de API real que é exibido no console do API Gateway ou retornado pelo comando [create-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.html) da AWS CLI. É necessário estabelecer conexão antes de usar esse comando.
Para enviar uma mensagem de retorno ao cliente, utilize:
```
POST https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
É possível testar essa solicitação usando `[Postman](https://www.postman.com/)` ou chamando `[awscurl](https://github.com/okigan/awscurl)` conforme o exemplo a seguir:
```
awscurl --service execute-api -X POST -d "hello world" https://{prefix}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Você precisa codificar o URL no comando, conforme mostrado no exemplo a seguir:
```
awscurl --service execute-api -X POST -d "hello world" https://aabbccddee.execute-api.us-east-1.amazonaws.com/prod/%40connections/R0oXAdfD0kwCH6w%3D
```
Para obter o status de conexão mais recente do cliente, use:
```
GET https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Para desconectar o cliente, use:
```
DELETE https://{api-id}.execute-api.us-east-1.amazonaws.com/{stage}/@connections/{connection_id}
```
Você pode criar dinamicamente uma URL de retorno de chamada ao utilizar as variáveis `$context` em sua integração. Por exemplo, se usar a integração de proxy do Lambda com uma função do Lambda `Node.js`, você poderá criar o URL e enviar uma mensagem para um cliente conectado da seguinte forma:
```
import {
ApiGatewayManagementApiClient,
PostToConnectionCommand,
} from "@aws-sdk/client-apigatewaymanagementapi";
export const handler = async (event) => {
const domain = event.requestContext.domainName;
const stage = event.requestContext.stage;
const connectionId = event.requestContext.connectionId;
const callbackUrl = `https://${domain}/${stage}`;
const client = new ApiGatewayManagementApiClient({ endpoint: callbackUrl });
const requestParams = {
ConnectionId: connectionId,
Data: "Hello!",
};
const command = new PostToConnectionCommand(requestParams);
try {
await client.send(command);
} catch (error) {
console.log(error);
}
return {
statusCode: 200,
};
};
```
Se você usar um nome de domínio personalizado para sua API de WebSocket, remova a variável `stage` do código da função.
Ao enviar uma mensagem de retorno de chamada, a função do Lambda deve ter permissão para chamar a API de gerenciamento do API Gateway. Você poderá receber um erro contendo `GoneException` se publicar uma mensagem antes do estabelecimento da conexão ou após a desconexão do cliente.
# Publicar APIs de WebSocket para os clientes invocarem
Apenas criar e desenvolver uma API do API Gateway não fará com que ela possa ser chamada automaticamente pelos usuários. Para que ela possa ser chamada, implante a API em um estágio. Além disso, você pode querer personalizar o URL que os usuários usarão para acessar a API. Você pode dar a ele um domínio que seja consistente com sua marca ou que seja mais memorável que o URL padrão da API.
Nesta seção, você pode aprender a implantar a API e personalizar o URL fornecido aos usuários para acessá-la.
**nota**
Para aumentar a segurança das APIs do API Gateway, o domínio `execute-api.{region}.amazonaws.com` é registrado na [Public Suffix List (PSL)](https://publicsuffix.org/). Para maior segurança, recomendamos que você use cookies com um prefixo `__Host-` se precisar definir cookies confidenciais no nome de domínio padrão para as APIs do API Gateway. Essa prática ajudará a defender seu domínio contra tentativas de falsificação de solicitação entre sites (CSRF). Para obter mais informações, consulte a página [Set-Cookie](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes) na Mozilla Developer Network.
**Topics**
+ [Criar estágios para APIs de WebSocket no API Gateway](websocket-api-stages.md)
+ [Implantar APIs de WebSocket no API Gateway](apigateway-set-up-websocket-deployment.md)
+ [Política de segurança para APIs de WebSocket no API Gateway](websocket-api-ciphers.md)
+ [Nomes de domínio personalizados para APIs de WebSocket no API Gateway](websocket-api-custom-domain-names.md)
# Criar estágios para APIs de WebSocket no API Gateway
O estágio de uma API é uma referência lógica a um estado do ciclo de vida de sua API (por exemplo, `dev`, `prod`, `beta` ou `v2`). Os estágios de API são identificados por seu ID de API e nome de estágio e são incluídos no URL que você usa para chamar a API. Cada estágio é uma referência nomeada a uma implantação da API e é disponibilizado para chamadas feitas por aplicativos cliente.
Uma implantação é um instantâneo da configuração da API. Depois de implantar uma API em um estágio, ela estará disponível para ser chamada por clientes. Você deve implantar uma API para que as alterações entrem em vigor.
## Variáveis de estágio
As variáveis de estágio são pares chave-valor que você pode definir para um estágio de uma API WebSocket. Elas atuam como variáveis de ambiente e podem ser usadas na configuração da API.
Por exemplo, você pode definir uma variável de estágio e, depois, definir seu valor como um endpoint HTTP para uma integração de proxy HTTP. Posteriormente, você pode fazer referência ao endpoint usando o nome da variável de estágio associada. Fazendo isso, você pode usar a mesma configuração de API com um endpoint diferente em cada estágio. Da mesma forma, você pode usar variáveis de estágio para especificar uma integração de função diferente do AWS Lambda para cada estágio da API.
**nota**
As variáveis de estágio não se destinam a ser usadas para dados confidenciais, como credenciais. Para transmitir dados confidenciais para integrações, use um autorizador do AWS Lambda. Você pode passar dados confidenciais para integrações na saída do autorizador do Lambda. Para saber mais, consulte [Formato de resposta do autorizador do Lambda](http-api-lambda-authorizer.md#http-api-lambda-authorizer.payload-format-response).
### Exemplos
Para usar uma variável de estágio para personalizar o endpoint de integração HTTP, primeiro defina o nome e o valor da variável de estágio (por exemplo, `url`) com um valor de `example.com`. Depois, configure uma integração de proxy HTTP. Em vez de inserir o URL do endpoint, você pode instruir o API Gateway a usar o valor da variável de estágio, **http://\$1\$1stageVariables.url\$1**. Esse valor instrui o API Gateway a substituir sua variável de estágio `${}` em tempo de execução, dependendo do estágio da API.
É possível fazer referência a variáveis de estágio de forma semelhante para especificar um nome de função do Lambda ou um ARN de função da AWS.
Ao especificar um nome de função do Lambda como um valor de variável de estágio, você deve configurar as permissões nessa função do Lambda manualmente. O comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) indicado abaixo adiciona as permissões necessárias:
```
aws lambda add-permission --function-name arn:aws:lambda:XXXXXX:your-lambda-function-name --source-arn arn:aws:execute-api:us-east-1:YOUR_ACCOUNT_ID:api_id/*/HTTP_METHOD/resource --principal apigateway.amazonaws.com --statement-id apigateway-access --action lambda:InvokeFunction
```
## Referência de variáveis de estágio do API Gateway
### URIs de integração HTTP
Uma variável de estágio pode ser usada como parte de um URI de integração HTTP, como mostram os exemplos a seguir.
+ Um URI completo sem protocol – `http://${stageVariables.}`
+ Um domínio complet – `http://${stageVariables.}/resource/operation`
+ Um subdomíni – `http://${stageVariables.}.example.com/resource/operation`
+ Um caminh – `http://example.com/${stageVariables.}/bar`
+ Uma string de consult – `http://example.com/foo?q=${stageVariables.}`
### Funções do Lambda
É possível usar uma variável de estágio no lugar de um nome de função ou alias do Lambda, conforme mostrado nos exemplos a seguir.
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function:${stageVariables.}/invocations`
+ `arn:aws:apigateway::lambda:path/2015-03-31/functions/arn:aws:lambda:::function::${stageVariables.}/invocations`
**nota**
Para usar uma variável de estágio para uma função do Lambda, a função deve estar na mesma conta que a API. As variáveis de estágio não suportam funções do Lambda entre contas.
### AWSCredenciais de integração da
É possível usar uma variável de estágio como parte de um ARN de credencial de usuário ou de função da AWS, conforme mostrado no exemplo a seguir.
+ `arn:aws:iam:::${stageVariables.}`
# Implantar APIs de WebSocket no API Gateway
Depois de criar sua API WebSocket, você deve implantá-la para permitir que seja invocada por seus usuários após a disponibilização.
Para implantar uma API, você cria uma [implantação da API](api-gateway-basic-concept.md#apigateway-definition-api-deployment) e a associa a um [estágio](api-gateway-basic-concept.md#apigateway-definition-api-stage). Cada estágio é um snapshot da API, sendo disponibilizado para ser chamado pelos aplicativos do cliente.
**Importante**
Toda vez que atualizar uma API, você deverá reimplantá-la. Alterações em qualquer item que não sejam as configurações do estágio exigem uma nova implantação, incluindo modificações nos seguintes recursos:
Rotas
Integrações
Authorizers
Por padrão, você está limitado a dez estágios para cada API. Recomendamos reutilizar estágios para as implantações.
Para chamar uma API WebSocket implantada, o cliente envia uma mensagem à URL da API. A URL é determinada pelo nome do host e pelo nome do estágio da API.
**nota**
O API Gateway oferecerá suporte a cargas de até 128 KB com quadros de máximo 32 KB. Se uma mensagem exceder 32 KB, deve ser dividida em vários quadros, cada qual contendo 32 KB ou menos.
Com o nome de domínio padrão da API, a URL base de uma (por exemplo) API WebSocket em determinado estágio (`{stageName}`) tem o seguinte formato:
```
wss://{api-id}.execute-api.{region}.amazonaws.com/{stageName}
```
Para facilitar o uso da URL da API WebSocket, você pode criar um nome de domínio personalizado (por exemplo, `api.example.com`) para substituir o nome de domínio padrão da API. O processo de configuração é o mesmo utilizado para APIs REST. Para obter mais informações, consulte [Nome de domínio personalizado para APIs REST públicas no API Gateway](how-to-custom-domains.md).
Os estágios permitem um controle de versão robusto para sua API. Por exemplo, você pode implantar uma API em um estágio `test` e um `prod`, e usar o estágio `test` como uma compilação de teste e o estágio `prod` como uma compilação estável. Depois que as atualizações passarem no teste, você poderá promover o estágio `test` para o estágio `prod`. Essa promoção pode ser feita por meio da reimplantação da API ao estágio `prod`. Para obter mais detalhes sobre estágios, consulte [Configurar um estágio para uma API REST no API Gateway](set-up-stages.md).
**Topics**
+ [Criar uma implantação de API do WebSocket usando a AWS CLI](#apigateway-create-websocket-deployment-using-awscli)
+ [Criar uma implantação de API WebSocket usando o console do API Gateway](#apigateway-create-websocket-deployment-using-console)
## Criar uma implantação de API do WebSocket usando a AWS CLI
O seguinte comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) cria uma implantação:
```
aws apigatewayv2 --region us-east-1 create-deployment --api-id aabbccddee
```
A saída será exibida da seguinte forma:
```
{
"DeploymentId": "fedcba",
"DeploymentStatus": "DEPLOYED",
"CreatedDate": "2018-11-15T06:49:09Z"
}
```
A API implantada não poderá ser chamada até que a implantação seja associada a um estágio. Você pode criar um novo estágio ou reutilizar um estágio que criou anteriormente.
O comando [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-stage.html) indicado abaixo cria um estágio e o associa à implantação:
```
aws apigatewayv2 --region us-east-1 create-stage --api-id aabbccddee --deployment-id fedcba --stage-name test
```
A saída será exibida como a seguir:
```
{
"StageName": "test",
"CreatedDate": "2018-11-15T06:50:28Z",
"DeploymentId": "fedcba",
"DefaultRouteSettings": {
"MetricsEnabled": false,
"ThrottlingBurstLimit": 5000,
"DataTraceEnabled": false,
"ThrottlingRateLimit": 10000.0
},
"LastUpdatedDate": "2018-11-15T06:50:28Z",
"StageVariables": {},
"RouteSettings": {}
}
```
É possível reutilizar um estágio existente atualizando a propriedade `deploymentId` do estágio com o ID da implantação recém-criado (*deployment-id*). O comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) indicado abaixo atualiza o ID de implantação do estágio:
```
aws apigatewayv2 update-stage --region region \
--api-id api-id \
--stage-name stage-name \
--deployment-id deployment-id
```
## Criar uma implantação de API WebSocket usando o console do API Gateway
Para usar o console do API Gateway a fim de criar uma implantação para uma API WebSocket:
1. Inicie uma sessão no console do API Gateway e escolha a API.
1. Escolha **Implantar API**.
1. Escolha o estágio desejado na lista suspensa ou insira o nome de um novo estágio.
# Política de segurança para APIs de WebSocket no API Gateway
O API Gateway impõe uma política de segurança de `TLS_1_2` para todos os endpoints da API de WebSocket.
Uma *política de segurança* é uma combinação predefinida da versão mínima do TLS e dos pacotes de criptografia oferecida pelo Amazon API Gateway. O protocolo TLS trata problemas de segurança de rede, como violação e interceptação entre um cliente e o servidor. Quando seus clientes estabelecem um handshake do TLS para a API por meio do domínio personalizado, a política de segurança aplica as opções do pacote de criptografia e da versão do TLS que seus clientes podem optar por usar. Essa política de segurança é compatível com tráfego TLS 1.2 e TLS 1.3 e rejeita tráfego TLS 1.0.
## Protocolos e cifras TLS compatíveis para APIs de WebSocket
A tabela a seguir descreve os protocolos TLS compatíveis com as APIs de WebSocket.
| **Protocolos TLS** | **Política de segurança TLS\$11\$12** |
| --- | --- |
| TLSv1.3 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| TLSv1.2 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
A tabela a seguir descreve as criptografias TLS disponíveis para a política de segurança TLS 1\$12 para APIs de WebSocket.
| **Cifras TLS** | **Política de segurança TLS\$11\$12** |
| --- | --- |
| TLS\$1AES\$1128\$1GCM\$1SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| TLS\$1AES\$1256\$1GCM\$1SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| TLS\$1CHACHA20\$1POLY1305\$1SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-ECDSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-RSA-AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-ECDSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-RSA-AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-ECDSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-RSA-AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-ECDSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| ECDHE-RSA-AES256-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| AES128-GCM-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| AES128-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| AES256-GCM-SHA384 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
| AES256-SHA256 | ![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/success_icon.svg) Sim |
## Nomes das criptografias OpenSSL e RFC
OpenSSL e IETF RFC 5246 usam nomes diferentes para as mesmas cifras. Para ver uma lista dos nomes das cifras, consulte [Nomes das criptografias OpenSSL e RFC](apigateway-security-policies-list.md#apigateway-secure-connections-openssl-rfc-cipher-names).
## Informações sobre APIs HTTP e APIs REST
Para saber mais sobre APIs REST e APIs HTTP, consulte [Escolher uma política de segurança para o domínio personalizado no API Gateway](apigateway-custom-domain-tls-version.md) e [Política de segurança para APIs HTTP no API Gateway](http-api-ciphers.md).
# Nomes de domínio personalizados para APIs de WebSocket no API Gateway
Os *nomes de domínio personalizados* são URLs mais simples e intuitivos que você pode fornecer aos usuários da API.
Após a implantação da sua API, você e seus clientes podem invocar essa API usando a URL de base padrão com o seguinte formato:
```
https://api-id.execute-api.region.amazonaws.com/stage
```
em que *api-id* é gerado pelo API Gateway, *region* é a região da AWS e *stage* é especificado por você ao implantar a API.
A parte do nome de host do URL, `api-id.execute-api.region.amazonaws.com`, refere-se a um endpoint de API. O endpoint de API padrão é gerado aleatoriamente, difícil de lembrar e não é simples de usar.
Com nomes de domínio personalizados, você pode configurar o nome de host da API e escolher um caminho base (por exemplo, `myservice`) para mapear o URL alternativo para sua API. Por exemplo, um URL de base de API mais amigável pode se tornar:
```
https://api.example.com/myservice
```
## Considerações
As considerações a seguir podem afetar o uso de um nome de domínio personalizado.
+ Se mapear um nome de domínio personalizado para uma API de WebSocket, você não poderá mapeá-lo para uma API REST ou uma API HTTP.
+ Somente nomes de domínio regionais personalizados são compatíveis.
+ Para a versão mínima de TLS, somente o TLS 1.2 é compatível.
+ É necessário criar ou atualizar o registro de recursos do provedor DNS para ser mapeado ao endpoint da API. Sem esse mapeamento, as solicitações de API que forem direcionadas para o nome de domínio personalizado não conseguirão acessar o API Gateway.
+ É possível comportar um número quase infinito de nomes de domínio sem exceder a cota padrão usando um certificado curinga. Para obter mais informações, consulte [Nomes de domínio personalizados curinga](http-api-custom-domain-names.md#http-wildcard-custom-domain-names).
## Pré-requisitos
Veja a seguir os pré-requisitos de um nome de domínio personalizado.
### Registrar um nome de domínio
É necessário ter um nome de domínio da Internet registrado para configurar nomes de domínio personalizados para as APIs. É possível registrar o domínio da internet usando o [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) ou um registrador de domínios de terceiros da sua escolha. O nome de domínio personalizado pode ser o nome de um subdomínio ou do domínio raiz (também conhecido como “ápex da zona”) de um domínio da internet registrado.
O nome de domínio deve seguir a especificação [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) e pode ter no máximo 63 octetos por etiqueta e 255 octetos no total.
### Certificados para nomes de domínio personalizados
Antes de configurar um nome de domínio personalizado para uma API, você deve ter um certificado SSL/TLS pronto no ACM. Se o ACM não estiver disponível na região da AWS onde você está criando o nome de domínio personalizado, será necessário importar um certificado para o API Gateway nessa região.
Para importar um certificado SSL/TLS, você deve fornecer o corpo do certificado SSL/TLS formatado em PEM, sua chave privada e a cadeia de certificado para o nome de domínio personalizado.
Cada certificado armazenado no ACM é identificado por seu ARN. Com certificados emitidos pelo ACM, não é necessário se preocupar em expor detalhes de certificados confidenciais, como a chave privada. Para usar um certificado gerenciado pela AWS para um nome de domínio, basta fazer referência ao seu ARN.
Se o seu aplicativo usa a fixação de certificados, às vezes chamada de fixação SSL, para fixar um certificado do ACM, talvez o aplicativo não consiga se conectar ao seu domínio após a AWS renovar o certificado. Para ter mais informações, consulte [Problemas de fixação do certificado](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) no *Guia do usuário do AWS Certificate Manager*.
## Nomes de domínio personalizados curinga
Com nomes de domínio personalizados curinga, você pode suportar um número quase infinito de nomes de domínio sem exceder a [cota padrão](limits.md). Por exemplo, você pode dar a cada um de seus clientes seu próprio nome de domínio `customername.api.example.com`.
Para criar um nome de domínio personalizado curinga, especifique um curinga (`*`) como o primeiro subdomínio de um domínio personalizado que representa todos os subdomínios possíveis de um domínio raiz.
Por exemplo, o nome de domínio personalizado curinga `*.example.com` resulta em subdomínios, como `a.example.com`, `b.example.com` e `c.example.com`, que são todos roteados para o mesmo domínio.
Os nomes de domínio personalizados curinga oferecem suporte a configurações distintas dos nomes de domínio personalizados padrão do API Gateway. Por exemplo, em uma única conta da AWS, é possível configurar `*.example.com` e `a.example.com` para se comportarem de forma diferente.
Você pode usar as variáveis de contexto `$context.domainName` e `$context.domainPrefix` para determinar o nome de domínio que um cliente usou para chamar sua API. Para saber mais sobre variáveis de contexto, consulte [Variáveis para transformações de dados para o API Gateway](api-gateway-mapping-template-reference.md).
Para criar um nome de domínio personalizado curinga, é necessário fornecer um certificado emitido pelo ACM que foi validado usando o DNS ou o método de validação por e-mail.
**nota**
Não é possível criar um nome de domínio personalizado curinga se uma conta da AWS diferente tiver criado um nome de domínio personalizado que esteja em conflito com o nome de domínio personalizado curinga. Por exemplo, se a conta A tiver criado `a.example.com`, a conta B não poderá criar o nome de domínio personalizado curinga `*.example.com`.
Se a conta A e a conta B compartilham um proprietário, entre em contato com a [Central de Suporte da AWS](https://console.aws.amazon.com/support/home#/) para solicitar uma exceção.
## Próximas etapas para nomes de domínio personalizados
Para configurar um nome de domínio personalizado para uma API HTTP, use a documentação da seção API REST do Guia do desenvolvedor do API Gateway.
Primeiro, especifique o certificado para o nome de domínio personalizado. Para obter mais informações, consulte [Preparar certificados no AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Depois, crie um nome de domínio regional personalizado. Para obter mais informações, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md).
# Mapear estágios de API para um nome de domínio personalizado para APIs de WebSocket
Você usa mapeamentos de API para conectar estágios de API a um nome de domínio personalizado. Depois de criar um nome de domínio e configurar registros DNS, você usa mapeamentos de API para enviar tráfego para as suas APIs utilizando o seu nome de domínio personalizado.
Um mapeamento de API especifica uma API, um estágio e, opcionalmente, um caminho a usar para o mapeamento. Por exemplo, você pode mapear o estágio `production` de uma API para `wss://api.example.com/orders`.
Antes de criar um mapeamento de API, você deve ter uma API, um estágio e um nome de domínio personalizado. Para saber mais sobre como criar um nome de domínio personalizado, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md).
## Restrições
+ Em um mapeamento de API, o nome de domínio personalizado e as APIs mapeadas devem estar na mesma conta da AWS.
+ Os mapeamentos de API devem conter apenas letras, números e os caracteres a seguir: `$-_.+!*'()`.
+ O comprimento máximo para o caminho em um mapeamento de API é de 300 caracteres.
+ Você não pode mapear APIs WebSocket para o mesmo nome de domínio personalizado que uma API HTTP ou API REST.
+ Se você criar mapeamentos de API com vários níveis, o API Gateway mudará todos os nomes de cabeçalho para minúsculas.
## Crie um mapeamento de API
Para criar um mapeamento de API, você deve primeiro criar um nome de domínio personalizado, uma API e um estágio. Para obter informações sobre como criar um nome de domínio personalizado, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md).
------
#### [ Console de gerenciamento da AWS ]
**Para criar um mapeamento de API**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom domain names** (Nomes de domínios personalizados).
1. Selecione um nome de domínio personalizado que você já criou.
1. Escolha **API mappings** (Mapeamentos de API).
1. Escolha **Configure API mappings (Configurar mapeamentos de API)**.
1. Escolha **Add new mapping (Adicionar novo mapeamento)**.
1. Insira uma **API**, um **Estágio** e, opcionalmente, um **Caminho**.
1. Escolha **Salvar**.
------
#### [ AWS CLI ]
O comando [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) a seguir cria um mapeamento de API. Neste exemplo, o API Gateway envia solicitações para `api.example.com/v1` para a API e o estágio especificados.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1 \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
O exemplo de CloudFormation a seguir cria um mapeamento de API.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'v1'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Tipos de endereço IP para nomes de domínio personalizados para APIs de WebSocket
Ao criar um nome de domínio personalizado, você especifica o tipo de endereços IP que podem invocar seu domínio. É possível escolher IPv4 para resolver endereços IPv4 e invocar seu domínio ou escolher pilha dupla para permitir que endereços IPv4 e IPv6 invoquem seu domínio. Recomendamos que você defina o tipo de endereço IP como pilha dupla para aliviar o esgotamento do espaço IP ou para seu procedimento de segurança. Para ter mais informações sobre os benefícios de um tipo de endereço IP de pilha dupla, consulte [IPv6 na AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
## Considerações sobre tipos de endereço IP
As considerações a seguir podem afetar o uso de tipos de endereço IP.
+ O tipo de endereço IP padrão para nomes de domínio personalizados do API Gateway é IPv4.
+ Seu nome de domínio personalizado não precisa ter o mesmo tipo de endereço IP para todas as APIs associadas a ele. Se você desabilitar seu endpoint de API padrão, isso poderá afetar como os chamadores podem invocar sua API.
## Alterar o tipo de endereço IP do nome de domínio personalizado
É possível alterar o tipo de endereço IP atualizando a configuração do endpoint do nome de domínio. É possível atualizar a configuração do endpoint usando o Console de gerenciamento da AWS, a AWS CLI, o CloudFormation ou um SDK da AWS.
------
#### [ Console de gerenciamento da AWS ]
**Como alterar o tipo de endereço IP de um nome de domínio personalizado**
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha um nome de domínio personalizado público.
1. Escolha **Configurações de endpoint**.
1. Em Tipo de endereço IP, escolha **IPv4** ou **Pilha dupla**.
1. Escolha **Salvar**.
------
#### [ AWS CLI ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) a seguir atualiza uma API para ter um tipo de endereço IP de pilha dupla:
```
aws apigatewayv2 update-domain-name \
--domain-name dualstack.example.com \
--domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack
```
A saída será exibida da seguinte forma:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "dualstack.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z3LQWSYCGH4ADY",
"SecurityPolicy": "TLS_1_2",
"IpAddressType": "dualstack"
}
],
"Tags": {}
}
```
------
# Desabilitar o endpoint padrão para APIs de WebSocket
Por padrão, os clientes podem invocar sua API usando o endpoint `execute-api` gerado pelo API Gateway para sua API. Para garantir que os clientes possam acessar sua API somente usando um nome de domínio personalizado, desabilite o endpoint `execute-api` padrão. Quando o endpoint padrão é desabilitado, ele afeta todos os estágios de uma API.
O procedimento a seguir mostra como desabilitar o endpoint padrão de uma API de WebSocket.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha uma API de WebSocket.
1. Escolha **Configurações da API**.
1. Em **Detalhes da API**, escolha **Editar**.
1. Em **Endpoint padrão**, selecione **Inativo**.
1. Escolha **Salvar alterações**.
1. No painel de navegação principal, selecione **Rotas**.
1. Selecione **Implantar** e reimplante a API ou crie uma etapa para que a alteração entre em vigor.
------
#### [ AWS CLI ]
O comando [update-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-api.html) indicado abaixo desabilita o endpoint padrão para uma API de WebSocket.
```
aws apigatewayv2 update-api \
--api-id abcdef123 \
--disable-execute-api-endpoint
```
Depois de desabilitar o endpoint padrão, é necessário implantar sua API para que a alteração entre em vigor.
O comando da AWS CLI a seguir cria uma implantação.
```
aws apigatewayv2 create-deployment \
--api-id abcdef123 \
--stage-name dev
```
------
# Proteger as APIs de WebSocket no API Gateway
O API Gateway fornece várias maneiras de proteger sua API de determinadas ameaças, como usuários mal-intencionados ou picos de tráfego. É possível proteger a API usando estratégias, como gerar certificados SSL ou configurar destinos de controle de utilização. Para ter mais informações sobre como gerar certificados, consulte [Gerar e configurar um certificado SSL para autenticação de backend no API Gateway](getting-started-client-side-ssl-authentication.md). O restante desta seção aborda a configuração de destinos de controle de utilização.
Você pode configurar o controle de utilização para as suas APIs para ajudar a protegê-las da sobrecarga de numerosas solicitações. Os controles de utilização são aplicados de acordo com o melhor esforço e devem ser considerados alvos, e não limites máximos garantidos de solicitações.
O API Gateway controla a utilização das solicitações para a sua API usando o algoritmo do bucket de token, em que um token equivale a uma solicitação. Especificamente, o API Gateway analisa a taxa e uma intermitência de envios de solicitações de todas as APIs na sua conta, por região. No algoritmo do bucket de token, uma intermitência pode permitir a saturação predefinida desses limites, mas há alguns casos em que outros fatores também podem exceder tais limites.
Quando os envios de solicitações excederem a taxa de solicitação de estado fixo e os limites de intermitência, o API Gateway iniciará o controle de utilização de solicitações. Neste momento, pode ser que os clientes recebam respostas de erro `429 Too Many Requests`. Ao capturar essas exceções, o cliente poderá reenviar as solicitações com falha de uma forma que restrinja as taxas.
Como desenvolvedor de APIs, você pode definir os limites alvo para estágios ou rotas de APIs particulares para melhorar a performance geral em todas as APIs na sua conta.
## Controle de utilização no nível da conta por região
Por padrão, o API Gateway controla a utilização das solicitações de estado fixo por segundo (RPS) em todas as APIs de uma conta da AWS, por região. Ele também limita a intermitência (ou seja, o tamanho máximo do bucket) em todas as APIs de uma conta da AWS, por região. No API Gateway, o limite de intermitência representa o número máximo alvo de envios simultâneos de solicitações que ele fará antes de retornar respostas de erro `429 Too Many Requests`. Para obter mais informações sobre cotas de controle de utilização, consulte [Cotas do Amazon API Gateway](limits.md).
Os limites por conta são aplicados a todas as APIs em uma conta em uma região especificada. O limite de taxas no nível da conta pode ser aumentado por meio de uma solicitação; é possível obter limites mais altos com APIs com tempos limite mais curtos e cargas úteis menores. Para solicitar um aumento nos limites de controle de utilização no nível da conta por região, entre em contato com a [Central de Suporte da AWS](https://console.aws.amazon.com/support/home#/). Para obter mais informações, consulte [Cotas do Amazon API Gateway](limits.md). Observe que tais limites não podem ser superiores aos limites de controle de utilização da AWS.
## Limitação em nível de rota
Você pode definir a limitação no nível da rota para substituir as limitações de solicitação no nível da conta para um estágio específico ou para rotas individuais em sua API. Os limites de controle de utilização da rota padrão não podem exceder os limites de taxa em nível de conta.
É possível configurar o controle de utilização de nível de rota usando a AWS CLI. O comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) indicado abaixo configura o controle de utilização personalizado para o estágio especificado e a rota de uma API:
```
aws apigatewayv2 update-stage \
--api-id a1b2c3d4 \
--stage-name dev \
--route-settings '{"messages":{"ThrottlingBurstLimit":100,"ThrottlingRateLimit":2000}}'
```
# Monitorar as APIs de WebSocket no API Gateway
É possível usar métricas do CloudWatch e o CloudWatch Logs para monitorar APIs WebSocket. Combinando logs e métricas, você pode registrar erros em log e monitorar o desempenho da API.
**nota**
O API Gateway pode não gerar logs e métricas nos seguintes casos:
Erros 413 de entidade de solicitação muito grande
Erros 429 de muitas solicitações excessivos
Erros da série 400 de solicitações enviadas a um domínio personalizado que não tem mapeamento de API
Erros da série 500 causados por falhas internas
**Topics**
+ [Monitorar a execução de APIs de WebSocket com métricas do CloudWatch](apigateway-websocket-api-logging.md)
+ [Configurar o registro em log para APIs de WebSocket no API Gateway](websocket-api-logging.md)
# Monitorar a execução de APIs de WebSocket com métricas do CloudWatch
É possível usar as métricas do [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) para monitorar as APIs WebSocket. A configuração é semelhante à usada para APIs REST. Para obter mais informações, consulte [Monitorar a execução da API REST com métricas do Amazon CloudWatch](monitoring-cloudwatch.md).
As métricas a seguir são compatíveis com APIs WebSocket:
| Métrica | Descrição |
| --- | --- |
| ConnectCount | O número de mensagens enviadas à integração de rotas \$1connect. |
| MessageCount | O número de mensagens enviadas à API WebSocket do cliente e vice-versa. |
| IntegrationError | O número de solicitações que retornam uma resposta 4XX/5XX da integração. |
| ClientError | O número de solicitações que têm uma resposta 4XX retornada pelo API Gateway antes de a integração ser invocada. |
| ExecutionError | Erros que ocorreram durante a chamada da integração. |
| IntegrationLatency | A diferença de hora entre o envio da solicitação para integração por parte do API Gateway e o recebimento da resposta da integração por parte do API Gateway. Supressão para retornos de chamada e integrações simuladas. |
É possível usar as dimensões na tabela a seguir para filtrar métricas do API Gateway.
| Dimensão | Descrição |
| --- | --- |
| ApiId | Filtra as métricas do API Gateway para uma API com o ID de API especificado. |
| ID da API, estágio | Filtra métricas do API Gateway para um estágio de API com o ID da API especificada e o ID do estágio. |
| ApiId, método, recurso, estágio | Filtra métricas do API Gateway para um método de API com o ID da API especificada, ID do estágio, caminho do recurso e ID da rota. O API Gateway não enviará essas métricas a menos que você tenha habilitado explicitamente métricas detalhadas do CloudWatch. Isso pode ser feito ao chamar a ação [UpdateStage](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-stages-stagename.html) da API REST V2 do API Gateway para atualizar a propriedade `detailedMetricsEnabled` como `true`. Como alternativa, você pode chamar o comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) da AWS CLI para atualizar a propriedade `DetailedMetricsEnabled` para `true`. Permitir essas métricas incorrerá em cobranças adicionais na conta. Para obter informações de definição de preço, consulte [Definição de preço do Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing/). |
# Configurar o registro em log para APIs de WebSocket no API Gateway
É possível habilitar o registro em log para gravar logs no CloudWatch Logs. Há dois tipos de registro de API em logs no CloudWatch: registro de execução e de acesso. No registro de execução, o API Gateway gerencia o CloudWatch Logs. O processo inclui a criação de grupos de log e fluxos de log, além de relatórios aos fluxos de log sobre solicitações e respostas de qualquer autor da chamada.
Para melhorar seu procedimento de segurança, recomendamos que você use o registro em log de execução no nível `ERROR` ou `INFO`. Você pode precisar fazer isso para cumprir vários requisitos de conformidade. Para ter mais informações, consulte [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) no *Guia do usuário do AWS Security Hub*.
No registro de acessos, você, assim como um desenvolvedor de API, registra quem acessou sua API e como o autor da chamada acessou a API. Você pode criar seu próprio grupo de logs ou escolher um existente que possa ser gerenciado pelo API Gateway. Para especificar os detalhes de acesso, selecione variáveis `$context` (expressas em um formato de sua escolha) e selecione um grupo de logs como o destino.
Para obter instruções sobre como configurar o registro em log do CloudWatch, consulte [Configurar o registro em log da API do CloudWatch usando o console do API Gateway](set-up-logging.md#set-up-access-logging-using-console).
Quando você especifica o **Formato de registro**, é possível escolher em quais variáveis de contexto se registrar. As seguintes variáveis são compatíveis.
| Parâmetro | Descrição |
| --- | --- |
| \$1context.apiId | O identificador que o API Gateway atribui à sua API. |
| \$1context.authorize.error | A mensagem de erro de autorização. |
| \$1context.authorize.latency | A latência de autorização em ms. |
| \$1context.authorize.status | O código de status retornado de uma tentativa de autorização. |
| \$1context.authorizer.error | A mensagem de erro retornada de um autorizador. |
| \$1context.authorizer.integrationLatency | A latência do autorizador do Lambda em ms. |
| \$1context.authorizer.integrationStatus | O código de status retornado de um autorizador do Lambda. |
| \$1context.authorizer.latency | A latência de autorizador em ms. |
| \$1context.authorizer.requestId | O ID da solicitação do endpoint da AWS. |
| \$1context.authorizer.status | O código de status retornado de um autorizador. |
| \$1context.authorizer.principalId | A identificação do usuário principal associada ao token enviado pelo cliente e retornado de uma função do Lambda do autorizador do Lambda do API Gateway. (Anteriormente, um autorizador do Lambda era conhecido como um autorizador personalizado.) |
| \$1context.authorizer.property | O valor transformado em string do par de chave/valor especificado do mapa `context` retornado de uma função de autorizador do Lambda do API Gateway. Por exemplo, se o autorizador retornar o seguinte mapa `context`: "context" : {
"key": "value",
"numKey": 1,
"boolKey": true
} chamar `$context.authorizer.key` retornará a string `"value"`, chamar `$context.authorizer.numKey` retornará a string `"1"` e chamar `$context.authorizer.boolKey` retornará a string `"true"`. |
| \$1context.authenticate.error | A mensagem de erro retornada de uma tentativa de autenticação. |
| \$1context.authenticate.latency | A latência de autenticação em ms. |
| \$1context.authenticate.status | O código de status retornado de uma tentativa de autenticação. |
| \$1context.connectedAt | O tempo de conexão formatado em [Epoch](https://en.wikipedia.org/wiki/Unix_time). |
| \$1context.connectionId | Um ID exclusivo para a conexão que pode ser utilizado para fazer uma chamada ao cliente. |
| \$1context.domainName | Um nome de domínio para a API WebSocket. Pode ser usado para fazer um retorno de chamada ao cliente (em vez de um valor codificado). |
| \$1context.error.message | Uma string que contém uma mensagem de erro do API Gateway. |
| \$1context.error.messageString | O valor citado de \$1context.error.message, ou seja, "\$1context.error.message". |
| \$1context.error.responseType | O tipo de resposta de erro. |
| \$1context.error.validationErrorString | Uma string que contém uma mensagem de erro de validação detalhada. |
| \$1context.eventType | O tipo de evento: `CONNECT`, `MESSAGE` ou `DISCONNECT`. |
| \$1context.extendedRequestId | Equivale a \$1context.requestId. |
| \$1context.identity.accountId | O ID da conta da AWS associado à solicitação. |
| \$1context.identity.apiKey | A chave do proprietário da API associada à solicitação de API habilitada por chave. |
| \$1context.identity.apiKeyId | O ID da chave da API associada à solicitação de API habilitada por chave |
| \$1context.identity.caller | O identificador da entidade do autor da chamada que assinou a solicitação. Compatível com rotas que usam a autorização do IAM. |
| \$1context.identity.cognitoAuthenticationProvider | Uma lista separada por vírgulas de todos os provedores de autenticação do Amazon Cognito usados pelo autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Por exemplo, para uma identidade de um grupo de usuários do Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Consulte informações sobre os provedores de autenticação do Amazon Cognito disponível em [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) no *Guia do desenvolvedor do Amazon Cognito*. |
| \$1context.identity.cognitoAuthenticationType | O tipo de autenticação do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Os valores possíveis incluem `authenticated` para identidades autenticadas e `unauthenticated` para identidades não autenticadas. |
| \$1context.identity.cognitoIdentityId | O ID de identidade do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. |
| \$1context.identity.cognitoIdentityPoolId | O ID do grupo de identidades do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. |
| \$1context.identity.principalOrgId | O [ID da organização da AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). Compatível com rotas que usam a autorização do IAM. |
| \$1context.identity.sourceIp | O endereço IP de origem da conexão TCP que está fazendo a solicitação para ao API Gateway. |
| \$1context.identity.user | O identificador da entidade do usuário que será autorizado contra o acesso a recursos. Compatível com rotas que usam a autorização do IAM. |
| \$1context.identity.userAgent | O agente de usuário do autor da chamada da API. |
| \$1context.identity.userArn | O Nome do Recurso Amazon (ARN) do usuário efetivo identificado após a autenticação. |
| \$1context.integration.error | A mensagem de erro retornada de uma integração. |
| \$1context.integration.integrationStatus | Para a integração de proxy do Lambda, o código de status retornado pelo AWS Lambda, e não pelo código de função do Lambda de backend. |
| \$1context.integration.latency | A latência de integração em ms. Equivale a \$1context.integrationLatency. |
| \$1context.integration.requestId | O ID da solicitação do endpoint da AWS. Equivale a \$1context.awsEndpointRequestId. |
| \$1context.integration.status | O código de status retornado de uma integração. Para integrações de proxy do Lambda, esse é o código de status que seu código de função do Lambda retorna. Equivale a \$1context.integrationStatus. |
| \$1context.integrationLatency | A latência de integração em ms, disponível somente para registro de log de acesso. |
| \$1context.messageId | Um ID exclusivo do servidor para uma mensagem. Disponível apenas quando o `$context.eventType` é `MESSAGE`. |
| \$1context.requestId | Igual a `$context.extendedRequestId`. |
| \$1context.requestTime | O horário da solicitação [CLF](https://httpd.apache.org/docs/current/logs.html#common) formatado (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). |
| \$1context.requestTimeEpoch | O tempo de solicitação formatado em [Epoch](https://en.wikipedia.org/wiki/Unix_time), em milissegundos. |
| \$1context.routeKey | A chave de roteamento selecionada. |
| \$1context.stage | O estágio de implantação da chamada da API (por exemplo, beta ou prod). |
| \$1context.status | O status da resposta. |
| \$1context.waf.error | A mensagem de erro retornada pelo AWS WAF. |
| \$1context.waf.latency | A latência do AWS WAF em ms. |
| \$1context.waf.status | O código de status retornado pelo AWS WAF. |
Exemplos de alguns formatos de log de acesso comumente usados são mostrados no console do API Gateway e estão listados a seguir.
+ `CLF` ([Formato de log comum](https://httpd.apache.org/docs/current/logs.html#common)):
```
$context.identity.sourceIp $context.identity.caller \
$context.identity.user [$context.requestTime] "$context.eventType $context.routeKey $context.connectionId" \
$context.status $context.requestId
```
Os caracteres de continuação (`\`) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (`\n`) no final do formato de log para incluir uma nova linha no final de cada entrada de log.
+ `JSON`:
```
{
"requestId":"$context.requestId", \
"ip": "$context.identity.sourceIp", \
"caller":"$context.identity.caller", \
"user":"$context.identity.user", \
"requestTime":"$context.requestTime", \
"eventType":"$context.eventType", \
"routeKey":"$context.routeKey", \
"status":"$context.status", \
"connectionId":"$context.connectionId"
}
```
Os caracteres de continuação (`\`) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (`\n`) no final do formato de log para incluir uma nova linha no final de cada entrada de log.
+ `XML`:
```
\
$context.identity.sourceIp \
$context.identity.caller \
$context.identity.user \
$context.requestTime \
$context.eventType \
$context.routeKey \
$context.status \
$context.connectionId \
```
Os caracteres de continuação (`\`) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (`\n`) no final do formato de log para incluir uma nova linha no final de cada entrada de log.
+ `CSV` (valores separados por vírgula):
```
$context.identity.sourceIp,$context.identity.caller, \
$context.identity.user,$context.requestTime,$context.eventType, \
$context.routeKey,$context.connectionId,$context.status, \
$context.requestId
```
Os caracteres de continuação (`\`) têm o objetivo de ajuda visual. O formato do log deve ser uma única linha. É possível adicionar um caractere de nova linha (`\n`) no final do formato de log para incluir uma nova linha no final de cada entrada de log.