# 在 API Gateway 中调用与 `$default` 路由和自定义路由的后端集成
<a name="apigateway-websocket-api-routes-integrations"></a>

以下部分介绍如何使用 WebSocket API 的 `$default` 路由或自定义路由来调用后端集成。

**Topics**
+ [使用路由处理消息](#apigateway-websocket-api-overview-routes)
+ [`$default` 路由](#apigateway-websocket-api-routes-about-default)
+ [自定义路由](#apigateway-websocket-api-routes-about-custom)
+ [使用 API Gateway WebSocket API 集成连接到您的业务逻辑](#apigateway-websocket-api-overview-integrations)
+ [WebSocket API 和 REST API 之间的重要区别](#apigateway-websocket-api-overview-integrations-differences)

## 使用路由处理消息
<a name="apigateway-websocket-api-overview-routes"></a>

在 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 的二进制媒体类型](websocket-api-develop-binary-media-types.md)。

使用 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` 路由
<a name="apigateway-websocket-api-routes-about-default"></a>

每个 API Gateway WebSocket API 都可以有一个 `$default` 路由。这是一个特殊的路由值，可以通过以下方式使用：
+ 您可以将它与已定义的路由键一起使用，来为与任何已定义路由键不匹配的传入消息指定“回退”路由（例如，返回特定错误消息的通用模拟集成）。
+ 您可以在没有任何已定义路由键的情况下使用它，来指定将路由委派给后端组件的代理模型。
+ 您可以使用它为非 JSON 负载指定路由。

## 自定义路由
<a name="apigateway-websocket-api-routes-about-custom"></a>

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

自定义路由使用您指定的路由键和集成。当传入消息包含 JSON 属性，并且该属性的计算结果为与路由键值匹配的值时，API Gateway 将会调用集成。（有关更多信息，请参阅 [API Gateway 中的 WebSocket API 概览](apigateway-websocket-api-overview.md)。）

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

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

而且，它可以通过发送如下消息来调用 `sendmessage` 路由：

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

## 使用 API Gateway WebSocket API 集成连接到您的业务逻辑
<a name="apigateway-websocket-api-overview-integrations"></a>

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

有关设置集成的更多信息，请参阅[API Gateway 中 WebSocket API 的集成](apigateway-websocket-api-integrations.md)。

## WebSocket API 和 REST API 之间的重要区别
<a name="apigateway-websocket-api-overview-integrations-differences"></a>

WebSocket API 的集成类似于 REST API 的集成，但有以下区别：
+ 目前，在 API Gateway 控制台中，您必须先创建一个路径，然后创建一个集成作为该路由的目标。但是，在 API 和 CLI 中，您可以按任何顺序独立创建路由和集成。
+ 您可以对多个路由使用单个集成。例如，如果您有一组彼此密切相关的操作，您可能希望所有这些路由都转到单个 Lambda 函数。您可以一次指定集成的详细信息并将其分配给每个相关路由，而不是多次定义它。
**注意**  
目前，控制台不支持重用集成，因此您必须先创建路由，然后为该路由创建集成。  
在 Amazon CLI 和 Amazon 开发工具包中，您可以通过将路由的目标设置 `"integrations/{integration-id}"` 的值来重用集成，其中 `{integration-id}"` 是要与路由关联的集成的唯一 ID。
+ API Gateway 提供多个[选择表达式](apigateway-websocket-api-selection-expressions.md)，您可以在路由和集成中使用它们。您无需依赖内容类型来选择输入模板或输出映射。与路径选择表达式一样，您可以定义要由 API Gateway 评估的选择表达式以选择正确的项。如果找不到匹配的模板，则所有这些都将回退到 `$default` 模板。
  + 在集成请求中，模板选择表达式支持 `$request.body.<json_path_expression>` 和静态值。
  + 在集成响应中，模板选择表达式支持 `$request.body.<json_path_expression>`、`$integration.response.statuscode`、`$integration.response.header.<headerName>` 和静态值。

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

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