AWS SDK for .NET 低レベル API を使用して、テーブル内の項目に対して、一般的な作成、読み込み、更新、削除 (CRUD) のオペレーションを実行できます。以下に、.NET の低レベル API を使用してデータ CRUD オペレーションを実行するための一般的なステップを示します。
-
AmazonDynamoDBClient
クラスのインスタンス(クライアント)を作成します。 -
対応するリクエストオブジェクトで、オペレーション固有の必須パラメータを指定します。
たとえば、項目をアップロードするときは
PutItemRequest
リクエストオブジェクトを使用し、既存の項目を取得するときはGetItemRequest
リクエストオブジェクトを使用します。リクエストオブジェクトを使用して、必須パラメータとオプションパラメータの両方を指定できます。
-
前述のステップで作成したリクエストオブジェクトを渡して、クライアントから提供された適切なメソッドを実行します。
AmazonDynamoDBClient
クライアントは、CRUD オペレーションに、PutItem
、GetItem
、UpdateItem
およびDeleteItem
メソッドを提供します。
トピック
項目の置換
PutItem
メソッドは、項目をテーブルにアップロードします。項目が存在する場合、その項目全体が置き換えられます。
注記
項目全体を置き換える代わりに固有の属性のみを更新する場合は、UpdateItem
メソッドを使用できます。詳細については、「」を参照してください項目の更新
以下に、低レベル .NET SDK API を使用して項目をアップロードするステップを示します。
-
AmazonDynamoDBClient
クラスのインスタンスを作成します。 -
PutItemRequest
クラスのインスタンスを作成して、必要なパラメータを指定します。項目を配置するには、テーブル名と項目を指定する必要があります。
-
前のステップで作成した
PutItemRequest
オブジェクトを指定して、PutItem
メソッドを実行します。
以下の 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);
前の例では、Id
、Title
、ISBN
および Authors
属性を持つブック項目をアップロードします。Id
は数値型の属性であり、他のすべての属性は文字列型であることに注意してください。作成者は String
セットです。
オプションパラメータの指定
次の C# 例に示すように、PutItemRequest
オブジェクトを使用してオプションのパラメータを指定することもできます。この例では、次のオプションパラメータが指定されています。
-
ExpressionAttributeNames
、ExpressionAttributeValues
および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 を使用して既存の項目を取得するステップを示します。
-
AmazonDynamoDBClient
クラスのインスタンスを作成します。 -
GetItemRequest
クラスのインスタンスを作成して、必要なパラメータを指定します。項目を吸いtpィするには、テーブル名と項目のプライマリキーを指定する必要があります。
-
前のステップで作成した
GetItemRequest
オブジェクトを指定して、GetItem
メソッドを実行します。
以下の 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
パラメータ。読み込み整合性の詳細については、「DynamoDB の読み取り整合性」を参照してください。
例
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 である場合は、属性を削除します。
-
ADD
にAction
を使用する場合は、既存のセット (文字列または数値セット) に値を追加するか、既存の数値属性値から数学的に加算 (正の数を使用) または減算 (負の数を使用) することができます。
-
注記
PutItem
オペレーションにより、更新を実行できます。詳細については、「」を参照してください項目の置換 たとえば、PutItem
をコールして項目をアップロードするときにプライマリキーが存在する場合は、PutItem
オペレーションによって項目全体が置き換わります。既存の項目内に属性があり、入力でそれらの属性が指定されていない場合、それらの属性は、PutItem
オペレーションによって削除されます。ただし、UpdateItem
が更新するのは指定された入力属性だけです。その項目では、その他の既存の属性は変更されません。
以下に、低レベル .NET SDK API を使用して既存の項目を更新するステップを示します。
-
AmazonDynamoDBClient
クラスのインスタンスを作成します。 -
UpdateItemRequest
クラスのインスタンスを作成して、必要なパラメータを指定します。これは、属性の追加、既存の属性の更新、属性の削除など、すべての更新を記述するリクエストオブジェクトです。既存の属性を削除するには、その属性名に null 値を指定します。
-
前のステップで作成した
UpdateItemRequest
オブジェクトを指定して、UpdateItem
メソッドを実行します。
以下の 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 である場合にのみ料金を更新できるように指定します。 -
レスポンスで更新された項目をリクエストする
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
および ADD
を、Action
として使用します。
次のサンプルはこのアトミックカウンターを示しており、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 を使用して項目を削除するステップを示します。
-
AmazonDynamoDBClient
クラスのインスタンスを作成します。 -
DeleteItemRequest
クラスのインスタンスを作成して、必要なパラメータを指定します。項目を削除するには、テーブル名と項目のプライマリキーが必要です。
-
前のステップで作成した
DeleteItemRequest
オブジェクトを指定して、DeleteItem
メソッドを実行します。
例
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 を使用して複数の項目を取得するステップを示します。
-
AmazonDynamoDBClient
クラスのインスタンスを作成します。 -
BatchWriteItemRequest
クラスのインスタンスを作成して、すべての入力および削除オペレーションを記述します。 -
前のステップで作成した
BatchWriteItemRequest
オブジェクトを指定して、BatchWriteItem
メソッドを実行します。 -
応答を処理します。返された未処理のリクエスト項目が応答内に存在していたかどうかをチェックする必要があります。これは、プロビジョニングされたスループットクォータまたは他の何らかの一時的エラーに達する場合に、発生する可能性があります。また、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 を使用して複数の項目を取得するステップを示します。
-
AmazonDynamoDBClient
クラスのインスタンスを作成します。 -
BatchGetItemRequest
クラスのインスタンスを作成して、必要なパラメータを指定します。複数の項目を取得するには、テーブル名とプライマリキーバリューのリストが必要です。
-
前のステップで作成した
BatchGetItemRequest
オブジェクトを指定して、BatchGetItem
メソッドを実行します。 -
応答を処理します。未処理キーがなかったかどうかを確認する必要があります。これは、プロビジョニングされたスループットクォータまたは他の何らかの一時的エラーに達する場合に発生する可能性があります。
以下の C# サンプルコードは、前述のステップの例です。この例では、Forum
および Thread
の 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 を参照してください。