本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS AppSync 解析器映射模板实用程序参考 **注意** 我们现在主要支持 APPSYNC\$1JS 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 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 中的映射帮助程序](https://docs.aws.amazon.com/appsync/latest/devguide/utility-helpers-in-map.html)：\$1util.map 包含一些方法以帮助执行常见的映射操作，例如在映射中删除或保留项目以用于筛选使用案例。 + [\$1util.dynamodb 中的 DynamoDB 帮助程序](https://docs.aws.amazon.com/appsync/latest/devguide/dynamodb-helpers-in-util-dynamodb.html)：\$1util.dynamodb 包含一些帮助程序方法，可以更轻松地在 Amazon DynamoDB 中写入和读取数据，例如自动类型映射和格式设置。 + [\$1util.rds 中的 Amazon RDS 帮助程序](https://docs.aws.amazon.com/appsync/latest/devguide/rds-helpers-in-util-rds.html)：\$1util.rds 包含一些帮助程序方法，可以删除结果输出中的无关数据以设置 RDS 操作格式。 + [\$1util.http 中的 HTTP 帮助程序](https://docs.aws.amazon.com/appsync/latest/devguide/http-helpers-in-utils-http.html)：\$1util.http 实用程序提供一些帮助程序方法，可用于管理 HTTP 请求参数和添加响应标头。 + [\$1util.xml 中的 XML 帮助程序](https://docs.aws.amazon.com/appsync/latest/devguide/xml-helpers-in-utils-xml.html)：\$1util.xml 包含一些帮助程序方法，可以更轻松地将 XML 响应转换为 JSON 或字典。 + [\$1util.transform 中的转换帮助程序](https://docs.aws.amazon.com/appsync/latest/devguide/transformation-helpers-in-utils-transform.html)：\$1util.transform 包含一些帮助程序方法，可以更轻松地对数据来源执行复杂的操作，例如 DynamoDB 筛选操作。 + [\$1util.math 中的数学帮助程序](https://docs.aws.amazon.com/appsync/latest/devguide/math-helpers-in-util-math.html)：\$1util.math 包含一些帮助进行常见数学运算的方法。 + [\$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 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$util` 变量包含帮助您处理数据的常规实用程序方法。除非另行指定，否则所有实用程序均使用 UTF-8 字符集。 ## JSON 解析实用程序 ### 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 生成实用程序 ### 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` ** 如果条件为假，则 CustomTemplateException 使用指定的消息抛出 a。 ** `$util.validate(Boolean, String, String) : void` ** 如果条件为 false，则 CustomTemplateException 使用指定的消息和错误类型抛出。 ** `$util.validate(Boolean, String, String, Object) : void` ** 如果条件为 false，则抛出 a， CustomTemplateException 其中包含指定的消息和错误类型，以及要在响应中返回的数据。 ## Null 行为实用程序 ### 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")`。此功能以[模式](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.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 上启用了请求级别和字段级日志 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”指示的所有变量替换为提供的对象的字符串表示形式。 ## 返回值行为实用程序 ### 返回值行为实用程序列表 ****`$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 字符串。 ## 解析器授权 ### 解析器授权列表 ** `$util.unauthorized()` ** 针对被解析的字段引发 `Unauthorized`。可以在请求或响应映射模板中使用该实用程序，以确定是否允许调用方解析该字段。 # AWS AppSync 指令 **注意** 我们现在主要支持 APPSYNC\$1JS 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 AWS AppSync 公开指令以提高开发人员在 VTL 中编写时的生产力。 ## 指令实用程序 ****`#return(Object)`**** `#return(Object)` 允许您提前从任何映射模板返回。`#return(Object)` 类似于编程语言中的 *return* 关键字，因为它从最近的逻辑范围块返回。在解析器映射模板内使用 `#return(Object)` 将从解析器返回。此外，从函数映射模板中使用 `#return(Object)` 将从该函数返回，并继续运行到管道中的下一个函数或解析器响应映射模板。 ****`#return`**** `#return` 指令具有与 `#return(Object)` 相同的行为，但返回 `null`。 # \$1util.time 中的时间帮助程序 **注意** 我们现在主要支持 APPSYNC\$1JS 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$util.time` 变量包含的日期时间方法有助于生成时间截，在不同的日期时间格式之间进行转换，并解析日期时间字符串。日期时间格式的语法基于该语法 [DateTimeFormatter](https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html)，您可以参考该语法以获取更多文档。我们在下面提供了一些示例以及可用方法和描述列表。 ## 时间实用程序 ### 时间实用程序列表 ** `$util.time.nowISO8601() : String` ** 以格式返回 UTC 的字符串表示[ISO8601形式](https://en.wikipedia.org/wiki/ISO_8601)。 ** `$util.time.nowEpochSeconds() : long` ** 返回从 1970-01-01T00:00:00Z 纪元到现在的秒数。 ** `$util.time.nowEpochMilliSeconds() : long` ** 返回从 1970-01-01T00:00:00Z 纪元到现在的毫秒数。 ** `$util.time.nowFormatted(String) : String` ** 使用字符串输入类型指定的格式返回当前 UTC 时间戳的字符串。 ** `$util.time.nowFormatted(String, String) : String` ** 使用字符串输入类型指定的格式和时区返回该时区当前时间戳的字符串。 ** `$util.time.parseFormattedToEpochMilliSeconds(String, String) : Long` ** 解析作为字符串传递的时间戳以及包含时区的格式，然后将时间戳作为自纪元以来的毫秒数返回。 ** `$util.time.parseFormattedToEpochMilliSeconds(String, String, String) : Long` ** 解析作为字符串传递的时间戳以及格式和时区，然后将时间戳作为自纪元以来的毫秒数返回。 ** `$util.time.parseISO8601ToEpochMilliSeconds(String) : Long` ** 解析作为字符串传递 ISO8601 的时间戳，然后返回自纪元以来的毫秒数的时间戳。 ** `$util.time.epochMilliSecondsToSeconds(long) : long` ** 将纪元毫秒数时间戳转换为纪元秒数时间戳。 ** `$util.time.epochMilliSecondsToISO8601(long) : String` ** 将纪元毫秒时间戳转换为时间戳。 ISO8601 ** `$util.time.epochMilliSecondsToFormatted(long, String) : String` ** 将以长型形式传递的纪元毫秒数时间戳转换为根据提供的 UTC 格式设置的时间戳。 ** `$util.time.epochMilliSecondsToFormatted(long, String, String) : String` ** 将以长型形式传递的纪元毫秒数时间戳转换为根据提供的时区和格式设置的时间戳。 ## 单独函数示例 ``` $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 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$util.list` 包含一些方法以帮助执行常见的列表操作，例如在列表中删除或保留项目以用于筛选使用案例。 ## 列表实用程序 ** `$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 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$util.map` 包含一些方法以帮助执行常见的映射操作，例如在映射中删除或保留项目以用于筛选使用案例。 ## 映射实用程序 ** `$util.map.copyAndRetainAllKeys(Map, List) : Map` ** 制作第一个映射的浅副本，同时仅保留列表中指定的键（如果存在）。所有其他键将从副本中移除。 ** `$util.map.copyAndRemoveAllKeys(Map, List) : Map` ** 制作第一个映射的浅副本，同时删除在列表中指定键的任何条目（如果存在）。所有其他键将保留在副本中。 # \$1util.dynamodb 中的 DynamoDB 帮助程序 **注意** 我们现在主要支持 APPSYNC\$1JS 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$util.dynamodb` 包含一些帮助程序方法，可以更轻松地在 Amazon DynamoDB 中写入和读取数据，例如自动类型映射和格式设置。这些方法旨在自动将基元类型和列表映射到正确的 DynamoDB 输入格式，即格式 `{ "TYPE" : VALUE }` 的 `Map`。 例如，以前用于在 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 实用程序 ### toString 实用程序列表 ****`$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 实用程序 ### toNumber 实用程序列表 ** `$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 实用程序 ### toBinary 实用程序列表 ** `$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 实用程序 ### toBoolean 实用程序列表 ** `$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 实用程序 ### toNull 实用程序列表 ** `$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 实用程序 ### 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 实用程序列表 ** `$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 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$util.rds` 包含一些帮助程序方法，可以删除结果输出中的无关数据以设置 Amazon RDS 操作格式。 ## \$1util.rds 实用程序列表 ****`$util.rds.toJsonString(String serializedSQLResult): String`**** 将字符串化的原始 Amazon Relational Database Service (Amazon RDS) 数据 API 操作结果格式转换为更简洁的字符串以返回 `String`。返回的字符串是结果集的序列化 SQL 记录列表。每条记录均表示为一个键-值对集合。键是对应的列名称。 如果输入中的相应语句是导致变更的 SQL 查询（例如 INSERT、UPDATE、DELETE），则返回空列表。例如，查询 `select * from Books limit 2` 提供 Amazon RDS 数据操作的原始结果： ``` { "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 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$util.http` 实用程序提供一些帮助程序方法，可用于管理 HTTP 请求参数和添加响应标头。 ## \$1util.http 实用程序列表 ** `$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)` 的标头，并生成一个 `ResponseHeaderError` 错误，该错误会添加到操作的 `errors` 输出中。 ``` 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 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$util.xml` 包含一些帮助程序方法，可以更轻松地将 XML 响应转换为 JSON 或字典。 ## \$1util.xml 实用程序列表 ****`$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* 类似，只不过输出是字符串。如果您要直接转换 XML 响应并将其从 HTTP 对象返回到 JSON，这非常有用。 ****`$util.xml.toJsonString(String, Boolean) : String`**** 使用可选的布尔值参数将 XML 字符串转换为 JSON 字符串，以确定您是否要对 JSON 进行字符串编码。 # \$1util.transform 中的转换帮助程序 **注意** 我们现在主要支持 APPSYNC\$1JS 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$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` 输入对象。第二个参数是字段名称 `List`，在构建 `SubscriptionFilter` 表达式对象时，将在第一个 `Map` 输入对象中忽略这些字段名称。 ****`$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` 对象，它具有以下键值： + 字段名称 + "and" + "or" 对于作为键的字段名称，这些字段的条目条件采用 `"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 或 OR 逻辑进行连接。键值 "and" 和 "or" 需要使用一个条件数组。 ``` "and" : [ { "field_name1" : { "operator1" : value } }, { "field_name2" : { "operator1" : value } }, . . ]. ``` 请注意，您可以嵌套 "and" 和 "or"。也就是说，您可以将 "and"/"or" 嵌套在另一个 "and"/"or" 块中。不过，这不适用于简单字段。 ``` "and" : [ { "field_name1" : { "operator" : value } }, { "or" : [ { "field_name2" : { "operator" : value } }, { "field_name3" : { "operator" : value } } ]. ``` 以下示例显示使用 `$util.transform.toSubscriptionFilter(Map) : Map` 的*参数 1* 的输入。 **输入** 参数 1：Map： ``` { "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 包含字段名称 `List`，在构建 `SubscriptionFilter` 表达式对象时，不应在输入 `Map`（参数 1）中考虑使用这些字段名称。`List` 也可以是空的。 以下示例显示使用 `$util.transform.toSubscriptionFilter(Map, List) : Map` 的参数 1 和参数 2 的输入。 **输入** 参数 1：Map： ``` { "percentageUp": { "lte": 50, "gte": 20 }, "and": [ { "title": { "ne": "Book1" } }, { "downvotes": { "gt": 20 } } ], "or": [ { "author": { "eq": "Admin" } }, { "isPublished": { "eq": false } } ] } ``` 参数 2：List： ``` ["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` 对象（不能具有 "and" 或 "or"）。对于作为键的字段名称，这些字段的条件是采用 `"operator" : "value"` 格式的条目。与参数 1 不同，参数 3 不能在同一键中具有多个条件。此外，参数 3 没有 "and" 或 "or" 子句，因此，也不涉及嵌套。 参数 3 表示一组严格规则，这些规则将添加到 `SubscriptionFilter` 表达式对象中，以便至少满足**其中的一个**条件才能通过筛选条件。 ``` { "fieldname1": { "operator": value }, "fieldname2": { "operator": value } } . . . ``` 以下示例显示使用 `$util.transform.toSubscriptionFilter(Map, List, Map) : Map` 的*参数 1*、*参数 2* 和*参数 3* 的输入。 **输入** 参数 1：Map： ``` { "percentageUp": { "lte": 50, "gte": 20 }, "and": [ { "title": { "ne": "Book1" } }, { "downvotes": { "lt": 20 } } ], "or": [ { "author": { "eq": "Admin" } }, { "isPublished": { "eq": false } } ] } ``` 参数 2：List： ``` ["percentageUp", "author"] ``` 参数 3：Map： ``` { "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 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$util.math` 包含一些方法以帮助进行常见的数学运算。 ## \$1util.math 实用程序列表 ** `$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 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$util.str` 包含一些方法以帮助执行常见的字符串操作。 ## \$1util.str 实用程序列表 ** `$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` ** 使用以下 4 种 unicode 规范化形式之一规范化字符串：NFC、NFD、NFKC 或 NFKD。第一个参数是要规范化的字符串。第二个参数是 "nfc"、"nfd"、"nfkc" 或 "nfkd"，它指定用于规范化过程的规范化类型。 # 扩展程序 **注意** 我们现在主要支持 APPSYNC\$1JS 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。 `$extensions` 包含一组在解析器中执行额外操作的方法。 ## 缓存扩展 **`$extensions.evictFromApiCache(String, String, Object) : Object`** 从 AWS AppSync 服务器端缓存中移出一个项目。第一个参数是类型名称。第二个参数是字段名称。第三个参数是一个对象，其中包含指定缓存键值的键值对项目。您必须按照与缓存解析器的 `cachingKey` 中的缓存键相同的顺序，将项目放入对象中。 该实用程序仅适用于变更，而不适用于查询。 ## 订阅扩展 **`$extensions.setSubscriptionFilter(filterJsonObject)`** 定义增强的订阅筛选条件。每个订阅通知事件都会根据提供的订阅筛选条件进行评估，如果所有筛选条件的评估结果均为 `true`，则向客户端发送通知。参数是 `filterJsonObject`，如下一节所述。 您只能在订阅解析器的响应映射模板中使用该扩展方法。 **`$extensions.setSubscriptionInvalidationFilter(filterJsonObject)`** 定义订阅失效筛选条件。根据失效负载评估订阅筛选条件，如果筛选条件的评估结果为 `true`，则使给定订阅失效。参数是 `filterJsonObject`，如下一节所述。 您只能在订阅解析器的响应映射模板中使用该扩展方法。 **`$extensions.invalidateSubscriptions(invalidationJsonObject)`** 用于启动变更导致的订阅失效。参数是 `invalidationJsonObject`，如下一节所述。 只能在变更解析器的响应映射模板中使用该扩展。 您最多只能在任何单个请求中使用 5 个唯一的 `$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` 字段匹配。如果通知负载包含 `service` 字段，并且 `value` 等于 `AWS AppSync`，则筛选条件的评估结果为 `true`： ``` { "fieldName" : "service", "operator" : "eq", "value" : "AWS AppSync" } ``` ### 字段：value 根据运算符，该值可能具有不同的类型： + 单个数字或布尔值 + 字符串示例：`"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]` ### 字段：operator 一个区分大小写的字符串，可能具有以下值： | | | 运算符 | 说明 | 可能的值类型 | | --- |--- |--- | | eq | Equal | 整数、浮点数、字符串、布尔值 | | ne | Not equal | 整数、浮点数、字符串、布尔值 | | le | Less than or equal | 整数、浮点数、字符串 | | lt | Less than | 整数、浮点数、字符串 | | ge | Greater than or equal | 整数、浮点数、字符串 | | gt | Greater than | 整数、浮点数、字符串 | | contains | 检查集合中的子序列或值。 | 整数、浮点数、字符串 | | 不包含 | 检查集合中是否缺少子序列或缺少值。 | 整数、浮点数、字符串 | | 开始于 | 检查前缀。 | 字符串 | | in | 检查列表中是否有匹配的元素。 | 整数、浮点数或字符串数组 | | notIn | 检查列表中是否有不在列表中的匹配元素。 | 整数、浮点数或字符串数组 | | 介于 | 在两个值之间 | 整数、浮点数、字符串 | | 包含任何 | 包含常见元素 | 整数、浮点数、字符串 | 下表介绍了如何在订阅通知中使用每个运算符。 ------ #### [ eq (equal) ] 如果订阅通知字段值匹配并且严格等于筛选条件的值，则 `eq` 运算符的评估结果为 `true`。在以下示例中，如果订阅通知的 `service` 字段值等于 `AWS AppSync`，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数、字符串、布尔值 ``` { "fieldName" : "service", "operator" : "eq", "value" : "AWS AppSync" } ``` ------ #### [ ne (not equal) ] 如果订阅通知字段值与筛选条件的值不同，则 `ne` 运算符的评估结果为 `true`。在以下示例中，如果订阅通知的 `service` 字段值不同于 `AWS AppSync`，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数、字符串、布尔值 ``` { "fieldName" : "service", "operator" : "ne", "value" : "AWS AppSync" } ``` ------ #### [ le (less or equal) ] 如果订阅通知字段值小于或等于筛选条件的值，则 `le` 运算符的评估结果为 `true`。在以下示例中，如果订阅通知的 `size` 字段值小于或等于 `5`，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数、字符串 ``` { "fieldName" : "size", "operator" : "le", "value" : 5 } ``` ------ #### [ lt (less than) ] 如果订阅通知字段值小于筛选条件的值，则 `lt` 运算符的评估结果为 `true`。在以下示例中，如果订阅通知的 `size` 字段值小于 `5`，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数、字符串 ``` { "fieldName" : "size", "operator" : "lt", "value" : 5 } ``` ------ #### [ ge (greater or equal) ] 如果订阅通知字段值大于或等于筛选条件的值，则 `ge` 运算符的评估结果为 `true`。在以下示例中，如果订阅通知的 `size` 字段值大于或等于 `5`，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数、字符串 ``` { "fieldName" : "size", "operator" : "ge", "value" : 5 } ``` ------ #### [ gt (greater than) ] 如果订阅通知字段值大于筛选条件的值，则 `gt` 运算符的评估结果为 `true`。在以下示例中，如果订阅通知的 `size` 字段值大于 `5`，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数、字符串 ``` { "fieldName" : "size", "operator" : "gt", "value" : 5 } ``` ------ #### [ contains ] `contains` 运算符检查集合或单个项目中的子字符串、子序列或值。如果订阅通知字段值包含筛选条件值，则具有 `contains` 运算符的筛选条件的评估结果为 `true`。在以下示例中，如果订阅通知的 `seats` 字段具有包含值 `10` 的数组值，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数、字符串 ``` { "fieldName" : "seats", "operator" : "contains", "value" : 10 } ``` 在另一个示例中，如果订阅通知的 `event` 字段将 `launch` 作为子字符串，则筛选条件的评估结果为 `true`。 ``` { "fieldName" : "event", "operator" : "contains", "value" : "launch" } ``` ------ #### [ notContains ] `notContains` 运算符检查在集合或单个项目中是否缺少子字符串、子序列或值。如果订阅通知字段值不包含筛选条件值，则具有 `notContains` 运算符的筛选条件的评估结果为 `true`。在以下示例中，如果订阅通知的 `seats` 字段具有不包含值 `10` 的数组值，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数、字符串 ``` { "fieldName" : "seats", "operator" : "notContains", "value" : 10 } ``` 在另一个示例中，如果订阅通知的 `event` 字段值没有将 `launch` 作为其子序列，则筛选条件的评估结果为 `true`。 ``` { "fieldName" : "event", "operator" : "notContains", "value" : "launch" } ``` ------ #### [ beginsWith ] `beginsWith` 运算符检查字符串中的前缀。如果订阅通知字段值以筛选条件的值开头，则包含 `beginsWith` 运算符的筛选条件的评估结果为 `true`。在以下示例中，如果订阅通知的 `service` 字段值以 `AWS` 开头，则筛选条件的评估结果为 `true`。 **可能的值类型：**字符串 ``` { "fieldName" : "service", "operator" : "beginsWith", "value" : "AWS" } ``` ------ #### [ in ] `in` 运算符在数组中检查匹配元素。如果订阅通知字段值在数组中存在，则包含 `in` 运算符的筛选条件的评估结果为 `true`。在以下示例中，如果订阅通知的 `severity` 字段具有数组 `[1,2,3]` 中存在的值之一，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数或字符串数组 ``` { "fieldName" : "severity", "operator" : "in", "value" : [1,2,3] } ``` ------ #### [ notIn ] `notIn` 运算符在数组中检查缺失元素。如果订阅通知字段值在数组中不存在，则包含 `notIn` 运算符的筛选条件的评估结果为 `true`。在以下示例中，如果订阅通知的 `severity` 字段具有数组 `[1,2,3]` 中不存在的值之一，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数或字符串数组 ``` { "fieldName" : "severity", "operator" : "notIn", "value" : [1,2,3] } ``` ------ #### [ between ] `between` 运算符检查两个数字或字符串之间的值。如果订阅通知字段值位于筛选条件的值对之间，则包含 `between` 运算符的筛选条件的评估结果为 `true`。在以下示例中，如果订阅通知的 `severity` 字段值为 `2`、`3`、`4`，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数或字符串对 ``` { "fieldName" : "severity", "operator" : "between", "value" : [1,5] } ``` ------ #### [ containsAny ] `containsAny` 运算符检查数组中的相同元素。如果订阅通知字段设置值和筛选条件设置值的交集不为空，则具有 `containsAny` 运算符的筛选条件的评估结果为 `true`。在以下示例中，如果订阅通知的 `seats` 字段具有包含 `10` 或 `15` 的数组值，则筛选条件的评估结果为 `true`。这意味着如果订阅通知的 `seats` 字段值为 `[10,11]` 或 `[15,20,30]`，则筛选条件的评估结果为 `true`。 **可能的值类型：**整数、浮点数或字符串 ``` { "fieldName" : "seats", "operator" : "containsAny", "value" : [10, 15] } ``` ------ ### AND 逻辑 您可以在 `filterGroup` 数组的 `filters` 对象中定义多个条目，以使用 AND 逻辑组合多个筛选条件。在以下示例中，如果订阅通知的 `userId` 字段值等于 `1` 并且 `group` 字段的值为 `Admin` 或 `Developer`，则筛选条件的评估结果为 `true`。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 }, { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` ### OR 逻辑 您可以在 `filterGroup` 数组中定义多个筛选条件对象，以使用 OR 逻辑组合多个筛选条件。在以下示例中，如果订阅通知的 `userId` 字段值等于 `1` 或者 `group` 字段的值为 `Admin` 或 `Developer`，则筛选条件的评估结果为 `true`。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 } ] }, { "filters" : [ { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` ### 异常 请注意，使用筛选条件存在一些限制： + 在 `filters` 对象中，每个筛选条件最多可以具有 5 个唯一的 `fieldName` 项目。这意味着，您可以使用 AND 逻辑组合最多 5 个单独的 `fieldName` 对象。 + `containsAny` 运算符最多可以具有 20 个值。 + `in` 和 `notIn` 运算符最多可以具有 5 个值。 + 每个字符串最多可以包含 256 个字符。 + 每个字符串比较都区分大小写。 + 嵌套对象筛选最多允许 5 个嵌套筛选级别。 + 每个 `filterGroup` 最多可以具有 10 个 `filters`。这意味着，您可以使用 OR 逻辑最多组合 10 个 `filters`。 + `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`，则将该列表作为使订阅失效的输入。 在订阅解析器中定义的失效筛选条件根据 `payload` 值评估的结果为 `true` 时，以下示例导致使用 `onUserDelete` 订阅的订阅和连接的客户端失效。 ``` $extensions.invalidateSubscriptions({ "subscriptionField": "onUserDelete", "payload": { "group": "Developer" "type" : "Full-Time" } }) ```