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