本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
在API閘道中叫用$default
路由和自訂路由的後端整合
下節說明如何使用$default
路由或自訂路由來叫用您的後端整合 WebSocket API。
使用路由來處理訊息
在 API Gateway 中 WebSocket APIs,消息可以從客戶端發送到後端服務,反之亦然。與HTTP請求/響應模型不同,在 WebSocket 後端可以將消息發送到客戶端,而無需客戶端採取任何行動。
訊息可以是JSON或非JSON。不過,只有JSON郵件才能根據訊息內容路由至特定整合。非JSON消息通過$default
路由傳遞到後端。
注意
API閘道支援訊息承載高達 128 KB,訊框大小上限為 32 KB。如果訊息超過 32 KB,則必須分割成多個影格,每個為 32 KB 或以下。如果接收到更大的訊息 (或影格),則該連線會關閉,並出現程式碼 1009。
目前不支援二進位承載。如果接收到二進位影格,則該連線會關閉,並出現程式碼 1003。不過,您可以將二進位承載轉換為文字。請參閱API Gateway 中 WebSocket API 的二進位媒體類型。
WebSocket APIs在 API Gateway 中,可以路由傳送JSON訊息,以根據訊息內容執行特定的後端服務。當用戶端透過其 WebSocket 連線傳送訊息時,會產生傳送至 WebSocket API. 請求將與具有 API Gateway 中相應路由密鑰的路由匹配。您可以在API閘道主控台 WebSocket API中設定路由要求,方法是使用 AWS CLI、或使用 AWS SDK.
注意
在 AWS CLI 和中 AWS SDKs,您可以在建立整合之前或之後建立路由。目前主控台不支援整合的重複使用,因此您必須先建立路由,然後建立該路由的整合。
您可以將 API Gateway 設定為在繼續進行整合要求之前,對路由要求執行驗證。如果驗證失敗,APIGateway 會在不呼叫後端的情況下失敗要求,將類似下列內容的"Bad request body"
閘道回應傳送給用戶端,然後在 CloudWatch 記錄檔中發佈驗證結果:
{"message" : "Bad request body", "connectionId": "
{connectionId}
", "messageId": "{messageId}
"}
這樣可以減少對後端的不必要調用,並讓您專注於API.
您也可以為您API的路由定義路由回應,以啟用雙向通訊。路由回應說明會在特定路由整合完成時,將哪些資料傳送到用戶端。例如,如果您希望用戶端將訊息傳送到後端,而不接收回應 (單向通訊),您不需要定義路由的回應。不過,如果您未提供路由回應,APIGateway 將不會傳送任何有關整合結果的資訊給您的用戶端。
$default
路由
每個API閘道都 WebSocket API可以有$default
路由。這是一個特殊路由值,使用方式如下:
-
您可以使用該值搭配定義的路由金鑰,來為不符合任何定義路由金鑰的內送訊息指定「備用」路由 (例如,一般偽裝整合,會傳回特定的錯誤訊息)。
-
您可以使用該值與任何定義路由金鑰,來指定將路由委派到後端元件的 Proxy 模型。
-
您可以使用它來指定非JSON承載的路由。
自訂路由
如果您想要根據訊息內容來叫用特定的整合,則可透過建立自訂路由來這麼做。
自訂路由會使用您指定的路由金鑰和整合。當內送郵件包含JSON屬性,且該屬性評估為符合路由金鑰值的值時,APIGateway 會叫用整合。(如需詳細資訊,請參閱「API閘道 WebSocket APIs中的概觀」。)
例如,假設您想要建立聊天空間應用程式。您可以先建立 WebSocket API其路由選取表示式為$request.body.action
。然後,您可以接著定義兩個路由:joinroom
和 sendmessage
。用戶端應用程式可以透過傳送如下訊息,來叫用 joinroom
路由:
{"action":"joinroom","roomname":"developers"}
其可以透過傳送如下訊息,來叫用 sendmessage
路由:
{"action":"sendmessage","message":"Hello everyone"}
使用API閘道 WebSocket API整合連接到您的業務邏輯
設定API閘道的路由之後 WebSocket API,您必須指定要使用的整合。如同路由 (可能會擁有路由請求和路由回應),整合可以擁有整合請求和整合回應。整合請求包含後端預期的資訊,以處理來自您用戶端的請求。整合回應包含後端傳回 API Gateway 的資料,並可用來建構要傳送給用戶端的訊息 (如果已定義路由回應)。
如需設定整合的詳細資訊,請參閱API閘道 WebSocket API中的整合。
和之間的重要差 WebSocket APIs異 REST APIs
的整合 WebSocket APIs類似於的整合 RESTAPIs,但下列差異除外:
-
目前,在 API Gateway 主控台中,您必須先建立路由,然後建立整合作為該路由的目標。不過,在API和中CLI,您可以依任何順序獨立建立路由和整合。
-
您可以為多個路由使用單一整合。例如,如果您有一組動作彼此間密切關聯,您可能需要所有路由來移至單一 Lambda 函數。您不必多次定義整合的詳細資訊,您可以指定一次,並將其指派給每個相關的路由。
注意
目前主控台不支援整合的重複使用,因此您必須先建立路由,然後建立該路由的整合。
在 AWS CLI 和中 AWS SDKs,您可以將路由的目標設定為值來重複使用整合
"integrations/
,其中{integration-id}
"
是要與路由相關聯之整合的唯一 ID。{integration-id}
" -
APIGateway 提供多種選擇表達式,您可以在路由和集成中使用。您不需要倚賴內容類型來選取輸入範本或輸出映射。與路由選取運算式一樣,您可以定義要由 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閘道不會自動將後端回應傳遞至路由回應。例如,在 LAMBDA_PROXY
整合的情況下,就不會將 Lambda 函數傳回的內文傳回給用戶端。如果您希望用戶端接收整合回應,您必須定義路由回應,以進行雙向的通訊。