Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

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

使用路由处理消息

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

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

注意

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

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

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

注意

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

您可以配置 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 的数据,可用于构造要发送给客户端的消息(如果定义了路由响应)。

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

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

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

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

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

    注意

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

    在 AWS CLI 和 AWS 开发工具包中,您可以通过将路由的目标设置 "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 函数返回的正文将不会返回到客户端。如果希望客户端接收集成响应,则必须定义路由响应以使双向通信成为可能。

处理二进制负载

API Gateway WebSocket API 目前在传入消息负载中不支持二进制帧。如果客户端应用程序发送二进制帧,API Gateway 会拒绝它并断开客户端,而且显示代码 1003。

此行为有一种解决方法。如果客户端发送文本编码二进制数据(例如,Base64)作为文本帧,您可以将集成的 contentHandlingStrategy 属性设置为 CONVERT_TO_BINARY,以将负载从 Base64 编码的字符串转换为二进制。

要在非代理集成中返回二进制负载的路由响应,可以将集成响应的 contentHandlingStrategy 属性设置为 CONVERT_TO_TEXT,以将负载从二进制转换为 Base64 编码字符串。