SDK を使用してトランザクション バッチを作成する

完了

トランザクション バッチ要求を使用すると、同じパーティション キー内で複数の操作を同時に実行できます。 すべての操作は指定された順序で実行され、すべての操作が成功した場合にのみトランザクションがコミットされます。 何らかの操作が失敗した場合、トランザクション全体が元に戻されます。 コンテナー、 摩耗したサドル 、 さびついたハンドルバーに 2 つの使用済み自転車アクセサリが作成される架空のシナリオを考えてみましょう。 わかりやすくするために、短い一意識別子とカテゴリ識別子があります。

Product saddle = new("0120", "Worn Saddle", "accessories-used");
Product handlebar = new("012A", "Rusty Handlebar", "accessories-used");

この例では、パブリック レコード定義の使用も選択しました。

public record Product(string id, string name, string categoryId);

Microsoft.Azure.Cosmos.Container クラスには、Fluent 構文をサポートする TransactionalBatch 型の新しいインスタンスを作成する CreateTransactionalBatch メンバー メソッドがあります。 このバッチと fluent CreateItem メソッドを使用して、同じパーティション キー値内に 2 つの項目を挿入する 2 段階認証トランザクションを作成できます。

PartitionKey partitionKey = new ("accessories-used");
TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey)
    .CreateItem<Product>(saddle)
    .CreateItem<Product>(handlebar);

バッチを実行するには、 ExecuteAsync メソッドを非同期的に呼び出します。 using ステートメントを追加して、オブジェクトが現在のアプリケーション スコープの後に正しく破棄されるようにします。

using TransactionalBatchResponse response = await batch.ExecuteAsync();

トランザクション バッチは、同じ論理パーティション キー 操作をサポートします。 論理パーティション キーが異なる操作は失敗します。 次の例では、異なる論理パーティション キーがあるため、トランザクション バッチが不適切な要求で失敗します。

Product saddle = new("0120", "Worn Saddle", "accessories-used");
Product handlebar = new("012C", "Pristine Handlebar", "accessories-new");
PartitionKey partitionKey = new ("accessories-used");
TransactionalBatch batch = container.CreateTransactionalBatch(partitionKey)
    .CreateItem<Product>(saddle)
    .CreateItem<Product>(handlebar);

トランザクション バッチでは、次のような fluent 構文を使用したさまざまな操作もサポートされています。ただし、これらに限定されません。

方式	説明
CreateItemStream()	既存のストリームから項目を作成する
DeleteItem()	項目を削除する
ReadItem()	項目を読み取る
ReplaceItem() および ReplaceItemStream()	既存のアイテムまたはストリームを更新する
UpsertItem() および UpsertItemStream()	アイテムの一意識別子に基づいて既存のアイテムまたはストリームを作成または更新する

saddle = ("create", (
    {"id": "0120", "name": "Worn Saddle", "categoryId": "accessories-used"},
))
handlebar = ("create", (
    {"id": "012A", "name": "Rusty Handlebar", "categoryId": "accessories-used"},
))

トランザクション バッチ操作は、単一の操作 API に似ていますが、kwargs ディクショナリは省略可能な (operation_type_string、args_tuple、batch_operation_kwargs_dictionary) を含むタプルです。

operation_type_string は、"create"、"upsert"、"replace"、"read"、"patch"、"delete" などの操作の種類を表す文字列です。

バッチを実行するには、コンテナー オブジェクトの execute_item_batch メソッドを使用します。 最初の引数は、バッチで実行される操作の一覧です。 この例では、同じパーティション キー値内に項目を作成する 2 つの操作があります。

# Partition key
partition_key = "accessories-used"

batch = [
    saddle,
    handlebar
]

try:
    # Execute the batch
    batch_response = container.execute_item_batch(batch, partition_key=partition_key)

    # Check the response and print results
    for result in batch_response:
        print(result.get("resourceBody"))
except exceptions.CosmosHttpResponseError as e:
    print(f"Failed to execute batch: {e.message}")

トランザクション バッチは、同じ論理パーティション キー 操作をサポートします。 論理パーティション キーが異なる操作は失敗します。 次の例では、異なる論理パーティション キーがあるため、トランザクション バッチが不適切な要求で失敗します。

partition_key = "accessories-used"

batch = [
    ("create", ({"id": "0120", "name": "Worn Saddle", "categoryId": "accessories-used"},)),
    ("create", ({"id": "012C", "name": "Pristine Handlebar", "categoryId": "accessories-new"},))
]
batch_response = container.execute_item_batch(batch, partition_key=partition_key)

const saddle = { id: "0120", name: "Worn Saddle", categoryId: "accessories-used" };
const handlebar = { id: "012A", name: "Rusty Handlebar", categoryId: "accessories-used" };

両方の項目のパーティション キーの値は同じです。 アクセサリが使用されます。

const partitionKey = "accessories-used";

JavaScript SDK には、BulkOperationTypeなどの操作を指定する Create 列挙型が用意されています。 バッチで実行する操作を表すオブジェクトの配列を作成します。

const { BulkOperationType } = require("@azure/cosmos");

const batch = [
    { operationType: BulkOperationType.Create, resourceBody: saddle },
    { operationType: BulkOperationType.Create, resourceBody: handlebar },
];

container.items.batch メソッドを使用してバッチを実行します。

const response = await container.items.batch(batch, partitionKey);

すべての操作が成功した場合、応答にはコミットされたトランザクションの詳細が含まれます。 いずれかの操作が失敗した場合は、トランザクション全体がロールバックされます。

トランザクション バッチは、同じ論理パーティション キー 操作をサポートします。 論理パーティション キーが異なる操作は失敗します。 次の例では、異なる論理パーティション キーがあるため、トランザクション バッチが不適切な要求で失敗します。

const saddle = { id: "0120", name: "Worn Saddle", categoryId: "accessories-used" };
const handlebar = { id: "012C", name: "Pristine Handlebar", categoryId: "accessories-new" };

const partitionKey = "accessories-used";

const batch = [
    { operationType: BulkOperationType.Create, resourceBody: saddle },
    { operationType: BulkOperationType.Create, resourceBody: handlebar },
];
const response = await container.items.batch(batch, partitionKey);