调用您的后端集成:$default 路由和自定义路由 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

调用您的后端集成:$default 路由和自定义路由

使用路由处理消息

在 API Gateway WebSocket API 中,消息可以从客户端发送到后端服务,反之亦然。与 HTTP 的请求/响应模型不同,在 WebSocket 中,后端可以在客户端不采取任何操作的情况下向客户端发送消息。

消息可以是 JSON 或非 JSON。但是,只有 JSON 消息可以根据消息内容路由到特定的集成。非 JSON 消息通过 $default 路由传递到后端。

注意

API Gateway 支持最大 128 KB 的消息负载,最大帧大小为 32 KB。如果消息超过 32 KB,则必须将其拆分为多个帧,每个 32 KB 或更小。如果接收到更大的消息(或帧),则连接会关闭并显示代码 1009。

目前不支持二进制负载。如果接收到二进制帧,则连接会关闭并显示代码 1003。但是,可以将二进制负载转换为文本。请参阅 为 WebSocket API 使用二进制媒体类型

使用 API Gateway 中的 WebSocket API,可以路由 JSON 消息以根据消息内容执行特定的后端服务。当客户端通过其 WebSocket 连接发送消息时,这会导致对 WebSocket API 的路由请求。请求将与 API Gateway 中具有相应路由键的路由匹配。您可以在 API Gateway 控制台中使用 Amazon CLI 或Amazon开发工具包为 WebSocket API 设置路由请求。

注意

在 Amazon CLI 和 Amazon 开发工具包中,您可以在创建集成之前或之后创建路由。目前,控制台不支持重用集成,因此您必须先创建路由,然后为该路由创建集成。

您可以配置 API Gateway,使其在继续集成请求之前对路由请求执行验证。如果验证失败,API Gateway 会在不调用后端的情况下使请求失败,向客户端发送类似于以下内容的 "Bad request body" 网关响应,并在 CloudWatch Logs 中发布验证结果:

{"message" : "Bad request body", "connectionId": "{connectionId}", "messageId": "{messageId}"}

这样可以减少对后端的不必要调用,并让您专注于 API 的其他要求。

您还可以为 API 的路由定义路由响应,以启用双向通信。路由响应描述了在完成特定路由的集成后将向客户端发送的数据。例如,如果您希望客户端向后端发送消息而不收到响应(单向通信),则无需为路由定义响应。但是,如果您不提供路由响应,API Gateway 将不会向您的客户端发送有关您的集成结果的任何信息。

$default 路由

每个 API Gateway WebSocket API 都可以有一个 $default 路由。这是一个特殊的路由值,可以通过以下方式使用:

  • 您可以将它与已定义的路由键一起使用,来为与任何已定义路由键不匹配的传入消息指定“回退”路由(例如,返回特定错误消息的通用模拟集成)。

  • 您可以在没有任何已定义路由键的情况下使用它,来指定将路由委派给后端组件的代理模型。

  • 您可以使用它为非 JSON 负载指定路由。

自定义路由

如果您希望根据消息内容来调用特定集成,则可以通过创建自定义路由来实现。

自定义路由使用您指定的路由键和集成。当传入消息包含 JSON 属性,并且该属性的计算结果为与路由键值匹配的值时,API Gateway 将会调用集成。(有关更多信息,请参阅 关于 API Gateway 中的 WebSocket API。)

例如,假设您要创建聊天室应用程序。您可以从创建 WebSocket API 开始,其路径选择表达式为 $request.body.action。然后,您可以定义两个路由:joinroomsendmessage。客户端应用程序可以通过发送如下消息来调用 joinroom 路由:

{"action":"joinroom","roomname":"developers"}

而且,它可以通过发送如下消息来调用 sendmessage 路由:

{"action":"sendmessage","message":"Hello everyone"}

使用 API Gateway WebSocket API 集成连接到您的业务逻辑

为 API Gateway WebSocket API 设置路由后,您必须指定您想使用的集成。与路由可以具有路由请求和路由响应一样,集成可以具有集成请求集成响应集成请求包含后端预期的信息,用以处理来自客户端的请求。集成响应 包含后端返回到 API Gateway 的数据,可用于构造要发送给客户端的消息(如果定义了路由响应)。

有关设置集成的更多信息,请参阅设置 WebSocket API 集成

WebSocket API 和 REST API 之间的重要区别

WebSocket API 的集成类似于 REST API 的集成,但有以下区别:

  • 目前,在 API Gateway 控制台中,您必须先创建一个路径,然后创建一个集成作为该路由的目标。但是,在 API 和 CLI 中,您可以按任何顺序独立创建路由和集成。

  • 您可以对多个路由使用单个集成。例如,如果您有一组彼此密切相关的操作,您可能希望所有这些路由都转到单个 Lambda 函数。您可以一次指定集成的详细信息并将其分配给每个相关路由,而不是多次定义它。

    注意

    目前,控制台不支持重用集成,因此您必须先创建路由,然后为该路由创建集成。

    在 Amazon CLI 和 Amazon 开发工具包中,您可以通过将路由的目标设置 "integrations/{integration-id}" 的值来重用集成,其中 {integration-id}" 是要与路由关联的集成的唯一 ID。

  • API Gateway 提供多个选择表达式,您可以在路由和集成中使用它们。您无需依赖内容类型来选择输入模板或输出映射。与路径选择表达式一样,您可以定义要由 API Gateway 评估的选择表达式以选择正确的项。如果找不到匹配的模板,则所有这些都将回退到 $default 模板。

    • 在集成请求中,模板选择表达式支持 $request.body.<json_path_expression> 和静态值。

    • 在集成响应中,模板选择表达式支持 $request.body.<json_path_expression>$integration.response.statuscode$integration.response.header.<headerName>

在 HTTP 协议中,请求和响应是同步发送的,通信基本上是单向的。在 WebSocket 协议中,通信是双向的。响应是异步的,客户端不一定以与发送客户端消息相同的顺序接收响应。此外,后端可以向客户端发送消息。

注意

对于配置为使用 AWS_PROXYLAMBDA_PROXY 集成的路由,通信是单向的,而 API Gateway 不会自动将后端响应传递给路由响应。例如,对于 LAMBDA_PROXY 集成,Lambda 函数返回的正文将不会返回到客户端。如果希望客户端接收集成响应,则必须定义路由响应以使双向通信成为可能。