$util 中的实用程序帮助程序
注意
我们现在主要支持 APPSYNC_JS 运行时系统及其文档。请考虑使用 APPSYNC_JS 运行时系统和此处的指南。
$util
变量包含帮助您处理数据的常规实用程序方法。除非另行指定,否则所有实用程序均使用 UTF-8 字符集。
JSON 解析实用程序
-
$util.parseJson(String) : Object
-
获取“字符串化的”JSON 并返回结果的对象表示形式。
-
$util.toJson(Object) : String
-
获取对象并返回该对象“字符串化的”JSON 表示形式。
编码实用程序
-
$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 生成实用程序
-
$util.autoId() : String
-
返回 128 位随机生成的 UUID。
$util.autoUlid() : String
-
返回一个 128 位随机生成的 ULID(可按字典排序的通用唯一标识符)。
$util.autoKsuid() : String
-
返回一个 128 位随机生成的 KSUID(K 可排序唯一标识符),它使用 Base62 编码为长度为 27 的字符串。
错误实用程序
-
$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
-
如果条件为 false,引发具有指定消息的 CustomTemplateException。
-
$util.validate(Boolean, String, String) : void
-
如果条件为 false,引发具有指定消息和错误类型的 CustomTemplateException。
-
$util.validate(Boolean, String, String, Object) : void
-
如果条件为 false,引发具有指定消息和错误类型,以及响应中返回的数据的 CustomTemplateException。
Null 行为实用程序
-
$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.typeOf(Object) : String
-
返回字符串,描述对象的类型。支持的类型标识为:"Null"、"Number"、"String"、"Map"、"List"、"Boolean"。如果无法识别类型,则返回 "Object" 类型。
-
$util.matches(String, String) : Boolean
-
如果在第一个参数中指定的模式与第二个参数中提供的数据匹配,则返回 true。模式必须为正则表达式,例如
$util.matches("a*b", "aaaaab")
。此功能以模式为基础,您可参考其他文档,进一步了解此内容。 -
$util.authType() : String
-
返回描述请求使用的多重身份验证类型的字符串,即,返回“IAM Authorization”、“User Pool Authorization”、“Open ID Connect Authorization”或“API Key Authorization”。
对象验证实用程序
-
$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 日志记录实用程序
$util.log.info(Object) : Void
-
在 API 上使用日志级别
ALL
启用请求级和字段级 CloudWatch 日志记录时,将提供的对象的字符串表示形式记录到请求的日志流中。 $util.log.info(String, Object...) : Void
-
在 API 上使用日志级别
ALL
启用请求级和字段级 CloudWatch 日志记录时,将提供的对象的字符串表示形式记录到请求的日志流中。该实用程序按顺序将第一个输入格式字符串中由“{}”指示的所有变量替换为提供的对象的字符串表示形式。 $util.log.error(Object) : Void
-
在 API 上使用日志级别
ERROR
或日志级别ALL
启用字段级 CloudWatch 日志记录时,将提供的对象的字符串表示形式记录到请求的日志流中。 $util.log.error(String, Object...) : Void
-
在 API 上使用日志级别
ERROR
或日志级别ALL
启用字段级 CloudWatch 日志记录时,将提供的对象的字符串表示形式记录到请求的日志流中。该实用程序按顺序将第一个输入格式字符串中由“{}”指示的所有变量替换为提供的对象的字符串表示形式。
返回值行为实用程序
$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
-
如果条件为 false,引发具有指定消息的 CustomTemplateException。
-
$util.validate(Boolean, String, String) : void
-
如果条件为 false,引发具有指定消息和错误类型的 CustomTemplateException。
-
$util.validate(Boolean, String, String, Object) : void
-
如果条件为 false,引发具有指定消息和错误类型,以及响应中返回的数据的 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")
。此功能以模式为基础,您可参考其他文档,进一步了解此内容。 -
$util.authType() : String
-
返回描述请求使用的多重身份验证类型的字符串,即,返回“IAM Authorization”、“User Pool Authorization”、“Open ID Connect Authorization”或“API Key Authorization”。
$util.log.info(Object) : Void
-
在 API 上使用日志级别
ALL
启用请求级和字段级 CloudWatch 日志记录时,将提供的对象的字符串表示形式记录到请求的日志流中。 $util.log.info(String, Object...) : Void
-
在 API 上使用日志级别
ALL
启用请求级和字段级 CloudWatch 日志记录时,将提供的对象的字符串表示形式记录到请求的日志流中。该实用程序按顺序将第一个输入格式字符串中由“{}”指示的所有变量替换为提供的对象的字符串表示形式。 $util.log.error(Object) : Void
-
在 API 上使用日志级别
ERROR
或日志级别ALL
启用字段级 CloudWatch 日志记录时,将提供的对象的字符串表示形式记录到请求的日志流中。 $util.log.error(String, Object...) : Void
-
在 API 上使用日志级别
ERROR
或日志级别ALL
启用字段级 CloudWatch 日志记录时,将提供的对象的字符串表示形式记录到请求的日志流中。该实用程序按顺序将第一个输入格式字符串中由“{}”指示的所有变量替换为提供的对象的字符串表示形式。
-
-
$util.escapeJavaScript(String) : String
-
将输入字符串作为 JavaScript 转义字符串返回。
解析器授权
-
$util.unauthorized()
-
针对被解析的字段引发
Unauthorized
。可以在请求或响应映射模板中使用该实用程序,以确定是否允许调用方解析该字段。