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

使用 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]"。因此,最好将表达式求解为值而不是数组或对象。

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

表达式 求解结果 Description
$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 或 AWS CLI 创建它们。如果需要,您可以创建自定义路由。有关更多信息,请参阅 关于 API Gateway 中的 WebSocket API

注意

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

使用 API Gateway 控制台创建路由

使用 API Gateway 控制台创建路由

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

  2. 要创建其中一个预定义路由($connect$disconnect$default),请选择其名称。

  3. 如果需要,您可以创建自定义路由。为此,请在 New Route Key (新路由键) 文本框中输入路由键名称,然后选中复选标记图标。

    注意

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

使用 AWS CLI 创建路由

要使用 AWS 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,以使用标准 AWS IAM 策略来控制对 API 的访问。

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

      注意

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

    重要

    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,然后选择 Routes (路由)

  2. Routes (路由) 下面,选择 $connect.

  3. 在路由概述窗格中选择 Route Request (路由请求)

  4. Access Settings (访问设置) 下面,配置路由设置,如下所示:

    1. 要编辑 Authorization (授权) 设置,请选择铅笔图标。从下拉菜单中选择所需的设置,然后选中复选标记图标以保存新设置。

    2. 要编辑 API Key Required (需要 API 键) 设置,请选择铅笔图标。从下拉菜单中选择 truefalse,然后选中复选标记图标以保存新设置。