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

# \$1util.transform 中的轉換協助程式
<a name="transformation-helpers-in-utils-transform"></a>

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

`$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`輸入物件。第二個引數是在建構`SubscriptionFilter`表達式物件時在第一個`Map`輸入物件中忽略`List`的欄位名稱。

****`$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`物件：
+ 欄位名稱
+ 「和」
+ 「或」

對於做為索引鍵的欄位名稱，這些欄位項目的條件格式為 `"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" : [
            
            {
                "field_name1" : {
                    "operator1" : value             
                }
             },
             
             {
                "field_name2" : {
                    "operator1" : value             
                }
             },
             .
             .
        ].
```

請注意，您可以巢狀化「和」和「或」。也就是說，您可以在另一個「和」/」或」區塊中巢狀「和」/」或「或」。不過，這不適用於簡單的欄位。

```
"and" : [
            
            {
                "field_name1" : {
                    "operator" : value             
                }
             },
             
             {
                "or" : [
                            {
                                "field_name2" : {
                                    "operator" : value             
                                }
                            },
                            
                            {
                                "field_name3" : {
                                    "operator" : value             
                                }
                            }
              
                        ].
```

下列範例顯示使用 *輸入引數 1*`$util.transform.toSubscriptionFilter(Map) : Map`。

**Input(s)**

引數 1：映射：

```
{
  "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 包含建構`SubscriptionFilter`表達式物件時不應在輸入中考慮`List`的一組欄位名稱 `Map`（引數 1)。`List` 也可以是空的。

下列範例顯示使用 輸入引數 1 和引數 2`$util.transform.toSubscriptionFilter(Map, List) : Map`。

**Input(s)**

引數 1：映射：

```
{

  "percentageUp": {
    "lte": 50,
    "gte": 20
  },
  "and": [
    {
      "title": {
        "ne": "Book1"
      }
    },
    {
      "downvotes": {
        "gt": 20
      }
    }
  ],
  "or": [
    {
      "author": {
        "eq": "Admin"
      }
    },
    {
      "isPublished": {
        "eq": false
      }
    }
  ]
}
```

引數 2：列出：

```
["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`物件 （不能具有「和」或「或」)。對於做為索引鍵的欄位名稱，這些欄位的條件是 形式的項目`"operator" : "value"`。與引數 1 不同，引數 3 不能在同一個索引鍵中有多個條件。此外，引數 3 沒有「和」或「或」子句，因此也沒有涉及巢狀。

引數 3 代表新增至`SubscriptionFilter`表達式物件的嚴格規則清單，因此**至少符合其中一個**條件以傳遞篩選條件。

```
{
  "fieldname1": {
    "operator": value
  },
  "fieldname2": {
    "operator": value
  }
}
.
.
.
```

下列範例顯示使用 的*引數 1*、*引數 2* 和*引數 3* 的輸入`$util.transform.toSubscriptionFilter(Map, List, Map) : Map`。

**Input(s)**

引數 1：映射：

```
{
  "percentageUp": {
    "lte": 50,
    "gte": 20
  },
  "and": [
    {
      "title": {
        "ne": "Book1"
      }
    },
    {
      "downvotes": {
        "lt": 20
      }
    }
  ],
  "or": [
    {
      "author": {
        "eq": "Admin"
      }
    },
    {
      "isPublished": {
        "eq": false
      }
    }
  ]
}
```

引數 2：列出：

```
["percentageUp", "author"]
```

引數 3：映射：

```
{
  "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"
        }
      ]
    }
  ]
}
```

------