本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 用於 API Gateway 的 WebSocket API 映射範本參考 此章節摘要說明目前 API Gateway 內 WebSocket API 支援的變數組。 | 參數 | 描述 | | --- | --- | | \$1context.connectionId | 連線的唯一 ID，可用來回呼用戶端。 | | \$1context.connectedAt | [Epoch](https://en.wikipedia.org/wiki/Unix_time) 格式化連線時間。 | | \$1context.domainName | WebSocket API 的網域名稱。此可用於回呼用戶端 (非硬式編碼的值)。 | | \$1context.eventType | 事件類型：`CONNECT`、`MESSAGE` 或 `DISCONNECT`。 | | \$1context.messageId | 訊息的伺服器端唯一 ID。僅在 `$context.eventType` 為 `MESSAGE` 時可用。 | | \$1context.routeKey | 所選路由金鑰。 | | \$1context.requestId | 與 `$context.extendedRequestId` 相同。 | | \$1context.extendedRequestId | API 呼叫的自動產生的 ID，其中包含更多除錯/故障排除的有用的資訊。 | | \$1context.apiId | API Gateway 指派給您 API 的識別碼。 | | \$1context.authorizer.principalId | 與用戶端所傳送並從 API Gateway Lambda 授權方 (先前稱作自訂授權方) Lambda 函數所傳回之權杖建立關聯的主要使用者識別。 | | \$1context.authorizer.property | API Gateway Lambda 授權方函數所傳回 `context` 映射之指定索引鍵/值組的字串化值。例如，如果授權方傳回下列 `context` 映射： 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
呼叫 `$context.authorizer.key` 會傳回 `"value"` 字串、呼叫 `$context.authorizer.numKey` 會傳回 `"1"` 字串，而呼叫 `$context.authorizer.boolKey` 會傳回 `"true"` 字串。 | | \$1context.error.messageString | \$1context.error.message 的引用值，即 "\$1context.error.message"。 | | \$1context.error.validationErrorString | 字串，其中包含詳細的驗證錯誤訊息。 | | \$1context.identity.accountId | 與請求相關聯的 AWS 帳戶 ID。 | | \$1context.identity.apiKey | 與啟用金鑰之 API 請求建立關聯的 API 擁有者金鑰。 | | \$1context.identity.apiKeyId | 與啟用金鑰之 API 請求建立關聯的 API 金鑰 ID。 | | \$1context.identity.caller | 提出請求之發起人的委託人識別符。 | | \$1context.identity.cognitoAuthenticationProvider | 提出請求的發起人所使用的所有 Amazon Cognito 驗證提供者清單 (以逗號分隔)。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。 例如，適用於 Amazon Cognito 使用者集區的身分，`cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` 如需有關 Amazon Cognito 驗證提供者的詳細資訊，請參閱《[Amazon Cognito 開發人員指南](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html)》中的*使用聯合身分*。 | | \$1context.identity.cognitoAuthenticationType | 提出請求的發起人的 Amazon Cognito 驗證類型。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。可能的值包括用於已驗證身分的 `authenticated` 和未經驗證身分的 `unauthenticated`。 | | \$1context.identity.cognitoIdentityId | 提出請求的發起人的 Amazon Cognito 身分 ID。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。 | | \$1context.identity.cognitoIdentityPoolId | 提出請求的發起人的 Amazon Cognito 身分集區 ID。僅在使用 Amazon Cognito 登入資料簽署請求時才可使用。 | | \$1context.identity.sourceIp | 對 API Gateway 提出請求之即時 TCP 連線的來源 IP 地址。 | | \$1context.identity.user | 提出請求之使用者的委託人識別符。 | | \$1context.identity.userAgent | API 發起人的使用者代理程式。 | | \$1context.identity.userArn | 身分驗證之後識別之有效使用者的 Amazon Resource Name (ARN)。 | | \$1context.requestTime | [CLF](https://httpd.apache.org/docs/current/logs.html#common) 格式化請求時間 (dd/MMM/yyyy:HH:mm:ss \$1-hhmm)。 | | \$1context.requestTimeEpoch | [Epoch](https://en.wikipedia.org/wiki/Unix_time) 格式化的要求時間，以毫秒為單位。 | | \$1context.stage | API 呼叫的部署階段 (例如，Beta 或 Prod)。 | | \$1context.status | 回應狀態。 | | \$1input.body | 傳回原始承載作為字串。 | | \$1input.json(x) | 此函數會評估 JSONPath 表達式，並傳回結果作為 JSON 字串。 例如，`$input.json('$.pets')` 會傳回代表 pets 結構的 JSON 字串。 如需 JSONPath 的詳細資訊，請參閱 [JSONPath](https://goessner.net/articles/JsonPath/) 或[適用於 Java 的 JSONPath](https://github.com/json-path/JsonPath)。 | | \$1input.path(x) | 採用 JSONPath 表達式字串 (`x`)，並傳回結果的 JSON 物件呈現。這可讓您存取和運用 [Apache Velocity 範本語言 (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) 中原生承載的元素。 例如，如果表達式 `$input.path('$.pets')` 傳回如下物件： 
[
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }, 
  { 
    "id": 2, 
    "type": "cat", 
    "price": 124.99 
  }, 
  { 
    "id": 3, 
    "type": "fish", 
    "price": 0.99 
  } 
]
`$input.path('$.pets').count()` 會傳回 `"3"`。 如需 JSONPath 的詳細資訊，請參閱 [JSONPath](http://goessner.net/articles/JsonPath/) 或[適用於 Java 的 JSONPath](https://github.com/jayway/JsonPath)。 | | \$1stageVariables. | ** 代表階段變數名稱。 | | \$1stageVariables[''] | ** 代表任何階段變數名稱。 | | \$1\$1stageVariables['']\$1 | ** 代表任何階段變數名稱。 | | \$1util.escapeJavaScript() | 使用 JavaScript 字串規則來逸出字串中的字元。 此函數會將任何一般單引號 (`'`) 轉換為逸出單引號 (`\'`)。不過，逸出單引號不適用於 JSON。因此，將此函數的輸出用於 JSON 屬性時，您必須將任何逸出單引號 (`\'`) 轉換為一般單引號 (`'`)。下列範例顯示這種情況： 
 $util.escapeJavaScript(data).replaceAll("\\'","'")
| | \$1util.parseJson() | 採用「字串化」JSON，並傳回結果的物件呈現。您可以使用此函數的結果，來存取和運用 Apache Velocity 範本語言 (VTL) 中原生承載的元素。例如，如果您有下列承載： 
{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}
並使用下列映射範本 
#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
您將會收到下列輸出： 
{
   "errorMessageObjKey2ArrVal" : 1
}
| | \$1util.urlEncode() | 將字串轉換為 "application/x-www-form-urlencoded" 格式。 | | \$1util.urlDecode() | 解碼 "application/x-www-form-urlencoded" 字串。 | | \$1util.base64Encode() | 將資料編碼為 base64 編碼字串。 | | \$1util.base64Decode() | 解碼 base64 編碼字串中的資料。 |