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

# \$1util.transform 中的转换帮助程序
<a name="transformation-helpers-in-utils-transform"></a>

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

`$util.transform` 包含一些帮助程序方法，可以更轻松地对数据来源执行复杂的操作，例如 Amazon DynamoDB 筛选操作。

## 转换帮助程序
<a name="transformation-helpers-conversions"></a>

### 转换帮助程序实用程序列表
<a name="transformation-helpers-in-utils-transform-list"></a>

****`$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。

## 转换帮助程序订阅筛选条件
<a name="transformation-helpers-conversions-subscription-filters"></a>

### 转换帮助程序订阅筛选条件实用程序列表
<a name="transformation-helpers-in-utils-transform-list"></a>

****`$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` 表达式对象中，以便至少满足其中的一个规则才能通过订阅筛选条件。

## 订阅筛选条件参数
<a name="subscription-filter-arguments"></a>

下表介绍了如何定义以下实用程序的参数：
+ `$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"
        }
      ]
    }
  ]
}
```

------