.NET 객체 지속성 모델의 DynamoDBContext 클래스 - Amazon DynamoDB
Create​MultiTable​BatchGetCreate​MultiTable​BatchWriteCreateBatchGetCreateBatchWrite삭제DisposeExecute​Batch​GetExecute​Batch​WriteFromDocumentFromQueryFromScanGet​Target​TableLoadQuerySave 스캔ToDocumentDynamoDBContext에 대한 옵션 파라미터 지정

.NET 객체 지속성 모델의 DynamoDBContext 클래스

DynamoDBContext 클래스는 Amazon DynamoDB 데이터베이스의 진입점입니다. 이 클래스는 DynamoDB로의 연결을 제공하며, 데이터를 다양한 테이블에 액세스하고 다양한 CRUD 작업을 수행하며 쿼리를 실행할 수 있게 합니다. DynamoDBContext 클래스는 다음과 같은 메서드를 제공합니다.

Create​MultiTable​BatchGet

여러 개의 개별 BatchGet 객체로 구성된 MultiTableBatchGet 객체를 만듭니다. 이러한 BatchGet 객체 각각은 단일 DynamoDB 테이블에서 항목을 가져오는 데 사용됩니다.

테이블에서 항목을 검색하려면 ExecuteBatchGet 메서드를 사용하여 MultiTableBatchGet 객체를 파라미터로 전달합니다.

Create​MultiTable​BatchWrite

여러 개의 개별 BatchWrite 객체로 구성된 MultiTableBatchWrite 객체를 만듭니다. 이러한 BatchWrite 객체 각각은 단일 DynamoDB 테이블에서 항목을 쓰거나 삭제하는 데 사용됩니다.

테이블에 쓰려면 ExecuteBatchWrite 메서드를 사용하여 MultiTableBatchWrite 객체를 파라미터로 전달합니다.

CreateBatchGet

BatchGet 객체를 만들어 테이블에서 여러 개의 항목을 가져올 수 있습니다.

CreateBatchWrite

BatchWrite 객체를 만들어 여러 개의 항목을 테이블에 넣는 데 사용하거나 테이블에서 여러 개의 항목을 삭제하는 데 사용할 수 있습니다.

삭제

항목을 테이블에서 삭제합니다. 메서드에는 삭제하려는 항목의 기본 키가 필요합니다. 기본 키 값 또는 기본 키 값을 포함하는 클라이언트 측 객체 중 한 가지를 파라미터로 이 메서드에 제공할 수 있습니다.

  • 클라이언트 측 객체를 파라미터로 지정하고 낙관적 잠금을 활성화했다면, 클라이언트 측과 객체의 서버 쪽 버전이 일치해야만 삭제가 성공적으로 이루어집니다.

  • 기본 키 값만을 파라미터로 지정한 경우, 낙관적 잠금을 활성화했는지의 여부와 상관없이 삭제가 성공적으로 이루어집니다.

참고

백그라운드에서 이 작업을 수행하려면 DeleteAsync 메서드를 대신 사용하세요.

Dispose

관리되거나 관리되지 않는 리소스를 모두 일괄합니다.

Execute​Batch​Get

모든 BatchGet 객체를 MultiTableBatchGet에서 처리하여, 하나 또는 그 이상의 테이블에서 데이터를 읽습니다.

참고

백그라운드에서 이 작업을 수행하려면 ExecuteBatchGetAsync 메서드를 대신 사용하세요.

Execute​Batch​Write

모든 BatchWrite 객체를 MultiTableBatchWrite에서 처리하여, 하나 또는 그 이상의 테이블에 데이터를 쓰거나 삭제합니다.

참고

백그라운드에서 이 작업을 수행하려면 ExecuteBatchWriteAsync 메서드를 대신 사용하세요.

FromDocument

할당된 Document 인스턴스에서 FromDocument 메서드가 클라이언트 측 클래스의 인스턴스를 반환합니다.

이것은 문서 모델 클래스를 객체 지속성 모델과 함께 사용하여 데이터 작업을 수행할 때 유용합니다. AWS SDK for .NET에 의해 제공되는 문서 모델 클래스에 대한 자세한 내용은 DynamoDB에서 .NET 문서 모델을 사용하여 작업 단원을 참조하세요.

Forum 항목 표시 정보를 포함하는 doc라는 이름의 Document 객체가 있는 경우 (이 객체를 구성하는 방법은 이 주제의 후반부에 있는 ToDocument 메서드 설명을 참조하세요.) 다음 C# 코드 예제와 같이 FromDocument를 사용하여 Document에서 Forum 항목을 검색할 수 있습니다.

예 
forum101 = context.FromDocument<Forum>(101);
참고

Document 객체가 IEnumerable 인터페이스를 구현하는 경우에는 FromDocuments 메서드를 대신 사용할 수 있습니다. 그러면 Document에서 모든 클래스 인스턴스를 반복적으로 처리할 수 있습니다.

FromQuery

QueryOperationConfig 객체에 정의된 쿼리 파라미터로 Query 작업을 실행합니다.

참고

백그라운드에서 이 작업을 수행하려면 FromQueryAsync 메서드를 대신 사용하세요.

FromScan

ScanOperationConfig 객체에 정의된 스캔 파라미터로 Scan 작업을 실행합니다.

참고

백그라운드에서 이 작업을 수행하려면 FromScanAsync 메서드를 대신 사용하세요.

Get​Target​Table

지정된 유형에 대한 대상 테이블을 가져옵니다. 이는 임의 데이터를 DynamoDB 테이블로 매핑하기 위한 사용자 지정 변환기를 작성하고 사용자 지정 데이터 형식과 연결되는 테이블을 확인해야 할 때 유용합니다.

Load

테이블에서 항목을 가져옵니다. 이 메서드에는 가져오려는 항목의 기본 키만 필요합니다.

기본적으로 DynamoDB는 최종적으로 일관된 값을 갖는 항목을 반환하기 때문입니다. 최종 일관성 모델에 대한 자세한 내용은 DynamoDB 읽기 일관성 단원을 참조하세요.

Load 또는 LoadAsync 메서드는 GetItem 작업을 직접 호출합니다. 이 작업을 수행하려면 테이블의 프라이머리 키를 지정해야 합니다. GetItem에서는 IndexName 파라미터를 무시하므로, 인덱스의 파티션 또는 정렬 키를 사용하여 항목을 로드할 수 없습니다. 따라서 테이블의 프라이머리 키를 사용하여 항목을 로드해야 합니다.

참고

백그라운드에서 이 작업을 수행하려면 LoadAsync 메서드를 대신 사용하세요. LoadAsync 메서드를 사용하여 DynamoDB 테이블에서 상위 수준의 CRUD 작업을 수행하는 예제를 보려면 다음 예제를 참조하세요.


    /// <summary>
    /// Shows how to perform high-level CRUD operations on an Amazon DynamoDB
    /// table.
    /// </summary>
    public class HighLevelItemCrud
    {
        public static async Task Main()
        {
            var client = new AmazonDynamoDBClient();
            DynamoDBContext context = new DynamoDBContext(client);
            await PerformCRUDOperations(context);
        }

        public static async Task PerformCRUDOperations(IDynamoDBContext context)
        {
            int bookId = 1001; // Some unique value.
            Book myBook = new Book
            {
                Id = bookId,
                Title = "object persistence-AWS SDK for.NET SDK-Book 1001",
                Isbn = "111-1111111001",
                BookAuthors = new List<string> { "Author 1", "Author 2" },
            };

            // Save the book to the ProductCatalog table.
            await context.SaveAsync(myBook);

            // Retrieve the book from the ProductCatalog table.
            Book bookRetrieved = await context.LoadAsync<Book>(bookId);

            // Update some properties.
            bookRetrieved.Isbn = "222-2222221001";

            // Update existing authors list with the following values.
            bookRetrieved.BookAuthors = new List<string> { " Author 1", "Author x" };
            await context.SaveAsync(bookRetrieved);

            // Retrieve the updated book. This time, add the optional
            // ConsistentRead parameter using DynamoDBContextConfig object.
            await context.LoadAsync<Book>(bookId, new DynamoDBContextConfig
            {
                ConsistentRead = true,
            });

            // Delete the book.
            await context.DeleteAsync<Book>(bookId);

            // Try to retrieve deleted book. It should return null.
            Book deletedBook = await context.LoadAsync<Book>(bookId, new DynamoDBContextConfig
            {
                ConsistentRead = true,
            });

            if (deletedBook == null)
            {
                Console.WriteLine("Book is deleted");
            }
        }
    }

Query

입력하는 쿼리 파라미터를 기반으로 테이블을 쿼리합니다.

테이블에 복합 기본 키(파티션 키 및 정렬 키)가 있는 경우에만 테이블을 쿼리할 수 있습니다. 쿼리 시에는 파티션 키를 비롯하여 정렬 키에 적용되는 조건을 지정해야 합니다.

DynamoDB의 Reply 테이블에 클라이언트 측 Reply 클래스가 매핑되어 있는 경우 다음 C# 코드 예제에서는 과거 15일 간 게시된 포럼 스레드 회신을 찾기 위해 Reply 테이블을 쿼리합니다. Reply 테이블에는 Id 파티션 키와 ReplyDateTime 정렬 키로 구성된 기본 키가 있습니다.

예 
DynamoDBContext context = new DynamoDBContext(client);

string replyId = "DynamoDB#DynamoDB Thread 1"; //Partition key
DateTime twoWeeksAgoDate = DateTime.UtcNow.Subtract(new TimeSpan(14, 0, 0, 0)); // Date to compare.
IEnumerable<Reply> latestReplies = context.Query<Reply>(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate);

이를 통해 Reply 객체 컬렉션이 반환됩니다.

Query 메서드는 "지연 로딩된(lazy-loaded)" IEnumerable 컬렉션을 반환합니다. 즉, 처음에는 결과 페이지를 하나만 반환하고, 필요에 따라 서비스를 호출하여 다음 페이지를 반환합니다. 일치하는 항목을 모두 가져오려면 IEnumerable을 반복하기만 하면 됩니다.

테이블에 단순 기본 키(파티션 키)가 있는 경우에는 Query 메서드를 사용할 수 없습니다. 대신 Load 메서드를 사용하면 파티션 키를 입력하여 항목을 가져올 수 있습니다.

참고

백그라운드에서 이 작업을 수행하려면 QueryAsync 메서드를 대신 사용하세요.

Save

지정한 객체를 테이블에 저장합니다. 입력 객체에 지정된 기본 키가 테이블에 존재하지 않는 경우 메서드가 테이블에 새 항목을 추가합니다. 기본 키가 있는 경우 메서드가 기존 항목을 업데이트합니다.

낙관적 잠금이 구성된 경우 항목의 서버 측 버전과 클라이언트 측 버전이 일치하는 경우에만 업데이트가 성공합니다. 자세한 내용은 DynamoDB 및 AWS SDK for .NET 객체 지속성 모델을 사용하여 낙관적 잠금 수행 단원을 참조하십시오.

참고

백그라운드에서 이 작업을 수행하려면 SaveAsync 메서드를 대신 사용하세요.

스캔

전체 테이블 스캔을 수행합니다.

스캔 조건을 지정하여 스캔 결과를 필터링할 수 있습니다. 스캔 조건은 테이블의 어느 속성 상에서든지 평가될 수 있습니다. DynamoDB의 ProductCatalog 테이블에 클라이언트 측 Book 클래스가 매핑되어 있는 경우 다음 C# 코드 예제에서는 테이블을 스캔하고 가격이 0보다 작은 책 항목만 반환합니다.

예 
IEnumerable<Book> itemsWithWrongPrice = context.Scan<Book>(
                    new ScanCondition("Price", ScanOperator.LessThan, price),
                    new ScanCondition("ProductCategory", ScanOperator.Equal, "Book")
      );

Scan 메서드는 "지연 로딩된(lazy-loaded)" IEnumerable 컬렉션을 반환합니다. 즉, 처음에는 결과 페이지를 하나만 반환하고, 필요에 따라 서비스를 호출하여 다음 페이지를 반환합니다. 일치하는 항목을 모두 가져오려면 IEnumerable을 반복하기만 하면 됩니다.

성능 문제 때문에 테이블 스캔을 피하고 테이블을 쿼리해야 합니다.

참고

백그라운드에서 이 작업을 수행하려면 ScanAsync 메서드를 대신 사용하세요.

ToDocument

클래스 인스턴스에서 Document 문서 모델 클래스의 인스턴스가 반환됩니다.

이것은 문서 모델 클래스를 객체 지속성 모델과 함께 사용하여 데이터 작업을 수행할 때 유용합니다. AWS SDK for .NET에 의해 제공되는 문서 모델 클래스에 대한 자세한 내용은 DynamoDB에서 .NET 문서 모델을 사용하여 작업 단원을 참조하세요.

샘플 Forum 테이블에 클라이언트 측 클래스가 매핑되어 있는 경우 다음 C# 코드 예제와 같이 DynamoDBContext를 사용하여 Forum 테이블에서 항목을 Document 객체로 얻을 수 있습니다.

예 
DynamoDBContext context = new DynamoDBContext(client);

Forum forum101 = context.Load<Forum>(101); // Retrieve a forum by primary key.
Document doc = context.ToDocument<Forum>(forum101);

DynamoDBContext에 대한 옵션 파라미터 지정

객체 지속성 모델을 사용하는 경우, DynamoDBContext에 대하여 다음과 같은 선택적 파라미터를 지정할 수 있습니다.

  • ConsistentRead - Load, Query 또는 Scan 작업을 사용하여 데이터를 검색할 때 이 선택적 파라미터를 추가하여 데이터의 최신 값을 요청할 수 있습니다.

  • IgnoreNullValues - 이 파라미터는 DynamoDBContext에 Save 작업 동안 속성의 null 값을 무시하도록 지시합니다. 이 파라미터가 false이거나 설정되지 않은 경우 null 값은 특정 속성을 삭제하라는 지시로 해석됩니다.

  • SkipVersionCheck - 이 파라미터는 항목을 저장하거나 삭제할 때 DynamoDBContext에 버전을 비교하지 않도록 지시합니다. 버전 관리에 대한 자세한 내용은 DynamoDB 및 AWS SDK for .NET 객체 지속성 모델을 사용하여 낙관적 잠금 수행 섹션을 참조하십시오.

  • TableNamePrefix - 모든 테이블 이름에서 특정 문자열을 접두사로 사용합니다. 이 파라미터가 null이거나 설정되지 않은 경우, 어떤 접두사도 사용되지 않습니다.

  • DynamoDBEntryConversion - 클라이언트가 사용하는 변환 스키마를 지정합니다. 이 파라미터를 버전 V1 또는 V2로 설정할 수 있습니다. 기본 버전은 V1입니다.

    설정한 버전에 따라 이 파라미터의 동작이 달라집니다. 예:

    • V1에서는 bool 데이터 형식이 N 숫자 형식으로 변환됩니다. 여기서 0은 false, 1은 true를 나타냅니다. V2에서는 bool이 BOOL로 변환됩니다.

    • V2에서는 목록과 배열이 HashSet과 함께 그룹화되지 않습니다. 숫자로 구성된 목록과 배열, 문자열 기반 형식, 이진 기반 형식은 L(목록) 형식으로 변환됩니다. 이 형식은 목록을 업데이트하기 위해 빈 상태로 보낼 수 있습니다. 이는 빈 목록이 유선으로 전송되지 않는 V1과는 다릅니다.

      V1에서는 목록, HashSet 및 배열과 같은 컬렉션 형식이 동일하게 취급됩니다. 숫자 목록, HashSet 및 배열은 NS(숫자 집합) 형식으로 변환됩니다.

    다음 예제에서는 변환 스키마 버전을 V2로 설정하여 .NET 형식과 DynamoDB 데이터 형식 간의 변환 동작을 변경합니다.

    var config = new DynamoDBContextConfig
{
    Conversion = DynamoDBEntryConversion.V2
};
var contextV2 = new DynamoDBContext(client, config);

다음 C# 예제에서는 앞에 나온 선택적 파라미터 중 두 개인 ConsistentRead 및 SkipVersionCheck를 지정하여 새 DynamoDBContext를 생성합니다.

예 
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
...
DynamoDBContext context =
       new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true});

DynamoDBContext에는 이 컨텍스트를 사용하여 보내는 각 요청과 함께 이러한 선택적 파라미터가 포함되어 있습니다.

이러한 파라미터를 DynamoDBContext 수준에 설정하는 대신 다음 C# 코드 예제와 같이 DynamoDBContext를 사용하여 실행하는 개별 작업에 대해 이러한 파라미터를 지정할 수 있습니다. 이 예제는 특정 책 항목을 로드합니다. DynamoDBContext의 Load 메서드는 선택적 파라미터인 ConsistentRead 및 SkipVersionCheck를 지정합니다.

예 
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
...
DynamoDBContext context = new DynamoDBContext(client);
Book bookItem = context.Load<Book>(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true });

이 경우 DynamoDBContext에는 Get 요청을 보내는 경우에 한하여 이러한 파라미터가 포함됩니다.