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

# WebSocket 選擇表達式
<a name="apigateway-websocket-api-selection-expressions"></a>

API Gateway 使用選擇表達式來評估請求及回應內容並產生金鑰。然後，金鑰會用來選擇一組通常由您 (即 API 開發人員) 提供的可能值。所支援的實際變數組將取決於特定表達式，各表達式詳細說明如下。

所有表達式的語言都遵循同一組規則：
+ 變數字首會加上 `"$"`。
+ 大括號可用來明確定義變數邊界，例如 `"${request.body.version}-beta"`。
+ 支援多個變數，但僅會評估一次 (無遞迴評估)。
+ 貨幣符號 (`$`) 可用 `"\"` 逸出。在定義映射至預留 `$default` 金鑰 (如 `"\$default"`) 的表達式時，這條規則十分實用。
+ 有時需要模式格式，此時，表達式前後應以斜線 (`"/"`) 包裝，例如應符合 `"/2\d\d/"` 狀態碼的 `2{{XX}}`。

**Topics**
+ [路由回應選擇表達式](#apigateway-websocket-api-route-response-selection-expressions)
+ [API 金鑰選擇表達式](#apigateway-websocket-api-apikey-selection-expressions)
+ [API 映射選擇表達式](#apigateway-websocket-api-mapping-selection-expressions)
+ [WebSocket 選擇表達式總結](#apigateway-websocket-api-selection-expression-table)

## 路由回應選擇表達式
<a name="apigateway-websocket-api-route-response-selection-expressions"></a>

[路由回應](apigateway-websocket-api-route-response.md)係用來將後端到用戶端的回應建模。以 WebSocket API 而言，路由回應為選用。如有定義，將指示 API Gateway 在接收 WebSocket 訊息時應將回應回傳至用戶端。

*路由回應選擇表達式*的評估將產生路由回應金鑰。此金鑰最終將選擇其中一個與 API 相關聯的 [https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-routes-routeid-routeresponses.html)。然而，目前僅支援 `$default` 金鑰。

## API 金鑰選擇表達式
<a name="apigateway-websocket-api-apikey-selection-expressions"></a>

本服務判定特定請求只在用戶端提供有效的 [API 金鑰](api-gateway-basic-concept.md#apigateway-definition-api-key)後才會繼續處理，此時將評估此表達式。

目前僅支援兩個值：`$request.header.x-api-key` 及 `$context.authorizer.usageIdentifierKey`。

## API 映射選擇表達式
<a name="apigateway-websocket-api-mapping-selection-expressions"></a>

當請求使用自訂網域提出時，須評估此表達式來判定應選取的 API 階段。

目前，僅支援的值為 `$request.basepath`。

## WebSocket 選擇表達式總結
<a name="apigateway-websocket-api-selection-expression-table"></a>

下表總結 WebSocket API 內選擇表達式的使用案例：


| 選擇表達式 | 判斷值為下列的金鑰 | 備註 | 範例使用案例 | 
| --- | --- | --- | --- | 
| Api.RouteSelectionExpression | Route.RouteKey | 所支援的 $default 為全部截獲路由。 | 依據用戶端請求內容路由 WebSocket 訊息。 | 
| Route.ModelSelectionExpression | Route.RequestModels 的金鑰 | 選用。<br />若提供給非代理整合，將出現模型驗證。<br />所支援的 `$default` 為全部截獲。 | 在相同路由內動態執行請求驗證。 | 
| Integration.TemplateSelectionExpression | Integration.RequestTemplates 的金鑰 | 選用。<br />可供非代理整合使用，藉此操控傳入承載。<br />支援 `${request.body.jsonPath}` 和靜態值。<br />所支援的 `$default` 為全部截獲。 | 依據請求的動態屬性操控發起人的請求。 | 
| Integration.IntegrationResponseSelectionExpression | IntegrationResponse.IntegrationResponseKey | 選用。可供非代理整合使用。<br />做為錯誤訊息 (來自 Lambda) 或狀態碼 (來自 HTTP 整合) 的模式比對。<br />非代理整合必須有 `$default` 來全部截獲成功回應。 | 從後端操控回應。<br />依據後端的動態回應來選擇欲採取的動作 (如明確處理特定錯誤)。 | 
| IntegrationResponse.TemplateSelectionExpression | IntegrationResponse.ResponseTemplates 的金鑰 | 選用。可供非代理整合使用。支援 $default。 | 回應的動態屬性有時會在相同路由與相關聯整合內做出不同轉換的決定。<br />支援 `${request.body.jsonPath}`、`${integration.response.statuscode}`、`${integration.response.header.headerName}`、`${integration.response.multivalueheader.headerName}` 和靜態值。<br />所支援的 `$default` 為全部截獲。 | 
| Route.RouteResponseSelectionExpression | RouteResponse.RouteResponseKey | 應提供，藉以啟動 WebSocket 路由的雙向通訊。<br />目前此值限制為 `$default`。 |  | 
| RouteResponse.ModelSelectionExpression | RouteResponse.RequestModels 的金鑰 | 目前不支援。 |  |