本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# \$1util 中的实用程序帮助程序
<a name="utility-helpers-in-util"></a>

**注意**  
我们现在主要支持 APPSYNC\$1JS 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。

`$util` 变量包含帮助您处理数据的常规实用程序方法。除非另行指定，否则所有实用程序均使用 UTF-8 字符集。

## JSON 解析实用程序
<a name="utility-helpers-in-json-parsing"></a>

### JSON 解析实用程序列表
<a name="utility-helpers-in-json-parsing-list"></a>

** **`$util.parseJson(String) : Object`** **  
获取“字符串化的”JSON 并返回结果的对象表示形式。

** **`$util.toJson(Object) : String`** **  
获取对象并返回该对象“字符串化的”JSON 表示形式。

## 编码实用程序
<a name="utility-helpers-in-encoding"></a>

### 编码实用程序列表
<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 生成实用程序
<a name="utility-helpers-in-id-gen"></a>

### ID 生成实用程序列表
<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 可排序唯一标识符），它使用 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` 字段。将在 GraphQL 响应中 `data` 内部对应的 `error` 块中添加 `errors` 值。  
`data` 将根据查询选择集进行筛选。

** `$util.error(String, String, Object, Object)` **  
引发自定义错误。如果模板检测到请求或调用结果的错误，可用于请求或响应映射模板中。此外，还可以指定 `errorType`、`data` 和 `errorInfo` 字段。将在 GraphQL 响应中 `data` 内部对应的 `error` 块中添加 `errors` 值。  
`data` 将根据查询选择集进行筛选。将在 GraphQL 响应中 `errorInfo` 内部对应的 `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)` 不同，不会中断模板评估，因此，可以向调用方返回数据。将在 GraphQL 响应中 `data` 内部对应的 `error` 块中添加 `errors` 值。  
`data` 将根据查询选择集进行筛选。

** `$util.appendError(String, String, Object, Object)` **  
追加自定义错误。如果模板检测到请求或调用结果的错误，可用于请求或响应映射模板中。此外，还可以指定 `errorType`、`data` 和 `errorInfo` 字段。与 `$util.error(String, String, Object, Object)` 不同，不会中断模板评估，因此，可以向调用方返回数据。将在 GraphQL 响应中 `data` 内部对应的 `error` 块中添加 `errors` 值。  
`data` 将根据查询选择集进行筛选。将在 GraphQL 响应中 `errorInfo` 内部对应的 `error` 块中添加 `errors` 值。  
`errorInfo` **不会**根据查询选择集进行筛选。

## 条件验证实用程序
<a name="utility-helpers-in-condition"></a>

### 条件验证实用程序列表
<a name="utility-helpers-in-condition-list"></a>

** `$util.validate(Boolean, String) : void` **  
如果条件为假，则 CustomTemplateException 使用指定的消息抛出 a。

** `$util.validate(Boolean, String, String) : void` **  
如果条件为 false，则 CustomTemplateException 使用指定的消息和错误类型抛出。

** `$util.validate(Boolean, String, String, Object) : void` **  
如果条件为 false，则抛出 a， CustomTemplateException 其中包含指定的消息和错误类型，以及要在响应中返回的数据。

## Null 行为实用程序
<a name="utility-helpers-in-null-behavior"></a>

### Null 行为实用程序列表
<a name="utility-helpers-in-null-behavior-list"></a>

** `$util.isNull(Object) : Boolean` **  
如果提供的对象为 null 则返回 true。

** `$util.isNullOrEmpty(String) : Boolean` **  
如果提供的数据为 null 或空字符串，则返回 true。否则返回 false。

** `$util.isNullOrBlank(String) : Boolean` **  
如果提供的数据为 null 或空白字符串，则返回 true。否则返回 false。

** `$util.defaultIfNull(Object, Object) : Object` **  
如果首个对象非 null，则返回它。否则返回第二个对象，作为“默认对象”。

** `$util.defaultIfNullOrEmpty(String, String) : String` **  
如果首个字符串非 null 也非空，则返回它。否则返回第二个字符串，作为“默认字符串”。

** `$util.defaultIfNullOrBlank(String, String) : String` **  
如果首个字符串非 null 也非空白，则返回它。否则返回第二个字符串，作为“默认字符串”。

## 模式匹配实用程序
<a name="utility-helpers-in-pattern-matching"></a>

### 类型和模式匹配实用程序列表
<a name="utility-helpers-in-type-pattern-matching-list"></a>

** `$util.typeOf(Object) : String` **  
返回字符串，描述对象的类型。支持的类型标识为："Null"、"Number"、"String"、"Map"、"List"、"Boolean"。如果无法识别类型，则返回 "Object" 类型。

** `$util.matches(String, String) : Boolean` **  
如果在第一个参数中指定的模式与第二个参数中提供的数据匹配，则返回 true。模式必须为正则表达式，例如 `$util.matches("a*b", "aaaaab")`。此功能以[模式](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html)为基础，您可参考其他文档，进一步了解此内容。

** `$util.authType() : String` **  
返回描述请求使用的多重身份验证类型的字符串，即，返回“IAM Authorization”、“User Pool Authorization”、“Open ID Connect Authorization”或“API Key Authorization”。

## 对象验证实用程序
<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 上启用了请求级别和字段级日志 CloudWatch 记录，则将所提供对象的字符串表示形式记录到请求的日志流`ALL``INFO`中。`DEBUG`

**`$util.log.info(String, Object...) : Void`**  
在 API 上启用请求级和字段级日志记录时，将所提供对象的字符串表示形式 CloudWatch 记录到请求的日志流中。`ALL`该实用程序按顺序将第一个输入格式字符串中由“\$1\$1”指示的所有变量替换为提供的对象的字符串表示形式。

**`$util.log.debug(Object) : Void`**  
当使用日志级别`ALL`或 `DEBUG` API 启用请求级和字段级日志 CloudWatch 记录时，将所提供对象的字符串表示形式记录到请求的日志流中。

**`$util.log.debug(String, Object...) : Void`**  
在 API 上使用日志级别`DEBUG`或日志级别启用字段级日志 CloudWatch 记录时，将所提供对象的字符串表示形式记录到请求的日志流中。`ALL`该实用程序按顺序将第一个输入格式字符串中由“\$1\$1”指示的所有变量替换为提供的对象的字符串表示形式。

**`$util.log.error(Object) : Void`**  
在 API 上启用**任何**日志级别（`ALL`、、`INFO`等）的字段级 CloudWatch 日志记录时，将所提供对象的字符串表示形式记录到请求的日志流中。`DEBUG`

**`$util.log.error(String, Object...) : Void`**  
在 API 上使用日志级别`ERROR`或日志级别启用字段级日志 CloudWatch 记录时，将所提供对象的字符串表示形式记录到请求的日志流中。`ALL`该实用程序按顺序将第一个输入格式字符串中由“\$1\$1”指示的所有变量替换为提供的对象的字符串表示形式。

## 返回值行为实用程序
<a name="utility-helpers-in-return-behavior"></a>

### 返回值行为实用程序列表
<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 可排序唯一标识符），它使用 Base62 编码为长度为 27 的字符串。  
** `$util.unauthorized()` **  
针对被解析的字段引发 `Unauthorized`。可以在请求或响应映射模板中使用该实用程序，以确定是否允许调用方解析该字段。  
** `$util.error(String)` **  
引发自定义错误。可以在请求或响应映射模板中使用该实用程序，以检测请求或调用结果的错误。  
** `$util.error(String, String)` **  
引发自定义错误。可以在请求或响应映射模板中使用该实用程序，以检测请求或调用结果的错误。您还可以指定 `errorType`。  
** `$util.error(String, String, Object)` **  
引发自定义错误。可以在请求或响应映射模板中使用该实用程序，以检测请求或调用结果的错误。您还可以指定 `errorType` 和 `data` 字段。将在 GraphQL 响应中 `data` 内部对应的 `error` 块中添加 `errors` 值。**注意**：将根据查询选择集筛选 `data`。  
** `$util.error(String, String, Object, Object)` **  
引发自定义错误。如果模板检测到请求或调用结果的错误，可用于请求或响应映射模板中。此外，还可指定 `errorType`、`data` 和 `errorInfo` 字段。将在 GraphQL 响应中 `data` 内部对应的 `error` 块中添加 `errors` 值。**注意**：将根据查询选择集筛选 `data`。将在 GraphQL 响应中 `errorInfo` 内部对应的 `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)` 不同，不会中断模板评估，因此，可以向调用方返回数据。将在 GraphQL 响应中 `data` 内部对应的 `error` 块中添加 `errors` 值。**注意**：将根据查询选择集筛选 `data`。  
** `$util.appendError(String, String, Object, Object)` **  
追加自定义错误。如果模板检测到请求或调用结果的错误，可用于请求或响应映射模板中。此外，还可指定 `errorType`、`data` 和 `errorInfo` 字段。与 `$util.error(String, String, Object, Object)` 不同，不会中断模板评估，因此，可以向调用方返回数据。将在 GraphQL 响应中 `data` 内部对应的 `error` 块中添加 `errors` 值。**注意**：将根据查询选择集筛选 `data`。将在 GraphQL 响应中 `errorInfo` 内部对应的 `error` 块中添加 `errors` 值。**注意**：`errorInfo`不会**根据查询选择集筛选 **。  
** `$util.validate(Boolean, String) : void` **  
如果条件为假，则 CustomTemplateException使用指定的消息抛出 a。  
** `$util.validate(Boolean, String, String) : void` **  
如果条件为 false，则 CustomTemplateException使用指定的消息和错误类型抛出。  
** `$util.validate(Boolean, String, String, Object) : void` **  
如果条件为 false，则抛出 a， CustomTemplateException其中包含指定的消息和错误类型，以及要在响应中返回的数据。  
** `$util.isNull(Object) : Boolean` **  
如果提供的对象为 null 则返回 true。  
** `$util.isNullOrEmpty(String) : Boolean` **  
如果提供的数据为 null 或空字符串，则返回 true。否则返回 false。  
** `$util.isNullOrBlank(String) : Boolean` **  
如果提供的数据为 null 或空白字符串，则返回 true。否则返回 false。  
** `$util.defaultIfNull(Object, Object) : Object` **  
如果首个对象非 null，则返回它。否则返回第二个对象，作为“默认对象”。  
** `$util.defaultIfNullOrEmpty(String, String) : String` **  
如果首个字符串非 null 也非空，则返回它。否则返回第二个字符串，作为“默认字符串”。  
** `$util.defaultIfNullOrBlank(String, String) : String` **  
如果首个字符串非 null 也非空白，则返回它。否则返回第二个字符串，作为“默认字符串”。  
** `$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。  
** `$util.typeOf(Object) : String` **  
返回字符串，描述对象的类型。支持的类型标识为："Null"、"Number"、"String"、"Map"、"List"、"Boolean"。如果无法识别类型，则返回 "Object" 类型。  
** `$util.matches(String, String) : Boolean` **  
如果在第一个参数中指定的模式与第二个参数中提供的数据匹配，则返回 true。模式必须为正则表达式，例如 `$util.matches("a*b", "aaaaab")`。此功能以[模式](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html)为基础，您可参考其他文档，进一步了解此内容。  
** `$util.authType() : String` **  
返回描述请求使用的多重身份验证类型的字符串，即，返回“IAM Authorization”、“User Pool Authorization”、“Open ID Connect Authorization”或“API Key Authorization”。  
****`$util.log.info(Object) : Void`****  
在 API 上启用请求级和字段级日志记录时，将所提供对象的字符串表示形式 CloudWatch记录到请求的日志流中。`ALL`  
****`$util.log.info(String, Object...) : Void`****  
在 API 上启用请求级和字段级日志记录时，将所提供对象的字符串表示形式 CloudWatch记录到请求的日志流中。`ALL`该实用程序按顺序将第一个输入格式字符串中由“\$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`。可以在请求或响应映射模板中使用该实用程序，以确定是否允许调用方解析该字段。