翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# トランザクションオペレーションを実行する
DynamoDB 拡張クライアント API には、`transactGetItems()` および `transactWriteItems()` メソッドが用意されています。SDK for Java のトランザクションによって DynamoDB テーブルに不可分性、一貫性、分離性、耐久性 (ACID) が実現されるため、アプリケーション内でのデータの精度を維持することができます。
## `transactGetItems()` の例
`[transactGetItems()](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html#transactGetItems(java.util.function.Consumer))` メソッドは、項目に対する個別のリクエストを最大 100 件受け付けます。すべてのアイテムは 1 つの不可分トランザクションで読み取られます。*Amazon DynamoDB デベロッパーガイド*には、[`transactGetItems()` メソッドが失敗する原因となる条件](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html#transaction-apis-txgetitems)や、`[transactGetItem()](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html#transaction-isolation)` の呼び出し時に使用される分離レベルに関する情報が記載されています。
次の例の 1 行目のコメントのあと、コードは `[builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/TransactGetItemsEnhancedRequest.Builder.html)` パラメータを使用して `transactGetItems()` メソッドを呼び出します。ビルダー `[addGetItem()](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/TransactGetItemsEnhancedRequest.Builder.html#addGetItem(software.amazon.awssdk.enhanced.dynamodb.MappedTableResource,T))` は、SDK が最終リクエストの生成に使用するキー値を含むデータオブジェクトを使用して 3 回呼び出されます。
このリクエストは、コメント行 2 の後に `[Document](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/Document.html)` オブジェクトのリストを返します。返されるドキュメントのリストには、アイテムデータの null 以外の [ドキュメント](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/Document.html) インスタンスがリクエストと同じ順序で含まれています。`[Document.getItem(MappedTableResource mappedTableResource)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/Document.html#getItem(software.amazon.awssdk.enhanced.dynamodb.MappedTableResource))` メソッドは、アイテムデータが返された場合は型指定されていない `Document` オブジェクトを型付きの Java オブジェクトに変換し、それ以外の場合は null を返します。
```
public static void transactGetItemsExample(DynamoDbEnhancedClient enhancedClient,
DynamoDbTable catalogTable,
DynamoDbTable movieActorTable) {
// 1. Request three items from two tables using a builder.
final List documents = enhancedClient.transactGetItems(b -> b
.addGetItem(catalogTable, Key.builder().partitionValue(2).sortValue("Title 55").build())
.addGetItem(movieActorTable, Key.builder().partitionValue("Sophie's Choice").sortValue("Meryl Streep").build())
.addGetItem(movieActorTable, Key.builder().partitionValue("Blue Jasmine").sortValue("Cate Blanchett").build())
.build());
// 2. A list of Document objects is returned in the same order as requested.
ProductCatalog title55 = documents.get(0).getItem(catalogTable);
if (title55 != null) {
logger.info(title55.toString());
}
MovieActor sophiesChoice = documents.get(1).getItem(movieActorTable);
if (sophiesChoice != null) {
logger.info(sophiesChoice.toString());
}
// 3. The getItem() method returns null if the Document object contains no item from DynamoDB.
MovieActor blueJasmine = documents.get(2).getItem(movieActorTable);
if (blueJasmine != null) {
logger.info(blueJasmine.toString());
}
}
```
コード例が実行される前は、DynamoDB テーブルには次の項目が含まれています。
```
ProductCatalog{id=2, title='Title 55', isbn='orig_isbn', authors=[b, g], price=10}
MovieActor{movieName='Sophie's Choice', actorName='Meryl Streep', actingAward='Best Actress', actingYear=1982, actingSchoolName='Yale School of Drama'}
```
次の出力が記録されます。リクエストされたアイテムが見つからなかった場合、`Blue Jasmine` という名前の映画のリクエストの場合とは異なり、アイテムは返されません。
```
ProductCatalog{id=2, title='Title 55', isbn='orig_isbn', authors=[b, g], price=10}
MovieActor{movieName='Sophie's Choice', actorName='Meryl Streep', actingAward='Best Actress', actingYear=1982, actingSchoolName='Yale School of Drama'}
```
## `transactWriteItems()` の例
`[transactWriteItems()](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html#transactWriteItems(java.util.function.Consumer))` は、複数のテーブルにわたる 1 回のアトミックトランザクションで最大 100 件の入力、更新、削除アクションを受け付けます。*Amazon DynamoDB デベロッパーガイド*には、[基盤となる DynamoDB サービスオペレーション](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html#transaction-apis-txwriteitems)の制限と障害条件に関する詳細が記載されています。
### 基本的な の例
次の例では、2 つのテーブルに対して 4 つのオペレーションがリクエストされています。対応するモデルクラスは、前に示した [`ProductCatalog`](ddb-en-client-use.md#ddb-en-client-use-compare-cs3) および [`MovieActor`](ddb-en-client-use-multirecord.md#ddb-en-client-use-movieactor-class) です。
入力、更新、削除の 3 つの操作では、それぞれ専用のリクエストパラメータを使用して詳細を指定します。
コメント行 1 の後のコードは、`addPutItem()` メソッドの単純なバリエーションを示しています。このメソッドは、`[MappedTableResource](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/MappedTableResource.html)` オブジェクトと入力するデータオブジェクトインスタンスを受け入れます。2 行目のコメントの後のステートメントには、`[TransactPutItemEnhancedRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/TransactPutItemEnhancedRequest.html)` インスタンスを受け付けるバリエーションが表示されます。このバリエーションでは、条件式などのオプションをリクエストに追加できます。次の[例](#ddb-en-client-use-multiop-trans-writeitems-opcondition)では、個々のオペレーションの条件式を示しています。
更新操作はコメント行 3 の後に要求されます。`[TransactUpdateItemEnhancedRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/TransactUpdateItemEnhancedRequest.Builder.html)` には、SDK がモデルオブジェクトの `null` 値を使って何をするかを設定できる `ignoreNulls()` メソッドがあります。`ignoreNulls()` メソッドが true を返す場合、SDK は `null` であるデータオブジェクト属性のテーブルの属性値を削除しません。`ignoreNulls()` メソッドが false を返す場合、SDK は DynamoDB サービスにテーブル内の項目から属性を削除するようリクエストします。`ignoreNulls` のデフォルト値は false です。
コメント 4 行目の後のステートメントは、データオブジェクトを取得する削除リクエストのバリエーションを示しています。拡張クライアントは、最後のリクエストをディスパッチする前にキー値を抽出します。
```
public static void transactWriteItems(DynamoDbEnhancedClient enhancedClient,
DynamoDbTable catalogTable,
DynamoDbTable movieActorTable) {
enhancedClient.transactWriteItems(b -> b
// 1. Simplest variation of put item request.
.addPutItem(catalogTable, getProductCatId2())
// 2. Put item request variation that accommodates condition expressions.
.addPutItem(movieActorTable, TransactPutItemEnhancedRequest.builder(MovieActor.class)
.item(getMovieActorStreep())
.conditionExpression(Expression.builder().expression("attribute_not_exists (movie)").build())
.build())
// 3. Update request that does not remove attribute values on the table if the data object's value is null.
.addUpdateItem(catalogTable, TransactUpdateItemEnhancedRequest.builder(ProductCatalog.class)
.item(getProductCatId4ForUpdate())
.ignoreNulls(Boolean.TRUE)
.build())
// 4. Variation of delete request that accepts a data object. The key values are extracted for the request.
.addDeleteItem(movieActorTable, getMovieActorBlanchett())
);
}
```
以下のヘルパーメソッドは、`add*Item` パラメータのデータオブジェクトを提供します。
#### ヘルパーメソッド
```
public static ProductCatalog getProductCatId2() {
return ProductCatalog.builder()
.id(2)
.isbn("1-565-85698")
.authors(new HashSet<>(Arrays.asList("a", "b")))
.price(BigDecimal.valueOf(30.22))
.title("Title 55")
.build();
}
public static ProductCatalog getProductCatId4ForUpdate() {
return ProductCatalog.builder()
.id(4)
.price(BigDecimal.valueOf(40.00))
.title("Title 1")
.build();
}
public static MovieActor getMovieActorBlanchett() {
MovieActor movieActor = new MovieActor();
movieActor.setActorName("Cate Blanchett");
movieActor.setMovieName("Tar");
movieActor.setActingYear(2022);
movieActor.setActingAward("Best Actress");
movieActor.setActingSchoolName("National Institute of Dramatic Art");
return movieActor;
}
public static MovieActor getMovieActorStreep() {
MovieActor movieActor = new MovieActor();
movieActor.setActorName("Meryl Streep");
movieActor.setMovieName("Sophie's Choice");
movieActor.setActingYear(1982);
movieActor.setActingAward("Best Actress");
movieActor.setActingSchoolName("Yale School of Drama");
return movieActor;
}
```
コード例が実行される前は、DynamoDB テーブルには次の項目が含まれています。
```
1 | ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=10}
2 | MovieActor{movieName='Tar', actorName='Cate Blanchett', actingAward='Best Actress', actingYear=2022, actingSchoolName='National Institute of Dramatic Art'}
```
コードの実行が完了すると、次の項目がテーブルに表示されます。
```
3 | ProductCatalog{id=2, title='Title 55', isbn='1-565-85698', authors=[a, b], price=30.22}
4 | ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=40.0}
5 | MovieActor{movieName='Sophie's Choice', actorName='Meryl Streep', actingAward='Best Actress', actingYear=1982, actingSchoolName='Yale School of Drama'}
```
2 行目の項目は削除され、3 行目と 5 行目には追加された項目が表示されます。4 行目は 1 行目の更新を示しています。アイテム上で変更されたのは `price` の値だけです。`ignoreNulls()` が false を返した場合、4 行目は次の行のようになります。
```
ProductCatalog{id=4, title='Title 1', isbn='null', authors=null, price=40.0}
```
### コンディションチェックの例
次の例は、条件チェックの使用を示しています。コンディションチェックは、アイテムの存在を確認したり、データベース内のアイテムの特定の属性の状態をチェックしたりするために使用されます。コンディションチェックでチェックされたアイテムは、トランザクション内の別のオペレーションでは使用できません。
**注記**
同じトランザクション内の複数のオペレーションが同じ項目をターゲットとすることはできません。たとえば、同じトランザクション内で同じ項目に対してコンディションチェックと更新を実行することはできません。
この例では、トランザクションによる項目書き込みリクエストにおける各タイプの操作を 1 つずつ示しています。2 行目のコメントの後、`addConditionCheck()` メソッドは、`conditionExpression` パラメータが `false` と評価された場合にトランザクションが失敗する条件を指定します。ヘルパーメソッドブロックに表示されているメソッドから返される条件式は、ムービーの受賞年度 `Sophie's Choice` が `1982` と等しくないかどうかをチェックします。一致した場合、式は `false` と評価され、トランザクションは失敗します。
このガイドでは、別のトピックで[式](ddb-en-client-expressions.md)について詳しく説明します。
```
public static void conditionCheckFailExample(DynamoDbEnhancedClient enhancedClient,
DynamoDbTable catalogTable,
DynamoDbTable movieActorTable) {
try {
enhancedClient.transactWriteItems(b -> b
// 1. Perform one of each type of operation with the next three methods.
.addPutItem(catalogTable, TransactPutItemEnhancedRequest.builder(ProductCatalog.class)
.item(getProductCatId2()).build())
.addUpdateItem(catalogTable, TransactUpdateItemEnhancedRequest.builder(ProductCatalog.class)
.item(getProductCatId4ForUpdate())
.ignoreNulls(Boolean.TRUE).build())
.addDeleteItem(movieActorTable, TransactDeleteItemEnhancedRequest.builder()
.key(b1 -> b1
.partitionValue(getMovieActorBlanchett().getMovieName())
.sortValue(getMovieActorBlanchett().getActorName())).build())
// 2. Add a condition check on a table item that is not involved in another operation in this request.
.addConditionCheck(movieActorTable, ConditionCheck.builder()
.conditionExpression(buildConditionCheckExpression())
.key(k -> k
.partitionValue("Sophie's Choice")
.sortValue("Meryl Streep"))
// 3. Specify the request to return existing values from the item if the condition evaluates to true.
.returnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD)
.build())
.build());
// 4. Catch the exception if the transaction fails and log the information.
} catch (TransactionCanceledException ex) {
ex.cancellationReasons().stream().forEach(cancellationReason -> {
logger.info(cancellationReason.toString());
});
}
}
```
前のコード例では以下のヘルパーメソッドが使用されています。
#### ヘルパーメソッド
```
private static Expression buildConditionCheckExpression() {
Map expressionValue = Map.of(
":year", numberValue(1982));
return Expression.builder()
.expression("actingyear <> :year")
.expressionValues(expressionValue)
.build();
}
public static ProductCatalog getProductCatId2() {
return ProductCatalog.builder()
.id(2)
.isbn("1-565-85698")
.authors(new HashSet<>(Arrays.asList("a", "b")))
.price(BigDecimal.valueOf(30.22))
.title("Title 55")
.build();
}
public static ProductCatalog getProductCatId4ForUpdate() {
return ProductCatalog.builder()
.id(4)
.price(BigDecimal.valueOf(40.00))
.title("Title 1")
.build();
}
public static MovieActor getMovieActorBlanchett() {
MovieActor movieActor = new MovieActor();
movieActor.setActorName("Cate Blanchett");
movieActor.setMovieName("Blue Jasmine");
movieActor.setActingYear(2013);
movieActor.setActingAward("Best Actress");
movieActor.setActingSchoolName("National Institute of Dramatic Art");
return movieActor;
}
```
コード例が実行される前は、DynamoDB テーブルには次の項目が含まれています。
```
1 | ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=10}
2 | MovieActor{movieName='Sophie's Choice', actorName='Meryl Streep', actingAward='Best Actress', actingYear=1982, actingSchoolName='Yale School of Drama'}
3 | MovieActor{movieName='Tar', actorName='Cate Blanchett', actingAward='Best Actress', actingYear=2022, actingSchoolName='National Institute of Dramatic Art'}
```
コードの実行が完了すると、次の項目がテーブルに表示されます。
```
ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=10}
MovieActor{movieName='Sophie's Choice', actorName='Meryl Streep', actingAward='Best Actress', actingYear=1982, actingSchoolName='Yale School of Drama'}
MovieActor{movieName='Tar', actorName='Cate Blanchett', actingAward='Best Actress', actingYear=2022, actingSchoolName='National Institute of Dramatic Art'}
```
トランザクションが失敗したため、テーブル内の項目は変更されません。ムービー `Sophie's Choice` の `actingYear` 値は `1982` であり、`transactWriteItem()` メソッドが呼び出される前のテーブル内の項目の 2 行目に示されているとおりです。
トランザクションのキャンセル情報を取得するには、`transactWriteItems()` メソッド呼び出しを `try` ブロックし、[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/model/TransactionCanceledException.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/model/TransactionCanceledException.html) を `catch` します。この例の 4 行目のコメントの後、コードは各 `[CancellationReason](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/model/CancellationReason.html)` オブジェクトをログに記録します。この例の 3 行目のコメントに続くコードでは、トランザクションが失敗した原因となった項目の値を返すように指定していたため、ログには `Sophie's Choice` ムービー項目の未加工のデータベース値が表示されます。
```
CancellationReason(Code=None)
CancellationReason(Code=None)
CancellationReason(Code=None)
CancellationReason(Item={actor=AttributeValue(S=Meryl Streep), movie=AttributeValue(S=Sophie's Choice), actingaward=AttributeValue(S=Best Actress), actingyear=AttributeValue(N=1982), actingschoolname=AttributeValue(S=Yale School of Drama)}, ¬
Code=ConditionalCheckFailed, Message=The conditional request failed.)
```
### 単一オペレーション条件の例
次の例は、トランザクションリクエスト内の 1 つのオペレーションで条件を使用する方法を示しています。コメント行 1 の後の削除操作には、操作の対象項目の値をデータベースと照合する条件が含まれています。この例では、ヘルパーメソッドでコメント行 2 の後に作成した条件式は、映画の制作年が 2013 年と等しくない場合はその項目をデータベースから削除するように指定しています。
[式](ddb-en-client-expressions.md)についてはこのガイドの後半で説明します。
```
public static void singleOperationConditionFailExample(DynamoDbEnhancedClient enhancedClient,
DynamoDbTable catalogTable,
DynamoDbTable movieActorTable) {
try {
enhancedClient.transactWriteItems(b -> b
.addPutItem(catalogTable, TransactPutItemEnhancedRequest.builder(ProductCatalog.class)
.item(getProductCatId2())
.build())
.addUpdateItem(catalogTable, TransactUpdateItemEnhancedRequest.builder(ProductCatalog.class)
.item(getProductCatId4ForUpdate())
.ignoreNulls(Boolean.TRUE).build())
// 1. Delete operation that contains a condition expression
.addDeleteItem(movieActorTable, TransactDeleteItemEnhancedRequest.builder()
.key((Key.Builder k) -> {
MovieActor blanchett = getMovieActorBlanchett();
k.partitionValue(blanchett.getMovieName())
.sortValue(blanchett.getActorName());
})
.conditionExpression(buildDeleteItemExpression())
.returnValuesOnConditionCheckFailure(ReturnValuesOnConditionCheckFailure.ALL_OLD)
.build())
.build());
} catch (TransactionCanceledException ex) {
ex.cancellationReasons().forEach(cancellationReason -> logger.info(cancellationReason.toString()));
}
}
// 2. Provide condition expression to check if 'actingyear' is not equal to 2013.
private static Expression buildDeleteItemExpression() {
Map expressionValue = Map.of(
":year", numberValue(2013));
return Expression.builder()
.expression("actingyear <> :year")
.expressionValues(expressionValue)
.build();
}
```
前のコード例では以下のヘルパーメソッドが使用されています。
#### ヘルパーメソッド
```
public static ProductCatalog getProductCatId2() {
return ProductCatalog.builder()
.id(2)
.isbn("1-565-85698")
.authors(new HashSet<>(Arrays.asList("a", "b")))
.price(BigDecimal.valueOf(30.22))
.title("Title 55")
.build();
}
public static ProductCatalog getProductCatId4ForUpdate() {
return ProductCatalog.builder()
.id(4)
.price(BigDecimal.valueOf(40.00))
.title("Title 1")
.build();
}
public static MovieActor getMovieActorBlanchett() {
MovieActor movieActor = new MovieActor();
movieActor.setActorName("Cate Blanchett");
movieActor.setMovieName("Blue Jasmine");
movieActor.setActingYear(2013);
movieActor.setActingAward("Best Actress");
movieActor.setActingSchoolName("National Institute of Dramatic Art");
return movieActor;
}
```
コード例が実行される前は、DynamoDB テーブルには次の項目が含まれています。
```
1 | ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=10}
2 | MovieActor{movieName='Blue Jasmine', actorName='Cate Blanchett', actingAward='Best Actress', actingYear=2013, actingSchoolName='National Institute of Dramatic Art'}
```
コードの実行が完了すると、次の項目がテーブルに表示されます。
```
ProductCatalog{id=4, title='Title 1', isbn='orig_isbn', authors=[b, g], price=10}
2023-03-15 11:29:07 [main] INFO org.example.tests.TransactDemoTest:168 - MovieActor{movieName='Blue Jasmine', actorName='Cate Blanchett', actingAward='Best Actress', actingYear=2013, actingSchoolName='National Institute of Dramatic Art'}
```
トランザクションが失敗したため、テーブル内の項目は変更されません。ムービー `Blue Jasmine` の `actingYear` 値は、コード例が実行される前の項目リストの 2 行目に表示されている `2013` です。
次の行がコンソールに記録されます。
```
CancellationReason(Code=None)
CancellationReason(Code=None)
CancellationReason(Item={actor=AttributeValue(S=Cate Blanchett), movie=AttributeValue(S=Blue Jasmine), actingaward=AttributeValue(S=Best Actress), actingyear=AttributeValue(N=2013), actingschoolname=AttributeValue(S=National Institute of Dramatic Art)},
Code=ConditionalCheckFailed, Message=The conditional request failed)
```