在API閘道中叫用$default路由和自訂路由的後端整合 - Amazon API Gateway

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

在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。然後,您可以接著定義兩個路由:joinroomsendmessage。用戶端應用程式可以透過傳送如下訊息,來叫用 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}",其中{integration-id}"是要與路由相關聯之整合的唯一 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_PROXYLAMBDA_PROXY整合的路由,通訊是單向的,API閘道不會自動將後端回應傳遞至路由回應。例如,在 LAMBDA_PROXY 整合的情況下,就不會將 Lambda 函數傳回的內文傳回給用戶端。如果您希望用戶端接收整合回應,您必須定義路由回應,以進行雙向的通訊。