WebSocket APIs在API閘道中建立路由

在您的中 WebSocket API，傳入的JSON消息將根據您配置的路由定向到後端集成。(非JSON訊息會導向至您設定的$default路由。)

路由包含的路由金鑰，是您可以在路由選擇表達式經評估後即預期的值。routeSelectionExpression是在層級定義的屬API性。它指JSON定預期將存在於消息有效負載的屬性。如需路由選擇表達式的詳細資訊，請參閱路由選擇表達式。

例如，如果您的JSON郵件包含action屬性，而您想要根據此屬性執行不同的動作，則您的路由選取運算式可能是${request.body.action}。您的路由表將指定要執行哪一個動作，方法是將 action 屬性值與您在資料表中定義的自訂路由鍵值進行比對。

有三種預先定義的路由可供使用：$connect、$disconnect 和 $default。此外，您可以建立自訂路由。

• API當用戶端與 a 之間的持續連$connect線正在起始時，閘道會呼 WebSocket API叫路由。

• API當用戶端或伺服器與中斷連$disconnect線時，閘道會呼叫路由。API

• API如果找到相符的路由，Gateway 會在針對訊息評估路由選取表示式之後呼叫自訂路由；相符項目會決定叫用哪一個整合。

• API如果無法根據訊息評估路由選取表示式，或者找不到相符的路由，Gateway 會呼叫路由。$default

路由選擇表達式

本服務針對傳入訊息選擇欲遵循的路由時，將評估路由選擇表達式。本服務將使用 routeKey 與評估值完全相符的路由。若無相符路由，且某路由存在 $default 路由金鑰，將選取該路由。若沒有路由符合評估值，而且沒有 $default 路由，本服務將回傳錯誤。對 WebSocket於基礎APIs，表達式應該是形式$request.body.{path_to_body_element}。

例如，假設您要傳送下列JSON訊息：

{
    "service" : "chat",
    "action" : "join",
    "data" : {
        "room" : "room1234"
   }
}

您可能希望根據action屬性選擇您API的行為。此時，您可以定義下列路由選擇表達式：

$request.body.action

在此示例中，request.body指的是消息的JSON有效負載，並且.action是一個JSONPath表達式。您可以在之後使用任何JSON路徑表達式request.body，但請記住，結果將被字符串化。例如，如果您的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閘道 WebSocket API中的路由

當您第一次建立新路由時 WebSocket API，會有三個預先定義的佈線：$connect$disconnect、和$default。您可以使用控制台API、或來建立它們 AWS CLI。如有需要，您可以建立自訂路由。如需詳細資訊，請參閱 API閘道 WebSocket APIs中的概觀。

注意

在中CLI，您可以在建立整合之前或之後建立路由，並且可以對多個路由重複使用相同的整合。

使用API閘道主控台建立路由

使用API閘道主控台建立路由

1. 登入API閘道主控台，選擇，然後API選擇 [路由]。

2. 選擇建立路由。

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

   注意

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

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

使用建立路線 AWS CLI

若要使用 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 的路由請求設定

當您為您設定$connect路由時API，可以使用下列選用設定來啟用您的授權API。如需詳細資訊，請參閱 $connect 路由。

• Authorization (授權)：若無須授權，可指定為 NONE。否則，您可指定：

  • AWS_IAM以使用標準 AWS IAM原則來控制您的API.

  • CUSTOM，API透過指定您先前建立的 Lambda 授權者函數來實作授權。授權者可以居住在您自己的 AWS 帳戶或不同的 AWS 帳戶中。如需 Lambda 授權方的詳細資訊，請參閱 使用 API Gateway Lambda 授權方。

    注意

    在 API Gateway 主控台中，只有在CUSTOM設定授權者功能後，才能看見此設定，如中設定 Lambda 授權方 （主控台）所述。

  重要

  授權設置應用於整個API，而不僅僅是$connect路由。$connect 路由會保護其他路由，因為每次連線都會呼叫該路由。

• API需要金鑰：您可以選擇性地要求$connect路由API的API金鑰。您可以將API金鑰與使用計劃一起使用，以控制和追蹤您的APIs. 如需詳細資訊，請參閱 API Gateway RESTAPIs中 的使用計劃和API金鑰 。

使用API閘道主控台設定$connect路由要求

若要 WebSocket API使用API閘道主控台設定$connect路由要求：

1. 登入API閘道主控台，選擇，然後API選擇 [路由]。

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

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

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

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

6. 選擇儲存變更。