# .NET 객체 지속성 모델의 DynamoDBContext 클래스 `DynamoDBContext` 클래스는 Amazon DynamoDB 데이터베이스의 진입점입니다. 이 클래스는 DynamoDB로의 연결을 제공하며, 데이터를 다양한 테이블에 액세스하고 다양한 CRUD 작업을 수행하며 쿼리를 실행할 수 있게 합니다. `DynamoDBContext` 클래스는 다음과 같은 메서드를 제공합니다. **Topics** + [Create​MultiTable​BatchGet](#w2aac17b9c21c23c39b7) + [Create​MultiTable​BatchWrite](#w2aac17b9c21c23c39b9) + [CreateBatchGet](#w2aac17b9c21c23c39c11) + [CreateBatchWrite](#w2aac17b9c21c23c39c13) + [삭제](#w2aac17b9c21c23c39c15) + [Dispose](#w2aac17b9c21c23c39c17) + [Execute​Batch​Get](#w2aac17b9c21c23c39c19) + [Execute​Batch​Write](#w2aac17b9c21c23c39c21) + [FromDocument](#w2aac17b9c21c23c39c23) + [FromQuery](#w2aac17b9c21c23c39c25) + [FromScan](#w2aac17b9c21c23c39c27) + [Get​Target​Table](#w2aac17b9c21c23c39c29) + [Load](#w2aac17b9c21c23c39c31) + [쿼리](#w2aac17b9c21c23c39c33) + [Save](#w2aac17b9c21c23c39c35) + [스캔](#w2aac17b9c21c23c39c37) + [ToDocument](#w2aac17b9c21c23c39c39) + [DynamoDBContext에 대한 옵션 파라미터 지정](#OptionalConfigParams) ## Create​MultiTable​BatchGet 여러 개의 개별 `MultiTableBatchGet` 객체로 구성된 `BatchGet` 객체를 만듭니다. 이러한 `BatchGet` 객체 각각은 단일 DynamoDB 테이블에서 항목을 가져오는 데 사용됩니다. 테이블에서 항목을 검색하려면 `ExecuteBatchGet` 메서드를 사용하여 `MultiTableBatchGet` 객체를 파라미터로 전달합니다. ## Create​MultiTable​BatchWrite 여러 개의 개별 `MultiTableBatchWrite` 객체로 구성된 `BatchWrite` 객체를 만듭니다. 이러한 `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 문서 모델을 사용하여 작업](DotNetSDKMidLevel.md) 단원을 참조하세요. `Document` 항목 표시 정보를 포함하는 `doc`라는 이름의 `Forum` 객체가 있는 경우 (이 객체를 구성하는 방법은 이 주제의 후반부에 있는 `ToDocument` 메서드 설명을 참조하세요.) 다음 C\$1 코드 예제와 같이 `FromDocument`를 사용하여 `Forum`에서 `Document` 항목을 검색할 수 있습니다. **Example** ``` forum101 = context.FromDocument(101); ``` **참고** `Document` 객체가 `IEnumerable` 인터페이스를 구현하는 경우에는 `FromDocuments` 메서드를 대신 사용할 수 있습니다. 그러면 `Document`에서 모든 클래스 인스턴스를 반복적으로 처리할 수 있습니다. ## FromQuery `QueryOperationConfig` 객체에 정의된 쿼리 파라미터로 `Query` 작업을 실행합니다. **참고** 백그라운드에서 이 작업을 수행하려면 `FromQueryAsync` 메서드를 대신 사용하세요. ## FromScan `ScanOperationConfig` 객체에 정의된 스캔 파라미터로 `Scan` 작업을 실행합니다. **참고** 백그라운드에서 이 작업을 수행하려면 `FromScanAsync` 메서드를 대신 사용하세요. ## Get​Target​Table 지정된 유형에 대한 대상 테이블을 가져옵니다. 이는 임의 데이터를 DynamoDB 테이블로 매핑하기 위한 사용자 지정 변환기를 작성하고 사용자 지정 데이터 형식과 연결되는 테이블을 확인해야 할 때 유용합니다. ## Load 테이블에서 항목을 가져옵니다. 이 메서드에는 가져오려는 항목의 기본 키만 필요합니다. 기본적으로 DynamoDB는 최종적으로 일관된 값을 갖는 항목을 반환하기 때문입니다. 최종 일관성 모델에 대한 자세한 내용은 [DynamoDB 읽기 일관성](HowItWorks.ReadConsistency.md) 단원을 참조하세요. `Load` 또는 `LoadAsync` 메서드는 [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html) 작업을 직접 호출합니다. 이 작업을 수행하려면 테이블의 프라이머리 키를 지정해야 합니다. `GetItem`에서는 `IndexName` 파라미터를 무시하므로, 인덱스의 파티션 또는 정렬 키를 사용하여 항목을 로드할 수 없습니다. 따라서 테이블의 프라이머리 키를 사용하여 항목을 로드해야 합니다. **참고** 백그라운드에서 이 작업을 수행하려면 `LoadAsync` 메서드를 대신 사용하세요. `LoadAsync` 메서드를 사용하여 DynamoDB 테이블에서 상위 수준의 CRUD 작업을 수행하는 예제를 보려면 다음 예제를 참조하세요. ``` /// /// Shows how to perform high-level CRUD operations on an Amazon DynamoDB /// table. /// 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 { "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(bookId); // Update some properties. bookRetrieved.Isbn = "222-2222221001"; // Update existing authors list with the following values. bookRetrieved.BookAuthors = new List { " 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(bookId, new DynamoDBContextConfig { ConsistentRead = true, }); // Delete the book. await context.DeleteAsync(bookId); // Try to retrieve deleted book. It should return null. Book deletedBook = await context.LoadAsync(bookId, new DynamoDBContextConfig { ConsistentRead = true, }); if (deletedBook == null) { Console.WriteLine("Book is deleted"); } } } ``` ## 쿼리 입력하는 쿼리 파라미터를 기반으로 테이블을 쿼리합니다. 테이블에 복합 기본 키(파티션 키 및 정렬 키)가 있는 경우에만 테이블을 쿼리할 수 있습니다. 쿼리 시에는 파티션 키를 비롯하여 정렬 키에 적용되는 조건을 지정해야 합니다. DynamoDB의 `Reply` 테이블에 클라이언트 측 `Reply` 클래스가 매핑되어 있는 경우 다음 C\$1 코드 예제에서는 과거 15일 간 게시된 포럼 스레드 회신을 찾기 위해 `Reply` 테이블을 쿼리합니다. `Reply` 테이블에는 `Id` 파티션 키와 `ReplyDateTime` 정렬 키로 구성된 기본 키가 있습니다. **Example** ``` 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 latestReplies = context.Query(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate); ``` 이를 통해 `Reply` 객체 컬렉션이 반환됩니다. `Query` 메서드는 "지연 로딩된(lazy-loaded)" `IEnumerable` 컬렉션을 반환합니다. 즉, 처음에는 결과 페이지를 하나만 반환하고, 필요에 따라 서비스를 호출하여 다음 페이지를 반환합니다. 일치하는 항목을 모두 가져오려면 `IEnumerable`을 반복하기만 하면 됩니다. 테이블에 단순 기본 키(파티션 키)가 있는 경우에는 `Query` 메서드를 사용할 수 없습니다. 대신 `Load` 메서드를 사용하면 파티션 키를 입력하여 항목을 가져올 수 있습니다. **참고** 백그라운드에서 이 작업을 수행하려면 `QueryAsync` 메서드를 대신 사용하세요. ## Save 지정한 객체를 테이블에 저장합니다. 입력 객체에 지정된 기본 키가 테이블에 존재하지 않는 경우 메서드가 테이블에 새 항목을 추가합니다. 기본 키가 있는 경우 메서드가 기존 항목을 업데이트합니다. 낙관적 잠금이 구성된 경우 항목의 서버 측 버전과 클라이언트 측 버전이 일치하는 경우에만 업데이트가 성공합니다. 자세한 내용은 [DynamoDB 및 AWS SDK for .NET 객체 지속성 모델을 사용하여 낙관적 잠금 수행](DynamoDBContext.VersionSupport.md) 섹션을 참조하세요. **참고** 백그라운드에서 이 작업을 수행하려면 `SaveAsync` 메서드를 대신 사용하세요. ## 스캔 전체 테이블 스캔을 수행합니다. 스캔 조건을 지정하여 스캔 결과를 필터링할 수 있습니다. 스캔 조건은 테이블의 어느 속성 상에서든지 평가될 수 있습니다. DynamoDB의 `ProductCatalog` 테이블에 클라이언트 측 `Book` 클래스가 매핑되어 있는 경우 다음 C\$1 코드 예제에서는 테이블을 스캔하고 가격이 0보다 작은 책 항목만 반환합니다. **Example** ``` IEnumerable itemsWithWrongPrice = context.Scan( 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 문서 모델을 사용하여 작업](DotNetSDKMidLevel.md) 단원을 참조하세요. 샘플 `Forum` 테이블에 클라이언트 측 클래스가 매핑되어 있는 경우 다음 C\$1 코드 예제와 같이 `DynamoDBContext`를 사용하여 `Document` 테이블에서 항목을 `Forum` 객체로 얻을 수 있습니다. **Example** ``` DynamoDBContext context = new DynamoDBContext(client); Forum forum101 = context.Load(101); // Retrieve a forum by primary key. Document doc = context.ToDocument(forum101); ``` ## DynamoDBContext에 대한 옵션 파라미터 지정 객체 지속성 모델을 사용하는 경우, `DynamoDBContext`에 대하여 다음과 같은 선택적 파라미터를 지정할 수 있습니다. + **`ConsistentRead`** - `Load`, `Query` 또는 `Scan` 작업을 사용하여 데이터를 검색할 때 이 선택적 파라미터를 추가하여 데이터의 최신 값을 요청할 수 있습니다. + **`IgnoreNullValues`** - 이 파라미터는 `DynamoDBContext`에 `Save` 작업 동안 속성의 null 값을 무시하도록 지시합니다. 이 파라미터가 false이거나 설정되지 않은 경우 null 값은 특정 속성을 삭제하라는 지시로 해석됩니다. + **`SkipVersionCheck`** - 이 파라미터는 항목을 저장하거나 삭제할 때 `DynamoDBContext`에 버전을 비교하지 않도록 지시합니다. 버전 관리에 대한 자세한 내용은 [DynamoDB 및 AWS SDK for .NET 객체 지속성 모델을 사용하여 낙관적 잠금 수행](DynamoDBContext.VersionSupport.md) 섹션을 참조하십시오. + ** `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\$1 예제에서는 앞에 나온 선택적 파라미터 중 두 개인 `ConsistentRead` 및 `SkipVersionCheck`를 지정하여 새 `DynamoDBContext`를 생성합니다. **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true}); ``` `DynamoDBContext`에는 이 컨텍스트를 사용하여 보내는 각 요청과 함께 이러한 선택적 파라미터가 포함되어 있습니다. 이러한 파라미터를 `DynamoDBContext` 수준에 설정하는 대신 다음 C\$1 코드 예제와 같이 `DynamoDBContext`를 사용하여 실행하는 개별 작업에 대해 이러한 파라미터를 지정할 수 있습니다. 이 예제는 특정 책 항목을 로드합니다. `DynamoDBContext`의 `Load` 메서드는 선택적 파라미터인 `ConsistentRead` 및 `SkipVersionCheck`를 지정합니다. **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client); Book bookItem = context.Load(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true }); ``` 이 경우 `DynamoDBContext`에는 `Get` 요청을 보내는 경우에 한하여 이러한 파라미터가 포함됩니다.