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, portanto, você deve assiná-las com o Signature Version 4 (SigV4). Para fazer isso, você pode usar a API de Gerenciamento do API Gateway. Para obter mais informações, consulte ApiGatewayManagementApi.

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 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 ou chamando 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,
  };
};

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.