翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# $util.dynamodb の DynamoDB ヘルパー
<a name="dynamodb-helpers-in-util-dynamodb"></a>

**注記**  
現在、主に APPSYNC\_JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)にある APPSYNC\_JS ランタイムとそのガイドの使用をご検討ください。

`$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(...)`) の 2 つのバージョンがあります。上記の例では、データを 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 バージョンは、非 JSON バージョンを `$util.toJson(...)` でラップすることと等価です。例えば、次の 2 つのステートメントはまったく同じです。

```
$util.toStringJson("Hello, World!")
$util.toJson($util.toString("Hello, World!"))
```

## toDynamoDB
<a name="utility-helpers-in-toDynamoDB"></a>

### toDynamoDB utils リスト
<a name="utility-helpers-in-toDynamoDB-list"></a>

** `$util.dynamodb.toDynamoDB(Object) : Map` **  
入力されたオブジェクトを適切な DynamoDB 表現形式に変換する DynamoDB 用の一般的なオブジェクト変換ツールです。このツールは、一部の型の表現方法に関して融通が利きません。例えば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。これは、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` と同じですが、DynamoDB の属性値を JSON エンコード形式の文字列として返します。

## toString utils
<a name="utility-helpers-in-toString"></a>

### toString utils リスト
<a name="utility-helpers-in-toString-list"></a>

****`$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` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

** `$util.dynamodb.toStringSet(List<String>) : Map` **  
文字列型のリスト型を DynamoDB の文字列セット形式に変換します。このツールは、DynamoDB の属性値を記述したオブジェクトを返します。  

```
Input:      $util.dynamodb.toStringSet([ "foo", "bar", "baz" ])
Output:     { "SS" : [ "foo", "bar", "baz" ] }
```

** `$util.dynamodb.toStringSetJson(List<String>) : String` **  
`$util.dynamodb.toStringSet(List<String>) : Map` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

## toNumber utils
<a name="utility-helpers-in-toNumber"></a>

### toNumber utils リスト
<a name="utility-helpers-in-toNumber-list"></a>

** `$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` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

** `$util.dynamodb.toNumberSet(List<Number>) : Map` **  
数値のリストを DynamoDB の数値セット形式に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。  

```
Input:      $util.dynamodb.toNumberSet([ 1, 23, 4.56 ])
Output:     { "NS" : [ 1, 23, 4.56 ] }
```

** `$util.dynamodb.toNumberSetJson(List<Number>) : String` **  
`$util.dynamodb.toNumberSet(List<Number>) : Map` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

## toBinary utils
<a name="utility-helpers-in-toBinary"></a>

### toBinary utils リスト
<a name="utility-helpers-in-toBinary-list"></a>

** `$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` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

** `$util.dynamodb.toBinarySet(List<String>) : Map` **  
base64 文字列としてエンコードされたバイナリデータのリストを DynamoDB のバイナリセット形式に変換します。これは、DynamoDB 属性値を記述するオブジェクトを返します。  

```
Input:      $util.dynamodb.toBinarySet([ "foo", "bar", "baz" ])
Output:     { "BS" : [ "foo", "bar", "baz" ] }
```

** `$util.dynamodb.toBinarySetJson(List<String>) : String` **  
`$util.dynamodb.toBinarySet(List<String>) : Map` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

## toBoolean utils
<a name="utility-helpers-in-toBoolean"></a>

### toBoolean utils リスト
<a name="utility-helpers-in-toBoolean-list"></a>

** `$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` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

## toNull utils
<a name="utility-helpers-in-toNull"></a>

### toNull utils リスト
<a name="utility-helpers-in-toNull-list"></a>

** `$util.dynamodb.toNull() : Map` **  
null を DynamoDB の null 形式で返します。これは、DynamoDB 属性値を記述するオブジェクトを返します。  

```
Input:      $util.dynamodb.toNull()
Output:     { "NULL" : null }
```

** `$util.dynamodb.toNullJson() : String` **  
`$util.dynamodb.toNull() : Map` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

## toList utils
<a name="utility-helpers-in-toList"></a>

### toList utils リスト
<a name="utility-helpers-in-toList-list"></a>

****`$util.dynamodb.toList(List) : Map`** **  
オブジェクトのリストを DynamoDB のリスト形式に変換します。リスト内の各項目も、該当する DynamoDB 形式に変換されます。このツールは、一部のネステッドオブジェクトの表現方法に関して融通が利きません。例えば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。このツールは、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` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

## toMap utils
<a name="utility-helpers-in-toMap"></a>

### toMap utils リスト
<a name="utility-helpers-in-toMap-list"></a>

** `$util.dynamodb.toMap(Map) : Map` **  
マップを DynamoDB のマップ形式に変換します。マップ内の各値も、該当する DynamoDB 形式に変換されます。このツールは、一部のネステッドオブジェクトの表現方法に関して融通が利きません。例えば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。このツールは、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` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

** `$util.dynamodb.toMapValues(Map) : Map` **  
マップ内の各値を該当する DynamoDB 形式に変換して、マップのコピーを作成します。このツールは、一部のネステッドオブジェクトの表現方法に関して融通が利きません。例えば、セット型 ("SS"、"NS"、"BS") ではなくリスト型 ("L") が使用されます。  

```
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 の属性値の内容のみを返します。例えば、次の 2 つのステートメントはまったく同じです。  

```
$util.dynamodb.toMapValues($map)
$util.dynamodb.toMap($map).get("M")
```

** `$util.dynamodb.toMapValuesJson(Map) : String` **  
`$util.dynamodb.toMapValues(Map) : Map` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

## S3Object utils
<a name="utility-helpers-in-S3Object"></a>

### S3Object utils リスト
<a name="utility-helpers-in-S3Object-list"></a>

** `$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` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

** `$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` と同じですが、 DynamoDBの属性値を JSON エンコード形式の文字列として返します。

** `$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" }
```