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

API Gateway 中的 WebSocket 选择表达式

API Gateway 使用选择表达式作为一种评估请求和响应上下文并生成键的方法。然后,该键用于从通常由您,即 API 开发人员提供的一组可能值中进行选择。确切的受支持变量集将因特定表达式而异。下文更为详细地描述了每个表达式。

对于所有表达式,该语言遵循相同的规则集:

  • 变量以 "$" 为前缀。

  • 大括号可用于明确定义变量边界,例如,"${request.body.version}-beta"

  • 支持多个变量,但评估仅发生一次(无递归评估)。

  • 可以使用 "\" 对美元符号 ($) 进行转义。这在定义映射到保留的 $default 键(例如 "\$default")的表达式时非常有用。

  • 在某些情况下,需要模式格式。在这种情况下,表达式应该用正斜杠 ("/") 包装起来,例如,"/2\d\d/",以便匹配 2XX 状态代码。

路由选择表达式

当服务正在为传入消息选择要遵循的路由时,将会对路由选择表达式进行求解。该服务将使用其 routeKey 与求解值完全匹配的路由。如果没有匹配项,并且存在具有 $default 路由键的路由,则将选择该路由。如果没有路由与求解值匹配,并且没有 $default 路由,则该服务将返回错误。对于基于 WebSocket 的 API,表达式的格式应为 $request.body.{path_to_body_element}

例如,假设您要发送以下 JSON 消息:

{ "service" : "chat", "action" : "join", "data" : { "room" : "room1234" } }

您可能希望根据 action 属性选择 API 的行为。在这种情况下,您可以定义以下路由选择表达式:

$request.body.action

在此示例中,request.body 是指您的消息的 JSON 负载,.actionJSONPath 表达式。您可以在 request.body 之后使用任何 JSON 路径表达式,但请记住,结果将会字符串化。例如,如果您的 JSONPath 表达式返回包含两个元素的数组,那么它将显示为字符串 "[item1, item2]"。因此,最好将表达式求解为值而不是数组或对象。

您可以仅使用一个静态值,也可以使用多个变量。下表显示了针对上述负载的示例及其求解结果。

表达式 求解结果 描述
$request.body.action join 未包装的变量
${request.body.action} join 包装的变量
${request.body.service}/${request.body.action} chat/join 具有静态值的多个变量
${request.body.action}-${request.body.invalidPath} join 如果找不到 JSONPath,则变量将解析为 ""。
action action 静态值
\$default $default 静态值

求解结果将用于查找路由。如果存在具有匹配路由键的路由,则将选择该路由来处理消息。如果找不到匹配的路由,则 API Gateway 将尝试查找 $default 路由(如果可用)。如果未定义 $default 路由,则 API Gateway 将返回错误。

模型选择表达式

当您为 WebSocket API 定义路由时,可以指定(可选)模型选择表达式。将会求解此表达式以选择在收到请求时用于正文验证的模型。表达式的求值结果为路由的 requestmodels 中的条目之一。

模型采用 JSON 架构表示,描述了请求正文的数据结构。此选择表达式的性质能让您为特定路径在运行时动态选择要用于对照进行验证的模型。有关如何创建模型的信息,请参阅为请求和响应映射创建模型和映射模板

模板选择表达式

当您为 WebSocket API 定义集成请求集成响应时,您可以指定(可选)模板选择表达式。将会求解此表达式以确定用于将请求正文转换为集成请求正文(通过输入模板)或将响应正文转换为路由响应正文(通过输出模板)的输入或输出模板(如果有)。

Integration.TemplateSelectionExpression 支持 ${request.body.jsonPath} 和静态值。

IntegratiionResponse.TemplateSelectionExpression 支持 ${request.body.jsonPath}${integration.response.statuscode}${integration.response.header.headerName}${integration.response.multivalueheader.headerName} 和静态值。

路由响应选择表达式

路由响应用于对从后端到客户端的响应建模。对于 WebSocket API,路由响应是可选的。定义后,它向 API Gateway 发出信号,表示它应该在收到 WebSocket 消息时向客户端返回响应。

路由响应选择表达式的求解会产生路由响应键。最终,此密钥将用于从与 API 相关联的一个 RouteResponses 中进行选择。但是,目前仅支持 $default 键。

API 键选择表达式

如果服务确定仅当客户端提供有效的 API 键时给定的请求才应继续,则会求解此表达式。

目前,仅支持的两个值是 $request.header.x-api-key$context.authorizer.usageIdentifierKey

API 映射选择表达式

将会求解估此表达式以确定在使用自定义域发出请求时选择哪个 API 阶段。

目前,唯一支持的值是 $request.basepath

集成响应选择表达式

当您为 WebSocket API 设置集成响应时,您可以指定(可选)集成响应选择表达式。此表达式确定在集成返回时应选择什么 IntegrationResponse。此表达式的值当前受 API Gateway 限制,定义如下。认识到此表达式只与非代理集成相关;代理集成无需建模或修改便会将响应负载传递回调用方。

与上面概述的其他选择表达式不同,此表达式当前支持模式匹配格式。表达式应该用正斜杠包装起来。

目前,该值是固定的,具体取决于 integrationType

  • 对于基于 Lambda 的集成,它是 $integration.response.body.errorMessage

  • 对于 HTTPMOCK 集成,它是 $integration.response.statuscode

  • 对于 HTTP_PROXYAWS_PROXY,不会使用此表达式,因为您请求负载传递给调用方。

WebSocket 选择表达式摘要

下表总结了 WebSocket API 中的选择表达式的用例:

选择表达式 求解为以下对象的键 备注 示例使用案例
Api.RouteSelectionExpression Route.RouteKey 支持 $default 作为包罗万象的路由。 根据客户端请求的上下文路由 WebSocket 消息。
Route.ModelSelectionExpression Route.RequestModels 的键

可选。

如果是为非代理集成提供的,则会发生模型验证。

支持 $default 作为包罗万象的路由。

在同一路径中动态执行请求验证。
Integration.TemplateSelectionExpression Integration.RequestTemplates 的键

可选。

可以为非代理集成提供,用于处理传入的负载。

支持 ${request.body.jsonPath} 和静态值。

支持 $default 作为包罗万象的路由。

根据请求的动态属性处理调用方的请求。
Integration.IntegrationResponseSelectionExpression IntegrationResponse.IntegrationResponseKey

可选。可以为非代理集成提供。

充当错误消息(来自 Lambda)或状态代码(来自 HTTP 集成)的模式匹配。

非代理集成需要 $default 来充当包罗万象的成功响应。

处理来自后端的响应。

选择根据后端的动态响应发生的操作(例如,明显地处理某些错误)。

IntegrationResponse.TemplateSelectionExpression IntegrationResponse.ResponseTemplates 的键 可选。可以为非代理集成提供。

支持 $default。

在某些情况下,响应的动态属性可能决定相同路径和相关集成内的不同变换。

支持 ${request.body.jsonPath}${integration.response.statuscode}${integration.response.header.headerName}${integration.response.multivalueheader.headerName} 和静态值。

支持 $default 作为包罗万象的路由。

Route.RouteResponseSelectionExpression RouteResponse.RouteResponseKey

应提供以对 WebSocket 路由启动双向通信。

目前,此值仅限于 $default

RouteResponse.ModelSelectionExpression RouteResponse.RequestModels 的键 目前不受支持。

本页内容: