在 WebSocket API 中使用路由 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

在 WebSocket API 中使用路由

在 WebSocket API 中,传入的 JSON 消息将根据您配置的路由定向到后端集成。(非 JSON 消息将定向到您配置的 $default 路由。)

路由包含一个路由键,这是在评估路由选择表达式时预期的值。routeSelectionExpression 是在 API 级别定义的属性。它指定了预期存在于消息负载中的 JSON 属性。有关路由选择表达式的更多信息,请参阅路由选择表达式

例如,如果您的 JSON 消息包含一个 action 属性,并且您想要根据此属性执行不同操作,则您的路由选择表达式可能是 ${request.body.action}。您的路由表将通过将 action 属性的值与您在表中定义的自定义路由键值相匹配来指定要执行的操作。

可以使用三个预定义路由:$connect$disconnect$default。此外,您还可以创建自定义路由。

  • API Gateway 会在客户端和 WebSocket API 之间的持久连接处于启动状态时调用 $connect 路由。

  • API Gateway 会在客户端或服务器与 API 断开连接时调用 $disconnect 路由。

  • 如果找到匹配的路由,则 API Gateway 会在针对消息评估路由选择表达式之后调用自定义路由;匹配项确定调用哪个集成。

  • 如果无法针对消息评估路径选择表达式或未找到匹配的路由,则 API Gateway 会调用 $default 路由。

路由选择表达式

当服务正在为传入消息选择要遵循的路由时,将会对路由选择表达式进行求解。该服务使用其 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 将返回错误。

在 API Gateway 中为 WebSocket API 设置路由

首次创建新的 WebSocket API 时,有三个预定义的路由:$connect$disconnect$default。您可以使用控制台、API 或 Amazon CLI 创建它们。如果需要,您可以创建自定义路由。有关更多信息,请参阅 关于 WebSocket API Gateway 中的 API

注意

在 CLI 中,您可以在创建集成之前或之后创建路由,并且可以为多个路由重用相同的集成。

使用 API Gateway 控制台创建路由

使用 API Gateway 控制台创建路由
  1. 登录到 API Gateway 控制台,选择 API,然后选择路由

  2. 选择创建路由

  3. 路径密钥中,输入路径密钥名称。您可以创建预定义路由($connect$disconnect$default),也可以创建自定义路由。

    注意

    当您创建自定义路由时,请勿在路由键名称中使用 $ 前缀。此前缀是专为预定义路由预留的。

  4. 选择并配置路径的集成类型。有关更多信息,请参阅使用 WebSocket API Gateway 控制台设置 API 集成请求

使用 Amazon CLI 创建路由

要使用 Amazon CLI 创建路由,请调用 create-route,如以下示例所示:

aws apigatewayv2 --region us-east-1 create-route --api-id aabbccddee --route-key $default

输出示例:

{ "ApiKeyRequired": false, "AuthorizationType": "NONE", "RouteKey": "$default", "RouteId": "1122334" }

$connect 指定路由请求设置

当您为 API 设置 $connect 路由时,可以使用以下可选设置为 API 启用授权。有关更多信息,请参阅 $connect 路由

  • Authorization (授权):如果不需要授权,您可以指定 NONE。否则,您可以指定:

    • AWS_IAM,以使用标准Amazon IAM 策略来控制对 API 的访问。

    • CUSTOM,以通过指定先前创建的 Lambda 授权方函数来实现 API 的授权。授权方可以驻留在您自己的Amazon账户或其他Amazon账户中。有关 Lambda 授权方的更多信息,请参阅 使用 API Gateway Lambda 授权方

      注意

      在 API Gateway 控制台中,只有在您设置了如CUSTOM中所述的授权方函数后,使用 API Gateway 控制台配置 Lambda 授权方 设置才可见。

    重要

    Authorization (授权) 设置将会应用于整个 API,而不仅仅是 $connect 路由。$connect 路由保护其他路由,因为它在每个连接上都会被调用。

  • API Key Required (需要 API 键):您可以要求(可选)API 的 $connect 路由有 API 键。您可以将 API 键与使用计划一起使用来控制和跟踪对 API 的访问。有关更多信息,请参阅 创建和使用带 API 密钥的使用计划

使用 API Gateway 控制台设置 $connect 路由请求

要使用 API Gateway 控制台为 WebSocket API 设置 $connect 路由请求,请执行以下操作:

  1. 登录到 API Gateway 控制台,选择 API,然后选择路由

  2. 路由下选择 $connect,或按照使用 API Gateway 控制台创建路由创建 $connect 路由。

  3. 路由请求设置部分中,选择编辑

  4. 对于授权,选择一种授权类型。

  5. 要为 $connect 路由要求 API,请选择需要 API 密钥

  6. 选择保存更改