翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# DynamoDB の AWS AppSync リゾルバーマッピングテンプレートリファレンス
**注記**
現在、主に APPSYNC\$1JS ランタイムとそのドキュメントをサポートしています。[こちら](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html) で APPSYNC\$1JS ランタイムとそのガイドの使用をご検討ください。
AWS AppSync DynamoDB 関数を使用すると、受信 [GraphQL](https://graphql.org) リクエストを DynamoDB 呼び出しにマッピングし、DynamoDB レスポンスを GraphQL にマッピングすることで、GraphQL を使用してアカウント内の既存の Amazon DynamoDB テーブルにデータを保存および取得できます。このセクションでは、サポートされる DynamoDB オペレーションのリクエストハンドラーとレスポンスハンドラーについて説明します。
+ [GetItem](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-getitem.html) - GetItem リクエストでは、DynamoDB 関数に DynamoDB への GetItem リクエストを行うように指示し、DynamoDB 内の項目のキーと、一貫した読み取りを使用するかどうかを指定できます。
+ [PutItem](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-putitem.html) - PutItem リクエストマッピングドキュメントでは、DynamoDB 関数に DynamoDB への PutItem リクエストを行うように指示し、DynamoDB の項目のキー、項目の全内容 (キーと attributeValues で構成される)、およびオペレーションが成功するための条件を指定できます。
+ [UpdateItem](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-updateitem.html) - UpdateItem リクエストでは、DynamoDB 関数に DynamoDB への UpdateItem リクエストを行うように指示し、DynamoDB の項目のキー、DynamoDB の項目を更新する方法を説明する更新式、およびオペレーションが成功するための条件を指定できます。
+ [DeleteItem](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-deleteitem.html) - DeleteItem リクエストでは、DynamoDB 関数に DynamoDB に DeleteItem リクエストを行うように指示し、DynamoDB 内の項目のキーと、オペレーションが成功するための条件を指定できます。
+ [Query](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-query.html) - Query リクエストオブジェクトを使用すると、DynamoDB リゾルバーに DynamoDB へのクエリリクエストを行うように指示できます。また、キー式、使用するインデックス、追加のフィルター、返す項目の数、一貫した読み取りを使用するかどうか、クエリの方向 (前方または後方)、ページ分割トークンを指定できます。
+ [Scan](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-scan.html) - Scan リクエストは、DynamoDB 関数に DynamoDB への Scan リクエストを指示することができ、結果を除外するフィルタ、使用するインデックス、返すアイテムの数、一貫性のある読み取りを使用するかどうか、ページ分割トークン、並列スキャンを指定することができます。
+ [Sync](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-sync.html) - Sync リクエストオブジェクトを使用すると、DynamoDB テーブルからすべての結果を取得し、最後のクエリ (差分更新) 以降に変更されたデータのみを受け取ることができます。Sync リクエストは、バージョン管理された DynamoDB データソースに対してのみ行うことができます。フィルタを指定して、結果、返す項目の数、ページ分割トークン、および最後の Sync オペレーションが開始された日時を除外できます。
+ [BatchGetItem](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-batch-get-item.html) - BatchGetItem リクエストオブジェクトを使用すると、DynamoDB の関数から DynamoDB への BatchGetItem リクエストで、複数のテーブルから複数の項目を取得するように指定できます。このリクエストオブジェクトでは、項目を取得するテーブル名と、各テーブルから取得する項目のキーを指定する必要があります。
+ [BatchDeleteItem](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-batch-delete-item.html) - BatchDeleteItem リクエストオブジェクトを使用すると、DynamoDB の関数から DynamoDB への BatchWriteItem リクエストで、複数のテーブルから複数の項目を削除するように指定できます。このリクエストオブジェクトでは、項目を削除するテーブル名と、各テーブルから削除する項目のキーを指定する必要があります。
+ [BatchPutItem](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-batch-put-item.html) - BatchPutItem リクエストオブジェクトを使用すると、DynamoDB の関数から DynamoDB への BatchWriteItem リクエストオブジェクトを使用すると リクエストで、複数のテーブルに複数の項目を配置するように指定できます。このリクエストオブジェクトでは、項目を配置するテーブル名と、各テーブルに配置する完全な項目を指定する必要があります。
+ [TransactGetItems](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-transact-get-items.html) - TransactGetItems リクエストオブジェクトを使用すると、DynamoDB の関数から DynamoDB への TransactGetItems リクエストで、複数のテーブルから複数の項目を取得するように指定できます。このリクエストオブジェクトでは、項目を取得する各リクエスト項目のテーブル名と、各テーブルから取得する各リクエスト項目のキーを指定する必要があります。
+ [TransactWriteItems](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-transact-write-items.html) - TransactWriteItems リクエストオブジェクトを使用すると、DynamoDB の関数から DynamoDB への TransactWriteItems リクエストで、複数のテーブルに複数の項目を書き込むように指定できます。このリクエストオブジェクトでは、各リクエスト項目の宛先テーブル名、実行する各リクエスト項目のオペレーション、および書き込む各リクエスト項目のキーを指定する必要があります。
+ [ タイプシステム (リクエストマッピング) ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.html) - DynamoDB タイピングが AWS AppSync リクエストに統合される方法について詳しく説明します。
+ [型システム (レスポンスマッピング)](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.html) - DynamoDB タイプがレスポンスペイロードで GraphQL または JSON に自動的に変換される方法について詳しく説明します。
+ [フィルター](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-filter.html) - クエリおよびスキャンオペレーションのフィルターの詳細について説明します。
+ [条件式](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.html) - PutItem オペレーション、UpdateItem オペレーション、DeleteItem オペレーションの条件式について説明します。
+ [トランザクション条件式](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.html) - TransactWriteItems オペレーションの条件式について説明します。
+ [プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-projections.html) - 読み取りオペレーションで属性を指定する方法について説明します。
# GetItem
`GetItem` リクエストマッピングドキュメントでは、 AWS AppSync DynamoDB リゾルバーに DynamoDB への`GetItem`リクエストを行うように指示し、以下を指定できます。
+ DynamoDB の項目のキー
+ 整合性のある読み込みを使用するかどうか
`GetItem` マッピングドキュメントの構造は次のとおりです。
```
{
"version" : "2017-02-28",
"operation" : "GetItem",
"key" : {
"foo" : ... typed value,
"bar" : ... typed value
},
"consistentRead" : true,
"projection" : {
...
}
}
```
各フィールドの定義は以下のようになります。
## GetItem フィールド
### GetItem フィールドリスト
**`version`**
テンプレート定義バージョン `2017-02-28` と `2018-05-29` は現在サポートされています。この値は必須です。
**`operation`**
実行する DynamoDB の処理。`GetItem` DynamoDB の処理を実行するには、これを `GetItem` に設定する必要があります。この値は必須です。
**`key`**
DynamoDB の項目のキー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この値は必須です。
**`consistentRead`**
DynamoDB で強力な整合性のある読み込みを実行するかどうかを示します。これはオプションであり、デフォルトは `false` です。
**`projection`**
DynamoDB オペレーションから返される属性を指定するために使用されるプロジェクション。プロジェクションの詳細については、「[プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)」を参照してください。このフィールドはオプションです。
DynamoDB から返された項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト (`$context.result`) で参照できます。
DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)」を参照してください。
レスポンスマッピングテンプレートの詳細については、「[リゾルバーのマッピングテンプレートの概要](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)」を参照してください。
## 例
以下の例は、GraphQL クエリ `getThing(foo: String!, bar: String!)` のマッピングテンプレートです。
```
{
"version" : "2017-02-28",
"operation" : "GetItem",
"key" : {
"foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
"bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
},
"consistentRead" : true
}
```
DynamoDB `GetItem` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html)」を参照してください。
# PutItem
`PutItem` リクエストマッピングドキュメントでは、 AWS AppSync DynamoDB リゾルバーに DynamoDB への`PutItem`リクエストを行うように指示し、以下を指定できます。
+ DynamoDB の項目のキー
+ 項目の完全なコンテンツ (`key` および `attributeValues` で構成されます)
+ 処理が成功する条件
`PutItem` マッピングドキュメントの構造は次のとおりです。
```
{
"version" : "2018-05-29",
"operation" : "PutItem",
"customPartitionKey" : "foo",
"populateIndexFields" : boolean value,
"key": {
"foo" : ... typed value,
"bar" : ... typed value
},
"attributeValues" : {
"baz" : ... typed value
},
"condition" : {
...
},
"_version" : 1
}
```
各フィールドの定義は以下のようになります。
## PutItem フィールド
### PutItem フィールドリスト
**`version`**
テンプレート定義バージョン `2017-02-28` と `2018-05-29` は現在サポートされています。この値は必須です。
**`operation`**
実行する DynamoDB の処理。`PutItem` DynamoDB の処理を実行するには、これを `PutItem` に設定する必要があります。この値は必須です。
**`key`**
DynamoDB の項目のキー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この値は必須です。
**`attributeValues`**
DynamoDB に渡す項目の残りの属性です。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。このフィールドはオプションです。
**`condition`**
DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件が指定されていない場合、`PutItem` リクエストはその項目の既存のエントリを上書きします。条件の詳細については、「[条件式](aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.md)」を参照してください。この値はオプションです。
**`_version`**
項目の既知の最新バージョンを表す数値。この値はオプションです。このフィールドは*競合の検出*に使用され、バージョン管理されたデータソースでのみサポートされます。
**`customPartitionKey`**
有効にすると、この文字列値は、バージョニングが有効になっているときにデルタ同期テーブルで使用される `ds_sk` および `ds_pk` レコードの形式を変更します (詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照)。有効にすると、`populateIndexFields` エントリの処理も有効になります。このフィールドはオプションです。
**`populateIndexFields`**
ブール値で、**`customPartitionKey` と一緒に有効にすると**、差分同期テーブル、具体的には `gsi_ds_pk` と `gsi_ds_sk` 列のレコードごとに新しいエントリが作成されます。詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照してください。このフィールドはオプションです。
DynamoDB に書き込まれた項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト (`$context.result`) で参照できます。
DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)」を参照してください。
レスポンスマッピングテンプレートの詳細については、「[リゾルバーのマッピングテンプレートの概要](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)」を参照してください。
## 例 1
以下は、GraphQL ミューテーション `updateThing(foo: String!, bar: String!, name: String!, version: Int!)` のマッピングテンプレートです。
指定したキーに対応する項目がない場合は、作成されます。指定したキーに対応する項目がすでにある場合は、上書きされます。
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key": {
"foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
"bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
},
"attributeValues" : {
"name" : $util.dynamodb.toDynamoDBJson($ctx.args.name),
"version" : $util.dynamodb.toDynamoDBJson($ctx.args.version)
}
}
```
## 例 2
以下は、GraphQL ミューテーション `updateThing(foo: String!, bar: String!, name: String!, expectedVersion: Int!)` のマッピングテンプレートです。
この例では、DynamoDB に現在ある項目の `version` フィールドに `expectedVersion` が設定されていることを確認します。
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key": {
"foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
"bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
},
"attributeValues" : {
"name" : $util.dynamodb.toDynamoDBJson($ctx.args.name),
#set( $newVersion = $context.arguments.expectedVersion + 1 )
"version" : $util.dynamodb.toDynamoDBJson($newVersion)
},
"condition" : {
"expression" : "version = :expectedVersion",
"expressionValues" : {
":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
}
}
}
```
DynamoDB `PutItem` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html)」を参照してください。
# UpdateItem
`UpdateItem` リクエストマッピングドキュメントでは、 AWS の AppSync DynamoDB リゾルバーから DynamoDB への `UpdateItem` リクエストを定義し、以下のように指定できます。
+ DynamoDB の項目のキー
+ DynamoDB の項目を更新する方法を示す更新式
+ 処理が成功する条件
`UpdateItem` マッピングドキュメントの構造は次のとおりです。
```
{
"version" : "2018-05-29",
"operation" : "UpdateItem",
"customPartitionKey" : "foo",
"populateIndexFields" : boolean value,
"key": {
"foo" : ... typed value,
"bar" : ... typed value
},
"update" : {
"expression" : "someExpression",
"expressionNames" : {
"#foo" : "foo"
},
"expressionValues" : {
":bar" : ... typed value
}
},
"condition" : {
...
},
"_version" : 1
}
```
各フィールドの定義は以下のようになります。
## UpdateItem フィールド
### UpdateItem フィールドリスト
**`version`**
テンプレート定義バージョン `2017-02-28` と `2018-05-29` は現在サポートされています。この値は必須です。
**`operation`**
実行する DynamoDB の処理。`UpdateItem` DynamoDB の処理を実行するには、これを `UpdateItem` に設定する必要があります。この値は必須です。
**`key`**
DynamoDB の項目のキー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この値は必須です。
**`update`**
`update` セクションには、 DynamoDBの項目の更新方法を示す更新式を指定することができます。更新式の記述方法の詳細については、「[DynamoDB UpdateExpressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)」のドキュメントを参照してください。このセクションは必須です。
`update` セクションには次の 3 つのコンポーネントがあります。
** `expression` **
更新式です。この値は必須です。
** `expressionNames` **
式の属性*名*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは `expression` で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、`expression` で使用される式の属性名のプレースホルダーのみを入力します。
** `expressionValues` **
式の属性*値*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは `expression` で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この指定は必須です。このフィールドはオプションであり、`expression` で使用される式の属性値のプレースホルダーのみを入力します。
**`condition`**
DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合は、`UpdateItem` リクエストによって、現在の状態にかかわらず、既存のエントリが更新されます。条件の詳細については、「[条件式](aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.md)」を参照してください。この値はオプションです。
**`_version`**
項目の既知の最新バージョンを表す数値。この値はオプションです。このフィールドは*競合の検出*に使用され、バージョン管理されたデータソースでのみサポートされます。
**`customPartitionKey`**
有効にすると、この文字列値は、バージョニングが有効になっているときにデルタ同期テーブルで使用される `ds_sk` および `ds_pk` レコードの形式を変更します (詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照)。有効にすると、`populateIndexFields` エントリの処理も有効になります。このフィールドはオプションです。
**`populateIndexFields`**
ブール値で、**`customPartitionKey` と一緒に有効にすると**、差分同期テーブル、具体的には `gsi_ds_pk` と `gsi_ds_sk` 列のレコードごとに新しいエントリが作成されます。詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照してください。このフィールドはオプションです。
DynamoDB の更新された項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト (`$context.result`) で参照できます。
DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)」を参照してください。
レスポンスマッピングテンプレートの詳細については、「[リゾルバーのマッピングテンプレートの概要](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)」を参照してください。
## 例 1
次の例は、GraphQL ミューテーション `upvote(id: ID!)` のマッピングテンプレートです。
この例では、DynamoDB の項目の `upvotes` フィールドと `version` フィールドが 1 ずつ増加されます。
```
{
"version" : "2017-02-28",
"operation" : "UpdateItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"update" : {
"expression" : "ADD #votefield :plusOne, version :plusOne",
"expressionNames" : {
"#votefield" : "upvotes"
},
"expressionValues" : {
":plusOne" : { "N" : 1 }
}
}
}
```
## 例 2
以下は、GraphQL ミューテーション `updateItem(id: ID!, title: String, author: String, expectedVersion: Int!)` のマッピングテンプレートです。
これは、引数を確認して、クライアントから入力された引数のみを含む更新式を動的に生成する複雑な例です。たとえば、`title` と `author` を省略すると、それらは更新されません。引数が指定されているが、その値が `null` の場合、そのフィールドは DynamoDB のオブジェクトから削除されます。最後に、この処理内の条件によって、DynamoDB に現在ある項目の `version` フィールドに `expectedVersion` が設定されているかどうかを確認します。
```
{
"version" : "2017-02-28",
"operation" : "UpdateItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
## Set up some space to keep track of things we're updating **
#set( $expNames = {} )
#set( $expValues = {} )
#set( $expSet = {} )
#set( $expAdd = {} )
#set( $expRemove = [] )
## Increment "version" by 1 **
$!{expAdd.put("version", ":newVersion")}
$!{expValues.put(":newVersion", { "N" : 1 })}
## Iterate through each argument, skipping "id" and "expectedVersion" **
#foreach( $entry in $context.arguments.entrySet() )
#if( $entry.key != "id" && $entry.key != "expectedVersion" )
#if( (!$entry.value) && ("$!{entry.value}" == "") )
## If the argument is set to "null", then remove that attribute from the item in DynamoDB **
#set( $discard = ${expRemove.add("#${entry.key}")} )
$!{expNames.put("#${entry.key}", "$entry.key")}
#else
## Otherwise set (or update) the attribute on the item in DynamoDB **
$!{expSet.put("#${entry.key}", ":${entry.key}")}
$!{expNames.put("#${entry.key}", "$entry.key")}
#if( $entry.key == "ups" || $entry.key == "downs" )
$!{expValues.put(":${entry.key}", { "N" : $entry.value })}
#else
$!{expValues.put(":${entry.key}", { "S" : "${entry.value}" })}
#end
#end
#end
#end
## Start building the update expression, starting with attributes we're going to SET **
#set( $expression = "" )
#if( !${expSet.isEmpty()} )
#set( $expression = "SET" )
#foreach( $entry in $expSet.entrySet() )
#set( $expression = "${expression} ${entry.key} = ${entry.value}" )
#if ( $foreach.hasNext )
#set( $expression = "${expression}," )
#end
#end
#end
## Continue building the update expression, adding attributes we're going to ADD **
#if( !${expAdd.isEmpty()} )
#set( $expression = "${expression} ADD" )
#foreach( $entry in $expAdd.entrySet() )
#set( $expression = "${expression} ${entry.key} ${entry.value}" )
#if ( $foreach.hasNext )
#set( $expression = "${expression}," )
#end
#end
#end
## Continue building the update expression, adding attributes we're going to REMOVE **
#if( !${expRemove.isEmpty()} )
#set( $expression = "${expression} REMOVE" )
#foreach( $entry in $expRemove )
#set( $expression = "${expression} ${entry}" )
#if ( $foreach.hasNext )
#set( $expression = "${expression}," )
#end
#end
#end
## Finally, write the update expression into the document, along with any expressionNames and expressionValues **
"update" : {
"expression" : "${expression}"
#if( !${expNames.isEmpty()} )
,"expressionNames" : $utils.toJson($expNames)
#end
#if( !${expValues.isEmpty()} )
,"expressionValues" : $utils.toJson($expValues)
#end
},
"condition" : {
"expression" : "version = :expectedVersion",
"expressionValues" : {
":expectedVersion" : $util.dynamodb.toDynamoDBJson($ctx.args.expectedVersion)
}
}
}
```
DynamoDB `UpdateItem` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html)」を参照してください。
# DeleteItem
`DeleteItem` リクエストマッピングドキュメントでは、 AWS AppSync DynamoDB リゾルバーに DynamoDB への`DeleteItem`リクエストを行うように指示し、以下を指定できます。
+ DynamoDB の項目のキー
+ 処理が成功する条件
`DeleteItem` マッピングドキュメントの構造は次のとおりです。
```
{
"version" : "2018-05-29",
"operation" : "DeleteItem",
"customPartitionKey" : "foo",
"populateIndexFields" : boolean value,
"key": {
"foo" : ... typed value,
"bar" : ... typed value
},
"condition" : {
...
},
"_version" : 1
}
```
各フィールドの定義は以下のようになります。
## DeleteItem フィールド
### DeleteItem フィールドリスト
** `version` **
テンプレート定義バージョン `2017-02-28` と `2018-05-29` は現在サポートされています。この値は必須です。
** `operation` **
実行する DynamoDB の処理。`DeleteItem` DynamoDB の処理を実行するには、これを `DeleteItem` に設定する必要があります。この値は必須です。
** `key` **
DynamoDB の項目のキー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この値は必須です。
** `condition` **
DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合、`DeleteItem` リクエストによって、現在の状態にかかわらず、項目が削除されます。条件の詳細については、「[条件式](aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.md)」を参照してください。この値はオプションです。
** `_version` **
項目の既知の最新バージョンを表す数値。この値はオプションです。このフィールドは*競合の検出*に使用され、バージョン管理されたデータソースでのみサポートされます。
**`customPartitionKey`**
有効にすると、この文字列値は、バージョニングが有効になっているときにデルタ同期テーブルで使用される `ds_sk` および `ds_pk` レコードの形式を変更します (詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照)。有効にすると、`populateIndexFields` エントリの処理も有効になります。このフィールドはオプションです。
**`populateIndexFields`**
ブール値で、**`customPartitionKey` と一緒に有効にすると**、差分同期テーブル、具体的には `gsi_ds_pk` と `gsi_ds_sk` 列のレコードごとに新しいエントリが作成されます。詳細については、**「AWS AppSyncデベロッパーガイド」の「[競合検出と同期](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)」を参照してください。このフィールドはオプションです。
DynamoDB から削除された項目が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト (`$context.result`) で参照できます。
DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)」を参照してください。
レスポンスマッピングテンプレートの詳細については、「[リゾルバーのマッピングテンプレートの概要](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)」を参照してください。
## 例 1
以下は、GraphQL ミューテーション `deleteItem(id: ID!)` のマッピングテンプレートです。この ID に対応する項目がある場合は、削除されます。
```
{
"version" : "2017-02-28",
"operation" : "DeleteItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
}
}
```
## 例 2
以下は、GraphQL ミューテーション `deleteItem(id: ID!, expectedVersion: Int!)` のマッピングテンプレートです。この ID に対応する項目がある場合は、その `version` フィールドに `expectedVersion` が設定されているときにのみ削除されます。
```
{
"version" : "2017-02-28",
"operation" : "DeleteItem",
"key" : {
"id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
},
"condition" : {
"expression" : "attribute_not_exists(id) OR version = :expectedVersion",
"expressionValues" : {
":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
}
}
}
```
DynamoDB `DeleteItem` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html)」を参照してください。
# クエリ
`Query` リクエストマッピングドキュメントでは、 AWS AppSync DynamoDB リゾルバーに DynamoDB への`Query`リクエストを行うように指示し、以下を指定できます。
+ キー式
+ 使用するインデックス
+ 任意の追加フィルタ
+ 返す項目の数
+ 整合性のある読み込みを使用するかどうか
+ クエリの方向 (前方または後方)
+ ページ分割トークン
`Query` マッピングドキュメントの構造は次のとおりです。
```
{
"version" : "2017-02-28",
"operation" : "Query",
"query" : {
"expression" : "some expression",
"expressionNames" : {
"#foo" : "foo"
},
"expressionValues" : {
":bar" : ... typed value
}
},
"index" : "fooIndex",
"nextToken" : "a pagination token",
"limit" : 10,
"scanIndexForward" : true,
"consistentRead" : false,
"select" : "ALL_ATTRIBUTES" | "ALL_PROJECTED_ATTRIBUTES" | "SPECIFIC_ATTRIBUTES",
"filter" : {
...
},
"projection" : {
...
}
}
```
各フィールドの定義は以下のようになります。
## Query フィールド
### Query フィールドリスト
** `version` **
テンプレート定義バージョン `2017-02-28` と `2018-05-29` は現在サポートされています。この値は必須です。
** `operation` **
実行する DynamoDB の処理。`Query` DynamoDB の処理を実行するには、これを `Query` に設定する必要があります。この値は必須です。
** `query` **
`query` セクションには、DynamoDB から取得する項目を指示するキー条件式を指定することができます。キー条件式の記述方法の詳細については、[DynamoDB KeyConditions のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.KeyConditions.html)を参照してください。このセクションの指定は必須です。
** `expression` **
クエリ式です。このフィールドの指定は必須です。
** `expressionNames` **
式の属性*名*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは `expression` で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、`expression` で使用される式の属性名のプレースホルダーのみを入力します。
** `expressionValues` **
式の属性*値*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは `expression` で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この値は必須です。このフィールドはオプションであり、`expression` で使用される式の属性値のプレースホルダーのみを入力します。
** `filter` **
DynamoDB からの結果が返される前に、その結果をフィルタリングするために使用する追加フィルタです。フィルタの詳細については、「[フィルタ](aws-appsync-resolver-mapping-template-reference-dynamodb-filter.md)」を参照してください。このフィールドはオプションです。
** `index` **
クエリを実行するインデックスの名前です。DynamoDB クエリの処理により、ハッシュキーのプライマリキーインデックスに加えて、ローカルセカンダリインデックスとグローバルセカンダリインデックスをスキャンできます。指定されると、DynamoDB が指定されたインデックスにクエリを実行します。省略すると、プライマリキーインデックスに対してクエリが実行されます。
** `nextToken` **
前のクエリを継続するためのページ分割トークンです。これは前のクエリから取得されます。このフィールドはオプションです。
** `limit` **
評価する項目の最大数 (一致する項目の数であるとは限りません)。このフィールドはオプションです。
** `scanIndexForward` **
クエリを前方と後方のどちらに実行するかを示すブール値です。このフィールドはオプションであり、デフォルトは `true` です。
** `consistentRead` **
DynamoDB にクエリを実行する際に整合性のある読み込みを使用するかどうかを示すブール値です。このフィールドはオプションであり、デフォルトは `false` です。
** `select` **
デフォルトでは、 AWS AppSync DynamoDB リゾルバーはインデックスに射影された属性のみを返します。より多くの属性が必要な場合に、このフィールドを設定できます。このフィールドはオプションです。サポートされている値には以下があります。
** `ALL_ATTRIBUTES` **
指定されたテーブルまたはインデックスのすべての項目の属性を返します。ローカルセカンダリインデックスに対してクエリを実行する場合、DynamoDB は、親のテーブルからインデックスの項目に一致したすべての項目をフェッチします。インデックスがすべての項目の属性を射影するように設定されている場合、すべてのデータはローカルセカンダリインデックスから取得されるため、フェッチは必要ありません。
** `ALL_PROJECTED_ATTRIBUTES` **
インデックスにクエリを実行する場合のみ使用できます。インデックスに投射されたすべての属性を取得します。インデックスがすべての属性を投射するように設定されている場合、この返り値は `ALL_ATTRIBUTES` を指定した場合と同等になります。
**`SPECIFIC_ATTRIBUTES`**
`projection` の `expression` にリストされている属性のみを返します。この戻り値は、`Select` の値を指定せずに `projection` の `expression` を指定するのと同じです。
**`projection`**
DynamoDB オペレーションから返される属性を指定するために使用されるプロジェクション。プロジェクションの詳細については、「[プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)」を参照してください。このフィールドはオプションです。
DynamoDB からの結果が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト (`$context.result`) で参照できます。
DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)」を参照してください。
レスポンスマッピングテンプレートの詳細については、「[リゾルバーのマッピングテンプレートの概要](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)」を参照してください。
結果は以下の構造を持ちます。
```
{
items = [ ... ],
nextToken = "a pagination token",
scannedCount = 10
}
```
各フィールドの定義は以下のようになります。
** `items` **
DynamoDB クエリで返された項目を含むリストです。
** `nextToken` **
さらに結果がある場合、`nextToken` には別のリクエストで使用できるページ分割トークンが含まれています。 AWS AppSync は、DynamoDB から返されるページ分割トークンを暗号化して難読化します。これにより、テーブルデータが誤って呼び出し元に漏えいされるのを防ぎます。また、これらのページ分割トークンは、異なるリゾルバー間では使用できないことにも注意してください。
** `scannedCount` **
フィルタ式 (ある場合) が適用される前に、クエリの条件式に一致した項目の数です。
## 例
次の例は、GraphQL クエリ `getPosts(owner: ID!)` のマッピングテンプレートです。
この例では、テーブルのグローバルセカンダリインデックスにクエリが実行され、指定した ID が所有するすべての投稿が返されます。
```
{
"version" : "2017-02-28",
"operation" : "Query",
"query" : {
"expression" : "ownerId = :ownerId",
"expressionValues" : {
":ownerId" : $util.dynamodb.toDynamoDBJson($context.arguments.owner)
}
},
"index" : "owner-index"
}
```
DynamoDB `Query` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)」を参照してください。
# Scan
`Scan` リクエストマッピングドキュメントでは、 AWS AppSync DynamoDB リゾルバーに DynamoDB への`Scan`リクエストを行うように指示し、以下を指定できます。
+ 結果を除外するフィルタ
+ 使用するインデックス
+ 返す項目の数
+ 整合性のある読み込みを使用するかどうか
+ ページ分割トークン
+ 並列スキャン
`Scan` マッピングドキュメントの構造は次のとおりです。
```
{
"version" : "2017-02-28",
"operation" : "Scan",
"index" : "fooIndex",
"limit" : 10,
"consistentRead" : false,
"nextToken" : "aPaginationToken",
"totalSegments" : 10,
"segment" : 1,
"filter" : {
...
},
"projection" : {
...
}
}
```
各フィールドの定義は以下のようになります。
## Scan フィールド
### Scan フィールドリスト
** `version` **
テンプレート定義バージョン `2017-02-28` と `2018-05-29` は現在サポートされています。この値は必須です。
** `operation` **
実行する DynamoDB の処理。`Scan` DynamoDB の処理を実行するには、これを `Scan` に設定する必要があります。この値は必須です。
** `filter` **
DynamoDB からの結果が返される前に、その結果をフィルタリングするために使用するフィルタです。フィルタの詳細については、「[フィルタ](aws-appsync-resolver-mapping-template-reference-dynamodb-filter.md)」を参照してください。このフィールドはオプションです。
** `index` **
クエリを実行するインデックスの名前です。DynamoDB クエリの処理により、ハッシュキーのプライマリキーインデックスに加えて、ローカルセカンダリインデックスとグローバルセカンダリインデックスをスキャンできます。指定されると、DynamoDB が指定されたインデックスにクエリを実行します。省略すると、プライマリキーインデックスに対してクエリが実行されます。
** `limit` **
一度に評価する項目の最大数です。このフィールドはオプションです。
** `consistentRead` **
DynamoDB にクエリを実行する際に整合性のある読み込みを使用するかどうかを示すブール値です。このフィールドはオプションであり、デフォルトは `false` です。
** `nextToken` **
前のクエリを継続するためのページ分割トークンです。これは前のクエリから取得されます。このフィールドはオプションです。
** `select` **
デフォルトでは、 AWS AppSync DynamoDB リゾルバーはインデックスに射影される属性のみを返します。より多くの属性が必要な場合にこのフィールドを設定します。このフィールドはオプションです。サポートされている値には以下があります。
** `ALL_ATTRIBUTES` **
指定されたテーブルまたはインデックスのすべての項目の属性を返します。ローカルセカンダリインデックスに対してクエリを実行する場合、DynamoDB は、親のテーブルからインデックスの項目に一致したすべての項目をフェッチします。インデックスがすべての項目の属性を射影するように設定されている場合、すべてのデータはローカルセカンダリインデックスから取得されるため、フェッチは必要ありません。
** `ALL_PROJECTED_ATTRIBUTES` **
インデックスにクエリを実行する場合のみ使用できます。インデックスに投射されたすべての属性を取得します。インデックスがすべての属性を投射するように設定されている場合、この返り値は `ALL_ATTRIBUTES` を指定した場合と同等になります。
**`SPECIFIC_ATTRIBUTES`**
`projection` の `expression` にリストされている属性のみを返します。この戻り値は、`Select` の値を指定せずに `projection` の `expression` を指定するのと同じです。
** `totalSegments` **
並列スキャンが実行されるまでにテーブルを分割するセグメントの数です。このフィールドはオプションですが、`segment` を指定した場合には指定する必要があります。
** `segment` **
並列スキャンの実行時のこの処理でのテーブルセグメントです。このフィールドはオプションですが、`totalSegments` を指定した場合には指定する必要があります。
**`projection`**
DynamoDB オペレーションから返される属性を指定するために使用されるプロジェクション。プロジェクションの詳細については、「[プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)」を参照してください。このフィールドはオプションです。
DynamoDB スキャンにより返された結果が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト (`$context.result`) で参照できます。
DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)」を参照してください。
レスポンスマッピングテンプレートの詳細については、「[リゾルバーのマッピングテンプレートの概要](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)」を参照してください。
結果は以下の構造を持ちます。
```
{
items = [ ... ],
nextToken = "a pagination token",
scannedCount = 10
}
```
各フィールドの定義は以下のようになります。
** `items` **
DynamoDB スキャンにより返された項目を含むリストです。
** `nextToken` **
さらに結果がある場合、 には、別のリクエストで使用できるページ分割トークン`nextToken`が含まれています。 AWS AppSync は、DynamoDB から返されるページ分割トークンを暗号化して難読化します。これにより、テーブルデータが誤って呼び出し元に漏えいされるのを防ぎます。また、これらのページ分割トークンは異なるリゾルバー間では使用できません。
** `scannedCount` **
フィルタ式 (ある場合) が適用される前に、DynamoDB により取得された項目の数です。
## 例 1
次の例は、GraphQL クエリ: `allPosts` のマッピングテンプレートです。
この例では、テーブル内のすべてのエントリが返されます。
```
{
"version" : "2017-02-28",
"operation" : "Scan"
}
```
## 例 2
次の例は、GraphQL クエリ: `postsMatching(title: String!)` のマッピングテンプレートです。
この例では、タイトルが `title` 引数で始まるテーブル内のすべてのエントリが返されます。
```
{
"version" : "2017-02-28",
"operation" : "Scan",
"filter" : {
"expression" : "begins_with(title, :title)",
"expressionValues" : {
":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
},
}
}
```
DynamoDB `Scan` API の詳細については、「[DynamoDB API のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html)」を参照してください。
# 同期
`Sync` リクエストマッピングドキュメントを使用すると、DynamoDB テーブルからすべての結果を取得し、最後のクエリ (差分更新) 以降に変更されたデータのみを受け取ることができます。 `Sync`リクエストは、バージョン管理された DynamoDB データソースに対してのみ実行できます。以下を指定できます。
+ 結果を除外するフィルタ
+ 返す項目の数
+ ページ分割トークン
+ 最後の `Sync` オペレーションが開始された日時
`Sync` マッピングドキュメントの構造は次のとおりです。
```
{
"version" : "2018-05-29",
"operation" : "Sync",
"basePartitionKey": "Base Tables PartitionKey",
"deltaIndexName": "delta-index-name",
"limit" : 10,
"nextToken" : "aPaginationToken",
"lastSync" : 1550000000000,
"filter" : {
...
}
}
```
各フィールドの定義は以下のようになります。
## Sync フィールド
### Sync フィールドリスト
** `version` **
テンプレート定義のバージョンです。現在、`2018-05-29` のみがサポートされています。この値は必須です。
** `operation` **
実行する DynamoDB の処理。`Sync` の処理を実行するには、これに `Sync` を設定する必要があります。この値は必須です。
** `filter` **
DynamoDB からの結果が返される前に、その結果をフィルタリングするために使用するフィルタです。フィルタの詳細については、「[フィルタ](aws-appsync-resolver-mapping-template-reference-dynamodb-filter.md)」を参照してください。このフィールドはオプションです。
** `limit` **
一度に評価する項目の最大数です。このフィールドはオプションです。省略した場合、デフォルトの制限は `100` 項目に設定されます。このフィールドの最大値は `1000` 項目です。
** `nextToken` **
前のクエリを継続するためのページ分割トークンです。これは前のクエリから取得されます。このフィールドはオプションです。
** `lastSync` **
最後に成功した `Sync` オペレーションが開始されたエポックミリ秒単位の時刻。指定すると、`lastSync` 以降に変更された項目のみが返されます。このフィールドはオプションです。最初の `Sync` オペレーションからすべてのページを取得した後にのみ入力する必要があります。省略した場合は、*ベース*テーブルの結果が返されます。それ以外の場合は、*差分*テーブルの結果が返されます。
**`basePartitionKey`**
`Sync` オペレーションを実行する際に使用される*ベース*テーブルのパーティションキー。このフィールドにより、テーブルがカスタムパーティションキーを使用している場合に `Sync` オペレーションを実行できます。これはオプションのフィールドです。
**`deltaIndexName`**
`Sync` オペレーションに使用されるインデックス。このインデックスは、テーブルがカスタムパーティションキーを使用する場合に、デルタストアテーブル全体で `Sync` オペレーション作を有効にするために必要です。`Sync` オペレーションは GSI (`gsi_ds_pk` と `gsi_ds_sk` で作成) 上で実行されます。このフィールドはオプションです。
DynamoDB 同期により返された結果が自動的に GraphQL プリミティブ型と JSON プリミティブ型に変換され、マッピングコンテキスト (`$context.result`) で参照できます。
DynamoDB の型変換の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)」を参照してください。
レスポンスマッピングテンプレートの詳細については、「[リゾルバーのマッピングテンプレートの概要](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)」を参照してください。
結果は以下の構造を持ちます。
```
{
items = [ ... ],
nextToken = "a pagination token",
scannedCount = 10,
startedAt = 1550000000000
}
```
各フィールドの定義は以下のようになります。
** `items` **
同期により返された項目を含むリストです。
** `nextToken` **
さらに結果がある場合、 には、別のリクエストで使用できるページ分割トークン`nextToken`が含まれています。 AWS AppSync は、DynamoDB から返されるページ分割トークンを暗号化して難読化します。これにより、テーブルデータが誤って呼び出し元に漏えいされるのを防ぎます。また、これらのページ分割トークンは異なるリゾルバー間では使用できません。
** `scannedCount` **
フィルタ式 (ある場合) が適用される前に、DynamoDB により取得された項目の数です。
** `startedAt` **
エポックミリ秒単位の時刻ですが、同期オペレーションが開始されれば、ローカルに保存して別のリクエストで `lastSync` の引数として使用することができます。ページ分割トークンがリクエストに含まれている場合、この値は、結果の最初のページのリクエストによって返されたものと同じになります。
## 例
次の例は、GraphQL クエリ: `syncPosts(nextToken: String, lastSync: AWSTimestamp)` のマッピングテンプレートです。
この例では、`lastSync` を省略すると、ベーステーブルのすべてのエントリが返されます。`lastSync` が指定されている場合は、`lastSync` 以降に変更された差分同期テーブルのエントリのみが返されます。
```
{
"version" : "2018-05-29",
"operation" : "Sync",
"limit": 100,
"nextToken": $util.toJson($util.defaultIfNull($ctx.args.nextToken, null)),
"lastSync": $util.toJson($util.defaultIfNull($ctx.args.lastSync, null))
}
```
# BatchGetItem
`BatchGetItem` リクエストマッピングドキュメントを使用すると、 AWS AppSync DynamoDB リゾルバーに、複数のテーブルにまたがる可能性のある複数の項目を取得するように DynamoDB に`BatchGetItem`リクエストするように指示できます。このリクエストテンプレートでは、以下の情報を指定する必要があります。
+ 項目を取得するテーブルの名前
+ 各テーブルから取得する項目のキー
DynamoDB の `BatchGetItem` 制限が適用されるため、**条件式を指定することはできません**。
`BatchGetItem` マッピングドキュメントの構造は次のとおりです。
```
{
"version" : "2018-05-29",
"operation" : "BatchGetItem",
"tables" : {
"table1": {
"keys": [
## Item to retrieve Key
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item2 to retrieve Key
{
"foo" : ... typed value,
"bar" : ... typed value
}
],
"consistentRead": true|false,
"projection" : {
...
}
},
"table2": {
"keys": [
## Item3 to retrieve Key
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item4 to retrieve Key
{
"foo" : ... typed value,
"bar" : ... typed value
}
],
"consistentRead": true|false,
"projection" : {
...
}
}
}
}
```
各フィールドの定義は以下のようになります。
## BatchGetItem フィールド
### BatchGetItem フィールドリスト
** `version` **
テンプレート定義のバージョンです。`2018-05-29` のみサポートされています。この値は必須です。
** `operation` **
実行する DynamoDB の処理。`BatchGetItem` DynamoDB の処理を実行するには、これを `BatchGetItem` に設定する必要があります。この値は必須です。
** `tables` **
項目を取得する DynamoDB テーブル。値は、キーとしてテーブル名が指定されているマップです。1 つ以上のテーブルを指定する必要があります。この `tables` の値は必須です。
** `keys` **
取り出す項目のプライマリキーを表す DynamoDB キーのリスト。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。
** `consistentRead` **
*GetItem* 処理の実行時に整合性のある読み込みを使用するかどうか。この値はオプションであり、デフォルトは *false* です。
**`projection`**
DynamoDB オペレーションから返される属性を指定するために使用されるプロジェクション。プロジェクションの詳細については、「[プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)」を参照してください。このフィールドはオプションです。
覚えておくべきポイント:
+ 項目がテーブルから取得されなかった場合は、そのテーブルの data ブロックに *null* 要素があります。
+ 呼び出し結果は、リクエストマッピングテンプレート内で提供された順序に基づいて、テーブル別にソートされます。
+ `Get` 内の各 `BatchGetItem` コマンドはアトミックですが、バッチは部分的に処理される場合があります。エラーのためにバッチが部分的に処理された場合、未処理のキーは *unprocessedKeys* ブロック内に呼び出し結果の一部として返されます。
+ `BatchGetItem` は 100 キーに制限されています。
以下に示しているのは、リクエストマッピングテンプレートの例です。
```
{
"version": "2018-05-29",
"operation": "BatchGetItem",
"tables": {
"authors": [
{
"author_id": {
"S": "a1"
}
},
],
"posts": [
{
"author_id": {
"S": "a1"
},
"post_id": {
"S": "p2"
}
}
],
}
}
```
`$ctx.result` で使用可能な呼び出し結果は以下のとおりです。
```
{
"data": {
"authors": [null],
"posts": [
# Was retrieved
{
"author_id": "a1",
"post_id": "p2",
"post_title": "title",
"post_description": "description",
}
]
},
"unprocessedKeys": {
"authors": [
# This item was not processed due to an error
{
"author_id": "a1"
}
],
"posts": []
}
}
```
`$ctx.error` にエラーに関する詳細が含まれています。**data** キー、**unprocessedKeys** キー、およびリクエストマッピングテンプレートで渡された各テーブルキーは呼び出し結果に必ずあります。削除された項目は **data** ブロックにあります。処理されなかった項目は、data ブロック内で *null* としてマークされ、**unprocessedKeys** ブロックに挿入されます。
より完全な例については、AppSync の DynamoDB Batch の「[チュートリアル: DynamoDB Batch リゾルバー」](tutorial-dynamodb-batch.md#aws-appsync-tutorial-dynamodb-batch)を参照してください。
# BatchDeleteItem
`BatchDeleteItem` リクエストマッピングドキュメントを使用すると、 AWS AppSync DynamoDB リゾルバーに、複数のテーブルにまたがる可能性のある複数の項目を削除するよう DynamoDB に`BatchWriteItem`リクエストするように指示できます。このリクエストテンプレートでは、以下の情報を指定する必要があります。
+ 項目を削除するテーブルの名前
+ 各テーブルから削除する項目のキー
DynamoDB の `BatchWriteItem` 制限が適用されるため、**条件式を指定することはできません**。
`BatchDeleteItem` マッピングドキュメントの構造は次のとおりです。
```
{
"version" : "2018-05-29",
"operation" : "BatchDeleteItem",
"tables" : {
"table1": [
## Item to delete Key
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item2 to delete Key
{
"foo" : ... typed value,
"bar" : ... typed value
}],
"table2": [
## Item3 to delete Key
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item4 to delete Key
{
"foo" : ... typed value,
"bar" : ... typed value
}],
}
}
```
各フィールドの定義は以下のようになります。
## BatchDeleteItem フィールド
### BatchDeleteItem フィールドリスト
** `version` **
テンプレート定義のバージョンです。`2018-05-29` のみサポートされています。この値は必須です。
** `operation` **
実行する DynamoDB の処理。`BatchDeleteItem` DynamoDB の処理を実行するには、これを `BatchDeleteItem` に設定する必要があります。この値は必須です。
** `tables` **
項目を削除する DynamoDB テーブル。各テーブルは、削除する項目のプライマリキーを表す DynamoDB キーのリストです。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。1 つ以上のテーブルを指定する必要があります。値 が必要です。
覚えておくべきポイント:
+ `DeleteItem` オペレーションとは対照的に、完全に削除された項目はレスポンスで返されません。渡されたキーのみが返されます。
+ 項目がテーブルから削除されなかった場合は、そのテーブルの data ブロックに *null* 要素があります。
+ 呼び出し結果は、リクエストマッピングテンプレート内で提供された順序に基づいて、テーブル別にソートされます。
+ `BatchDeleteItem` 内部の各 `Delete` コマンドはアトミックです。ただし、バッチは部分的に処理できます。エラーのためにバッチが部分的に処理された場合、未処理のキーは *unprocessedKeys* ブロック内に呼び出し結果の一部として返されます。
+ `BatchDeleteItem` は 25 キーに制限されています。
+ このオペレーション、競合検出で使用するとサポート**されていません**。両方を同時に使用すると、エラーが発生する可能性があります。
以下に示しているのは、リクエストマッピングテンプレートの例です。
```
{
"version": "2018-05-29",
"operation": "BatchDeleteItem",
"tables": {
"authors": [
{
"author_id": {
"S": "a1"
}
},
],
"posts": [
{
"author_id": {
"S": "a1"
},
"post_id": {
"S": "p2"
}
}
],
}
}
```
`$ctx.result` で使用可能な呼び出し結果は以下のとおりです。
```
{
"data": {
"authors": [null],
"posts": [
# Was deleted
{
"author_id": "a1",
"post_id": "p2"
}
]
},
"unprocessedKeys": {
"authors": [
# This key was not processed due to an error
{
"author_id": "a1"
}
],
"posts": []
}
}
```
`$ctx.error` にエラーに関する詳細が含まれています。**data** キー、**unprocessedKeys** キー、およびリクエストマッピングテンプレートで渡された各テーブルキーは呼び出し結果に必ずあります。削除された項目は **data** ブロックにあります。処理されなかった項目は、data ブロック内で *null* としてマークされ、**unprocessedKeys** ブロックに挿入されます。
より完全な例については、AppSync の DynamoDB Batch の「[チュートリアル: DynamoDB Batch リゾルバー」](tutorial-dynamodb-batch.md#aws-appsync-tutorial-dynamodb-batch)を参照してください。
# BatchPutItem
`BatchPutItem` リクエストマッピングドキュメントを使用すると、 AWS AppSync DynamoDB リゾルバーに、複数のテーブルにまたがる可能性のある複数の項目を配置するように DynamoDB に`BatchWriteItem`リクエストするように指示できます。このリクエストテンプレートでは、以下の情報を指定する必要があります。
+ 項目を挿入するテーブルの名前
+ 各テーブルに挿入するすべての項目
DynamoDB の `BatchWriteItem` 制限が適用されるため、**条件式を指定することはできません**。
`BatchPutItem` マッピングドキュメントの構造は次のとおりです。
```
{
"version" : "2018-05-29",
"operation" : "BatchPutItem",
"tables" : {
"table1": [
## Item to put
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item2 to put
{
"foo" : ... typed value,
"bar" : ... typed value
}],
"table2": [
## Item3 to put
{
"foo" : ... typed value,
"bar" : ... typed value
},
## Item4 to put
{
"foo" : ... typed value,
"bar" : ... typed value
}],
}
}
```
各フィールドの定義は以下のようになります。
## BatchPutItem フィールド
### BatchPutItem フィールドリスト
** `version` **
テンプレート定義のバージョンです。`2018-05-29` のみサポートされています。この値は必須です。
** `operation` **
実行する DynamoDB の処理。`BatchPutItem` DynamoDB の処理を実行するには、これを `BatchPutItem` に設定する必要があります。この値は必須です。
** `tables` **
項目を挿入する DynamoDB テーブル。各テーブルエントリは、この特定のテーブルに挿入する DynamoDB 項目のリストを表します。1 つ以上のテーブルを指定する必要があります。この値は必須です。
覚えておくべきポイント:
+ 完全に挿入された項目がレスポンスに返されます (正常に挿入された場合)。
+ 項目がテーブルに挿入されなかった場合は、そのテーブルの data ブロックに *null* 要素があります。
+ 挿入された項目は、リクエストマッピングテンプレート内で提供された順序に基づいて、テーブル別にソートされます。
+ `BatchPutItem` 内の各 `Put` コマンドはアトミックですが、バッチは部分的に処理される場合があります。エラーのためにバッチが部分的に処理された場合、未処理のキーは *unprocessedKeys* ブロック内に呼び出し結果の一部として返されます。
+ `BatchPutItem` は 25 項目に制限されています。
+ このオペレーション、競合検出で使用するとサポート**されていません**。両方を同時に使用すると、エラーが発生する可能性があります。
以下に示しているのは、リクエストマッピングテンプレートの例です。
```
{
"version": "2018-05-29",
"operation": "BatchPutItem",
"tables": {
"authors": [
{
"author_id": {
"S": "a1"
},
"author_name": {
"S": "a1_name"
}
},
],
"posts": [
{
"author_id": {
"S": "a1"
},
"post_id": {
"S": "p2"
},
"post_title": {
"S": "title"
}
}
],
}
}
```
`$ctx.result` で使用可能な呼び出し結果は以下のとおりです。
```
{
"data": {
"authors": [
null
],
"posts": [
# Was inserted
{
"author_id": "a1",
"post_id": "p2",
"post_title": "title"
}
]
},
"unprocessedItems": {
"authors": [
# This item was not processed due to an error
{
"author_id": "a1",
"author_name": "a1_name"
}
],
"posts": []
}
}
```
`$ctx.error` にエラーに関する詳細が含まれています。**data** キー、**The keys data, unprocessedItems** キー、およびリクエストマッピングテンプレートで渡された各テーブルキーは呼び出し結果に必ずあります。挿入された項目は **data** ブロックにあります。処理されなかった項目は、data ブロック内で *null* としてマークされ、**unprocessedItems** ブロックに挿入されます。
より完全な例については、AppSync の DynamoDB Batch の「[チュートリアル: DynamoDB Batch リゾルバー」](tutorial-dynamodb-batch.md#aws-appsync-tutorial-dynamodb-batch)を参照してください。
# TransactGetItems
`TransactGetItems` リクエストマッピングドキュメントを使用すると、 AWS AppSync DynamoDB リゾルバーに、複数のテーブルにまたがる可能性のある複数の項目を取得するリクエストを DynamoDB `TransactGetItems`に行うように指示できます。このリクエストテンプレートでは、以下の情報を指定する必要があります。
+ 項目の取得元となる各リクエスト項目のテーブル名
+ 各テーブルから取得する各リクエスト項目のキー
DynamoDB の `TransactGetItems` 制限が適用されるため、**条件式を指定することはできません**。
`TransactGetItems` マッピングドキュメントの構造は次のとおりです。
```
{
"version": "2018-05-29",
"operation": "TransactGetItems",
"transactItems": [
## First request item
{
"table": "table1",
"key": {
"foo": ... typed value,
"bar": ... typed value
},
"projection" : {
...
}
},
## Second request item
{
"table": "table2",
"key": {
"foo": ... typed value,
"bar": ... typed value
},
"projection" : {
...
}
}
]
}
```
各フィールドの定義は以下のようになります。
## TransactGetItems フィールド
### TransactGetItems フィールドリスト
** `version` **
テンプレート定義のバージョンです。`2018-05-29` のみサポートされています。この値は必須です。
** `operation` **
実行する DynamoDB の処理。`TransactGetItems` DynamoDB の処理を実行するには、これを `TransactGetItems` に設定する必要があります。この値は必須です。
** `transactItems` **
含めるリクエスト項目。値はリクエスト項目の配列です。少なくとも 1 つのリクエスト項目を指定する必要があります。この `transactItems` の値は必須です。
** `table` **
項目の取得元となる DynamoDB テーブル。値はテーブル名の文字列です。この `table` の値は必須です。
** `key` **
取り出す項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。
**`projection`**
DynamoDB オペレーションから返される属性を指定するために使用されるプロジェクション。プロジェクションの詳細については、「[プロジェクション](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)」を参照してください。このフィールドはオプションです。
覚えておくべきポイント:
+ トランザクションが成功すると、`items` ブロック内で取得された項目の順序はリクエスト項目の順序と同じになります。
+ トランザクションは、オールオアナッシング方式で実行されます。いずれかのリクエスト項目でエラーが発生した場合、トランザクション全体は実行されず、エラーの詳細が返されます。
+ リクエスト項目を取得できなくても、エラーではありません。代わりに、*null*要素が対応する位置の*項目*ブロックに表示されます。
+ トランザクションのエラーが *TransactionCanceledException* である場合、`cancellationReasons` ブロックに入力されます。`cancellationReasons` ブロック内のキャンセル理由の順序は、リクエスト項目の順序と同じになります。
+ `TransactGetItems` のリクエスト項目数は 100 個に制限されています。
以下に示しているのは、リクエストマッピングテンプレートの例です。
```
{
"version": "2018-05-29",
"operation": "TransactGetItems",
"transactItems": [
## First request item
{
"table": "posts",
"key": {
"post_id": {
"S": "p1"
}
}
},
## Second request item
{
"table": "authors",
"key": {
"author_id": {
"S": a1
}
}
}
]
}
```
トランザクションが成功し、最初にリクエストされた項目だけが取得された場合、`$ctx.result` で使用できる呼び出し結果は次のようになります。
```
{
"items": [
{
// Attributes of the first requested item
"post_id": "p1",
"post_title": "title",
"post_description": "description"
},
// Could not retrieve the second requested item
null,
],
"cancellationReasons": null
}
```
最初のリクエスト項目によって発生した *TransactionCanceledException* が原因でトランザクションが失敗した場合、`$ctx.result` で使用可能な呼び出し結果は次のようになります。
```
{
"items": null,
"cancellationReasons": [
{
"type":"Sample error type",
"message":"Sample error message"
},
{
"type":"None",
"message":"None"
}
]
}
```
`$ctx.error` にエラーに関する詳細が含まれています。キー **items** と **cancellationReasons** は、`$ctx.result` にあることが保証されています。
より完全な例については、AppSync を使用した DynamoDB トランザクションのチュートリアル「[チュートリアル: DynamoDB Transaction リゾルバー](tutorial-dynamodb-transact.md#aws-appsync-tutorial-dynamodb-transact)」を参照してください。
# TransactWriteItems
`TransactWriteItems` リクエストマッピングドキュメントを使用すると、 AWS AppSync DynamoDB リゾルバーに、複数のテーブル`TransactWriteItems`に複数の項目を書き込むリクエストを DynamoDB に行うように指示できます。このリクエストテンプレートでは、以下の情報を指定する必要があります。
+ 各リクエスト項目の書き込み先テーブル名
+ 実行する各リクエスト項目のオペレーション。サポートされているオペレーションには、*PutItem*、*UpdateItem*、*DeleteItem*、および *ConditionCheck* の 4 種類があります。
+ 書き込む各リクエスト項目のキー
DynamoDB の `TransactWriteItems` 制限が適用されます。
`TransactWriteItems` マッピングドキュメントの構造は次のとおりです。
```
{
"version": "2018-05-29",
"operation": "TransactWriteItems",
"transactItems": [
{
"table": "table1",
"operation": "PutItem",
"key": {
"foo": ... typed value,
"bar": ... typed value
},
"attributeValues": {
"baz": ... typed value
},
"condition": {
"expression": "someExpression",
"expressionNames": {
"#foo": "foo"
},
"expressionValues": {
":bar": ... typed value
},
"returnValuesOnConditionCheckFailure": true|false
}
},
{
"table":"table2",
"operation": "UpdateItem",
"key": {
"foo": ... typed value,
"bar": ... typed value
},
"update": {
"expression": "someExpression",
"expressionNames": {
"#foo": "foo"
},
"expressionValues": {
":bar": ... typed value
}
},
"condition": {
"expression": "someExpression",
"expressionNames": {
"#foo":"foo"
},
"expressionValues": {
":bar": ... typed value
},
"returnValuesOnConditionCheckFailure": true|false
}
},
{
"table": "table3",
"operation": "DeleteItem",
"key":{
"foo": ... typed value,
"bar": ... typed value
},
"condition":{
"expression": "someExpression",
"expressionNames": {
"#foo": "foo"
},
"expressionValues": {
":bar": ... typed value
},
"returnValuesOnConditionCheckFailure": true|false
}
},
{
"table": "table4",
"operation": "ConditionCheck",
"key":{
"foo": ... typed value,
"bar": ... typed value
},
"condition":{
"expression": "someExpression",
"expressionNames": {
"#foo": "foo"
},
"expressionValues": {
":bar": ... typed value
},
"returnValuesOnConditionCheckFailure": true|false
}
}
]
}
```
## TransactWriteItems フィールド
### TransactWriteItems フィールドリスト
**各フィールドの定義は以下のようになります。**
** `version` **
テンプレート定義のバージョンです。`2018-05-29` のみサポートされています。この値は必須です。
** `operation` **
実行する DynamoDB の処理。`TransactWriteItems` DynamoDB の処理を実行するには、これを `TransactWriteItems` に設定する必要があります。この値は必須です。
** `transactItems` **
含めるリクエスト項目。値はリクエスト項目の配列です。少なくとも 1 つのリクエスト項目を指定する必要があります。この `transactItems` の値は必須です。
`PutItem` の場合、各フィールドの定義は以下のようになります。
** `table` **
送信先のの DynamoDB テーブル。値はテーブル名の文字列です。この `table` の値は必須です。
** `operation` **
実行する DynamoDB の処理。`PutItem` DynamoDB の処理を実行するには、これを `PutItem` に設定する必要があります。この値は必須です。
** `key` **
配置する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この値は必須です。
** `attributeValues` **
DynamoDB に渡す項目の残りの属性です。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。このフィールドはオプションです。
** `condition` **
DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件が指定されていない場合、`PutItem` リクエストはその項目の既存のエントリを上書きします。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「[トランザクション条件式](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)」を参照してください。この値はオプションです。
`UpdateItem` の場合、各フィールドの定義は以下のようになります。
** `table` **
更新する DynamoDB テーブル。値はテーブル名の文字列です。この `table` の値は必須です。
** `operation` **
実行する DynamoDB の処理。`UpdateItem` DynamoDB の処理を実行するには、これを `UpdateItem` に設定する必要があります。この値は必須です。
** `key` **
更新する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この値は必須です。
** `update` **
`update` セクションには、 DynamoDBの項目の更新方法を示す更新式を指定することができます。更新式の記述方法の詳細については、「[DynamoDB UpdateExpressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)」のドキュメントを参照してください。このセクションは必須です。
** `condition` **
DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合は、`UpdateItem` リクエストによって、現在の状態にかかわらず、既存のエントリが更新されます。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「[トランザクション条件式](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)」を参照してください。この値はオプションです。
`DeleteItem` の場合、各フィールドの定義は以下のようになります。
** `table` **
項目を削除する DynamoDB テーブル。値はテーブル名の文字列です。この `table` の値は必須です。
** `operation` **
実行する DynamoDB の処理。`DeleteItem` DynamoDB の処理を実行するには、これを `DeleteItem` に設定する必要があります。この値は必須です。
** `key` **
削除する項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この値は必須です。
** `condition` **
DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件を指定していない場合、`DeleteItem` リクエストによって、現在の状態にかかわらず、項目が削除されます。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「[トランザクション条件式](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)」を参照してください。この値はオプションです。
`ConditionCheck` の場合、各フィールドの定義は以下のようになります。
** `table` **
条件をチェックする DynamoDB テーブル。値はテーブル名の文字列です。この `table` の値は必須です。
** `operation` **
実行する DynamoDB の処理。`ConditionCheck` DynamoDB の処理を実行するには、これを `ConditionCheck` に設定する必要があります。この値は必須です。
** `key` **
条件チェックする項目のプライマリキーを表す DynamoDB キー。DynamoDB の項目には、単一のハッシュキー、またはハッシュキーとソートキーが含まれています。これはテーブルの構造によって変わります。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この値は必須です。
** `condition` **
DynamoDB 内に既に存在するオブジェクトの状態に基づき、リクエストが成功するかどうかを判断する条件です。条件チェックに失敗した場合に、既存の項目を取得し直すかどうかを指定できます。トランザクション条件の詳細については、「[トランザクション条件式](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)」を参照してください。この値は必須です。
覚えておくべきポイント:
+ リクエスト項目のキーのみがレスポンスに返されます (正常に挿入された場合)。キーの順序は、リクエスト項目の順序と同じです。
+ トランザクションは、オールオアナッシング方式で実行されます。いずれかのリクエスト項目でエラーが発生した場合、トランザクション全体は実行されず、エラーの詳細が返されます。
+ 同じ項目をターゲットにできるリクエスト項目が 2 つありません。それ以外の場合は、*TransactionCanceledException* エラーが発生します。
+ トランザクションのエラーが *TransactionCanceledException* である場合、`cancellationReasons` ブロックに入力されます。リクエスト項目の条件チェックが失敗し、**かつ** `returnValuesOnConditionCheckFailure` を `false` に指定しなかった場合、テーブルに存在する項目が取得され、`item` で `cancellationReasons` ブロックの対応する位置に保存されます。
+ `TransactWriteItems` のリクエスト項目数は 100 個に制限されています。
+ このオペレーション、競合検出で使用するとサポート**されていません**。両方を同時に使用すると、エラーが発生する可能性があります。
以下に示しているのは、リクエストマッピングテンプレートの例です。
```
{
"version": "2018-05-29",
"operation": "TransactWriteItems",
"transactItems": [
{
"table": "posts",
"operation": "PutItem",
"key": {
"post_id": {
"S": "p1"
}
},
"attributeValues": {
"post_title": {
"S": "New title"
},
"post_description": {
"S": "New description"
}
},
"condition": {
"expression": "post_title = :post_title",
"expressionValues": {
":post_title": {
"S": "Expected old title"
}
}
}
},
{
"table":"authors",
"operation": "UpdateItem",
"key": {
"author_id": {
"S": "a1"
},
},
"update": {
"expression": "SET author_name = :author_name",
"expressionValues": {
":author_name": {
"S": "New name"
}
}
},
}
]
}
```
トランザクションが成功した場合、`$ctx.result` で使用できる呼び出し結果は次のようになります。
```
{
"keys": [
// Key of the PutItem request
{
"post_id": "p1",
},
// Key of the UpdateItem request
{
"author_id": "a1"
}
],
"cancellationReasons": null
}
```
`PutItem` リクエストの条件チェックに失敗したためにトランザクションが失敗した場合、 で使用できる呼び出し結果は次のようになります。
```
{
"keys": null,
"cancellationReasons": [
{
"item": {
"post_id": "p1",
"post_title": "Actual old title",
"post_description": "Old description"
},
"type": "ConditionCheckFailed",
"message": "The condition check failed."
},
{
"type": "None",
"message": "None"
}
]
}
```
`$ctx.error` にエラーに関する詳細が含まれています。**keys** および **cancellationReasons** が `$ctx.result` に存在することが保証されています。
より完全な例については、AppSync を使用した DynamoDB トランザクションのチュートリアル「[チュートリアル: DynamoDB Transaction リゾルバー](tutorial-dynamodb-transact.md#aws-appsync-tutorial-dynamodb-transact)」を参照してください。
# 型システム (リクエストマッピング)
AWS AppSync DynamoDB リゾルバーを使用して DynamoDB テーブルを呼び出す場合、 AWS AppSync はその呼び出しで使用する各値のタイプを知る必要があります。これは、DynamoDB が GraphQL や JSON よりも多くのタイプのプリミティブ (セットやバイナリデータなど) をサポートしているためです。 AWS AppSync は、GraphQL と DynamoDB の間で変換するときにいくつかのヒントを必要とします。そうしないと、テーブル内のデータの構造についていくつかの仮定を行う必要があります。
DynamoDB のデータ型の詳細については、DynamoDB の「[データ型記述子](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html#Programming.LowLevelAPI.DataTypeDescriptors)」および「[データ型](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)」の各ドキュメントを参照してください。
DynamoDB の値は、単一のキーと値のペアを含む JSON オブジェクトで表されます。キーは DynamoDB の型を指定し、値はその値自身を指定します。次の例では、キー `S` は値が文字列であることを示し、値 `identifier` がその文字列値です。
```
{ "S" : "identifier" }
```
JSON オブジェクトは複数のキーと値のペアを持つことはできません。複数のキーと値のペアが指定されている場合、リクエストマッピングドキュメントは解析されません。
DynamoDB の値は、値を指定する必要がある場合にはリクエストマッピングドキュメントのどこかで使用されます。これが必要になる箇所には、`key` セクションと `attributeValue` セクション、および式セクションの `expressionValues` セクションが含まれています。次の例では、DynamoDB の文字列値 `identifier` が、(おそらくは `GetItem` リクエストマッピングドキュメントの) `key` セクションの `id` フィールドに割り当てられています。
```
"key" : {
"id" : { "S" : "identifier" }
}
```
**サポートされているタイプ**
AWS AppSync は、次の DynamoDB スカラー、ドキュメント、およびセットタイプをサポートしています。
**文字列型 `S` **
単一の文字列値です。DynamoDB の文字列値は次のように表されます。
```
{ "S" : "some string" }
```
以下は使用例です。
```
"key" : {
"id" : { "S" : "some string" }
}
```
**文字列セット型 `SS` **
1 組の文字列値です。DynamoDB の文字列セット値は次のように表されます。
```
{ "SS" : [ "first value", "second value", ... ] }
```
以下は使用例です。
```
"attributeValues" : {
"phoneNumbers" : { "SS" : [ "+1 555 123 4567", "+1 555 234 5678" ] }
}
```
**数値型 `N` **
単一の数値です。DynamoDB の数値は次のように表されます。
```
{ "N" : 1234 }
```
以下は使用例です。
```
"expressionValues" : {
":expectedVersion" : { "N" : 1 }
}
```
**数値セット型 `NS` **
1 組の数値です。DynamoDB の数値セット値は次のように表されます。
```
{ "NS" : [ 1, 2.3, 4 ... ] }
```
以下は使用例です。
```
"attributeValues" : {
"sensorReadings" : { "NS" : [ 67.8, 12.2, 70 ] }
}
```
**バイナリ型 `B` **
バイナリ値です。DynamoDB のバイナリ値は次のように表されます。
```
{ "B" : "SGVsbG8sIFdvcmxkIQo=" }
```
値は実際には文字列であり、文字列はバイナリデータの base64 でエンコードされた表現です。 AWS AppSync はこの文字列をバイナリ値にデコードしてから DynamoDB に送信します。 AWS AppSync は RFC 2045 で定義されている base64 デコードスキームを使用します。base64 アルファベットにない文字は無視されます。
以下は使用例です。
```
"attributeValues" : {
"binaryMessage" : { "B" : "SGVsbG8sIFdvcmxkIQo=" }
}
```
**バイナリセット型 `BS` **
1 組のバイナリ値です。DynamoDB のバイナリセット値は次のように表されます。
```
{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }
```
値は実際には文字列であり、文字列はバイナリデータの base64 でエンコードされた表現です。 AWS AppSync はこの文字列をバイナリ値にデコードしてから DynamoDB に送信します。 AWS AppSync は、RFC 2045 で定義されている base64 デコードスキームを使用します。base64 アルファベットにない文字は無視されます。
以下は使用例です。
```
"attributeValues" : {
"binaryMessages" : { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ] }
}
```
**ブール型 `BOOL` **
ブール値。DynamoDB のブール値は次のように表されます。
```
{ "BOOL" : true }
```
有効な値は、`true` と `false` のみです。
以下は使用例です。
```
"attributeValues" : {
"orderComplete" : { "BOOL" : false }
}
```
**リスト型 `L` **
サポートされているその他の DynamoDB の値のリストです。DynamoDB のリスト値は次のように表されます。
```
{ "L" : [ ... ] }
```
この値は複合値です。リストには、サポートされる DynamoDB の値 (他のリストも含む) が 0 個以上入ります。このリストには、異なる型を混在させることもできます。
以下は使用例です。
```
{ "L" : [
{ "S" : "A string value" },
{ "N" : 1 },
{ "SS" : [ "Another string value", "Even more string values!" ] }
]
}
```
**マップ型 `M` **
サポートされる他の DynamoDB の値の、キーと値のペアの順序付けされていない集合を表します。DynamoDB のマップ値は次のように表されます。
```
{ "M" : { ... } }
```
マップには 0 個以上のキーと値のペアが入ります。キーは文字列である必要があり、値には、サポートされている DynamoDB の任意の値 (他のマップを含む) が使用できます。このマップには、異なる型を混在させることもできます。
以下は使用例です。
```
{ "M" : {
"someString" : { "S" : "A string value" },
"someNumber" : { "N" : 1 },
"stringSet" : { "SS" : [ "Another string value", "Even more string values!" ] }
}
}
```
**Null 型 `NULL` **
null 値です。DynamoDB の Null 値は次のように表されます。
```
{ "NULL" : null }
```
以下は使用例です。
```
"attributeValues" : {
"phoneNumbers" : { "NULL" : null }
}
```
各タイプの詳細については、[DynamoDB のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html)を参照してください。
# 型システム (レスポンスマッピング)
DynamoDB からレスポンスを受信すると、 AWS AppSync はそれを GraphQL プリミティブ型と JSON プリミティブ型に自動的に変換します。DynamoDB の各属性はデコードされ、レスポンスマッピングコンテキストで返されます。
たとえば、DynamoDB が以下を返したとします。
```
{
"id" : { "S" : "1234" },
"name" : { "S" : "Nadia" },
"age" : { "N" : 25 }
}
```
次に、 AWS AppSync DynamoDB リゾルバーはそれを次のように GraphQL 型と JSON 型に変換します。
```
{
"id" : "1234",
"name" : "Nadia",
"age" : 25
}
```
このセクションでは、 AWS AppSync が次の DynamoDB スカラー、ドキュメント、およびセットタイプを変換する方法について説明します。
**文字列型 `S` **
単一の文字列値です。DynamoDB 文字列値が文字列として返されます。
たとえば、DynamoDB が次の DynamoDB の文字列値を返したとします。
```
{ "S" : "some string" }
```
AWS AppSync はこれを文字列に変換します。
```
"some string"
```
**文字列セット型 `SS` **
1 組の文字列値です。DynamoDB 文字列セット値が文字列のリストとして返されます。
たとえば、DynamoDB が次の DynamoDB 文字列セット値を返したとします。
```
{ "SS" : [ "first value", "second value", ... ] }
```
AWS AppSync はこれを文字列のリストに変換します。
```
[ "+1 555 123 4567", "+1 555 234 5678" ]
```
**数値型 `N` **
単一の数値です。DynamoDB 数値が数字として返されます。
たとえば、DynamoDB が次の DynamoDB の数値を返したとします。
```
{ "N" : 1234 }
```
AWS AppSync はこれを数値に変換します。
```
1234
```
**数値セット型 `NS` **
1 組の数値です。DynamoDB 数値セットが数字のリストとして返されます。
たとえば、DynamoDB が次の DynamoDB の数値セット値を返したとします。
```
{ "NS" : [ 67.8, 12.2, 70 ] }
```
AWS AppSync はこれを数値のリストに変換します。
```
[ 67.8, 12.2, 70 ]
```
**バイナリ型 `B` **
バイナリ値です。DynamoDB のバイナリ値は、その値を Base64 で表した文字列として返されます。
たとえば、DynamoDB が次の DynamoDB のバイナリ値を返したとします。
```
{ "B" : "SGVsbG8sIFdvcmxkIQo=" }
```
AWS AppSync は、値を base64 で表現した文字列に変換します。
```
"SGVsbG8sIFdvcmxkIQo="
```
バイナリデータは、[RFC 4648](https://tools.ietf.org/html/rfc4648) と [RFC 2045](https://tools.ietf.org/html/rfc2045) で指定されているようにして Base64 エンコーディングスキームにエンコードされます。
**バイナリセット型 `BS` **
1 組のバイナリ値です。DynamoDB のバイナリセット値は、その値を Base64 で表した文字列のリストとして返されます。
たとえば、DynamoDB が次の DynamoDB のバイナリ値を返したとします。
```
{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }
```
AWS AppSync は、値を base64 で表現した文字列のリストに変換します。
```
[ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ]
```
バイナリデータは、[RFC 4648](https://tools.ietf.org/html/rfc4648) と [RFC 2045](https://tools.ietf.org/html/rfc2045) で指定されているようにして Base64 エンコーディングスキームにエンコードされます。
**ブール型 `BOOL` **
ブール値。DynamoDB ブール値がブールとして返されます。
たとえば、DynamoDB が次の DynamoDB のブール値を返したとします。
```
{ "BOOL" : true }
```
AWS AppSync はこれをブールに変換します。
```
true
```
**リスト型 `L` **
サポートされているその他の DynamoDB の値のリストです。DynamoDB のリスト値は値のリストとして返され、内部のそれぞれの値も変換されます。
たとえば、DynamoDB が次の DynamoDB の文字列値を返したとします。
```
{ "L" : [
{ "S" : "A string value" },
{ "N" : 1 },
{ "SS" : [ "Another string value", "Even more string values!" ] }
]
}
```
AWS AppSync はこれを変換された値のリストに変換します。
```
[ "A string value", 1, [ "Another string value", "Even more string values!" ] ]
```
**マップ型 `M` **
サポートされるその他の DynamoDB の値のキー/値の集合です。DynamoDB のマップ値は JSON オブジェクトとして返されます。それぞれのキー/値も変換されます。
たとえば、DynamoDB が次の DynamoDB のバイナリ値を返したとします。
```
{ "M" : {
"someString" : { "S" : "A string value" },
"someNumber" : { "N" : 1 },
"stringSet" : { "SS" : [ "Another string value", "Even more string values!" ] }
}
}
```
AWS AppSync はこれを JSON オブジェクトに変換します。
```
{
"someString" : "A string value",
"someNumber" : 1,
"stringSet" : [ "Another string value", "Even more string values!" ]
}
```
**Null 型 `NULL` **
null 値です。
たとえば、DynamoDB が次の DynamoDB のブール値を返したとします。
```
{ "NULL" : null }
```
AWS AppSync はこれを null に変換します。
```
null
```
# フィルター
`Query` 処理と `Scan` 処理を使用して DynamoDB のオブジェクトにクエリを実行する場合、オプションで、結果を評価する `filter` を指定して、必要な値のみを返すことができます。
`Query` または `Scan` マッピングドキュメントのフィルタマッピングセクションは以下の構造を持ちます。
```
"filter" : {
"expression" : "filter expression"
"expressionNames" : {
"#name" : "name",
},
"expressionValues" : {
":value" : ... typed value
},
}
```
各フィールドの定義は以下のようになります。
** `expression` **
クエリ式です。フィルタ式の記述方法の詳細については、「[DynamoDB QueryFilter](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.QueryFilter.html)」および「[DynamoDB ScanFilter](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.ScanFilter.html)」の各ドキュメントを参照してください。このフィールドの指定は必須です。
** `expressionNames` **
式の属性*名*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは、`expression` で使用される名前のプレースホルダーに対応します。値は、DynamoDB の項目の属性名に対応する文字列である必要があります。このフィールドはオプションであり、`expression` で使用される式の属性名のプレースホルダーのみを入力します。
** `expressionValues` **
式の属性*値*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは `expression` で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この指定は必須です。このフィールドはオプションであり、`expression` で使用される式の属性値のプレースホルダーのみを入力します。
## 例
次の例は、マッピングテンプレートのフィルターセクションです。ここでは、DynamoDB から取得されたエントリのうち、タイトルが `title` 引数で始まるもののみが返されます。
```
"filter" : {
"expression" : "begins_with(#title, :title)",
"expressionNames" : {
"#title" : "title"
},
"expressionValues" : {
":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
}
}
```
# 条件式
`PutItem`、`UpdateItem`、および `DeleteItem` の各 DynamoDB 処理を使用して DynamoDB のオブジェクトをミューテーションする場合、オプションで、処理を実行する前に、DynamoDB にある既存のオブジェクトの状態に基づいてリクエストが成功するかどうかを制御する条件式を指定することができます。
AWS AppSync DynamoDB リゾルバーでは`PutItem`、、`UpdateItem`、および `DeleteItem` リクエストマッピングドキュメントで条件式を指定できます。また、条件が失敗し、オブジェクトが更新されなかった場合に従う戦略も指定できます。
## 例 1
以下の `PutItem` マッピングドキュメントには条件式がありません。その結果、同じキーに対応する項目がすでにある場合でも、項目は DynamoDB に挿入され、それにより既存の項目が上書きされます。
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "1" }
}
}
```
## 例 2
次の `PutItem` マッピングドキュメントには条件式があります。この場合、同じキーの項目が DynamoDB に存在*しない*場合のみ処理が成功します。
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "1" }
},
"condition" : {
"expression" : "attribute_not_exists(id)"
}
}
```
デフォルトでは、条件チェックが失敗した場合、 AWS AppSync DynamoDB リゾルバーはミューテーションのエラーを返します。ただし、 AWS AppSync DynamoDB リゾルバーには、開発者が一般的なエッジケースを処理するのに役立ついくつかの追加機能があります。
+ AWS AppSync DynamoDB リゾルバーは、DynamoDB の現在の値が目的の結果と一致すると判断できる場合、オペレーションが成功したかのように処理します。
+ エラーを返す代わりに、カスタム Lambda 関数を呼び出して AWS AppSync DynamoDB リゾルバーが障害を処理する方法を決定するようにリゾルバーを設定できます。
これらの詳細については、「[条件チェックでのエラーを処理する](#aws-appsync-resolver-mapping-template-reference-dynamodb-condition-handling)」セクションを参照してください。
DynamoDB の条件式の詳細については、「[DynamoDB ConditionExpressions のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)」を参照してください。
## 条件を指定する
`PutItem`、`UpdateItem`、および `DeleteItem` の各リクエストマッピングドキュメントはすべて、オプションで `condition` セクションが指定できます。省略した場合、条件チェックは実行されません。指定した場合、処理が成功するには、条件が true となる必要があります。
`condition` セクションは以下の構造を持ちます。
```
"condition" : {
"expression" : "someExpression"
"expressionNames" : {
"#foo" : "foo"
},
"expressionValues" : {
":bar" : ... typed value
},
"equalsIgnore" : [ "version" ],
"consistentRead" : true,
"conditionalCheckFailedHandler" : {
"strategy" : "Custom",
"lambdaArn" : "arn:..."
}
}
```
以下のフィールドに条件を指定します。
** `expression` **
更新式そのものを指定します。条件式の記述方法の詳細については、[DynamoDB ConditionExpressions のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)を参照してください。このフィールドの指定は必須です。
** `expressionNames` **
式の属性名のプレースホルダーを示します。キー - 値のペアの形式になります。キーは *expression* で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、*expression* で使用される式の属性名のプレースホルダーのみを入力します。
** `expressionValues` **
式の属性値のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「[型システム (リクエストマッピング)](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)」を参照してください。この指定は必須です。このフィールドはオプションであり、expression で使用される式の属性値のプレースホルダーのみを入力します。
残りのフィールドは、 AWS AppSync DynamoDB リゾルバーに条件チェックの失敗を処理する方法を指示します。
** `equalsIgnore` **
`PutItem` オペレーションの使用時に条件チェックが失敗すると、 AWS AppSync DynamoDB リゾルバーは、DynamoDB の現在の項目と、書き込みを試みた項目を比較します。これらが同じ場合、処理は成功として扱われます。`equalsIgnore` フィールドを使用して、 AWS AppSync がその比較を実行するときに無視する属性のリストを指定できます。たとえば、唯一の違いが `version` 属性である場合、オペレーションは成功として扱われます。このフィールドはオプションです。
** `consistentRead` **
条件チェックが失敗すると、 AWS AppSync は強力な整合性のある読み込みを使用して DynamoDB から項目の現在の値を取得します。このフィールドを使用して、 AWS AppSync DynamoDB リゾルバーに結果整合性のある読み込みを使用するように指示できます。このフィールドはオプションであり、デフォルトは `true` です。
** `conditionalCheckFailedHandler` **
このセクションでは、 AWS AppSync DynamoDB リゾルバーが DynamoDB の現在の値を予想される結果と比較した後に、条件チェックの失敗を処理する方法を指定できます。このセクションはオプションです。省略した場合、デフォルトの処理は `Reject` です。
** `strategy` **
AWS AppSync DynamoDB リゾルバーが DynamoDB の現在の値を期待される結果と比較した後に実行する戦略。このフィールドは必須であり、以下を値を設定できます。
** `Reject` **
ミューテーションは失敗し、GraphQL レスポンスにエラーが追加されます。
** `Custom` **
AWS AppSync DynamoDB リゾルバーは、カスタム Lambda 関数を呼び出して、条件チェックの失敗を処理する方法を決定します。`strategy` が `Custom` に設定されている場合、`lambdaArn` フィールドには、呼び出す Lambda 関数の ARN が含まれている必要があります。
** `lambdaArn` **
AWS AppSync DynamoDB リゾルバーが条件チェックの失敗を処理する方法を決定する、呼び出す Lambda 関数の ARN。このフィールドは、`strategy` が `Custom` に設定されている場合のみ指定する必要があります。この機能の使用方法の詳細については、「[条件チェックでのエラーを処理する](#aws-appsync-resolver-mapping-template-reference-dynamodb-condition-handling)」を参照してください。
## 条件チェックでのエラーを処理する
デフォルトでは、条件チェックが失敗すると、 AWS AppSync DynamoDB リゾルバーはミューテーションのエラーと DynamoDB 内のオブジェクトの現在の値を返します。ただし、 AWS AppSync DynamoDB リゾルバーには、開発者が一般的なエッジケースを処理するのに役立ついくつかの追加機能があります。
+ AWS AppSync DynamoDB リゾルバーは、DynamoDB の現在の値が目的の結果と一致すると判断できる場合、オペレーションが成功したかのように処理します。
+ エラーを返す代わりに、カスタム Lambda 関数を呼び出して AWS AppSync DynamoDB リゾルバーが障害を処理する方法を決定するようにリゾルバーを設定できます。
このプロセスのフローチャートは次のとおりです。
![\[Flowchart showing process for transforming requests with mutation attempts and value checks.\]](http://docs.aws.amazon.com/ja_jp/appsync/latest/devguide/images/DynamoDB-condition-check-failure-handling.png)
### 必要な結果をチェックする
条件チェックが失敗すると、 AWS AppSync DynamoDB リゾルバーは `GetItem` DynamoDB リクエストを実行して DynamoDB から項目の現在の値を取得します。デフォルトでは、強力な整合性のある読み込みを使用しますが、`condition` ブロックの `consistentRead` フィールドを使用してこれを設定し、この値を期待した結果と比較することができます。
+ `PutItem` オペレーションでは、 AWS AppSync DynamoDB リゾルバーは、現在の値を書き込みを試みた値と比較します。ただし、 にリストされている属性は比較`equalsIgnore`から除外されます。項目が同じ場合は、処理は成功として扱われ、DynamoDB から取得された項目が返されます。それ以外の場合は、設定された処理に従います。
たとえば、`PutItem` リクエストマッピングドキュメントが以下のようになっているとします。
```
{
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "1" }
},
"attributeValues" : {
"name" : { "S" : "Steve" },
"version" : { "N" : 2 }
},
"condition" : {
"expression" : "version = :expectedVersion",
"expressionValues" : {
":expectedVersion" : { "N" : 1 }
},
"equalsIgnore": [ "version" ]
}
}
```
現在、DynamoDB にある項目は以下のようになりました。
```
{
"id" : { "S" : "1" },
"name" : { "S" : "Steve" },
"version" : { "N" : 8 }
}
```
AWS AppSync DynamoDB リゾルバーは、書き込もうとした項目を現在の値と比較します。唯一の違いは `version`フィールドでしたが、 `version`フィールドを無視するように設定されているため、オペレーションは成功として扱われ、DynamoDB から取得した項目が返されます。
+ `DeleteItem` オペレーションでは、 AWS AppSync DynamoDB リゾルバーは項目が DynamoDB から返されたことを確認します。項目が返されなかった場合、処理は成功として扱われます。それ以外の場合は、設定された処理に従います。
+ `UpdateItem` オペレーションの場合、 AWS AppSync DynamoDB リゾルバーには、現在 DynamoDB にある項目が期待される結果と一致するかどうかを判断するのに十分な情報がないため、設定された戦略に従います。
DynamoDB のオブジェクトの現在の状態が予想される結果と異なる場合、 AWS AppSync DynamoDB リゾルバーは設定された戦略に従ってミューテーションを拒否するか、Lambda 関数を呼び出して次に何をするかを決定します。
### 「reject」の戦略に従う
`Reject` 戦略に従うと、 AWS AppSync DynamoDB リゾルバーはミューテーションのエラーを返します。
たとえば、次のミューテーションリクエストが指定されたとします。
```
mutation {
updatePerson(id: 1, name: "Steve", expectedVersion: 1) {
Name
theVersion
}
}
```
DynamoDB から返された項目が以下のようになっているとします。
```
{
"id" : { "S" : "1" },
"name" : { "S" : "Steve" },
"version" : { "N" : 8 }
}
```
また、レスポンスマッピングテンプレートは以下のようになっているとします。
```
{
"id" : $util.toJson($context.result.id),
"Name" : $util.toJson($context.result.name),
"theVersion" : $util.toJson($context.result.version)
}
```
GraphQL レスポンスは以下のようになります。
```
{
"data": null,
"errors": [
{
"message": "The conditional request failed (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: ConditionalCheckFailedException; Request ID: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ)"
"errorType": "DynamoDB:ConditionalCheckFailedException",
...
}
]
}
```
また、返されたオブジェクトのフィールドすべてが他のリゾルバーによって入力され、そのミューテーションが成功した場合、オブジェクトが `error` セクションに返されたときに、それらのフィールドは解決されません。
### 「custom」戦略に従う
`Custom` 戦略に従うと、 AWS AppSync DynamoDB リゾルバーは Lambda 関数を呼び出して、次に何をするかを決定します。Lambda 関数は以下のオプションのいずれかを選択します。
+ ミューテーション を `reject` する これにより、 AWS AppSync DynamoDB リゾルバーは、設定された戦略が であるかのように動作し`Reject`、前のセクションで説明したように、ミューテーションのエラーと DynamoDB 内のオブジェクトの現在の値を返します。
+ ミューテーション を `discard` する これにより、 AWS AppSync DynamoDB リゾルバーは条件チェックの失敗を黙って無視し、DynamoDB に値を返します。
+ ミューテーション を `retry` する これにより、 AWS AppSync DynamoDB リゾルバーは新しいリクエストマッピングドキュメントでミューテーションを再試行するように指示されます。
**Lambda 呼び出しリクエスト**
AWS AppSync DynamoDB リゾルバーは、 で指定された Lambda 関数を呼び出します`lambdaArn`。また、データソースに設定されたものと同じ `service-role-arn` を使用します。呼び出しのペイロードは以下の構造を持ちます。
```
{
"arguments": { ... },
"requestMapping": {... },
"currentValue": { ... },
"resolver": { ... },
"identity": { ... }
}
```
各フィールドの定義は以下のようになります。
** `arguments` **
GraphQL ミューテーションの引数です。これは、`$context.arguments` のリクエストマッピングドキュメントで使用できる引数と同じです。
** `requestMapping` **
この処理のリクエストマッピングドキュメントです。
** `currentValue` **
DynamoDB のオブジェクトの現在値。
** `resolver` **
AWS AppSync リゾルバーに関する情報。
** `identity` **
呼び出し元に関する情報。これは、`$context.identity` のリクエストマッピングドキュメントで使用できる識別情報と同じです。
完全なペイロードの例を次に示します。
```
{
"arguments": {
"id": "1",
"name": "Steve",
"expectedVersion": 1
},
"requestMapping": {
"version" : "2017-02-28",
"operation" : "PutItem",
"key" : {
"id" : { "S" : "1" }
},
"attributeValues" : {
"name" : { "S" : "Steve" },
"version" : { "N" : 2 }
},
"condition" : {
"expression" : "version = :expectedVersion",
"expressionValues" : {
":expectedVersion" : { "N" : 1 }
},
"equalsIgnore": [ "version" ]
}
},
"currentValue": {
"id" : { "S" : "1" },
"name" : { "S" : "Steve" },
"version" : { "N" : 8 }
},
"resolver": {
"tableName": "People",
"awsRegion": "us-west-2",
"parentType": "Mutation",
"field": "updatePerson",
"outputType": "Person"
},
"identity": {
"accountId": "123456789012",
"sourceIp": "x.x.x.x",
"user": "AIDAAAAAAAAAAAAAAAAAA",
"userArn": "arn:aws:iam::123456789012:user/appsync"
}
}
```
**Lambda 呼び出しレスポンス**
Lambda 関数は、呼び出しペイロードを確認し、任意のビジネスロジックを適用して、 AWS の AppSync DynamoDB リゾルバーがエラーを処理する方法を決定することができます。条件チェックで検出されたエラーを処理するために、以下の 3 つのオプションが指定できます。
+ ミューテーション を `reject` する このオプションのレスポンスペイロードは次の構造を持ちます。
```
{
"action": "reject"
}
```
これにより、 AWS AppSync DynamoDB リゾルバーは設定された戦略が であるかのように動作し`Reject`、上記のセクションで説明したように、ミューテーションのエラーと DynamoDB 内のオブジェクトの現在の値を返します。
+ ミューテーション を `discard` する このオプションのレスポンスペイロードは次の構造を持ちます。
```
{
"action": "discard"
}
```
これにより、 AWS AppSync DynamoDB リゾルバーは条件チェックの失敗を黙って無視し、DynamoDB に値を返します。
+ ミューテーション を `retry` する このオプションのレスポンスペイロードは次の構造を持ちます。
```
{
"action": "retry",
"retryMapping": { ... }
}
```
これにより、 AWS AppSync DynamoDB リゾルバーは新しいリクエストマッピングドキュメントでミューテーションを再試行するように指示されます。`retryMapping` セクションの構造は DynamoDB の処理によって異なり、その処理の完全なリクエストマッピングドキュメントのサブセットとなります。
`PutItem` の場合、`retryMapping` セクションは次の構造を持ちます。`attributeValues` フィールドについては、「[PutItem](aws-appsync-resolver-mapping-template-reference-dynamodb-putitem.md)」を参照してください。
```
{
"attributeValues": { ... },
"condition": {
"equalsIgnore" = [ ... ],
"consistentRead" = true
}
}
```
`UpdateItem` の場合、`retryMapping` セクションは次の構造を持ちます。`update` セクションについては、「[UpdateItem](aws-appsync-resolver-mapping-template-reference-dynamodb-updateitem.md)」を参照してください。
```
{
"update" : {
"expression" : "someExpression"
"expressionNames" : {
"#foo" : "foo"
},
"expressionValues" : {
":bar" : ... typed value
}
},
"condition": {
"consistentRead" = true
}
}
```
`DeleteItem` の場合、`retryMapping` セクションは次の構造を持ちます。
```
{
"condition": {
"consistentRead" = true
}
}
```
使用する別の処理やキーを指定する方法はありません。 AWS AppSync DynamoDB リゾルバーは、同じオブジェクトに対して同じオペレーションの再試行のみを許可します。また、`condition` セクションでは `conditionalCheckFailedHandler` は指定できません。再試行が失敗した場合、 AWS AppSync DynamoDB リゾルバーは `Reject`戦略に従います。
以下は、失敗した `PutItem` リクエストを処理する Lambda 関数の例です。ビジネスロジックは呼び出し元を調べます。呼び出し元が `jeffTheAdmin` の場合は、リクエストを再試行して、現在 DynamoDB にある項目の `version` と `expectedVersion` を更新します。それ以外の場合は、ミューテーションを拒否します。
```
exports.handler = (event, context, callback) => {
console.log("Event: "+ JSON.stringify(event));
// Business logic goes here.
var response;
if ( event.identity.user == "jeffTheAdmin" ) {
response = {
"action" : "retry",
"retryMapping" : {
"attributeValues" : event.requestMapping.attributeValues,
"condition" : {
"expression" : event.requestMapping.condition.expression,
"expressionValues" : event.requestMapping.condition.expressionValues
}
}
}
response.retryMapping.attributeValues.version = { "N" : event.currentValue.version.N + 1 }
response.retryMapping.condition.expressionValues[':expectedVersion'] = event.currentValue.version
} else {
response = { "action" : "reject" }
}
console.log("Response: "+ JSON.stringify(response))
callback(null, response)
};
```
# トランザクション条件式
トランザクション条件式は、`TransactWriteItems` の 4 つのタイプのオペレーション (`PutItem`、`DeleteItem`、`UpdateItem`、`ConditionCheck`) すべてに対応するリクエストマッピングテンプレートで使用できます。
`PutItem`、`DeleteItem`、および `UpdateItem` の場合、トランザクション条件式はオプションです。`ConditionCheck` の場合、トランザクション条件式が必要です。
## 例 1
次のトランザクション `DeleteItem` マッピングドキュメントには条件式がありません。その結果、DynamoDB の項目が削除されます。
```
{
"version": "2018-05-29",
"operation": "TransactWriteItems",
"transactItems": [
{
"table": "posts",
"operation": "DeleteItem",
"key": {
"id": { "S" : "1" }
}
}
]
}
```
## 例 2
次のトランザクション `DeleteItem` マッピングドキュメントには、その投稿の作成者が特定の名前に等しい場合にのみオペレーションが成功できるトランザクション条件式があります。
```
{
"version": "2018-05-29",
"operation": "TransactWriteItems",
"transactItems": [
{
"table": "posts",
"operation": "DeleteItem",
"key": {
"id": { "S" : "1" }
}
"condition": {
"expression": "author = :author",
"expressionValues": {
":author": { "S" : "Chunyan" }
}
}
}
]
}
```
条件チェックが失敗すると、`TransactionCanceledException` が発生し、エラーの詳細が `$ctx.result.cancellationReasons` で返されます。デフォルトでは、その条件チェックの失敗となった DynamoDB の古い項目は `$ctx.result.cancellationReasons` で返されます。
## 条件を指定する
`PutItem`、`UpdateItem`、および `DeleteItem` の各リクエストマッピングドキュメントはすべて、オプションで `condition` セクションが指定できます。省略した場合、条件チェックは実行されません。指定した場合、処理が成功するには、条件が true となる必要があります。`ConditionCheck` では、`condition` セクションを指定する必要があります。トランザクション全体が成功するためには、条件が true でなければなりません。
`condition` セクションは以下の構造を持ちます。
```
"condition": {
"expression": "someExpression",
"expressionNames": {
"#foo": "foo"
},
"expressionValues": {
":bar": ... typed value
},
"returnValuesOnConditionCheckFailure": false
}
```
以下のフィールドに条件を指定します。
** `expression` **
更新式そのものを指定します。条件式の記述方法の詳細については、[DynamoDB ConditionExpressions のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)を参照してください。このフィールドの指定は必須です。
** `expressionNames` **
式の属性名のプレースホルダーを示します。キー - 値のペアの形式になります。キーは *expression* で使用される名前のプレースホルダーに対応し、値は DynamoDB の項目の属性名と一致する文字列でなければなりません。このフィールドはオプションであり、*expression* で使用される式の属性名のプレースホルダーのみを入力します。
** `expressionValues` **
式の属性値のプレースホルダーを示します。キー - 値のペアの形式になります。キーは expression で使用される値のプレースホルダーに対応し、値は型付き値でなければなりません。「型付き値」を指定する方法の詳細については、「型システム (リクエストマッピング)」を参照してください。この指定は必須です。このフィールドはオプションであり、expression で使用される式の属性値のプレースホルダーのみを入力します。
** `returnValuesOnConditionCheckFailure` **
条件チェックが失敗した場合に、DynamoDB の項目を取得し直すかどうかを指定します。取得された項目は `$ctx.result.cancellationReasons[$index].item` にあります。ここで `$index` は、条件チェックに失敗したリクエスト項目のインデックスです。この値のデフォルト値は true です。
# 計画
`GetItem`、`Scan`、`Query`、`BatchGetItem`、および `TransactGetItems` オペレーションを使用して DynamoDB のオブジェクトを読み取る場合、必要な属性を識別するプロジェクションをオプションで指定できます。プロジェクションは次のような構造で、フィルタ-に似ています。
```
"projection" : {
"expression" : "projection expression"
"expressionNames" : {
"#name" : "name",
}
}
```
各フィールドの定義は以下のようになります。
**`expression`**
プロジェクション式、これは文字列です。1 つの属性を取得するには、名前を指定します。複数の属性の場合、名前をカンマで区切る必要があります。プロジェクション式の記述の詳細については、「[DynamoDB プロジェクション式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html)」のドキュメントを参照してください。このフィールドは必須です。
**`expressionNames`**
式の属性*名*のプレースホルダーを示します。キー - 値のペアの形式になります。キーは、`expression` で使用される名前のプレースホルダーに対応します。値は、DynamoDB の項目の属性名に対応する文字列である必要があります。このフィールドはオプションであり、`expression` で使用される式の属性名のプレースホルダーのみを入力します。`expressionNames` の詳細については、「[Amazon DynamoDB のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html)」を参照してください。
## 例 1
次の例は、属性 `author` と`id` が DynamoDB から返される VTL マッピングテンプレートのプロジェクション セクションです。
```
"projection" : {
"expression" : "#author, id",
"expressionNames" : {
"#author" : "author"
}
}
```
**ヒント**
GraphQL リクエストセレクションセットには [\$1context.info.SelectionSetList](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference.html#aws-appsync-resolver-context-reference-info) を使用してアクセスできます。このフィールドを使うと、必要に応じてプロジェクション式を動的にフレーミングできます。
**注記**
`Query` と `Scan` のオペレーションでプロジェクション式を使用する場合、`select` の値は `SPECIFIC_ATTRIBUTES` でなければなりません。詳細については、「[DynamoDB のドキュメント](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html#DDB-Query-request-Select)」を参照してください。