本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 API Gateway 中調用與 `$default` Route 和自訂路由的後端整合
<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 中，您可以將訊息從用戶端傳送到後端服務，反之亦然。後端與在 WebSocket 中的 HTTP 請求/回應模型不同，可以將訊息傳送給用戶端，而用戶端不需採取任何動作。

訊息可以是 JSON 或非 JSON。不過，只能夠根據訊息內容將 JSON 訊息路由到特定的整合。會透過 `$default` 路由將非 JSON 訊息傳遞到後端。

**注意**  
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 中之對應的路由金鑰來將請求對應至路由。您可以使用 AWS CLI或使用 AWS SDK，在 API Gateway 主控台中設定 WebSocket API 的路由請求。

**注意**  
在 AWS CLI AWS SDKs中，您可以在建立整合之前或之後建立路由。目前主控台不支援整合的重複使用，因此您必須先建立路由，然後建立該路由的整合。

您可以將 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` 路由。這是一個特殊路由值，使用方式如下：
+ 您可以使用該值搭配定義的路由金鑰，來為不符合任何定義路由金鑰的內送訊息指定「備用」路由 (例如，一般偽裝整合，會傳回特定的錯誤訊息)。
+ 您可以使用該值與任何定義路由金鑰，來指定將路由委派到後端元件的 Proxy 模型。
+ 您可以使用該值來為非 JSON 承載指定路由。

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

如果您想要根據訊息內容來叫用特定的整合，則可透過建立自訂路由來這麼做。

自訂路由會使用您指定的路由金鑰和整合。當內送訊息包含 JSON 屬性，而且該屬性的判斷值符合路由金鑰值時，API Gateway 會叫用整合。(如需詳細資訊，請參閱「[API Gateway 中的 WebSocket API 概觀](apigateway-websocket-api-overview.md)」。)

例如，假設您想要建立聊天空間應用程式。您可以透過建立路由選擇表達式為 `$request.body.action` 的 WebSocket API 來開始。然後，您可以接著定義兩個路由：`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 函數。您不必多次定義整合的詳細資訊，您可以指定一次，並將其指派給每個相關的路由。
**注意**  
目前主控台不支援整合的重複使用，因此您必須先建立路由，然後建立該路由的整合。  
在 AWS CLI 和 AWS SDKs中，您可以透過將路由的目標設定為 的值來重複使用整合`"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 函數傳回的內文傳回給用戶端。如果您希望用戶端接收整合回應，您必須定義路由回應，以進行雙向的通訊。