本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS AppSync 解析程式映射範本公用程式參考 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 AWS AppSync 定義一組公用程式，您可以在 GraphQL 解析程式中用來簡化與資料來源的互動。其中一些公用程式用於任何資料來源的一般用途，例如產生 IDs 或時間戳記。其他則是特定於一種資料來源類型。下列公用程式可供使用： + [ \$1util 中的公用程式協助程式 ](https://docs.aws.amazon.com/appsync/latest/devguide/utility-helpers-in-util.html) - \$1util 變數包含一般公用程式方法，可協助您處理資料。除非另行指定，否則所有公用程式皆使用 UTF-8 字元集。 + [ AppSync 指令](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-directives.html) - AppSync 公開指令，以促進開發人員在 VTL 中寫入時的生產力。 + [ \$1util.time 中的時間協助程式 ](https://docs.aws.amazon.com/appsync/latest/devguide/time-helpers-in-util-time.html) - \$1util.time 變數包含日期時間方法，可協助產生時間戳記、在日期時間格式之間轉換，以及剖析日期時間字串。日期時間格式的語法是以 [DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html) 為基礎，您可以參考以取得進一步的文件。 + 在[ \$1util.list 中列出協助程式 ](https://docs.aws.amazon.com/appsync/latest/devguide/list-helpers-in-util-list.html) - \$1util.list 包含有助於常見清單操作的方法，例如從清單中移除或保留項目以篩選使用案例。 + [ \$1util.map - \$1util.map 中的映射協助程式](https://docs.aws.amazon.com/appsync/latest/devguide/utility-helpers-in-map.html)包含有助於常見映射操作的方法，例如從映射中移除或保留項目以篩選使用案例。 + [ \$1util.dynamodb - \$1util.dynamodb 中的 DynamoDB 協助程式](https://docs.aws.amazon.com/appsync/latest/devguide/dynamodb-helpers-in-util-dynamodb.html)包含協助程式方法，可讓您更輕鬆地將資料寫入和讀取至 Amazon DynamoDB，例如自動類型映射和格式化。 + [ \$1util.rds - \$1util.rds 中的 Amazon RDS 協助程式](https://docs.aws.amazon.com/appsync/latest/devguide/rds-helpers-in-util-rds.html)包含協助程式方法，可透過消除結果輸出中的外部資料來格式化 RDS 操作。 + [ \$1util.http 中的 HTTP 協助程式 ](https://docs.aws.amazon.com/appsync/latest/devguide/http-helpers-in-utils-http.html) - \$1util.http 公用程式提供可用於管理 HTTP 請求參數和新增回應標頭的協助程式方法。 + [ \$1util.xml - \$1util.xml 中的 XML 協助程式](https://docs.aws.amazon.com/appsync/latest/devguide/xml-helpers-in-utils-xml.html)包含協助程式方法，可讓您更輕鬆地將 XML 回應轉譯為 JSON 或字典。 + [ \$1util.transform 中的轉換協助程式 ](https://docs.aws.amazon.com/appsync/latest/devguide/transformation-helpers-in-utils-transform.html) - \$1util.transform 包含協助程式方法，可讓您更輕鬆地對資料來源執行複雜的操作，例如 DynamoDB 篩選操作。 + [ \$1util.math - \$1util.math 中的數學協助程式](https://docs.aws.amazon.com/appsync/latest/devguide/math-helpers-in-util-math.html)包含有助於常見數學操作的方法。 + [ \$1util.str 中的字串協助程式 ](https://docs.aws.amazon.com/appsync/latest/devguide/str-helpers-in-util-str.html) - \$1util.str 包含有助於常見字串操作的方法。 + [ 延伸 ](https://docs.aws.amazon.com/appsync/latest/devguide/extensions.html)- \$1extensions 包含一組方法，可在解析程式中執行其他動作。 # \$1util 中的公用程式協助程式 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$util` 變數包含可協助您處理資料的一般公用程式方法。除非另行指定，否則所有公用程式皆使用 UTF-8 字元集。 ## JSON 剖析公用程式 ### JSON 剖析 utils 清單 ** **`$util.parseJson(String) : Object`** ** 採用「字串化」JSON，並傳回結果的物件呈現。 ** **`$util.toJson(Object) : String`** ** 採用物件，並傳回該物件的「字串化」JSON 呈現。 ## 編碼 utils ### 編碼 utils 清單 ** **`$util.urlEncode(String) : String`** ** 以 `application/x-www-form-urlencoded` 編碼字串的形式傳回輸入字串。 ** **`$util.urlDecode(String) : String`** ** 將 `application/x-www-form-urlencoded` 編碼的字串解碼回非編碼格式。 ** **`$util.base64Encode( byte[] ) : String`** ** 將輸入編碼為 base64 編碼字串。 ** **`$util.base64Decode(String) : byte[]`** ** 解碼 base64 編碼字串中的資料。 ## ID 產生 utils ### ID 產生 utils 清單 ** **`$util.autoId() : String`** ** 傳回 128 位元隨機產生的 UUID。 ****`$util.autoUlid() : String`**** 傳回 128 位元隨機產生的 ULID （通用可排序序列識別符）。 ****`$util.autoKsuid() : String`**** 傳回 128 位元隨機產生的 KSUID (K-Sortable Unique Identifier) base62，其編碼為長度為 27 的字串。 ## 錯誤率 ### 錯誤使用率清單 ** `$util.error(String)` ** 擲回自訂錯誤。在請求或回應映射範本中使用此參數來偵測請求或調用結果的錯誤。 ** `$util.error(String, String)` ** 擲回自訂錯誤。在請求或回應映射範本中使用此參數來偵測請求或調用結果的錯誤。您也可以指定 `errorType`。 ** `$util.error(String, String, Object)` ** 擲回自訂錯誤。在請求或回應映射範本中使用此參數來偵測請求或調用結果的錯誤。您也可以指定 `errorType`和 `data` 欄位。`data` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。 `data` 將根據查詢選取集進行篩選。 ** `$util.error(String, String, Object, Object)` ** 擲回自訂錯誤。如果範本偵測到要求或呼叫結果的錯誤，您可以將此用於要求或回應映射範本。此外，也可以指定 `errorType` 欄位、 `data` 欄位和 `errorInfo` 欄位。`data` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。 `data` 將根據查詢選取集進行篩選。`errorInfo` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。 `errorInfo` **將不會**根據查詢選取集進行篩選。 ** `$util.appendError(String)` ** 附加自訂錯誤。如果範本偵測到要求或呼叫結果的錯誤，您可以將此用於要求或回應映射範本。與 `$util.error(String)` 不同的是，範本評估不會受中斷，因此可以將資料傳回給發起人。 ** `$util.appendError(String, String)` ** 附加自訂錯誤。如果範本偵測到要求或呼叫結果的錯誤，您可以將此用於要求或回應映射範本。您同時可以指定 `errorType`。與 `$util.error(String, String)` 不同的是，範本評估不會受中斷，因此可以將資料傳回給發起人。 ** `$util.appendError(String, String, Object)` ** 附加自訂錯誤。如果範本偵測到要求或呼叫結果的錯誤，您可以將此用於要求或回應映射範本。您同時可以指定 `errorType` 和 `data` 欄位。與 `$util.error(String, String, Object)` 不同的是，範本評估不會受中斷，因此可以將資料傳回給發起人。`data` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。 `data` 將根據查詢選取集進行篩選。 ** `$util.appendError(String, String, Object, Object)` ** 附加自訂錯誤。如果範本偵測到要求或呼叫結果的錯誤，您可以將此用於要求或回應映射範本。此外，也可以指定 `errorType` 欄位、 `data` 欄位和 `errorInfo` 欄位。與 `$util.error(String, String, Object, Object)` 不同的是，範本評估不會受中斷，因此可以將資料傳回給發起人。`data` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。 `data` 將根據查詢選取集進行篩選。`errorInfo` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。 `errorInfo` **將不會**根據查詢選取集進行篩選。 ## 條件驗證公用程式 ### 條件驗證使用率清單 ** `$util.validate(Boolean, String) : void` ** 如果條件為假，會擲回含指定訊息的 CustomTemplateException。 ** `$util.validate(Boolean, String, String) : void` ** 如果條件為假，會擲回含指定訊息和錯誤類型的 CustomTemplateException。 ** `$util.validate(Boolean, String, String, Object) : void` ** 如果條件為假，會擲回含指定訊息、錯誤類型以及在回應中回傳之資料的 CustomTemplateException。 ## Null 行為 utils ### Null 行為利用率清單 ** `$util.isNull(Object) : Boolean` ** 如果提供物件為 null，則傳回真。 ** `$util.isNullOrEmpty(String) : Boolean` ** 如果提供資料為 null 或空白字串，則傳回真。否則即傳回 false。 ** `$util.isNullOrBlank(String) : Boolean` ** 如果提供資料為 null 或空白字串，則傳回真。否則即傳回 false。 ** `$util.defaultIfNull(Object, Object) : Object` ** 如果不是 null，則傳回第一個物件。否則，會傳回第二個物件做為「預設物件」。 ** `$util.defaultIfNullOrEmpty(String, String) : String` ** 如果不是 null 或空白，則傳回第一個字串。否則，會傳回第二個字串做為「預設字串」。 ** `$util.defaultIfNullOrBlank(String, String) : String` ** 如果不是 null 或空白，則傳回第一個字串。否則，會傳回第二個字串做為「預設字串」。 ## 模式比對 utils ### 類型和模式比對 utils 清單 ** `$util.typeOf(Object) : String` ** 傳回描述物件類型的字串。支援的類型識別為：「Null」、「數字」、「字串」、「映射」、「清單」、「布林值」。如果無法識別類型，則傳回類型為「物件」。 ** `$util.matches(String, String) : Boolean` ** 如果第一個引數中指定的模式與第二個引數中提供的資料相符，則傳回真。模式必須為規則表達式，例如 `$util.matches("a*b", "aaaaab")`。此功能是根據[模式](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html)，您可以參考以取得更詳細的文件。 ** `$util.authType() : String` ** 傳回描述請求所使用之多重身分類型的字串，傳回「IAM 授權」、「使用者集區授權」、「開放 ID Connect 授權」或「API 金鑰授權」。 ## 物件驗證公用程式 ### 物件驗證公用程式清單 ** `$util.isString(Object) : Boolean` ** 如果物件是字串，則傳回 true。 ** `$util.isNumber(Object) : Boolean` ** 如果物件是數字，則傳回 true。 ** `$util.isBoolean(Object) : Boolean` ** 如果物件是布林值，則傳回 true。 ** `$util.isList(Object) : Boolean` ** 如果物件是清單，則傳回 true。 ** `$util.isMap(Object) : Boolean` ** 如果物件是映射，則傳回 true。 ## CloudWatch 記錄公用程式 ### CloudWatch 記錄公用程式清單 **`$util.log.info(Object) : Void`** 在 API `DEBUG`上使用日誌層級 `INFO`、 或 啟用請求層級和欄位層級 CloudWatch 記錄時`ALL`，將所提供物件的字串表示法記錄到請求的日誌串流。 **`$util.log.info(String, Object...) : Void`** 在 API `ALL`上使用日誌層級啟用請求層級和欄位層級 CloudWatch 記錄時，將所提供物件的字串表示法記錄到請求的日誌串流。此公用程式會依序將第一個輸入格式字串中「\$1\$1」指示的所有變數取代為所提供物件的字串表示法。 **`$util.log.debug(Object) : Void`** 使用日誌層級`ALL`或在 API `DEBUG`上啟用請求層級和欄位層級 CloudWatch 記錄時，將所提供物件的字串表示法記錄到請求的日誌串流。 **`$util.log.debug(String, Object...) : Void`** 使用 API 上的日誌層級`DEBUG`或日誌層級啟用欄位層級 CloudWatch 記錄時，將所提供物件的字串表示法記錄到請求`ALL`的日誌串流。此公用程式會依序將第一個輸入格式字串中「\$1\$1」指示的所有變數取代為所提供物件的字串表示法。 **`$util.log.error(Object) : Void`** 在 API 上以**任何**日誌層級 (`ALL`、`DEBUG`、 等） 啟用欄位層級 CloudWatch 記錄時`INFO`，將所提供物件的字串表示記錄到請求的日誌串流。 **`$util.log.error(String, Object...) : Void`** 使用 API 上的日誌層級`ERROR`或日誌層級啟用欄位層級 CloudWatch 記錄時，將所提供物件的字串表示法記錄到請求`ALL`的日誌串流。此公用程式會依序將第一個輸入格式字串中「\$1\$1」指示的所有變數取代為所提供物件的字串表示法。 ## 傳回值行為 utils ### 傳回值行為 utils 清單 ****`$util.qr()`** 和 `$util.quiet()` ** 執行 VTL 陳述式，同時隱藏傳回的值。這適用於執行方法而不使用臨時預留位置，例如將項目新增至地圖。例如： ``` #set ($myMap = {}) #set($discard = $myMap.put("id", "first value")) ``` 變成： ``` #set ($myMap = {}) $util.qr($myMap.put("id", "first value")) ``` ** `$util.escapeJavaScript(String) : String` ** 以 JavaScript 逸出字串傳回輸入字串。 ** `$util.urlEncode(String) : String` ** 以 `application/x-www-form-urlencoded` 編碼字串的形式傳回輸入字串。 ** `$util.urlDecode(String) : String` ** 將 `application/x-www-form-urlencoded` 編碼的字串解碼回非編碼格式。 ** `$util.base64Encode( byte[] ) : String` ** 將輸入編碼為 base64 編碼字串。 ** `$util.base64Decode(String) : byte[]` ** 解碼 base64 編碼字串中的資料。 ** `$util.parseJson(String) : Object` ** 採用「字串化」JSON，並傳回結果的物件呈現。 ** `$util.toJson(Object) : String` ** 採用物件，並傳回該物件的「字串化」JSON 呈現。 ** `$util.autoId() : String` ** 傳回 128 位元隨機產生的 UUID。 ****`$util.autoUlid() : String`**** 傳回 128 位元隨機產生的 ULID （通用可排序序列識別符）。 ****`$util.autoKsuid() : String`**** 傳回 128 位元隨機產生的 KSUID (K-Sortable Unique Identifier) base62，其編碼為長度為 27 的字串。 ** `$util.unauthorized()` ** 擲回欲解析之欄位的 `Unauthorized`。在請求或回應映射範本中使用此選項，以決定是否允許發起人解析 欄位。 ** `$util.error(String)` ** 擲回自訂錯誤。在請求或回應映射範本中使用此參數來偵測請求或調用結果的錯誤。 ** `$util.error(String, String)` ** 擲回自訂錯誤。在請求或回應映射範本中使用此參數來偵測請求或調用結果的錯誤。您也可以指定 `errorType`。 ** `$util.error(String, String, Object)` ** 擲回自訂錯誤。在請求或回應映射範本中使用此參數來偵測請求或調用結果的錯誤。您也可以指定 `errorType`和 `data` 欄位。`data` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。**注意**：`data` 將根據查詢選取範圍集進行篩選。 ** `$util.error(String, String, Object, Object)` ** 擲回自訂錯誤。如果範本偵測到要求或呼叫結果的錯誤，您可以將此用於要求或回應映射範本。您同時可以指定 `errorType` 欄位、`data` 欄位和 `errorInfo` 欄位。`data` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。**注意**：`data` 將根據查詢選取範圍集進行篩選。`errorInfo` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。**注意**：`errorInfo` 將**不會**根據查詢選取範圍集進行篩選。 ** `$util.appendError(String)` ** 附加自訂錯誤。如果範本偵測到要求或呼叫結果的錯誤，您可以將此用於要求或回應映射範本。與 `$util.error(String)` 不同的是，範本評估不會受中斷，因此可以將資料傳回給發起人。 ** `$util.appendError(String, String)` ** 附加自訂錯誤。如果範本偵測到要求或呼叫結果的錯誤，您可以將此用於要求或回應映射範本。您同時可以指定 `errorType`。與 `$util.error(String, String)` 不同的是，範本評估不會受中斷，因此可以將資料傳回給發起人。 ** `$util.appendError(String, String, Object)` ** 附加自訂錯誤。如果範本偵測到要求或呼叫結果的錯誤，您可以將此用於要求或回應映射範本。您同時可以指定 `errorType` 和 `data` 欄位。與 `$util.error(String, String, Object)` 不同的是，範本評估不會受中斷，因此可以將資料傳回給發起人。`data` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。**注意**：`data` 將根據查詢選取範圍集進行篩選。 ** `$util.appendError(String, String, Object, Object)` ** 附加自訂錯誤。如果範本偵測到要求或呼叫結果的錯誤，您可以將此用於要求或回應映射範本。您同時可以指定 `errorType` 欄位、`data` 欄位和 `errorInfo` 欄位。與 `$util.error(String, String, Object, Object)` 不同的是，範本評估不會受中斷，因此可以將資料傳回給發起人。`data` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。**注意**：`data` 將根據查詢選取範圍集進行篩選。`errorInfo` 值將新增到 GraphQL 回應中，`error` 內對應的 `errors` 區塊。**注意**：`errorInfo` 將**不會**根據查詢選取範圍集進行篩選。 ** `$util.validate(Boolean, String) : void` ** 如果條件為假，會擲回含指定訊息的 CustomTemplateException。 ** `$util.validate(Boolean, String, String) : void` ** 如果條件為假，會擲回含指定訊息和錯誤類型的 CustomTemplateException。 ** `$util.validate(Boolean, String, String, Object) : void` ** 如果條件為假，會擲回含指定訊息、錯誤類型以及在回應中回傳之資料的 CustomTemplateException。 ** `$util.isNull(Object) : Boolean` ** 如果提供物件為 null，則傳回真。 ** `$util.isNullOrEmpty(String) : Boolean` ** 如果提供資料為 null 或空白字串，則傳回真。否則即傳回 false。 ** `$util.isNullOrBlank(String) : Boolean` ** 如果提供資料為 null 或空白字串，則傳回真。否則即傳回 false。 ** `$util.defaultIfNull(Object, Object) : Object` ** 如果不是 null，則傳回第一個物件。否則，會傳回第二個物件做為「預設物件」。 ** `$util.defaultIfNullOrEmpty(String, String) : String` ** 如果不是 null 或空白，則傳回第一個字串。否則，會傳回第二個字串做為「預設字串」。 ** `$util.defaultIfNullOrBlank(String, String) : String` ** 如果不是 null 或空白，則傳回第一個字串。否則，會傳回第二個字串做為「預設字串」。 ** `$util.isString(Object) : Boolean` ** 如果物件是字串，則傳回真。 ** `$util.isNumber(Object) : Boolean` ** 如果物件是數字，則傳回真。 ** `$util.isBoolean(Object) : Boolean` ** 如果物件是布林值，則傳回真。 ** `$util.isList(Object) : Boolean` ** 如果物件是清單，則傳回真。 ** `$util.isMap(Object) : Boolean` ** 如果物件是映射，則傳回真。 ** `$util.typeOf(Object) : String` ** 傳回描述物件類型的字串。支援的類型識別為：「Null」、「數字」、「字串」、「映射」、「清單」、「布林值」。如果無法識別類型，則傳回類型為「物件」。 ** `$util.matches(String, String) : Boolean` ** 如果第一個引數中指定的模式與第二個引數中提供的資料相符，則傳回真。模式必須為規則表達式，例如 `$util.matches("a*b", "aaaaab")`。此功能是根據[模式](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html)，您可以參考以取得更詳細的文件。 ** `$util.authType() : String` ** 傳回描述請求所使用之多重身分類型的字串，傳回「IAM 授權」、「使用者集區授權」、「開放 ID Connect 授權」或「API 金鑰授權」。 ****`$util.log.info(Object) : Void`**** 在 API `ALL`上使用日誌層級啟用請求層級和欄位層級 CloudWatch 記錄時，將所提供物件的字串表示記錄到請求的日誌串流。 ****`$util.log.info(String, Object...) : Void`**** 在 API `ALL`上使用日誌層級啟用請求層級和欄位層級 CloudWatch 記錄時，將所提供物件的字串表示法記錄到請求的日誌串流。此公用程式會依序將第一個輸入格式字串中「\$1\$1」指示的所有變數取代為所提供物件的字串表示法。 ****`$util.log.error(Object) : Void`**** 使用 API 上的日誌層級`ERROR`或日誌層級啟用欄位層級 CloudWatch 記錄時，將所提供物件的字串表示法記錄到請求`ALL`的日誌串流。 ****`$util.log.error(String, Object...) : Void`**** 使用 API 上的日誌層級`ERROR`或日誌層級啟用欄位層級 CloudWatch 記錄時，將所提供物件的字串表示法記錄到請求`ALL`的日誌串流。此公用程式會依序將第一個輸入格式字串中「\$1\$1」指示的所有變數取代為所提供物件的字串表示法。 ** `$util.escapeJavaScript(String) : String` ** 以 JavaScript 逸出字串傳回輸入字串。 ## 解析程式授權 ### 解析程式授權清單 ** `$util.unauthorized()` ** 擲回欲解析之欄位的 `Unauthorized`。在請求或回應映射範本中使用此選項，以決定是否允許發起人解析 欄位。 # AWS AppSync 指令 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 AWS AppSync 公開指令，以促進開發人員在 VTL 中寫入時的生產力。 ## 指令 utils ****`#return(Object)`**** `#return(Object)` 可讓您從任何映射範本提早傳回 。 `#return(Object)` 類似於程式設計語言的*傳回*關鍵字，因為它將從邏輯的最接近範圍區塊傳回。在解析程式映射範本`#return(Object)`內部使用 會從解析程式傳回 。此外，`#return(Object)`從函數映射範本使用 會從函數傳回，並繼續執行到管道中的下一個函數或解析程式回應映射範本。 ****`#return`**** `#return` 指令會呈現與 相同的行為`#return(Object)`，但`null`會改為傳回。 # \$1util.time 中的時間協助程式 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$util.time` 變數包含日期時間方法，可協助產生時間戳記、在日期時間格式之間轉換，以及剖析日期時間字串。日期時間格式的語法是根據 [DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html)，您可以參考以取得更詳細的文件。我們提供以下一些範例，以及可用方法和描述的清單。 ## 時間 utils ### 時間使用率清單 ** `$util.time.nowISO8601() : String` ** 以 [ISO8601 格式](https://en.wikipedia.org/wiki/ISO_8601)傳回 UTC 的字串表示方式。 ** `$util.time.nowEpochSeconds() : long` ** 傳回從 1970-01-01T00:00:00Z 的 epoch 到現在的秒數。 ** `$util.time.nowEpochMilliSeconds() : long` ** 傳回從 1970-01-01T00:00:00Z 的 epoch 到現在的毫秒數。 ** `$util.time.nowFormatted(String) : String` ** 使用字串輸入類型的指定格式，傳回 UTC 中目前時間戳記的字串。 ** `$util.time.nowFormatted(String, String) : String` ** 使用字串輸入類型的指定格式和時區，傳回時區目前時間戳記的字串。 ** `$util.time.parseFormattedToEpochMilliSeconds(String, String) : Long` ** 剖析以字串形式傳遞的時間戳記，以及包含時區的格式，然後傳回自 epoch 以來以毫秒為單位的時間戳記。 ** `$util.time.parseFormattedToEpochMilliSeconds(String, String, String) : Long` ** 剖析以字串形式傳遞的時間戳記，以及格式和時區，然後以毫秒為單位傳回自 epoch 以來的時間戳記。 ** `$util.time.parseISO8601ToEpochMilliSeconds(String) : Long` ** 剖析以字串形式傳遞的 ISO8601 時間戳記，然後將時間戳記傳回為自 epoch 以來的毫秒。 ** `$util.time.epochMilliSecondsToSeconds(long) : long` ** 將 epoch 毫秒時間戳記轉換為 epoch 秒時間戳記。 ** `$util.time.epochMilliSecondsToISO8601(long) : String` ** 將 epoch 毫秒時間戳記轉換為 ISO8601 時間戳記。 ** `$util.time.epochMilliSecondsToFormatted(long, String) : String` ** 將 epoch 毫秒時間戳記轉換為根據 UTC 格式提供的時間戳記。 ** `$util.time.epochMilliSecondsToFormatted(long, String, String) : String` ** 將長傳遞的 epoch 毫秒時間戳記轉換為根據所提供時區中提供的格式格式化的時間戳記。 ## 獨立函數範例 ``` $util.time.nowISO8601() : 2018-02-06T19:01:35.749Z $util.time.nowEpochSeconds() : 1517943695 $util.time.nowEpochMilliSeconds() : 1517943695750 $util.time.nowFormatted("yyyy-MM-dd HH:mm:ssZ") : 2018-02-06 19:01:35+0000 $util.time.nowFormatted("yyyy-MM-dd HH:mm:ssZ", "+08:00") : 2018-02-07 03:01:35+0800 $util.time.nowFormatted("yyyy-MM-dd HH:mm:ssZ", "Australia/Perth") : 2018-02-07 03:01:35+0800 ``` ## 轉換範例 ``` #set( $nowEpochMillis = 1517943695758 ) $util.time.epochMilliSecondsToSeconds($nowEpochMillis) : 1517943695 $util.time.epochMilliSecondsToISO8601($nowEpochMillis) : 2018-02-06T19:01:35.758Z $util.time.epochMilliSecondsToFormatted($nowEpochMillis, "yyyy-MM-dd HH:mm:ssZ") : 2018-02-06 19:01:35+0000 $util.time.epochMilliSecondsToFormatted($nowEpochMillis, "yyyy-MM-dd HH:mm:ssZ", "+08:00") : 2018-02-07 03:01:35+0800 ``` ## 剖析範例 ``` $util.time.parseISO8601ToEpochMilliSeconds("2018-02-01T17:21:05.180+08:00") : 1517476865180 $util.time.parseFormattedToEpochMilliSeconds("2018-02-02 01:19:22+0800", "yyyy-MM-dd HH:mm:ssZ") : 1517505562000 $util.time.parseFormattedToEpochMilliSeconds("2018-02-02 01:19:22", "yyyy-MM-dd HH:mm:ss", "+08:00") : 1517505562000 ``` ## 使用已 AWS AppSync 定義的純量 以下格式與 `AWSDate`、`AWSDateTime` 和 `AWSTime` 相容。 ``` $util.time.nowFormatted("yyyy-MM-dd[XXX]", "-07:00:30") : 2018-07-11-07:00 $util.time.nowFormatted("yyyy-MM-dd'T'HH:mm:ss[XXXXX]", "-07:00:30") : 2018-07-11T15:14:15-07:00:30 ``` # 在 \$1util.list 中列出協助程式 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$util.list` 包含有助於常見清單操作的方法，例如從清單中移除或保留項目以篩選使用案例。 ## 列出 utils ** `$util.list.copyAndRetainAll(List, List) : List` ** 製作第一個引數中所提供清單的淺層副本，如果項目存在，則僅保留第二個引數中指定的項目。所有其他項目將從副本中刪除。 ** `$util.list.copyAndRemoveAll(List, List) : List` ** 製作第一個引數中所提供清單的淺層副本，同時移除在第二個引數中指定項目的任何項目，如果有的話。所有其他項目將保留在副本中。 ** `$util.list.sortList(List, Boolean, String) : List` ** 排序在第一個引數中提供的物件清單。如果第二個引數為 true，清單會以遞減方式排序；如果第二個引數為 false，清單會以遞增方式排序。第三個引數是用來排序自訂物件清單的 屬性字串名稱。如果只是字串、整數、浮點數或雙數的清單，則第三個引數可以是任何隨機字串。如果所有物件不是來自相同類別，則會傳回原始清單。僅支援最多包含 1000 個物件的清單。以下是此公用程式使用的範例： ``` INPUT: $util.list.sortList([{"description":"youngest", "age":5},{"description":"middle", "age":45}, {"description":"oldest", "age":85}], false, "description") OUTPUT: [{"description":"middle", "age":45}, {"description":"oldest", "age":85}, {"description":"youngest", "age":5}] ``` # 在 \$1util.map 中映射協助程式 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$util.map` 包含有助於常見 Map 操作的方法，例如從 Map 中移除或保留項目，以篩選使用案例。 ## 映射 utils ** `$util.map.copyAndRetainAllKeys(Map, List) : Map` ** 製作第一個映射的淺層副本，同時只保留清單中指定的索引鍵，如果它們存在的話。所有其他金鑰將從副本中刪除。 ** `$util.map.copyAndRemoveAllKeys(Map, List) : Map` ** 在移除清單中指定金鑰的任何項目時，製作第一個映射的淺層副本，如果有的話。所有其他金鑰將保留在副本中。 # \$1util.dynamodb 中的 DynamoDB 協助程式 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$util.dynamodb` 包含協助程式方法，可讓您更輕鬆地將資料寫入和讀取至 Amazon DynamoDB，例如自動類型映射和格式化。這些方法旨在將基本類型和清單自動映射至適當的 DynamoDB 輸入格式，這是 格式`Map`的 `{ "TYPE" : VALUE }`。 例如，先前在 DynamoDB 中建立新項目的請求映射範本可能如下所示： ``` { "version" : "2017-02-28", "operation" : "PutItem", "key": { "id" : { "S" : "$util.autoId()" } }, "attributeValues" : { "title" : { "S" : $util.toJson($ctx.args.title) }, "author" : { "S" : $util.toJson($ctx.args.author) }, "version" : { "N", $util.toJson($ctx.args.version) } } } ``` 如果我們想要將欄位新增到物件，必須在結構描述中更新 GraphQL 查詢和要求映射範本。不過，我們現在可以重組請求映射範本，讓它自動挑選在我們的結構描述中新增的新欄位，並將它們新增至具有正確類型的 DynamoDB： ``` { "version" : "2017-02-28", "operation" : "PutItem", "key": { "id" : $util.dynamodb.toDynamoDBJson($util.autoId()) }, "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args) } ``` 在先前的範例中，我們使用`$util.dynamodb.toDynamoDBJson(...)`協助程式自動取得產生的 ID，並將其轉換為字串屬性的 DynamoDB 表示法。然後，我們採用所有引數並將其轉換為其 DynamoDB 表示法，並將其輸出至範本中的 `attributeValues` 欄位。 每個協助程式有兩個版本：傳回物件的版本 (例如，`$util.dynamodb.toString(...)`)，以及傳回物件做為 JSON 字串的版本 (例如，`$util.dynamodb.toStringJson(...)`)。在前述範例中，我們使用傳回資料做為 JSON 字串的版本。如果您想要在範本使用物件之前，對物件進行操作，可以選擇傳回物件，如下所示： ``` { "version" : "2017-02-28", "operation" : "PutItem", "key": { "id" : $util.dynamodb.toDynamoDBJson($util.autoId()) }, #set( $myFoo = $util.dynamodb.toMapValues($ctx.args) ) #set( $myFoo.version = $util.dynamodb.toNumber(1) ) #set( $myFoo.timestamp = $util.dynamodb.toString($util.time.nowISO8601())) "attributeValues" : $util.toJson($myFoo) } ``` 在前述範例中，我們傳回轉換引數做為映射而非 JSON 字串，然後在使用 `version` 將其輸出到範本的 `timestamp` 欄位之前，新增 `attributeValues` 和 `$util.toJson(...)` 欄位。 每個 JSON 版本的協助程式等同於以 `$util.toJson(...)` 包裝非 JSON 版本。例如，下列陳述式完全相同： ``` $util.toStringJson("Hello, World!") $util.toJson($util.toString("Hello, World!")) ``` ## toDynamoDB ### toDynamoDB 公用程式清單 ** `$util.dynamodb.toDynamoDB(Object) : Map` ** DynamoDB 的一般物件轉換工具，可將輸入物件轉換為適當的 DynamoDB 表示法。它在代表一些類型的方式上是固定的：例如，它會使用清單 (「L」) 而不是集合 (「SS」、「NS」、「BS」)。這會傳回描述 DynamoDB 屬性值的物件。 **字串範例** ``` Input: $util.dynamodb.toDynamoDB("foo") Output: { "S" : "foo" } ``` **數字範例** ``` Input: $util.dynamodb.toDynamoDB(12345) Output: { "N" : 12345 } ``` **布林值範例** ``` Input: $util.dynamodb.toDynamoDB(true) Output: { "BOOL" : true } ``` **清單範例** ``` Input: $util.dynamodb.toDynamoDB([ "foo", 123, { "bar" : "baz" } ]) Output: { "L" : [ { "S" : "foo" }, { "N" : 123 }, { "M" : { "bar" : { "S" : "baz" } } } ] } ``` **地圖範例** ``` Input: $util.dynamodb.toDynamoDB({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] }) Output: { "M" : { "foo" : { "S" : "bar" }, "baz" : { "N" : 1234 }, "beep" : { "L" : [ { "S" : "boop" } ] } } } ``` ****`$util.dynamodb.toDynamoDBJson(Object) : String`** ** 與 相同`$util.dynamodb.toDynamoDB(Object) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ## toString utils ### toString utils 清單 ****`$util.dynamodb.toString(String) : String`** ** 將輸入字串轉換為 DynamoDB 字串格式。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toString("foo") Output: { "S" : "foo" } ``` ** `$util.dynamodb.toStringJson(String) : Map` ** 與 相同`$util.dynamodb.toString(String) : String`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ** `$util.dynamodb.toStringSet(List) : Map` ** 將具有字串的清單轉換為 DynamoDB 字串集格式。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toStringSet([ "foo", "bar", "baz" ]) Output: { "SS" : [ "foo", "bar", "baz" ] } ``` ** `$util.dynamodb.toStringSetJson(List) : String` ** 與 相同`$util.dynamodb.toStringSet(List) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ## toNumber utils ### toNumber utils 清單 ** `$util.dynamodb.toNumber(Number) : Map` ** 將數字轉換為 DynamoDB 數字格式。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toNumber(12345) Output: { "N" : 12345 } ``` ** `$util.dynamodb.toNumberJson(Number) : String` ** 與 相同`$util.dynamodb.toNumber(Number) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ** `$util.dynamodb.toNumberSet(List) : Map` ** 將數字清單轉換為 DynamoDB 數字集格式。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toNumberSet([ 1, 23, 4.56 ]) Output: { "NS" : [ 1, 23, 4.56 ] } ``` ** `$util.dynamodb.toNumberSetJson(List) : String` ** 與 相同`$util.dynamodb.toNumberSet(List) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ## toBinary utils ### toBinary utils 清單 ** `$util.dynamodb.toBinary(String) : Map` ** 將編碼為 base64 字串的二進位資料轉換為 DynamoDB 二進位格式。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toBinary("foo") Output: { "B" : "foo" } ``` ** `$util.dynamodb.toBinaryJson(String) : String` ** 與 相同`$util.dynamodb.toBinary(String) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ** `$util.dynamodb.toBinarySet(List) : Map` ** 將編碼為 base64 字串的二進位資料清單轉換為 DynamoDB 二進位集格式。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toBinarySet([ "foo", "bar", "baz" ]) Output: { "BS" : [ "foo", "bar", "baz" ] } ``` ** `$util.dynamodb.toBinarySetJson(List) : String` ** 與 相同`$util.dynamodb.toBinarySet(List) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ## toBoolean utils ### toBoolean utils 清單 ** `$util.dynamodb.toBoolean(Boolean) : Map` ** 將布林值轉換為適當的 DynamoDB 布林值格式。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toBoolean(true) Output: { "BOOL" : true } ``` ** `$util.dynamodb.toBooleanJson(Boolean) : String` ** 與 相同`$util.dynamodb.toBoolean(Boolean) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ## toNull utils ### toNull utils 清單 ** `$util.dynamodb.toNull() : Map` ** 以 DynamoDB null 格式傳回 null。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toNull() Output: { "NULL" : null } ``` ** `$util.dynamodb.toNullJson() : String` ** 與 相同`$util.dynamodb.toNull() : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ## toList utils ### toList 公用程式清單 ****`$util.dynamodb.toList(List) : Map`** ** 將物件清單轉換為 DynamoDB 清單格式。清單中的每個項目也會轉換為適當的 DynamoDB 格式。它在代表一些巢狀物件的方式上是固定的：例如，它會使用清單 (「L」) 而不是集合 (「SS」、「NS」、「BS」)。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toList([ "foo", 123, { "bar" : "baz" } ]) Output: { "L" : [ { "S" : "foo" }, { "N" : 123 }, { "M" : { "bar" : { "S" : "baz" } } } ] } ``` ** `$util.dynamodb.toListJson(List) : String` ** 與 相同`$util.dynamodb.toList(List) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ## toMap 公用程式 ### toMap utils 清單 ** `$util.dynamodb.toMap(Map) : Map` ** 將映射轉換為 DynamoDB 映射格式。映射中的每個值也會轉換為其適當的 DynamoDB 格式。它在代表一些巢狀物件的方式上是固定的：例如，它會使用清單 (「L」) 而不是集合 (「SS」、「NS」、「BS」)。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toMap({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] }) Output: { "M" : { "foo" : { "S" : "bar" }, "baz" : { "N" : 1234 }, "beep" : { "L" : [ { "S" : "boop" } ] } } } ``` ** `$util.dynamodb.toMapJson(Map) : String` ** 與 相同`$util.dynamodb.toMap(Map) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ** `$util.dynamodb.toMapValues(Map) : Map` ** 建立映射的副本，其中每個值都已轉換為其適當的 DynamoDB 格式。它在代表一些巢狀物件的方式上是固定的：例如，它會使用清單 (「L」) 而不是集合 (「SS」、「NS」、「BS」)。 ``` Input: $util.dynamodb.toMapValues({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] }) Output: { "foo" : { "S" : "bar" }, "baz" : { "N" : 1234 }, "beep" : { "L" : [ { "S" : "boop" } ] } } ``` 這與 略有不同，`$util.dynamodb.toMap(Map) : Map`因為它只會傳回 DynamoDB 屬性值的內容，但不會傳回整個屬性值本身。例如，下列陳述式完全相同： ``` $util.dynamodb.toMapValues($map) $util.dynamodb.toMap($map).get("M") ``` ** `$util.dynamodb.toMapValuesJson(Map) : String` ** 與 相同`$util.dynamodb.toMapValues(Map) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ## S3Object 公用程式 ### S3Object 公用程式清單 ** `$util.dynamodb.toS3Object(String key, String bucket, String region) : Map` ** 將金鑰、儲存貯體和區域轉換為 DynamoDB S3 物件表示法。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toS3Object("foo", "bar", region = "baz") Output: { "S" : "{ \"s3\" : { \"key\" : \"foo", \"bucket\" : \"bar", \"region\" : \"baz" } }" } ``` ** `$util.dynamodb.toS3ObjectJson(String key, String bucket, String region) : String` ** 與 相同`$util.dynamodb.toS3Object(String key, String bucket, String region) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ** `$util.dynamodb.toS3Object(String key, String bucket, String region, String version) : Map` ** 將金鑰、儲存貯體、區域和選用版本轉換為 DynamoDB S3 物件表示法。這會傳回描述 DynamoDB 屬性值的物件。 ``` Input: $util.dynamodb.toS3Object("foo", "bar", "baz", "beep") Output: { "S" : "{ \"s3\" : { \"key\" : \"foo\", \"bucket\" : \"bar\", \"region\" : \"baz\", \"version\" = \"beep\" } }" } ``` ** `$util.dynamodb.toS3ObjectJson(String key, String bucket, String region, String version) : String` ** 與 相同`$util.dynamodb.toS3Object(String key, String bucket, String region, String version) : Map`，但 會以 JSON 編碼字串的形式傳回 DynamoDB 屬性值。 ** `$util.dynamodb.fromS3ObjectJson(String) : Map` ** 接受 DynamoDB S3 物件的字串值，並傳回包含金鑰、儲存貯體、區域和選用版本的映射。 ``` Input: $util.dynamodb.fromS3ObjectJson({ "S" : "{ \"s3\" : { \"key\" : \"foo\", \"bucket\" : \"bar\", \"region\" : \"baz\", \"version\" = \"beep\" } }" }) Output: { "key" : "foo", "bucket" : "bar", "region" : "baz", "version" : "beep" } ``` # \$1util.rds 中的 Amazon RDS 協助程式 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$util.rds` 包含協助程式方法，透過消除結果輸出中的外部資料來格式化 Amazon RDS 操作。 ## \$1util.rds utils 清單 ****`$util.rds.toJsonString(String serializedSQLResult): String`**** 透過將字串化原始 Amazon Relational Database Service (Amazon RDS) Data API 操作結果格式`String`轉換為更簡潔的字串，傳回 。傳回的字串是結果集的 SQL 記錄序列化清單。每筆記錄都會顯示為鍵值對集合。索引鍵是對應的欄位名稱。 如果輸入中的對應陳述式是造成變動的 SQL 查詢 （例如 INSERT、UPDATE、DELETE)，則會傳回空清單。例如，查詢`select * from Books limit 2`提供來自 Amazon RDS Data 操作的原始結果： ``` { "sqlStatementResults": [ { "numberOfRecordsUpdated": 0, "records": [ [ { "stringValue": "Mark Twain" }, { "stringValue": "Adventures of Huckleberry Finn" }, { "stringValue": "978-1948132817" } ], [ { "stringValue": "Jack London" }, { "stringValue": "The Call of the Wild" }, { "stringValue": "978-1948132275" } ] ], "columnMetadata": [ { "isSigned": false, "isCurrency": false, "label": "author", "precision": 200, "typeName": "VARCHAR", "scale": 0, "isAutoIncrement": false, "isCaseSensitive": false, "schemaName": "", "tableName": "Books", "type": 12, "nullable": 0, "arrayBaseColumnType": 0, "name": "author" }, { "isSigned": false, "isCurrency": false, "label": "title", "precision": 200, "typeName": "VARCHAR", "scale": 0, "isAutoIncrement": false, "isCaseSensitive": false, "schemaName": "", "tableName": "Books", "type": 12, "nullable": 0, "arrayBaseColumnType": 0, "name": "title" }, { "isSigned": false, "isCurrency": false, "label": "ISBN-13", "precision": 15, "typeName": "VARCHAR", "scale": 0, "isAutoIncrement": false, "isCaseSensitive": false, "schemaName": "", "tableName": "Books", "type": 12, "nullable": 0, "arrayBaseColumnType": 0, "name": "ISBN-13" } ] } ] } ``` `util.rds.toJsonString` 是： ``` [ { "author": "Mark Twain", "title": "Adventures of Huckleberry Finn", "ISBN-13": "978-1948132817" }, { "author": "Jack London", "title": "The Call of the Wild", "ISBN-13": "978-1948132275" }, ] ``` ****`$util.rds.toJsonObject(String serializedSQLResult): Object`**** 這與 相同`util.rds.toJsonString`，但結果為 JSON `Object`。 # \$1util.http 中的 HTTP 協助程式 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$util.http` 公用程式提供協助程式方法，您可以用來管理 HTTP 請求參數和新增回應標頭。 ## \$1util.http utils 清單 ** `$util.http.copyHeaders(Map) : Map` ** 從映射複製標頭，不包括下列受限 HTTP 標頭： + transfer-encoding + connection + host + expect + keep-alive + upgrade + proxy-authenticate + proxy-authorization + te + content-length 您可以使用此公用程式將請求標頭轉送至下游 HTTP 端點。 ``` { ... "params": { ... "headers": $util.http.copyHeaders($ctx.request.headers), ... }, ... } ``` **\$1util.http.addResponseHeader（字串、物件）** 新增具有回應名稱 (`String`) 和值 (`Object`) 的單一自訂標頭。有下列限制： + 除了 的限制標頭清單之外`copyHeaders(Map)`，標頭名稱也不符合下列任何項目： + Access-Control-Allow-Credentials + Access-Control-Allow-Origin + Access-Control-Expose-Headers + Access-Control-Max-Age + Access-Control-Allow-Methods + Access-Control-Allow-Headers + Vary + Content-Type + 標頭名稱不能以限制字首`x-amzn-`或 開頭`x-amz-`。 + 自訂回應標頭的大小不能超過 4 KB。這包括標頭名稱和值。 + 您應該為每個 GraphQL 操作定義每個回應標頭一次。不過，如果您多次定義同名的自訂標頭，最近的定義會出現在回應中。無論命名為何，所有標頭都會計入標頭大小限制。 + 具有空白或限制名稱`(String)`或 null 值的標頭`(Object)`將被忽略，並產生新增到操作`errors`輸出的`ResponseHeaderError`錯誤。 ``` export function request(ctx) { util.http.addResponseHeader('itemsCount', 7) util.http.addResponseHeader('render', ctx.args.render) return {} } ``` ****`$util.http.addResponseHeaders(Map)`**** 從指定的名稱`(String)`和值映射將多個回應標頭新增至回應`(Object)`。為 `addResponseHeader(String, Object)`方法列出的相同限制也適用於此方法。 ``` export function request(ctx) { const headers = { headerInt: 12, headerString: 'stringValue', headerObject: { field1: 7, field2: 'string' } } util.http.addResponseHeaders(headers) return {} } ``` # \$1util.xml 中的 XML 協助程式 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$util.xml` 包含協助程式方法，可讓您更輕鬆地將 XML 回應轉譯為 JSON 或字典。 ## \$1util.xml utils 清單 ****`$util.xml.toMap(String) : Map`**** 將 XML 字串轉換為字典。 ``` Input: 1 Getting started with GraphQL Output (JSON representation): { "posts":{ "post":{ "id":1, "title":"Getting started with GraphQL" } } } Input: 1 Getting started with GraphQL 2 Getting started with AWS AppSync Output (JSON representation): { "posts":{ "post":[ { "id":1, "title":"Getting started with GraphQL" }, { "id":2, "title":"Getting started with AWS AppSync" } ] } } ``` ****`$util.xml.toJsonString(String) : String`**** 將 XML 字串轉換為 JSON 字串。這類似於 *toMap*，但輸出是字串。如果要將來自 HTTP 物件的 XML 回應直接轉換並傳回給 JSON，這非常實用。 ****`$util.xml.toJsonString(String, Boolean) : String`**** 將 XML 字串轉換為具有選用布林值參數的 JSON 字串，以判斷您是否要對 JSON 進行字串編碼。 # \$1util.transform 中的轉換協助程式 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$util.transform` 包含協助程式方法，可讓您更輕鬆地對資料來源執行複雜的操作，例如 Amazon DynamoDB 篩選操作。 ## 轉換協助程式 ### 轉換協助程式使用清單 ****`$util.transform.toDynamoDBFilterExpression(Map) : Map`**** 將輸入字串轉換為篩選條件表達式，以搭配 DynamoDB 使用。 ``` Input: $util.transform.toDynamoDBFilterExpression({ "title":{ "contains":"Hello World" } }) Output: { "expression" : "contains(#title, :title_contains)" "expressionNames" : { "#title" : "title", }, "expressionValues" : { ":title_contains" : { "S" : "Hello World" } }, } ``` ****`$util.transform.toElasticsearchQueryDSL(Map) : Map`**** 將指定的輸入轉換為其同等的 OpenSearch Query DSL 表達式，將其傳回為 JSON 字串。 ``` Input: $util.transform.toElasticsearchQueryDSL({ "upvotes":{ "ne":15, "range":[ 10, 20 ] }, "title":{ "eq":"hihihi", "wildcard":"h*i" } }) Output: { "bool":{ "must":[ { "bool":{ "must":[ { "bool":{ "must_not":{ "term":{ "upvotes":15 } } } }, { "range":{ "upvotes":{ "gte":10, "lte":20 } } } ] } }, { "bool":{ "must":[ { "term":{ "title":"hihihi" } }, { "wildcard":{ "title":"h*i" } } ] } } ] } } ``` 預設運算子假設為 AND。 ## 轉換協助程式訂閱篩選條件 ### 轉換協助程式訂閱篩選條件使用清單 ****`$util.transform.toSubscriptionFilter(Map) : Map`**** 將`Map`輸入物件轉換為`SubscriptionFilter`表達式物件。`$util.transform.toSubscriptionFilter` 方法用作`$extensions.setSubscriptionFilter()`延伸模組的輸入。如需詳細資訊，請參閱[延伸模組](https://docs.aws.amazon.com/appsync/latest/devguide/extensions)。 ****`$util.transform.toSubscriptionFilter(Map, List) : Map`**** 將`Map`輸入物件轉換為`SubscriptionFilter`表達式物件。`$util.transform.toSubscriptionFilter` 方法用作`$extensions.setSubscriptionFilter()`延伸模組的輸入。如需詳細資訊，請參閱[延伸模組](https://docs.aws.amazon.com/appsync/latest/devguide/extensions)。 第一個引數是轉換為`SubscriptionFilter`表達式物件的`Map`輸入物件。第二個引數是在建構`SubscriptionFilter`表達式物件時在第一個`Map`輸入物件中忽略`List`的欄位名稱。 ****`$util.transform.toSubscriptionFilter(Map, List, Map) : Map`**** 將`Map`輸入物件轉換為`SubscriptionFilter`表達式物件。`$util.transform.toSubscriptionFilter` 方法用作`$extensions.setSubscriptionFilter()`延伸模組的輸入。如需詳細資訊，請參閱 [延伸模組](https://docs.aws.amazon.com/appsync/latest/devguide/extensions)。 第一個引數是轉換為`SubscriptionFilter`表達式物件的`Map`輸入物件，第二個引數是在第一個`Map`輸入物件中忽略`List`的欄位名稱，第三個引數是建構`SubscriptionFilter`表達式物件時包含的嚴格規則的`Map`輸入物件。這些嚴格的規則包含在`SubscriptionFilter`表達式物件中，方式是至少滿足其中一個規則以傳遞訂閱篩選條件。 ## 訂閱篩選條件引數 下表說明如何定義下列公用程式的引數： + `$util.transform.toSubscriptionFilter(Map) : Map` + `$util.transform.toSubscriptionFilter(Map, List) : Map` + `$util.transform.toSubscriptionFilter(Map, List, Map) : Map` ------ #### [ Argument 1: Map ] 引數 1 是具有下列索引鍵值的`Map`物件： + 欄位名稱 + 「和」 + 「或」 對於做為索引鍵的欄位名稱，這些欄位項目的條件格式為 `"operator" : "value"`。 下列範例顯示如何將項目新增至 `Map`： ``` "field_name" : { "operator1" : value } ## We can have multiple conditions for the same field_name: "field_name" : { "operator1" : value "operator2" : value . . . } ``` 當欄位上有兩個或多個條件時，所有這些條件都會被視為使用 OR 操作。 輸入`Map`也可以將「和」和「或」做為索引鍵，表示這些輸入中的所有項目都應該使用 AND 或 OR 邏輯聯結，視索引鍵而定。鍵值「和」和「或」預期有一系列條件。 ``` "and" : [ { "field_name1" : { "operator1" : value } }, { "field_name2" : { "operator1" : value } }, . . ]. ``` 請注意，您可以巢狀化「和」和「或」。也就是說，您可以在另一個「和」/」或」區塊中巢狀「和」/」或「或」。不過，這不適用於簡單的欄位。 ``` "and" : [ { "field_name1" : { "operator" : value } }, { "or" : [ { "field_name2" : { "operator" : value } }, { "field_name3" : { "operator" : value } } ]. ``` 下列範例顯示使用 *輸入引數 1*`$util.transform.toSubscriptionFilter(Map) : Map`。 **Input(s)** 引數 1：映射： ``` { "percentageUp": { "lte": 50, "gte": 20 }, "and": [ { "title": { "ne": "Book1" } }, { "downvotes": { "gt": 2000 } } ], "or": [ { "author": { "eq": "Admin" } }, { "isPublished": { "eq": false } } ] } ``` **輸出** 結果是`Map`物件： ``` { "filterGroup": [ { "filters": [ { "fieldName": "percentageUp", "operator": "lte", "value": 50 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "author", "operator": "eq", "value": "Admin" } ] }, { "filters": [ { "fieldName": "percentageUp", "operator": "lte", "value": 50 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "isPublished", "operator": "eq", "value": false } ] }, { "filters": [ { "fieldName": "percentageUp", "operator": "gte", "value": 20 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "author", "operator": "eq", "value": "Admin" } ] }, { "filters": [ { "fieldName": "percentageUp", "operator": "gte", "value": 20 }, { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 2000 }, { "fieldName": "isPublished", "operator": "eq", "value": false } ] } ] } ``` ------ #### [ Argument 2: List ] 引數 2 包含建構`SubscriptionFilter`表達式物件時不應在輸入中考慮`List`的一組欄位名稱 `Map`（引數 1)。`List` 也可以是空的。 下列範例顯示使用 輸入引數 1 和引數 2`$util.transform.toSubscriptionFilter(Map, List) : Map`。 **Input(s)** 引數 1：映射： ``` { "percentageUp": { "lte": 50, "gte": 20 }, "and": [ { "title": { "ne": "Book1" } }, { "downvotes": { "gt": 20 } } ], "or": [ { "author": { "eq": "Admin" } }, { "isPublished": { "eq": false } } ] } ``` 引數 2：列出： ``` ["percentageUp", "author"] ``` **輸出** 結果是`Map`物件： ``` { "filterGroup": [ { "filters": [ { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 20 }, { "fieldName": "isPublished", "operator": "eq", "value": false } ] } ] } ``` ------ #### [ Argument 3: Map ] 引數 3 是具有欄位名稱作為索引鍵值的`Map`物件 （不能具有「和」或「或」)。對於做為索引鍵的欄位名稱，這些欄位的條件是 形式的項目`"operator" : "value"`。與引數 1 不同，引數 3 不能在同一個索引鍵中有多個條件。此外，引數 3 沒有「和」或「或」子句，因此也沒有涉及巢狀。 引數 3 代表新增至`SubscriptionFilter`表達式物件的嚴格規則清單，因此**至少符合其中一個**條件以傳遞篩選條件。 ``` { "fieldname1": { "operator": value }, "fieldname2": { "operator": value } } . . . ``` 下列範例顯示使用 的*引數 1*、*引數 2* 和*引數 3* 的輸入`$util.transform.toSubscriptionFilter(Map, List, Map) : Map`。 **Input(s)** 引數 1：映射： ``` { "percentageUp": { "lte": 50, "gte": 20 }, "and": [ { "title": { "ne": "Book1" } }, { "downvotes": { "lt": 20 } } ], "or": [ { "author": { "eq": "Admin" } }, { "isPublished": { "eq": false } } ] } ``` 引數 2：列出： ``` ["percentageUp", "author"] ``` 引數 3：映射： ``` { "upvotes": { "gte": 250 }, "author": { "eq": "Person1" } } ``` **輸出** 結果是`Map`物件： ``` { "filterGroup": [ { "filters": [ { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 20 }, { "fieldName": "isPublished", "operator": "eq", "value": false }, { "fieldName": "upvotes", "operator": "gte", "value": 250 } ] }, { "filters": [ { "fieldName": "title", "operator": "ne", "value": "Book1" }, { "fieldName": "downvotes", "operator": "gt", "value": 20 }, { "fieldName": "isPublished", "operator": "eq", "value": false }, { "fieldName": "author", "operator": "eq", "value": "Person1" } ] } ] } ``` ------ # \$1util.math 中的數學協助程式 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$util.math` 包含可協助處理常見數學操作的方法。 ## \$1util.math utils 清單 ** `$util.math.roundNum(Double) : Integer` ** 採取雙數並四捨五入到最接近的整數。 ** `$util.math.minVal(Double, Double) : Double` ** 需要兩個倍數，並傳回兩個倍數之間的最小值。 ** `$util.math.maxVal(Double, Double) : Double` ** 需要兩個倍數，並傳回兩個倍數之間的最大值。 ** `$util.math.randomDouble() : Double` ** 傳回介於 0 和 1 之間的隨機倍數。 此函數不應用於需要高熵隨機性 （例如密碼編譯） 的任何內容。 ** `$util.math.randomWithinRange(Integer, Integer) : Integer` ** 傳回指定範圍內的隨機整數值，第一個引數指定範圍的較低值，第二個引數指定範圍的上限值。 此函數不應用於需要高熵隨機性 （例如密碼編譯） 的任何內容。 # \$1util.str 中的字串協助程式 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$util.str` 包含有助於常見字串操作的方法。 ## \$1util.str utils 清單 ** `$util.str.toUpper(String) : String` ** 採用字串並將其轉換為完全大寫。 ** `$util.str.toLower(String) : String` ** 採用字串並將其轉換為完全小寫。 ** `$util.str.toReplace(String, String, String) : String` ** 將字串中的子字串取代為另一個字串。第一個引數指定要在其中執行取代操作的字串。第二個引數指定要取代的子字串。第三個引數指定要取代第二個引數的字串。以下是此公用程式使用的範例： ``` INPUT: $util.str.toReplace("hello world", "hello", "mellow") OUTPUT: "mellow world" ``` ** `$util.str.normalize(String, String) : String` ** 使用四種 Unicode 標準化形式之一來標準化字串：NFC、NFD、NFKC 或 NFKD。第一個引數是要標準化的字串。第二個引數是 "nfc"、"nfd"、"nfkc" 或 "nfkd"，指定用於標準化程序的標準化類型。 # 延伸模組 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$extensions` 包含一組方法，可在解析程式中執行其他動作。 ## 快取擴充功能 **`$extensions.evictFromApiCache(String, String, Object) : Object`** 從 AWS AppSync 伺服器端快取中移出項目。第一個引數是類型名稱。第二個引數是欄位名稱。第三個引數是包含金鑰值對項目的物件，可指定快取金鑰值。您必須以與快取解析程式 中的快取金鑰相同的順序，將項目放在物件中`cachingKey`。 此公用程式僅適用於變動，不適用於查詢。 ## 訂閱擴充功能 **`$extensions.setSubscriptionFilter(filterJsonObject)`** 定義增強型訂閱篩選條件。每個訂閱通知事件都會根據提供的訂閱篩選條件進行評估，並在所有篩選條件評估為 時傳送通知給用戶端`true`。引數`filterJsonObject`如下節所述。 您只能在訂閱解析程式的回應映射範本中使用此延伸方法。 **`$extensions.setSubscriptionInvalidationFilter(filterJsonObject)`** 定義訂閱失效篩選條件。系統會針對失效承載評估訂閱篩選條件，如果篩選條件評估為 ，則會使指定的訂閱失效`true`。引數`filterJsonObject`如下節所述。 您只能在訂閱解析程式的回應映射範本中使用此延伸方法。 **`$extensions.invalidateSubscriptions(invalidationJsonObject)`** 用來從變動啟動訂閱失效。引數`invalidationJsonObject`如下節所述。 此延伸模組只能用於變動解析程式的回應映射範本。 在任何單一請求中，您最多只能使用五個唯一的`$extensions.invalidateSubscriptions()`方法呼叫。如果您超過此限制，您將會收到 GraphQL 錯誤。 ## 引數：filterJsonObject JSON 物件會定義訂閱或失效篩選條件。這是 中的一系列篩選條件`filterGroup`。每個篩選條件都是個別篩選條件的集合。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 } ] }, { "filters" : [ { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` 每個篩選條件都有三個屬性： + `fieldName` – GraphQL 結構描述欄位。 + `operator` – 運算子類型。 + `value` – 要與訂閱通知值比較`fieldName`的值。 以下是這些屬性的範例指派： ``` { "fieldName" : "severity", "operator" : "le", "value" : $context.result.severity } ``` ### 欄位：fieldName 字串類型`fieldName`是指在 GraphQL 結構描述中定義的欄位，符合訂閱通知承載`fieldName`中的 。找到相符項目時，GraphQL 結構描述欄位`value`的 會與訂閱通知篩選條件`value`的 進行比較。在下列範例中，`fieldName`篩選條件符合指定 GraphQL 類型中定義的`service`欄位。如果通知承載包含等於 `value` `service`的欄位`AWS AppSync`，則篩選條件會評估為 `true`： ``` { "fieldName" : "service", "operator" : "eq", "value" : "AWS AppSync" } ``` ### 欄位：值 根據運算子，值可以是不同的類型： + 單一數字或布林值 + 字串範例：`"test"`、 `"service"` + 數字範例：`1`、`2`、 `45.75` + 布林值範例：`true`、 `false` + 一組數字或字串 + 字串對範例：`["test1","test2"]`、 `["start","end"]` + 數字對範例：`[1,4]`、`[67,89]`、 `[12.45, 95.45]` + 數字或字串陣列 + 字串陣列範例： `["test1","test2","test3","test4","test5"]` + 數字陣列範例：`[1,2,3,4,5]`、 `[12.11,46.13,45.09,12.54,13.89]` ### 欄位：運算子 具有下列可能值的區分大小寫字串： | | | 運算子 | Description | 可能的值類型 | | --- |--- |--- | | eq | Equal | integer, float, string, Boolean | | ne | Not equal | integer, float, string, Boolean | | le | Less than or equal | integer, float, string | | lt | Less than | integer, float, string | | ge | Greater than or equal | integer, float, string | | gt | Greater than | integer, float, string | | contains | Checks for a subsequence or value in the set. | integer, float, string | | notContains | Checks for the absence of a subsequence or absence of a value in the set. | integer, float, string | | beginsWith | Checks for a prefix. | string | | in | Checks for matching elements that are in the list. | Array of integer, float, or string | | notIn | Checks for matching elements that aren't in the list. | Array of integer, float, or string | | between | Between two values | integer, float, string | | containsAny | Contains common elements | integer, float, string | 下表說明訂閱通知中每個運算子的使用方式。 ------ #### [ eq (equal) ] 如果`true`訂閱通知欄位值相符且嚴格等於篩選條件的值，則`eq`運算子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值等於 `service`的欄位`AWS AppSync`。 **可能的值類型：**整數、浮點數、字串、布林值 ``` { "fieldName" : "service", "operator" : "eq", "value" : "AWS AppSync" } ``` ------ #### [ ne (not equal) ] 如果`true`訂閱通知欄位值與篩選條件的值不同，運算`ne`子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值與 不同的`service`欄位`AWS AppSync`。 **可能的值類型：**整數、浮點數、字串、布林值 ``` { "fieldName" : "service", "operator" : "ne", "value" : "AWS AppSync" } ``` ------ #### [ le (less or equal) ] 如果`true`訂閱通知欄位值小於或等於篩選條件的值，`le`運算子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值小於或等於 `size`的欄位`5`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "size", "operator" : "le", "value" : 5 } ``` ------ #### [ lt (less than) ] 如果`true`訂閱通知欄位值低於篩選條件的值，運算`lt`子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值低於 `size`的欄位`5`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "size", "operator" : "lt", "value" : 5 } ``` ------ #### [ ge (greater or equal) ] 如果`true`訂閱通知欄位值大於或等於篩選條件的值，運算`ge`子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值大於或等於 `size`的欄位`5`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "size", "operator" : "ge", "value" : 5 } ``` ------ #### [ gt (greater than) ] 如果`true`訂閱通知欄位值大於篩選條件的值，運算`gt`子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值大於 `size`的欄位`5`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "size", "operator" : "gt", "value" : 5 } ``` ------ #### [ contains ] `contains` 運算子會檢查集合或單一項目中的子字串、子序列或值。如果訂閱通知欄位值包含篩選條件值，則具有 `contains` 運算子的篩選條件會評估`true`為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有`seats`欄位的陣列值包含值 `10`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "seats", "operator" : "contains", "value" : 10 } ``` 在另一個範例中，篩選條件會評估訂閱通知`true`是否具有 `launch`做為子字串`event`的欄位。 ``` { "fieldName" : "event", "operator" : "contains", "value" : "launch" } ``` ------ #### [ notContains ] `notContains` 運算子會檢查集合或單一項目中是否存在子字串、子序列或值。如果訂閱通知欄位值不包含篩選條件值`true`，則具有 `notContains` 運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否具有陣列值不包含值 `seats`的欄位`10`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "seats", "operator" : "notContains", "value" : 10 } ``` 在另一個範例中，篩選條件會評估訂閱通知`true`是否具有 `launch`作為其子序列的 `event` 欄位值。 ``` { "fieldName" : "event", "operator" : "notContains", "value" : "launch" } ``` ------ #### [ beginsWith ] `beginsWith` 運算子會檢查字串中的字首。如果訂閱通知欄位值以篩選條件的值開頭`true`，則包含`beginsWith`運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值開頭為 `service`的欄位`AWS`。 **可能的值類型：**字串 ``` { "fieldName" : "service", "operator" : "beginsWith", "value" : "AWS" } ``` ------ #### [ in ] `in` 運算子會檢查陣列中的相符元素。如果訂閱通知欄位值存在於陣列中`true`，包含 `in` 運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有`severity`欄位具有陣列中存在的其中一個值：`[1,2,3]`。 **可能的值類型：**整數陣列、浮點數或字串 ``` { "fieldName" : "severity", "operator" : "in", "value" : [1,2,3] } ``` ------ #### [ notIn ] `notIn` 運算子會檢查陣列中是否有遺失的元素。如果訂閱通知欄位值不存在於陣列中`true`，則包含`notIn`運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有`severity`欄位，其中包含陣列中不存在的其中一個值：`[1,2,3]`。 **可能的值類型：**整數陣列、浮點數或字串 ``` { "fieldName" : "severity", "operator" : "notIn", "value" : [1,2,3] } ``` ------ #### [ between ] `between` 運算子會檢查兩個數字或字串之間的值。如果訂閱通知欄位值介於篩選條件的值對之間`true`，則包含`between`運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否具有值為 `2`、`3`、 `severity`的欄位`4`。 **可能的值類型：**整數、浮點數或字串的配對 ``` { "fieldName" : "severity", "operator" : "between", "value" : [1,5] } ``` ------ #### [ containsAny ] `containsAny` 運算子會檢查陣列中的常見元素。如果訂閱通知欄位集值和篩選條件集值的交集不是空的`true`，則具有 `containsAny` 運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否具有陣列值包含 `10`或 `seats`的欄位`15`。這表示`true`如果訂閱通知`seats`的欄位值為 `[10,11]`或 ，篩選條件會評估為 `[15,20,30]`。 **可能的值類型：**整數、浮點數或字串 ``` { "fieldName" : "seats", "operator" : "containsAny", "value" : [10, 15] } ``` ------ ### AND 邏輯 您可以使用 AND 邏輯結合多個篩選條件，方法是在`filterGroup`陣列中的 `filters` 物件中定義多個項目。在下列範例中，篩選條件會評估訂閱通知`true`是否有 欄位`userId`的值等於 `1` AND `group` 欄位值 `Admin`或 `Developer`。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 }, { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` ### OR 邏輯 您可以在`filterGroup`陣列中定義多個篩選條件物件，以使用 OR 邏輯結合多個篩選條件。在下列範例中，篩選條件會評估訂閱通知`true`是否有欄位`userId`的值等於 `1` OR `group` 欄位值 `Admin`或 `Developer`。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 } ] }, { "filters" : [ { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` ### 例外狀況 請注意，使用篩選條件有幾項限制： + 在 `filters` 物件中，每個篩選條件最多可以有五個唯一`fieldName`項目。這表示您最多可以使用 AND 邏輯結合五個個別`fieldName`物件。 + 運算`containsAny`子最多可有 20 個值。 + `in` 和 `notIn`運算子最多可有五個值。 + 每個字串最多可有 256 個字元。 + 每個字串比較都區分大小寫。 + 巢狀物件篩選最多允許五個巢狀層級的篩選。 + 每個 `filterGroup` 最多可有 10 個 `filters`。這表示您可以使用 `filters` OR 邏輯結合最多 10 個。 + `in` 運算子是 OR 邏輯的特殊案例。在下列範例中，有兩個 `filters`： ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 }, { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` 上述篩選條件群組的評估如下所示，並計入最大篩選條件限制： ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 }, { "fieldName" : "group", "operator" : "eq", "value" : "Admin" } ] }, { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 }, { "fieldName" : "group", "operator" : "eq", "value" : "Developer" } ] } ] } ``` ## 引數： invalidationJsonObject `invalidationJsonObject` 定義下列項目： + `subscriptionField` – 要失效的 GraphQL 結構描述訂閱。定義為 中字串的單一訂閱`subscriptionField`會被視為失效。 + `payload` – 金鑰/值對清單，當失效篩選條件`true`根據其值評估為 時，此清單會做為使訂閱失效的輸入。 當訂閱解析程式中定義的失效篩選條件`true`針對 `payload`值評估為 時，下列範例會使用`onUserDelete`訂閱使已訂閱和已連線的用戶端失效。 ``` $extensions.invalidateSubscriptions({ "subscriptionField": "onUserDelete", "payload": { "group": "Developer" "type" : "Full-Time" } }) ```