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 메서드를 한 번 사용합니다. 이 메서드는 DynamoDB로 왕복하는 DescribeTable 호출을 수행하기 때문입니다.

이렇게 생성된 Table 객체를 사용하여 다양한 데이터 작업을 수행할 수 있습니다. 이러한 각 데이터 작업에는 두 가지 유형의 오버로드가 있습니다. 하나는 최소 필수 파라미터를 사용하고, 또 다른 하나는 작업별 선택적 구성 정보를 사용합니다. 예를 들어, 항목을 검색하려면 테이블의 기본 키 값을 제공해야 하며, 이 경우 다음과 같은 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 클래스에서 지원되는 각 데이터 작업을 다룹니다.

항목 올리기 - 테이블. PutItem 메서드

PutItem 메서드는 테이블에 입력 Document 인스턴스를 업로드합니다. 입력 Document에 지정된 기본 키가 있는 항목이 테이블에 있는 경우 PutItem 작업은 전체 기존 항목을 바꿉니다. 새 항목은 PutItem 메서드에 제공한 Document 객체와 동일합니다. 원본 항목에 추가 속성이 있어도 새 항목에는 추가 속성이 더 이상 존재하지 않습니다.

다음은 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 SetBoolean, 및 Null 속성을 가진 항목을 생성합니다. (Null이 제품의 제품을 알 수 QuantityOnHand없음을 나타내는 데 사용됩니다.) Boolean 및 Null의 경우 생성자 메서드 DynamoDBBool 및 DynamoDBNull을 사용합니다.

DynamoDB에서 List 및 Map 데이터 형식은 다른 데이터 형식으로 구성된 요소를 포함할 수 있습니다. 다음은 이러한 데이터 형식을 문서 모델 API에 매핑하는 방법입니다.

• 목록 - DynamoDBList 생성자를 사용합니다.

• 맵 - 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 속성과 같은 복잡한 중첩 속성을 만들 수 있습니다.

옵션 파라미터 지정

PutItemOperationConfig 파라미터를 추가하여 PutItem 작업에 대한 선택적 파라미터를 구성할 수 있습니다. 선택적 파라미터의 전체 목록은 PutItem을 참조하십시오. 다음 C# 코드 예제에서는 ProductCatalog 테이블에 항목을 입력합니다. 이 예제에서 지정하는 옵션 파라미터는 다음과 같습니다.

• ConditionalExpression 파라미터는 이를 조건부 PUT 요청으로 만듭니다. 이 예제에서는 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);

아이템 가져오기 - 표. GetItem

GetItem 작업은 항목을 Document 인스턴스로 가져옵니다. 검색할 항목의 기본 키를 다음 C# 코드 예제와 같이 제공해야 합니다.

예

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

GetItem 작업은 항목의 모든 속성을 반환하고 기본적으로 최종적 일관된 읽기(읽기 정합성 참조)를 수행합니다.

옵션 파라미터 지정

GetItemOperationConfig 파라미터를 추가하여 GetItem 작업에 대한 옵션을 추가로 구성할 수 있습니다. 선택적 파라미터의 전체 목록은 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 메서드를 사용합니다.

다음 코드 예제는 Document 객체에서 a List (RelatedItems) 및 a Map (Pictures) 를 검색하는 방법을 보여줍니다.

예

DynamoDBList relatedItems = doc["RelatedItems"].AsDynamoDBList();

Document pictures = doc["Pictures"].AsDocument();

항목 삭제 - 표. DeleteItem

DeleteItem 작업은 테이블에서 항목을 삭제합니다. 항목의 기본 키를 파라미터로 전달할 수 있습니다. 또는 항목을 이미 읽었고 해당하는 Document 객체가 있는 경우 다음 C# 코드 예제와 같이 이를 파라미터로 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)

옵션 파라미터 지정

DeleteItemOperationConfig 파라미터를 추가하여 Delete 작업에 대한 옵션을 추가로 구성할 수 있습니다. 선택적 파라미터의 전체 목록은 DeleteTable을 참조하십시오. 다음 C# 코드 예제에서는 다음과 같은 두 개의 선택적 파라미터를 지정합니다.

• ConditionalExpression 파라미터는 삭제 중인 책 항목에 ISBN 속성에 대한 특정 값이 있음을 보장합니다.

• 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);

항목 업데이트 - 테이블 UpdateItem

UpdateItem 작업은 기존 항목이 있는 경우 이를 업데이트합니다. 지정된 기본 키가 있는 항목을 찾을 수 없는 경우, UpdateItem 작업은 새 항목을 추가합니다.

UpdateItem 작업을 사용하여 기존 속성 값을 업데이트하거나, 기존 모음에 새 속성을 추가하거나, 기존 모음에서 속성을 삭제할 수 있습니다. 수행할 업데이트를 설명하는 Document 인스턴스를 생성하여 이러한 업데이트를 제공합니다.

UpdateItem 작업은 다음 지침을 사용합니다.

• 항목이 없는 경우 UpdateItem은 입력에서 지정한 기본 키를 사용하여 새 항목을 추가합니다.

• 항목이 있는 경우 UpdateItem은 다음과 같이 업데이트를 적용합니다.

  • 기존 속성 값을 업데이트 값으로 바꿉니다.

  • 입력한 속성이 없는 경우 항목에 새 속성을 추가합니다.

  • 입력 속성 값이 null인 경우 해당 속성을 삭제합니다(있는 경우).

참고

이 중간 수준 UpdateItem 작업은 기본 DynamoDB 작업에서 지원하는 Add 작업 (참조 UpdateItem) 을 지원하지 않습니다.

참고

PutItem 작업(항목 올리기 - 테이블. 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);

옵션 파라미터 지정

UpdateItemOperationConfig 파라미터를 추가하여 UpdateItem 작업에 대한 옵션을 추가로 구성할 수 있습니다. 선택적 파라미터의 전체 목록은 UpdateItem을 참조하십시오.

다음 C# 코드 예제에서는 책 항목 가격을 25로 업데이트합니다. 이 조각은 다음과 같은 두 개의 선택적 파라미터를 지정합니다.

• ConditionalExpression 파라미터는 값이 20인 Price 속성(사용자가 있을 것이라고 기대)을 식별합니다.

• 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);

일괄 쓰기 - 여러 항목 추가 및 삭제

배치 쓰기란 다수의 항목을 배치로 입력 및 삭제하는 것을 말합니다. 이 작업을 사용하면 단일 호출로 하나 이상의 테이블에서 여러 개의 항목을 추가하고 삭제할 수 있습니다. 다음은 AWS SDK for .NET 문서 모델 API를 사용하여 하나의 테이블에서 여러 개의 항목을 추가하거나 삭제하는 단계입니다.

1. 배치 작업을 수행할 테이블의 이름을 제공하고 Table.LoadTable 메서드를 실행하여 Table 객체를 생성합니다.

2. 이전 단계에서 생성된 테이블 인스턴스에서 createBatchWrite 메서드를 실행하고 DocumentBatchWrite 객체를 생성합니다.

3. DocumentBatchWrite 객체 메서드를 사용하여 업로드하거나 삭제할 문서를 지정합니다.

4. DocumentBatchWrite.Execute 메서드를 호출하여 배치 작업을 실행합니다.

   이 문서 모델 API를 사용하면 일괄 처리의 작업을 얼마든지 지정할 수 있습니다. 그러나 DynamoDB는 배치 작업 수 및 배치 작업의 총 배치 크기를 제한합니다. 특정 제한에 대한 자세한 내용은 BatchWriteItem을 참조하십시오. 이 문서 모델 API가 배치 쓰기 요청이 허용된 쓰기 요청 수를 초과했거나 배치의 HTTP 페이로드 크기가 BatchWriteItem에서 허용하는 제한을 초과했음을 감지하면 배치를 여러 개의 작은 배치로 분할합니다. 또한 배치 쓰기에 대한 응답이 처리되지 않은 항목을 반환하면 문서 모델 API는 처리되지 않은 항목과 함께 다른 배치 요청을 자동으로 보냅니다.

다음 C# 코드 예제에서는 이전 단계를 설명합니다. 이 예제에서는 배치 쓰기 작업을 사용하여 책 항목 업로드 및 다른 책 항목 삭제와 같은 두 개의 쓰기를 수행합니다.

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();