Gerenciar usuários conectados e aplicações clientes: rotas $connect e $disconnect

A seção a seguir descreve como usar as rotas $connect e $disconnect para sua API de WebSocket.

A rota $connect

Os aplicativos do cliente se conectam à sua API WebSocket ao enviar uma solicitação de atualização do WebSocket. Se a solicitação for bem-sucedida, a rota $connect é executada enquanto a conexão estiver sendo criada.

Como a conexão do WebSocket é uma conexão stateful, você pode configurar a autorização somente na rota $connect. AuthN/AuthZ será realizada somente pelo tempo de conexão.

Enquanto a execução de integração associada à rota $connect é concluída, a solicitação de atualização está pendente e a conexão real não será estabelecida. Se a solicitação $connect falhar (por exemplo, devido a uma falha AuthN/AuthZ ou falha de integração), a conexão não será estabelecida.

nota

Se a autorização falhar em $connect, a conexão não será estabelecida, e o cliente receberá uma resposta 401 ou 403.

A configuração de uma integração para $connect é opcional. Você deve considerar configurar uma integração $connect se:

• Deseja permitir que os clientes especifiquem subprotocolos usando o campo Sec-WebSocket-Protocol. Para ver um código demonstrativo, consulte Configurar uma rota $connect que requer um subprotocolo de WebSocket.

• Deseja receber notificação quando os clientes se conectarem.

• Deseja limitar as conexões ou controlar quem se conecta.

• Deseja que o backend envie mensagens de volta aos clientes usando uma URL de retorno de chamada.

• Deseja armazenar cada ID de conexão e outras informações em um banco de dados (por exemplo, Amazon DynamoDB).

Transmitir informações de conexão da rota $connect

É possível usar integrações de proxy e não proxy para transmitir informações da rota $connect para um banco de dados ou outro AWS service (Serviço da AWS).

Como transmitir informações de conexão usando uma integração de proxy

É possível acessar as informações de conexão por uma integração de proxy do Lambda no evento. Use outro AWS service (Serviço da AWS) ou função do AWS Lambda para publicar na conexão.

A função do Lambda a seguir mostra como usar o objeto requestContext para registrar o ID da conexão, o nome do domínio, o nome do estágio e as strings de consulta.

Node.js

 export const handler = async(event, context) => {
    const connectId = event["requestContext"]["connectionId"]
    const domainName = event["requestContext"]["domainName"]
    const stageName = event["requestContext"]["stage"]
    const qs = event['queryStringParameters']
    console.log('Connection ID: ', connectId, 'Domain Name: ', domainName, 'Stage Name: ', stageName, 'Query Strings: ', qs )
    return {"statusCode" : 200}
};

Python

import json
import logging
logger = logging.getLogger()
logger.setLevel("INFO")


def lambda_handler(event, context):
    connectId = event["requestContext"]["connectionId"]
    domainName = event["requestContext"]["domainName"]
    stageName = event["requestContext"]["stage"]
    qs = event['queryStringParameters']
    connectionInfo = {
        'Connection ID': connectId,
        'Domain Name': domainName,
        'Stage Name': stageName,
        'Query Strings': qs}
    logging.info(connectionInfo)
    return {"statusCode": 200}

Como transmitir informações de conexão usando uma integração que não seja de proxy

• É possível acessar as informações de conexão com uma integração não proxy. Configure a solicitação de integração e forneça um modelo de solicitação da API de WebSocket. O modelo de mapeamento Velocity Template Language (VTL) a seguir fornece uma solicitação de integração. Essa solicitação envia os seguintes detalhes para uma integração sem proxy:

  • ID da conexão

  • Nome de domínio

  • Nome da etapa

  • Path

  • Cabeçalhos

  • Strings de consulta

  Essa solicitação envia o ID da conexão, o nome do domínio, o nome do estágio, os caminhos, os cabeçalhos e as strings de consulta para uma integração sem proxy.

  {
      "connectionId": "$context.connectionId",
      "domain": "$context.domainName",
      "stage": "$context.stage",
      "params": "$input.params()"
  }

  Para obter mais informações sobre a configuração de transformações de dados, consulte Transformações de dados para APIs de WebSocket no API Gateway.

  Para concluir a solicitação de integração, defina StatusCode: 200 para a resposta de integração. Para saber mais sobre como configurar uma resposta de integração, consulte Configurar uma resposta de integração usando o console do API Gateway.

A rota $disconnect

A rota $disconnect é executada depois de a conexão ser encerrada.

A conexão pode ser encerrada pelo servidor ou pelo cliente. Como a conexão já está fechada quando é executado, $disconnect é um evento de melhor esforço. O API Gateway tentará o seu melhor para entregar o evento $disconnect à sua integração, mas não pode garantir a entrega.

O backend pode iniciar a desconexão ao utilizar a API @connections. Para ter mais informações, consulte Usar os comandos @connections em seu serviço de backend.