Invocar sua integração de backend com o $default Route e rotas personalizadas no API Gateway
A seção a seguir descreve como invocar sua integração de backend usando a rota $default ou uma rota personalizada para uma API de WebSocket.
Tópicos
Usar rotas para processar mensagens
Nas APIs WebSocket do API Gateway, as mensagens podem ser enviadas do cliente para o serviço de backend e vice-versa. Ao contrário do modelo de solicitação/resposta HTTP, no WebSocket é possível que o backend envie mensagens para o cliente sem que o cliente realize qualquer ação.
As mensagens podem estar no formato JSON ou não. No entanto, somente as mensagens JSON podem ser roteadas para integrações específicas com base no conteúdo da mensagem. As mensagens que não estão no formato JSON não são transmitidas ao backend pela rota $default.
nota
O API Gateway é compatível com cargas de mensagem de até 128 KB com quadros no tamanho máximo de 32 KB. Se uma mensagem exceder 32 KB, é necessário dividi-la em vários quadros, cada qual contendo 32 KB ou menos. Se uma mensagem (ou quadro) maior for recebida, a conexão será encerrada com o código 1009.
Atualmente, cargas binárias não são compatíveis. Se um quadro binário for recebido, a conexão será encerrada com o código 1003. No entanto, é possível converter cargas binárias para texto. Consulte Tipos de mídia binários para APIs de WebSocket no API Gateway.
Com APIs WebSocket no API Gateway, as mensagens JSON podem ser roteadas para executar um serviço de backend determinado com base no conteúdo da mensagem. Quando um cliente envia uma mensagem sobre sua conexão WebSocket, isso resulta em uma solicitação de rota para a API WebSocket. A solicitação será vinculada à rota com a chave da rota correspondente no API Gateway. É possível configurar uma solicitação de rota para uma API WebSocket no console do API Gateway, usando a AWS CLI ou um AWS SDK.
nota
Na AWS CLI e nos AWS SDKs, você pode criar rotas antes ou depois de criar integrações. Atualmente, o console não oferece suporte à reutilização de integrações, portanto, você deve criar a rota primeiro e, em seguida, gerar a integração para essa rota.
É 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 ocorrer uma falha na validação, o API Gateway não atenderá à solicitação sem chamar o backend, enviará uma resposta do gateway "Bad request body" semelhante à seguinte para o cliente e publicará os resultados da validação no CloudWatch Logs:
{"message" : "Bad request body", "connectionId": "{connectionId}", "messageId": "{messageId}"}
Isso reduz as chamadas desnecessárias para o backend e permite que você se concentre em outros requisitos da sua API.
Você também pode definir uma resposta de rota para suas rotas da API, permitindo comunicações bidirecionais. Uma resposta de rota descreve quais dados serão enviados ao cliente após a conclusão da integração de uma rota determinada. Não é necessário definir uma resposta para uma rota se, por exemplo, você deseja que um cliente envie mensagens para o backend sem receber uma resposta (comunicação unidirecional). No entanto, se você não fornecer uma resposta de rota, o API Gateway não enviará nenhuma informação sobre o resultado da sua integração aos clientes.
A rota $default
Cada API WebSocket do API Gateway pode ter uma rota $default. Esse é um valor de roteamento especial que pode ser usado das seguintes formas:
-
Você pode usá-lo em conjunto com chaves de roteamento definidas, para especificar uma rota de "fallback" (por exemplo, uma integração simulada genérica que retorna determinada mensagem de erro) para mensagens recebidas que não corresponderem a nenhuma das chaves de roteamento definidas.
-
Você pode usá-lo sem qualquer chave de roteamento definida para especificar um modelo de proxy que delega o roteamento a um componente de backend.
-
Você pode usá-lo para especificar uma rota para cargas que não estão no formato JSON.
Rotas personalizadas
Se deseja invocar uma integração específica com base no conteúdo da mensagem, você pode fazê-lo ao criar uma rota personalizada.
A rota personalizada utiliza uma chave de roteamento e a integração que você especificar. Quando uma mensagem de entrada contém uma propriedade JSON, e essa propriedade é avaliada como um valor que corresponde ao valor da chave de roteamento, o API Gateway invoca a integração. (Para obter mais informações, consulte Visão geral das APIs de WebSocket no API Gateway.)
Por exemplo, suponha que você queira criar um aplicativo de salas de bate-papo. Você pode começar com a criação de uma API WebSocket cuja expressão de seleção de rotas é $request.body.action. Em seguida, você pode definir duas rotas: joinroom e sendmessage. Um aplicativo do cliente pode invocar a rota joinroom ao enviar uma mensagem como a seguinte:
{"action":"joinroom","roomname":"developers"}
Também pode invocar a rota sendmessage ao enviar uma mensagem como a seguinte:
{"action":"sendmessage","message":"Hello everyone"}
Usar integrações da API WebSocket do API Gateway para se conectar à sua lógica de negócios
Após a configuração de uma rota para uma API WebSocket do API Gateway, é necessário especificar a integração a ser utilizada. Assim como ocorre com uma rota, que pode apresentar uma solicitação de rota e uma resposta de rota, uma integração pode apresentar uma solicitação de integração e uma resposta de integração. Uma solicitação de integração contém as informações esperadas pelo backend para processar a solicitação recebida de seu cliente. Uma resposta de integração contém os dados que o backend retorna para o API Gateway e que podem ser usados para elaborar uma mensagem a ser enviada ao cliente (se uma resposta de rota for definida).
Para obter mais informações sobre a configuração de integrações, consulte Integrações para a API de WebSocket no API Gateway.
Diferenças importantes entre APIs WebSocket e APIs REST
Integrações para APIs do WebSocket são semelhantes às integrações para APIs REST, exceto com relação às seguintes diferenças:
-
Atualmente, no console do API Gateway, é necessário criar uma rota primeiro e, depois, criar uma integração como o destino da rota. No entanto, na API e CLI, você pode criar rotas e integrações de maneira independente, em qualquer ordem.
-
Você pode usar uma única integração para várias rotas. Por exemplo, se você tiver um conjunto de ações que tenham uma relação estreita entre si, é recomendável que todas essas rotas sejam direcionadas a uma única função do Lambda. Em vez de definir os detalhes da integração várias vezes, você pode especificá-los uma vez e atribuí-los a cada uma das rotas relacionadas.
nota
Atualmente, o console não oferece suporte à reutilização de integrações, portanto, você deve criar a rota primeiro e, em seguida, gerar a integração para essa rota.
Na AWS CLI e nos AWS SDKs, você pode reutilizar uma integração definindo o destino da rota como um valor de
"integrations/, em que{integration-id}"{integration-id}" -
O API Gateway fornece várias expressões de seleção que podem ser usadas em suas rotas e integrações. Você não precisa depender do tipo de conteúdo para selecionar um modelo de entrada ou mapeamento de saída. Assim como ocorre com expressões de seleção de rotas, você pode definir uma expressão de seleção a ser avaliada pelo API Gateway para escolher o item correto. Todas elas serão recuadas para o modelo
$defaultse um modelo correspondente não for encontrado.-
Nas solicitações de integração, a expressão de seleção do modelo é compatível com
$request.body.e valores estáticos.<json_path_expression> -
Nas respostas de integração, a expressão de seleção do modelo é compatível com
$request.body.,<json_path_expression>$integration.response.statuscode,$integration.response.header.e valores estáticos.<headerName>
-
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.
