管理连接的用户和客户端应用程序:$connect 和 $disconnect 路由 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

管理连接的用户和客户端应用程序:$connect$disconnect 路由

$connect 路由

客户端应用程序通过发送 WebSocket 升级请求连接到 WebSocket API。如果请求成功,则在建立连接时会执行 $connect 路由。

由于 WebSocket 连接是有状态连接,因此您只能在 $connect 路由上配置授权。AuthN/AuthZ 仅在连接时执行。

在执行完与 $connect 路由关联的集成之前,升级请求处于待处理状态,将不会建立实际连接。如果 $connect 请求失败(例如,由于 AuthN/AuthZ 失败或集成失败),则不会建立连接。

注意

如果授权在 $connect 上失败,则不会建立连接,客户端将收到 401403 响应。

$connect 设置集成是可选的。在以下情况下,您应该考虑设置 $connect 集成:

  • 您希望使客户端能够使用 Sec-WebSocket-Protocol 字段指定子协议。有关示例代码,请参阅 设置需要 WebSocket 子协议的 $connect 路由

  • 您希望在客户端连接时收到通知。

  • 您希望限制连接或控制谁会连接。

  • 您希望后端使用回调 URL 将消息发送回客户端。

  • 您希望将每个连接 ID 和其他信息存储到数据库中(例如,Amazon DynamoDB)。

$connect 路由传递连接信息

您可以使用代理和非代理集成将信息从 $connect 路由传递到数据库或其他 Amazon Web Service。

使用代理集成传递连接信息

您可以通过事件中的 Lambda 代理集成访问连接信息。使用其他 Amazon Web Service 或 Amazon Lambda 函数发布到连接。

以下 Lambda 函数显示如何使用 requestContext 对象记录连接 ID、域名、阶段名和查询字符串。

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}

使用非代理集成传递连接信息

  • 您可以使用非代理集成访问连接信息。设置集成请求并提供 WebSocket API 请求模板。以下 Velocity 模板语言(VTL)映射模板提供了集成请求。此请求将以下详细信息发送给非代理集成:

    • 连接 ID

    • 域名

    • 阶段名称

    • 路径

    • 标头

    • 查询字符串

    此请求将连接 ID、域名、阶段名、路径、标头和查询字符串发送到非代理集成。

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

    有关设置数据转换的更多信息,请参阅针对 API Gateway 中的 WebSocket API 的数据转换

    要完成集成请求,请为集成响应设置 StatusCode: 200。要了解有关设置集成响应的更多信息,请参阅使用 API Gateway 控制台设置集成响应

$disconnect 路由

在连接关闭后,会执行 $disconnect 路由。

连接可以由服务器或客户端关闭。由于连接在执行时已经关闭,因此 $disconnect 是最适合的事件。API Gateway 将尽最大努力将 $disconnect 事件传送到您的集成,但它不能保证交付。

后端可以使用 @connections API 启动断开连接。有关更多信息,请参阅 在后端服务中使用 @connections 命令