AWS SDK for .NET ドキュメントモデルを使用して DynamoDB の項目の操作します - Amazon DynamoDB
項目の入力 – Table.PutItem メソッドオプションパラメータの指定項目の取得 – Table.GetItem 項目の削除 – Table.DeleteItem 項目の更新 – Table.UpdateItemバッチ書き込み – 複数の項目の書き込みおよび削除

AWS SDK for .NET ドキュメントモデルを使用して DynamoDB の項目の操作します

以下のコード例は、AWS SDK for .NET ドキュメントモデルを使用してさまざまなオペレーションを実行する方法を示しています。これらの例を使用して、CRUD、バッチ、トランザクションの各オペレーションを実行できます。

ドキュメントモデルを使用してデータオペレーションを実行するには、最初に Table.LoadTable メソッドを呼び出して、特定のテーブルを表す Table クラスのインスタンスを作成します。次の C# の例では、Amazon DynamoDB の ProductCatalog テーブルに対応している Table オブジェクトを作成しています。

例 
Table table = Table.LoadTable(client, "ProductCatalog");
注記

通常、LoadTable メソッドはアプリケーションの開始時に 1 回使用するだけです。このメソッドによって、DynamoDB へのラウンドトリップに DescribeTable 呼び出しが追加されるためです。

その後、Table オブジェクトを使用して、さまざまなデータオペレーションを実行することができます。各データオペレーションには 2 種類のオーバーロードがあります。1 つは最小限必要なパラメーターを受け取り、もう 1 つはオプションのオペレーション固有の設定情報を受け取ります。たとえば項目を取得するには、テーブルのプライマリキーの値を入力する必要がありますが、その場合は次の GetItem オーバーロードを使用できます。

例 
// Get the item from a table that has a primary key that is composed of only a partition key.
Table.GetItem(Primitive partitionKey);
// Get the item from a table whose primary key is composed of both a partition key and sort key.
Table.GetItem(Primitive partitionKey, Primitive sortKey);

これらのメソッドには、オプションのパラメータを渡すこともできます。たとえば前述の GetItem では、すべての属性を含む項目全体が返されます。オプションで、取り出す属性のリストを指定することもできます。この場合は、オペレーション固有の設定オブジェクトパラメータをとる、次の GetItem オーバーロードを使用します。

例 

// Configuration object that specifies optional parameters.
GetItemOperationConfig config = new GetItemOperationConfig()
{
  AttributesToGet = new List<string>() { "Id", "Title" },
};
// Pass in the configuration to the GetItem method.
// 1. Table that has only a partition key as primary key.
Table.GetItem(Primitive partitionKey, GetItemOperationConfig config);
// 2. Table that has both a partition key and a sort key.
Table.GetItem(Primitive partitionKey, Primitive sortKey, GetItemOperationConfig config);

設定オブジェクトを使用することで、特定の属性リストのリクエストやページサイズ（ページあたりの項目数）の指定など、複数のオプションパラメータを指定できます。それぞれのデータオペレーションメソッドには、独自の設定クラスがあります。たとえば、GetItemOperationConfig クラスを使用して、GetItem オペレーションのオプションを指定します。PutItemOperationConfig クラスを使用して、PutItem オペレーション用にオプションのパラメータを指定することができます。

以下のセクションでは、Table クラスでサポートされているそれぞれのデータオペレーションについて説明します。

項目の入力 – Table.PutItem メソッド

PutItem メソッドは、入力された Document インスタンスをテーブルにアップロードします。入力された Document で指定されているプライマリキーを持つ項目がテーブル内に存在する場合は、PutItem オペレーションによって、既存の項目全体が置換されます。新しい項目は、Document メソッドに指定した PutItem オブジェクトと同じになります。元の項目にそれ以外の属性が存在していたとしても、新しい項目には存在しません。

次に、AWS SDK for .NET ドキュメントモデルを使用してテーブルに新しい項目を入力するステップを示します。

  1. 項目を追加するテーブル名を生成するために、Table.LoadTable メソッドを実行します。

  2. 属性名と値のリストが含まれる、Document オブジェクトを作成します。

  3. Document インスタンスをパラメータとして指定しながら Table.PutItem を実行します。

以下の C# コード例は、前述のタスクの例です。この例では、項目を ProductCatalog テーブルにアップロードします。

例 
Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 101;
book["Title"] = "Book 101 Title";
book["ISBN"] = "11-11-11-11";
book["Authors"] = new List<string> { "Author 1", "Author 2" };
book["InStock"] = new DynamoDBBool(true);
book["QuantityOnHand"] = new DynamoDBNull();

table.PutItem(book);

前述の例では、Document インスタンスで、Number、String、String Set、Boolean、および Null 属性を含む項目が作成されます。(Null は、この製品の QuantityOnHand が不明なことを示す場合に使用されます) Booleanと Null の場合は、コンストラクタメソッド DynamoDBBool および DynamoDBNull を使用します。

DynamoDB では、データ型 List および Map に、他のデータ型で構成された要素を含むこができます。これらのデータ型をドキュメントモデル API にマッピングする方法を以下に示します。

  • List – DynamoDBList コンストラクタを使用します。

  • Map – Document コンストラクタを使用します。

項目に List 属性を追加するように、前述の例を変更することができます。これを行うには、次のサンプルコードに示すように、DynamoDBList コンストラクタを使用します。

例 
Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 101;

/*other attributes omitted for brevity...*/

var relatedItems = new DynamoDBList();
relatedItems.Add(341);
relatedItems.Add(472);
relatedItems.Add(649);
book.Add("RelatedItems", relatedItems);

table.PutItem(book);

書籍に Map 属性を追加するには、別の Document を定義します。次のコード例はこれを行う方法を示しています。

例 
Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 101;

/*other attributes omitted for brevity...*/

var pictures = new Document();
pictures.Add("FrontView", "http://example.com/products/101_front.jpg" );
pictures.Add("RearView", "http://example.com/products/101_rear.jpg" );

book.Add("Pictures", pictures);

table.PutItem(book);

これらの例は、式を使用する時の項目属性の指定 に示された項目に基づいています。ドキュメントモデルを使用すると、導入事例の ProductReviews 属性のように複雑な入れ子になった属性を作成することができます。

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

PutItem オペレーションに PutItemOperationConfig パラメータを追加することで、オプションパラメータを設定できます。すべてのオプションパラメータのリストは、「PutItem」でご確認ください。次の C# のサンプルコードでは、ProductCatalog テーブルに項目を配置します。次のオプションパラメータが指定されています。

  • 条件付き入力リクエストとする ConditionalExpression パラメータ。例では、置き換える項目に ISBN 属性が存在し、それが特定の値でなくてはならないことを指定する式を作成します。

例 
Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 555;
book["Title"] = "Book 555 Title";
book["Price"] = "25.00";
book["ISBN"] = "55-55-55-55";
book["Name"] = "Item 1 updated";
book["Authors"] = new List<string> { "Author x", "Author y" };
book["InStock"] = new DynamoDBBool(true);
book["QuantityOnHand"] = new DynamoDBNull();

// Create a condition expression for the optional conditional put operation.
Expression expr = new Expression();
expr.ExpressionStatement = "ISBN = :val";
expr.ExpressionAttributeValues[":val"] = "55-55-55-55";

PutItemOperationConfig config = new PutItemOperationConfig()
{
  // Optional parameter.
     ConditionalExpression = expr
};

table.PutItem(book, config);

項目の取得 – 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 にマッピングする方法を以下に示します。

  • List – AsDynamoDBList メソッドを使用します。

  • Map – AsDocument メソッドを使用します。

次のサンプルコードは、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 つのオプションパラメータが指定されています。

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

  • 更新された項目が返される 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";

UpdateItemOperationConfig config = new UpdateItemOperationConfig()
{
    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();