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

# \$1util 中的公用程式協助程式
<a name="utility-helpers-in-util"></a>

**注意**  
我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。

`$util` 變數包含可協助您處理資料的一般公用程式方法。除非另行指定，否則所有公用程式皆使用 UTF-8 字元集。

## JSON 剖析公用程式
<a name="utility-helpers-in-json-parsing"></a>

### JSON 剖析 utils 清單
<a name="utility-helpers-in-json-parsing-list"></a>

** **`$util.parseJson(String) : Object`** **  
採用「字串化」JSON，並傳回結果的物件呈現。

** **`$util.toJson(Object) : String`** **  
採用物件，並傳回該物件的「字串化」JSON 呈現。

## 編碼 utils
<a name="utility-helpers-in-encoding"></a>

### 編碼 utils 清單
<a name="utility-helpers-in-encoding-list"></a>

** **`$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
<a name="utility-helpers-in-id-gen"></a>

### ID 產生 utils 清單
<a name="utility-helpers-in-id-gen-list"></a>

** **`$util.autoId() : String`** **  
傳回 128 位元隨機產生的 UUID。

****`$util.autoUlid() : String`****  
傳回 128 位元隨機產生的 ULID （通用可排序序列識別符）。

****`$util.autoKsuid() : String`****  
傳回 128 位元隨機產生的 KSUID (K-Sortable Unique Identifier) base62，其編碼為長度為 27 的字串。

## 錯誤率
<a name="utility-helpers-in-error"></a>

### 錯誤使用率清單
<a name="utility-helpers-in-error-list"></a>

** `$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` **將不會**根據查詢選取集進行篩選。

## 條件驗證公用程式
<a name="utility-helpers-in-condition"></a>

### 條件驗證使用率清單
<a name="utility-helpers-in-condition-list"></a>

** `$util.validate(Boolean, String) : void` **  
如果條件為假，會擲回含指定訊息的 CustomTemplateException。

** `$util.validate(Boolean, String, String) : void` **  
如果條件為假，會擲回含指定訊息和錯誤類型的 CustomTemplateException。

** `$util.validate(Boolean, String, String, Object) : void` **  
如果條件為假，會擲回含指定訊息、錯誤類型以及在回應中回傳之資料的 CustomTemplateException。

## Null 行為 utils
<a name="utility-helpers-in-null-behavior"></a>

### Null 行為利用率清單
<a name="utility-helpers-in-null-behavior-list"></a>

** `$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
<a name="utility-helpers-in-pattern-matching"></a>

### 類型和模式比對 utils 清單
<a name="utility-helpers-in-type-pattern-matching-list"></a>

** `$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 金鑰授權」。

## 物件驗證公用程式
<a name="utility-helpers-in-object-validation"></a>

### 物件驗證公用程式清單
<a name="utility-helpers-in-object-validation-list"></a>

** `$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 記錄公用程式
<a name="utility-helpers-in-logging"></a>

### CloudWatch 記錄公用程式清單
<a name="utility-helpers-in-cloudwatch-logs"></a>

**`$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
<a name="utility-helpers-in-return-behavior"></a>

### 傳回值行為 utils 清單
<a name="utility-helpers-in-behavior-list"></a>

****`$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 逸出字串傳回輸入字串。

## 解析程式授權
<a name="utility-helpers-in-resolver-auth"></a>

### 解析程式授權清單
<a name="utility-helpers-in-resolver-auth-list"></a>

** `$util.unauthorized()` **  
擲回欲解析之欄位的 `Unauthorized`。在請求或回應映射範本中使用此選項，以決定是否允許發起人解析 欄位。