Amazon DynamoDB
開発者ガイド (API バージョン 2012-08-10)

.NET ドキュメントモデル

AWS SDK for .NET では、低レベル Amazon DynamoDB オペレーションの一部をまとめるドキュメントモデルクラスを使用して、コーディングをさらに簡略化することができます。ドキュメントモデルのプライマリクラスは TableDocument です。Table クラスでは、PutItemGetItemDeleteItem などのデータオペレーション方法を使用できます。Query および Scan メソッドも使用できます。Document クラスは、テーブル内の単一の項目を表します。

前述のドキュメントモデルクラスは、Amazon.DynamoDBv2.DocumentModel 名前空間で使用できます。

ドキュメントモデルでサポートされていないオペレーション

ドキュメントモデルクラスは、テーブルの作成、更新、削除に使用することはできません。ただし、ドキュメントモデルは、ほとんどの一般的なデータオペレーションをサポートしています。

項目の取得 – Table.GetItem

GetItem オペレーションでは、項目を Document インスタンスとして取り出します。次の C# サンプルコードに示すように、取得する項目のプライマリキーを入力する必要があります。

Table table = Table.LoadTable(client, "ProductCatalog"); Document document = table.GetItem(101); // Primary key 101.

GetItem オペレーションを実行すると、項目のすべての属性が返され、デフォルトで結果整合性のある読み込み (「読み込み整合性」を参照) が実行されます。

オプションパラメータの指定

GetItem パラメータを追加することで、GetItemOperationConfig オペレーションに追加オプションを設定できます。オプションパラメータの詳細なリストについては、GetItem を参照してください。次の C# のサンプルコードでは、ProductCatalog から項目を取得します。次のオプションパラメータを使用して GetItemOperationConfig が指定されています。

  • 指定された属性だけを取り出す AttributesToGet パラメータ。

  • 指定されたすべての属性に対する最新の値をリクエストする ConsistentRead パラメータデータの整合性の詳細については、「読み込み整合性」を参照してください。

Table table = Table.LoadTable(client, "ProductCatalog"); GetItemOperationConfig config = new GetItemOperationConfig() { AttributesToGet = new List<string>() { "Id", "Title", "Authors", "InStock", "QuantityOnHand" }, ConsistentRead = true }; Document doc = table.GetItem(101, config);

ドキュメントモデル API を使用して項目を取得すると、以下の例に示されるように、返る Document オブジェクト内の個々の要素にアクセスできます。

int id = doc["Id"].AsInt(); string title = doc["Title"].AsString(); List<string> authors = doc["Authors"].AsListOfString(); bool inStock = doc["InStock"].AsBoolean(); DynamoDBNull quantityOnHand = doc["QuantityOnHand"].AsDynamoDBNull();

List 型または Map 型の属性の場合に、属性をドキュメントモデル API にマッピングする方法を以下に示します。

  • ListAsDynamoDBList メソッドを使用します。

  • MapAsDocument メソッドを使用します。

次のサンプルコードは、List (RelatedItems) および Map (Pictures) を Document オブジェクトから取得する方法を示します。

DynamoDBList relatedItems = doc["RelatedItems"].AsDynamoDBList(); Document pictures = doc["Pictures"].AsDocument();

項目の削除 – Table.DeleteItem

DeleteItem オペレーションは、テーブルから項目を削除します。項目のプライマリキーをパラメータとして渡すことができます。また、以下の C# のサンプルコードに示されているように、すでに項目を読み取っていて対応する Document オブジェクトを取得している場合には、それをパラメータとして DeleteItem メソッドに渡すこともできます。

Table table = Table.LoadTable(client, "ProductCatalog"); // Retrieve a book (a Document instance) Document document = table.GetItem(111); // 1) Delete using the Document instance. table.DeleteItem(document); // 2) Delete using the primary key. int partitionKey = 222; table.DeleteItem(partitionKey)

オプションパラメータの指定

Delete パラメータを追加することで、DeleteItemOperationConfig オペレーションに追加オプションを設定できます。オプションパラメータの詳細なリストについては、DeleteTable を参照してください。次の C# サンプルコードでは、以下の 2 つのオプションパラメータを指定します。

  • ISBN 属性に特定の値が含まれている書籍項目が削除されるようにする ConditionalExpression パラメータ。

  • 削除された項目が ReturnValues メソッドによって返されることをリクエストする Delete パラメータ。

Table table = Table.LoadTable(client, "ProductCatalog"); int partitionKey = 111; Expression expr = new Expression(); expr.ExpressionStatement = "ISBN = :val"; expr.ExpressionAttributeValues[":val"] = "11-11-11-11"; // Specify optional parameters for Delete operation. DeleteItemOperationConfig config = new DeleteItemOperationConfig { ConditionalExpression = expr, ReturnValues = ReturnValues.AllOldAttributes // This is the only supported value when using the document model. }; // Delete the book. Document d = table.DeleteItem(partitionKey, config);

項目の更新 – Table.UpdateItem

UpdateItem オペレーションは、既存の項目があればそれを更新します。プライマリキーが指定されている項目がない場合は、UpdateItem オペレーションによって新しい項目が追加されます。

UpdateItem オペレーションを使用して、既存の属性値を更新するか、既存のコレクションに新しい属性を追加するか、既存のコレクションから属性を削除することができます。実行する更新を記述する Document インスタンスを作成して、これらの更新を提供します。

UpdateItem アクションは、以下のガイドラインに従います。

  • 項目が存在しない場合、UpdateItem は入力で指定されたプライマリキーを使用して、新しい項目を追加します。

  • 項目が存在する場合、UpdateItem は次のように更新を適用します。

    • 既存の属性値を更新に含まれる値に置き換えます。

    • 入力で指定された属性が存在しない場合は、新しい属性を項目に追加します。

    • 入力された属性値が null である場合は、属性を削除します。

注記

この中間レベルの UpdateItem オペレーションでは、基本となる DynamoDB オペレーションでサポートされている Add アクション (UpdateItem を参照) はサポートされていません。

注記

PutItem オペレーション(項目の入力 – Table.PutItem メソッド)により、更新を実行できます。PutItem を呼び出して項目をアップロードするときにプライマリキーが存在する場合は、PutItem オペレーションによって項目全体が置き換わります。既存の項目内に属性があり、入力された Document でそれらの属性が指定されていない場合、それらの属性は、PutItem オペレーションによって削除されます。ただし、UpdateItem が更新するのは指定された入力属性だけです。その項目では、その他の既存の属性は変更されません。

AWS SDK for .NET ドキュメントモデルを使用して項目を更新するステップは次のとおりです。

  1. 更新オペレーションを実行するテーブルの名前を入力して、Table.LoadTable メソッドを実行します。

  2. 実行するすべての更新を指定して、Document インスタンスを作成します。

    既存の属性を削除するには、その属性値に null を指定します。

  3. Table.UpdateItem メソッドを呼び出し、Document インスタンスを入力パラメータとして指定します。

    プライマリキーを、Document インスタンスで、または明示的にパラメータとして指定する必要があります。

以下の C# コード例は、前述のタスクの例です。このサンプルコードでは、Book テーブルの項目を更新します。UpdateItem オペレーションによって、既存の Authors 属性が更新され、PageCount 属性が削除され、新しい属性 XYZ が追加されます。Document インスタンスには、更新する書籍のプライマリキーが含まれています。

Table table = Table.LoadTable(client, "ProductCatalog"); var book = new Document(); // Set the attributes that you wish to update. book["Id"] = 111; // Primary key. // Replace the authors attribute. book["Authors"] = new List<string> { "Author x", "Author y" }; // Add a new attribute. book["XYZ"] = 12345; // Delete the existing PageCount attribute. book["PageCount"] = null; table.Update(book);

オプションパラメータの指定

UpdateItem パラメータを追加することで、UpdateItemOperationConfig オペレーションに追加オプションを設定できます。オプションパラメータの詳細なリストについては、UpdateItem を参照してください。

次の C# サンプルコードでは、書籍項目の価格が 25 に更新されています。次の 2 つのオプションパラメータが指定されています。

  • 存在すると予測される Price 属性の値が 20 であることを指定する ConditionalExpression パラメータ。

  • 更新された項目が返される ReturnValues オペレーションをリクエストする UpdateItem パラメータ。

Table table = Table.LoadTable(client, "ProductCatalog"); string partitionKey = "111"; var book = new Document(); book["Id"] = partitionKey; book["Price"] = 25; Expression expr = new Expression(); expr.ExpressionStatement = "Price = :val"; expr.ExpressionAttributeValues[":val"] = "20"; UpdateOperationConfig config = new UpdateOperationConfig() { ConditionalExpression = expr, ReturnValues = ReturnValues.AllOldAttributes }; Document d1 = table.Update(book, config);

バッチ書き込み – 複数の項目の書き込みおよび削除

バッチ書き込みは、複数の項目の書き込みと削除をバッチで行うことを意味します。このオペレーションでは、単一の 呼び出しの 1 つ以上のテーブルから、複数の項目の書き込みと削除を行うことができます。AWS SDK for .NET ドキュメントモデル API を使用して、テーブルで複数の項目の書き込みまたは削除を行うステップを次に示します。

  1. Table オブジェクトを作成するには、バッチオペレーションを実行するテーブルの名前を指定して、Table.LoadTable メソッドを実行します。

  2. 前述のステップで作成したテーブルインスタンスで CreateBatchWrite メソッドを実行し、DocumentBatchWrite オブジェクトを作成します。

  3. DocumentBatchWrite オブジェクトメソッドを使用して、アップロードまたは削除するドキュメントを指定します。

  4. DocumentBatchWrite.Execute メソッドを呼び出してバッチオペレーションを実行します。

    ドキュメントモデル API を使用する場合は、1 つのバッチに任意の数のオペレーションを指定できます。ただし DynamoDB では、1 つのバッチ内のオペレーションの数と、1 つのバッチオペレーションでのバッチの合計サイズが制限されています。制限の具体的な詳細については、BatchWriteItem を参照してください。許可されている書き込みリクエスト数をバッチ書き込みリクエストが超えたこと、またはバッチの HTTP ペイロードサイズが BatchWriteItem で許可されている制限を超えたことをドキュメントモデル API が検出した場合には、バッチが複数の小さなバッチに分割されます。さらに、バッチ書き込みに対する応答で、未処理の項目が返された場合には、ドキュメントモデル API がそれら未処理の項目を使用して、別のバッチリクエストを自動的に送信します。

以下の C# サンプルコードは、前述のステップの例です。この例では、バッチ書き込みオペレーションを使用して、書籍項目のアップロードと別の書籍項目の削除という 2 つの書き込みが実行されています。

Table productCatalog = Table.LoadTable(client, "ProductCatalog"); var batchWrite = productCatalog.CreateBatchWrite(); var book1 = new Document(); book1["Id"] = 902; book1["Title"] = "My book1 in batch write using .NET document model"; book1["Price"] = 10; book1["Authors"] = new List<string> { "Author 1", "Author 2", "Author 3" }; book1["InStock"] = new DynamoDBBool(true); book1["QuantityOnHand"] = 5; batchWrite.AddDocumentToPut(book1); // specify delete item using overload that takes PK. batchWrite.AddKeyToDelete(12345); batchWrite.Execute();

実例については、「例: AWS SDK for .NET ドキュメントモデル API を使用したバッチオペレーション」を参照してください。

batchWrite オペレーションを使用すると、複数のテーブルで入力および削除オペレーションを実行できます。AWS SDK for .NET ドキュメントモデルを使用して、複数のテーブルで複数の項目の書き込みまたは削除を行うステップを次に示します。

  1. 前述の手順で示したように、複数の項目の入力または削除を行う各テーブルについて DocumentBatchWrite インスタンスを作成します。

  2. MultiTableDocumentBatchWrite のインスタンスを作成し、その中に個々の DocumentBatchWrite オブジェクトを追加します。

  3. MultiTableDocumentBatchWrite.Execute メソッドを実行します。

以下の C# サンプルコードは、前述のステップの例です。この例では、バッチ書き込みオペレーションを使用して、次の書き込みオペレーションを実行しています。

  • Forum テーブル項目内に新しい項目を入力します。

  • Thread テーブル内に項目を入力し、同じテーブルから項目を削除します。

// 1. Specify item to add in the Forum table. Table forum = Table.LoadTable(client, "Forum"); var forumBatchWrite = forum.CreateBatchWrite(); var forum1 = new Document(); forum1["Name"] = "Test BatchWrite Forum"; forum1["Threads"] = 0; forumBatchWrite.AddDocumentToPut(forum1); // 2a. Specify item to add in the Thread table. Table thread = Table.LoadTable(client, "Thread"); var threadBatchWrite = thread.CreateBatchWrite(); var thread1 = new Document(); thread1["ForumName"] = "Amazon S3 forum"; thread1["Subject"] = "My sample question"; thread1["Message"] = "Message text"; thread1["KeywordTags"] = new List<string>{ "Amazon S3", "Bucket" }; threadBatchWrite.AddDocumentToPut(thread1); // 2b. Specify item to delete from the Thread table. threadBatchWrite.AddKeyToDelete("someForumName", "someSubject"); // 3. Create multi-table batch. var superBatch = new MultiTableDocumentBatchWrite(); superBatch.AddBatch(forumBatchWrite); superBatch.AddBatch(threadBatchWrite); superBatch.Execute();