Configurar respostas de integração da API de WebSocket no API Gateway

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.

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.

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.

2. Selecione sua API de WebSocket e rota.

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

4. 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\d\d/ para receber e transformar erros de solicitação inválida ou inserir $default para receber e transformar todas as respostas que correspondam à expressão de seleção do modelo.

5. Em Expressão de seleção de modelos, insira uma expressão de seleção para avaliar a mensagem de saída.

6. Selecione Criar resposta.

7. Você também pode definir um modelo de mapeamento para configurar as transformações da carga útil da mensagem retornada. Selecione Criar modelo.

8. Insira um nome de chave. Se você estiver selecionando a expressão de seleção de modelo padrão, insira \$default.

9. Em Modelo de resposta, insira o modelo de mapeamento no editor de código.

10. Selecione Criar modelo.

11. Selecione Implantar API para implantar a API.

Use o comando 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.

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

Para configurar uma resposta de integração para uma API de WebSocket usando a AWS CLI, chame o comando create-integration-response. O comando da CLI a seguir mostra um exemplo de criação de uma resposta de integração $default:

aws apigatewayv2 create-integration-response \
    --api-id vaz7da96z6 \
    --integration-id a1b2c3 \
    --integration-response-key '$default'