在 API Gateway 中建立 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 的連線時，API Gateway 會呼叫 $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 承載，而 .action 則為 JSONPath 表達式。request.body 之後可使用任何 JSON 路徑表達式，但請記住結果會字串化。例如，若您的 JSONPath 表達式回傳兩個元素的陣列，該結果將以字串 "[item1, item2]" 呈現。有鑑於此，理想做法是將表達式的評估結果設為一個值，而非陣列或物件。

您可僅使用靜態值，或者也可以使用多個變數。下表為上述承載的範例及其評估結果。

表達式	評估結果	描述
$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. 選擇建立路由。

3. 針對路由金鑰，輸入路由金鑰名稱。您可以建立預先定義的路由 ($connect、$disconnect 和 $default)，或是自訂路由。

   注意

   建立自訂路由時，請勿在路由金鑰名稱字首使用 $。此字首保留供預先定義路由使用。

4. 選取並設定路由的整合類型。如需詳細資訊，請參閱使用 API Gateway 主控台設定 WebSocket API 整合請求。

使用 建立路由 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 主控台中，只有在您設定授權方函數 (如 CUSTOM 所述) 後，才會看到 設定 Lambda 授權方 (主控台) 設定。

  重要

  Authorization (授權) 設定會套用至整個 API，不只是 $connect 路由。$connect 路由會保護其他路由，因為每次連線都會呼叫該路由。

• API Key Required (需要 API 金鑰)：API 的 $connect 路由可選擇要求 API 金鑰。您可以同時使用 API 金鑰與用量計劃，以控制並追蹤對 API 的存取。如需更多詳細資訊，請參閱 API Gateway 中 REST API 的用量計畫和 API 金鑰。

使用 API Gateway 主控台設定 $connect 路由請求

若要使用 API Gateway 主控台來設定 WebSocket API 的 $connect 路由請求：

1. 登入 API Gateway 主控台、選擇 API，然後選擇 Routes (路由)。

2. 在路由下，選擇 $connect，或依照 使用 API Gateway 主控台建立路由 建立 $connect 路由。

3. 在路由請求設定區段中，選擇編輯。

4. 針對授權，選取授權類型。

5. 若要針對 $connect 路由要求 API，請選取需要 API 金鑰。

6. 選擇 Save changes (儲存變更)。