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

項目の操作 : .NET

AWS SDK for .NET 低レベル API を使用して、テーブル内の項目に対して、一般的な作成、読み込み、更新、削除 (CRUD) のオペレーションを実行できます。以下に、.NET の低レベル API を使用してデータ CRUD オペレーションを実行する手順を示します。

  1. AmazonDynamoDBClient クラスのインスタンス(クライアント)を作成します。

  2. 対応するリクエストオブジェクト内に、オペレーション固有の必須パラメータを指定します。

    たとえば、項目をアップロードするには PutItemRequest リクエストオブジェクトを使用し、既存の項目を取り出すには GetItemRequest リクエストオブジェクトを使用します。

    リクエストオブジェクトを使用して、必須パラメータとオプションパラメータの両方を指定できます。

  3. 前の手順で作成したリクエストオブジェクト内でパスすることにより、クライアントから提供された適切なメソッドを実行します。

    AmazonDynamoDBClient クライアントは、CRUD オペレーション用のメソッドとして、PutItemGetItemUpdateItemDeleteItem を提供します。

項目の置換

PutItem メソッドによって、項目をテーブルにアップロードします。項目が存在する場合、その項目全体が置き換えられます。

注記

項目全体を置き換える代わりに固有の属性のみを更新する場合は、UpdateItem メソッドを使用できます。詳細については、「項目の更新」を参照してください。

以下に、低レベルの .NET SDK API を使用して項目をアップロードする手順を示します。

  1. AmazonDynamoDBClient クラスのインスタンスを作成します。

  2. PutItemRequest クラスのインスタンスを作成し、必須パラメータを指定します。

    項目を置き換えるには、テーブル名と項目を指定する必要があります。

  3. 前の手順で作成した PutItem オブジェクトを指定して、PutItemRequest メソッドを実行します。

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

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new PutItemRequest { TableName = tableName, Item = new Dictionary<string, AttributeValue>() { { "Id", new AttributeValue { N = "201" }}, { "Title", new AttributeValue { S = "Book 201 Title" }}, { "ISBN", new AttributeValue { S = "11-11-11-11" }}, { "Price", new AttributeValue { S = "20.00" }}, { "Authors", new AttributeValue { SS = new List<string>{"Author1", "Author2"} } } } }; client.PutItem(request);

上記の例では IdTitleISBNAuthors の属性を持つ書籍項目をアップロードしています。Id は数値型の属性で、それ以外の属性はすべて文字列型です。作成者は String セットです。

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

以下の C# サンプルに示すように、PutItemRequest オブジェクトを使用してオプションのパラメータを指定することもできます。この例では、次のオプションパラメータが指定されています。

  • ExpressionAttributeNamesExpressionAttributeValues、および ConditionExpression は、特定の値が設定された ISBN 属性が既存の項目にある場合にのみ項目を置き換えるという条件を指定します。

  • ReturnValues パラメータ。応答内で古い項目をリクエストします。

var request = new PutItemRequest { TableName = tableName, Item = new Dictionary<string, AttributeValue>() { { "Id", new AttributeValue { N = "104" }}, { "Title", new AttributeValue { S = "Book 104 Title" }}, { "ISBN", new AttributeValue { S = "444-4444444444" }}, { "Authors", new AttributeValue { SS = new List<string>{"Author3"}}} }, // Optional parameters. ExpressionAttributeNames = new Dictionary<string,string>() { {"#I", "ISBN"} }, ExpressionAttributeValues = new Dictionary<string, AttributeValue>() { {":isbn",new AttributeValue {S = "444-4444444444"}} }, ConditionExpression = "#I = :isbn" }; var response = client.PutItem(request);

詳細については、「PutItem」を参照してください。

項目の取得

GetItem メソッドにより、項目を取り出します。

注記

複数の項目を取り出すために、BatchGetItem メソッドを使用できます。詳細については、「バッチ取得: 複数の項目の取得」を参照してください。

以下に、低レベルの AWS SDK for .NET API を使用して既存の項目を取り出す手順を示します。

  1. AmazonDynamoDBClient クラスのインスタンスを作成します。

  2. GetItemRequest クラスのインスタンスを作成し、必須パラメータを指定します。

    項目を取得するには、その項目のテーブル名とプライマリキーを指定する必要があります。

  3. 前の手順で作成した GetItem オブジェクトを指定して、GetItemRequest メソッドを実行します。

以下の C# サンプルは、前述のステップの例です。サンプルでは、ProductCatalog から項目を取得します。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new GetItemRequest { TableName = tableName, Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "202" } } }, }; var response = client.GetItem(request); // Check the response. var result = response.GetItemResult; var attributeMap = result.Item; // Attribute list in the response.

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

以下の C# サンプルに示すように、GetItemRequest オブジェクトを使用してオプションのパラメータを指定することもできます。このサンプルでは、次のオプションパラメータが指定されています。

  • 取得対象の属性を指定する ProjectionExpression パラメータ。

  • 強力な整合性のある読み込みを実行する ConsistentRead パラメータ。読み込みの整合性に関する詳細については、「読み込み整合性」を参照してください。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new GetItemRequest { TableName = tableName, Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "202" } } }, // Optional parameters. ProjectionExpression = "Id, ISBN, Title, Authors", ConsistentRead = true }; var response = client.GetItem(request); // Check the response. var result = response.GetItemResult; var attributeMap = result.Item;

詳細については、「GetItem」を参照してください。

項目の更新

既存の項目がある場合に、UpdateItem メソッドにより、その項目を更新します。UpdateItem オペレーションを使用して、既存の属性値の更新、新しい属性の追加、または既存のコレクションからの属性の削除ができます。指定のプライマリキーのある項目が見つからない場合は、新しい項目を追加します。

UpdateItem オペレーションは、以下のガイドラインに従います。

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

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

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

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

    • 入力属性が null の場合、属性がある場合は、削除します。

    • ActionADD を使用すると、既存のセット (文字列または数セット) に値を追加できます。あるいは、既存の数値属性の値に対して足し算 (正の数を使用) したり、引き算 (負の数を使用) することもできます。

注記

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

以下に、低レベルの .NET SDK API を使用して既存の項目を更新する手順を示します。

  1. AmazonDynamoDBClient クラスのインスタンスを作成します。

  2. UpdateItemRequest クラスのインスタンスを作成し、必須パラメータを指定します。

    これは、属性の追加、既存の属性の更新、属性の削除など、すべての更新を記述するリクエストオブジェクトです。既存の属性を削除するには、null 値の属性名を指定します。

  3. 前の手順で作成した UpdateItem オブジェクトを指定して、UpdateItemRequest メソッドを実行します。

以下の C# サンプルコードは、前述のステップの例です。このサンプルでは、ProductCatalog テーブルの書籍項目を更新します。この例では、Authors コレクションに著者を追加し、既存の ISBN 属性を削除します。また、価格を 1 引き下げます。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new UpdateItemRequest { TableName = tableName, Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "202" } } }, ExpressionAttributeNames = new Dictionary<string,string>() { {"#A", "Authors"}, {"#P", "Price"}, {"#NA", "NewAttribute"}, {"#I", "ISBN"} }, ExpressionAttributeValues = new Dictionary<string, AttributeValue>() { {":auth",new AttributeValue { SS = {"Author YY","Author ZZ"}}}, {":p",new AttributeValue {N = "1"}}, {":newattr",new AttributeValue {S = "someValue"}}, }, // This expression does the following: // 1) Adds two new authors to the list // 2) Reduces the price // 3) Adds a new attribute to the item // 4) Removes the ISBN attribute from the item UpdateExpression = "ADD #A :auth SET #P = #P - :p, #NA = :newattr REMOVE #I" }; var response = client.UpdateItem(request);

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

以下の C# サンプルに示すように、UpdateItemRequest オブジェクトを使用してオプションのパラメータを指定することもできます。以下のオプションパラメータを指定します。

  • ExpressionAttributeValues および ConditionExpression パラメータ。既存の価格が 20.00 USD である場合にのみ価格を更新できることを指定します。

  • ReturnValues パラメータ。応答内で更新された項目をリクエストします。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new UpdateItemRequest { Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "202" } } }, // Update price only if the current price is 20.00. ExpressionAttributeNames = new Dictionary<string,string>() { {"#P", "Price"} }, ExpressionAttributeValues = new Dictionary<string, AttributeValue>() { {":newprice",new AttributeValue {N = "22"}}, {":currprice",new AttributeValue {N = "20"}} }, UpdateExpression = "SET #P = :newprice", ConditionExpression = "#P = :currprice", TableName = tableName, ReturnValues = "ALL_NEW" // Return all the attributes of the updated item. }; var response = client.UpdateItem(request);

詳細については、「UpdateItem」を参照してください。

アトミックカウンター

updateItem を使用してアトミックカウンターを実装できます。アトミックカウンターでは、他の書き込みリクエストを妨げることなく、既存の属性の値をインクリメントまたはデクリメントします。アトミックカウンターを更新するには、UpdateExpression パラメータの Number 型の属性を持つ updateItem と、Action として ADD を使用します。

次のサンプルはこのアトミックカウンターを示しており、Quantity 属性を 1 ずつインクリメントさせています。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new UpdateItemRequest { Key = new Dictionary<string, AttributeValue>() { { "Id", new AttributeValue { N = "121" } } }, ExpressionAttributeNames = new Dictionary<string, string>() { {"#Q", "Quantity"} }, ExpressionAttributeValues = new Dictionary<string, AttributeValue>() { {":incr",new AttributeValue {N = "1"}} }, UpdateExpression = "SET #Q = #Q + :incr", TableName = tableName }; var response = client.UpdateItem(request);

項目の削除

DeleteItem メソッドによって、テーブルから項目を削除します。

以下に、低レベルの .NET SDK API を使用して項目を削除する手順を示します。

  1. AmazonDynamoDBClient クラスのインスタンスを作成します。

  2. DeleteItemRequest クラスのインスタンスを作成し、必須パラメータを指定します。

    項目を削除するには、テーブル名とその項目のプライマリキーが必要です。

  3. 前の手順で作成した DeleteItem オブジェクトを指定して、DeleteItemRequest メソッドを実行します。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new DeleteItemRequest { TableName = tableName, Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "201" } } }, }; var response = client.DeleteItem(request);

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

以下の C# コード例に示すように、DeleteItemRequest オブジェクトを使用してオプションのパラメータを指定することもできます。以下のオプションパラメータを指定します。

  • ExpressionAttributeValues および ConditionExpression パラメータ。廃刊になっている(InPublication の属性値が false)場合にのみ書籍項目を削除するという条件を指定します。

  • ReturnValues パラメータ。応答内で削除済みの項目をリクエストします。

var request = new DeleteItemRequest { TableName = tableName, Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "201" } } }, // Optional parameters. ReturnValues = "ALL_OLD", ExpressionAttributeNames = new Dictionary<string, string>() { {"#IP", "InPublication"} }, ExpressionAttributeValues = new Dictionary<string, AttributeValue>() { {":inpub",new AttributeValue {BOOL = false}} }, ConditionExpression = "#IP = :inpub" }; var response = client.DeleteItem(request);

詳細については、「DeleteItem」を参照してください。

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

バッチ書き込みは、複数の項目の書き込みと削除をバッチで行うことを意味します。BatchWriteItem メソッドによって、単一の コール内にある 1 つまたは複数のテーブルから複数の項目を置換および削除できます。以下に、低レベルの .NET SDK API を使用して複数の項目を取り出す手順を示します。

  1. AmazonDynamoDBClient クラスのインスタンスを作成します。

  2. BatchWriteItemRequest クラスのインスタンスを作成して、置換および削除のすべてのオペレーションを説明します。

  3. 前の手順で作成した BatchWriteItem オブジェクトを指定して、BatchWriteItemRequest メソッドを実行します。

  4. 応答を処理します。返された未処理のリクエスト項目が応答内に存在していたかどうかをチェックする必要があります。これは、プロビジョニングされたスループットの制限または他の何らかの一時的エラーに達する場合に、発生する可能性があります。また、DynamoDB によって、リクエストのサイズ、およびリクエスト内で指定できるオペレーションの数が制限されます。これらの制限を超えると、DynamoDB によってリクエストが却下されます。詳細については、「BatchWriteItem」を参照してください。

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

  • Forum テーブルに項目を配置します。

  • Thread テーブルに対して項目の配置および削除を実行します。

コードにより、BatchWriteItem が実行され、バッチオペレーションが行われます。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string table1Name = "Forum"; string table2Name = "Thread"; var request = new BatchWriteItemRequest { RequestItems = new Dictionary<string, List<WriteRequest>> { { table1Name, new List<WriteRequest> { new WriteRequest { PutRequest = new PutRequest { Item = new Dictionary<string,AttributeValue> { { "Name", new AttributeValue { S = "Amazon S3 forum" } }, { "Threads", new AttributeValue { N = "0" }} } } } } } , { table2Name, new List<WriteRequest> { new WriteRequest { PutRequest = new PutRequest { Item = new Dictionary<string,AttributeValue> { { "ForumName", new AttributeValue { S = "Amazon S3 forum" } }, { "Subject", new AttributeValue { S = "My sample question" } }, { "Message", new AttributeValue { S = "Message Text." } }, { "KeywordTags", new AttributeValue { SS = new List<string> { "Amazon S3", "Bucket" } } } } } }, new WriteRequest { DeleteRequest = new DeleteRequest { Key = new Dictionary<string,AttributeValue>() { { "ForumName", new AttributeValue { S = "Some forum name" } }, { "Subject", new AttributeValue { S = "Some subject" } } } } } } } } }; response = client.BatchWriteItem(request);

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

バッチ取得: 複数の項目の取得

BatchGetItem メソッドによって、1 つまたは複数のテーブルから複数の項目を取得できます。

注記

単一の項目を取り出すために、GetItem メソッドを使用できます。

以下に、低レベルの AWS SDK for .NET API を使用して複数の項目を取り出す手順を示します。

  1. AmazonDynamoDBClient クラスのインスタンスを作成します。

  2. BatchGetItemRequest クラスのインスタンスを作成し、必須パラメータを指定します。

    複数の項目を取り出すには、テーブル名、およびプライマリキー値のリストが必要です。

  3. 前の手順で作成した BatchGetItem オブジェクトを指定して、BatchGetItemRequest メソッドを実行します。

  4. 応答を処理します。未処理キーがなかったかどうかをチェックする必要があります。これは、プロビジョニングされたスループットの制限または他の何らかの一時的エラーに達する場合に、発生する可能性があります。

以下の C# サンプルコードは、前述のステップの例です。この例では、ForumThread の 2 つのテーブルから項目を取り出します。このリクエストには、Forum テーブル内の 2 つの項目、および Thread テーブル内の 3 つの項目を指定します。応答には、両方のテーブルの項目が含まれます。このコードには、応答を処理する方法が示されます。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string table1Name = "Forum"; string table2Name = "Thread"; var request = new BatchGetItemRequest { RequestItems = new Dictionary<string, KeysAndAttributes>() { { table1Name, new KeysAndAttributes { Keys = new List<Dictionary<string, AttributeValue>>() { new Dictionary<string, AttributeValue>() { { "Name", new AttributeValue { S = "DynamoDB" } } }, new Dictionary<string, AttributeValue>() { { "Name", new AttributeValue { S = "Amazon S3" } } } } } }, { table2Name, new KeysAndAttributes { Keys = new List<Dictionary<string, AttributeValue>>() { new Dictionary<string, AttributeValue>() { { "ForumName", new AttributeValue { S = "DynamoDB" } }, { "Subject", new AttributeValue { S = "DynamoDB Thread 1" } } }, new Dictionary<string, AttributeValue>() { { "ForumName", new AttributeValue { S = "DynamoDB" } }, { "Subject", new AttributeValue { S = "DynamoDB Thread 2" } } }, new Dictionary<string, AttributeValue>() { { "ForumName", new AttributeValue { S = "Amazon S3" } }, { "Subject", new AttributeValue { S = "Amazon S3 Thread 1" } } } } } } } }; var response = client.BatchGetItem(request); // Check the response. var result = response.BatchGetItemResult; var responses = result.Responses; // The attribute list in the response. var table1Results = responses[table1Name]; Console.WriteLine("Items in table {0}" + table1Name); foreach (var item1 in table1Results.Items) { PrintItem(item1); } var table2Results = responses[table2Name]; Console.WriteLine("Items in table {1}" + table2Name); foreach (var item2 in table2Results.Items) { PrintItem(item2); } // Any unprocessed keys? could happen if you exceed ProvisionedThroughput or some other error. Dictionary<string, KeysAndAttributes> unprocessedKeys = result.UnprocessedKeys; foreach (KeyValuePair<string, KeysAndAttributes> pair in unprocessedKeys) { Console.WriteLine(pair.Key, pair.Value); }

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

以下の C# コード例に示すように、BatchGetItemRequest オブジェクトを使用してオプションのパラメータを指定することもできます。サンプルでは、Forum テーブルから 2 つの項目を取得します。次のオプションパラメータが指定されています。

  • 取得対象の属性を指定する ProjectionExpression パラメータ。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string table1Name = "Forum"; var request = new BatchGetItemRequest { RequestItems = new Dictionary<string, KeysAndAttributes>() { { table1Name, new KeysAndAttributes { Keys = new List<Dictionary<string, AttributeValue>>() { new Dictionary<string, AttributeValue>() { { "Name", new AttributeValue { S = "DynamoDB" } } }, new Dictionary<string, AttributeValue>() { { "Name", new AttributeValue { S = "Amazon S3" } } } } }, // Optional - name of an attribute to retrieve. ProjectionExpression = "Title" } } }; var response = client.BatchGetItem(request);

詳細については、「BatchGetItem」を参照してください。