기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# DynamoDB Mapper 시작하기
<a name="ddb-mapper-get-started"></a>

****  
**DynamoDB Mapper는 개발자 미리 보기 릴리스입니다. 기능이 완전하지 않으며 변경될 수 있습니다.**

다음 자습서에서는 DynamoDB Mapper의 기본 구성 요소를 소개하고 코드에서 이를 사용하는 방법을 보여줍니다.

## 종속성 추가
<a name="ddb-mapper-get-started-deps"></a>

Gradle 프로젝트에서 DynamoDB Mapper 작업을 시작하려면 `build.gradle.kts` 파일에 플러그인과 두 개의 종속성을 추가합니다.

({{X.Y.Z}} 링크로 이동하여 사용 가능한 최신 버전을 볼 수 있습니다.)

```
// build.gradle.kts
val sdkVersion: String = [https://github.com/awslabs/aws-sdk-kotlin/releases/latest](https://github.com/awslabs/aws-sdk-kotlin/releases/latest)

plugins {
    id("aws.sdk.kotlin.hll.dynamodbmapper.schema.generator") version "$sdkVersion-beta" // For the Developer Preview, use the beta version of the latest SDK.
}

dependencies {
    implementation("aws.sdk.kotlin:dynamodb-mapper:$sdkVersion-beta")
    implementation("aws.sdk.kotlin:dynamodb-mapper-annotations:$sdkVersion-beta")
}
```

\*{{<Version>}}을 SDK의 최신 릴리스로 바꿉니다. SDK의 최신 버전을 찾으려면 [ GitHub에서 최신 릴리스를](https://github.com/awslabs/aws-sdk-kotlin/releases/latest) 확인하세요.

**참고**  
스키마를 수동으로 정의하려는 경우 이러한 종속성 중 일부는 선택 사항입니다. [수동으로 스키마 정의](ddb-mapper-code-schemas.md) 자세한 내용과 감소된 종속성 세트는 단원을 참조하십시오.

## 매퍼 생성 및 사용
<a name="ddb-mapper-get-started-mapper"></a>

DynamoDB Mapper는 AWS SDK for Kotlin의 DynamoDB 클라이언트를 사용하여 DynamoDB와 상호 작용합니다. 다음 코드 조각과 같이 매퍼 [https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb/aws.sdk.kotlin.services.dynamodb/-dynamo-db-client/index.html](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb/aws.sdk.kotlin.services.dynamodb/-dynamo-db-client/index.html) 인스턴스를 생성할 때 완전히 구성된 인스턴스를 제공해야 합니다.

```
import aws.sdk.kotlin.hll.dynamodbmapper.DynamoDbMapper
import aws.sdk.kotlin.services.dynamodb.DynamoDbClient

val client = DynamoDbClient.fromEnvironment()
val mapper = DynamoDbMapper(client)
```

**참고**  
`DynamoDbMapper`는 테이블 생성 작업을 지원하지 않습니다. 를 사용하여 테이블`DynamoDbClient`을 생성합니다.

매퍼 인스턴스를 생성한 후에는 다음과 같이 매퍼 인스턴스를 사용하여 테이블 인스턴스를 가져올 수 있습니다.

```
val carsTable = mapper.getTable("cars", CarSchema)
```

이전 코드는에서 정의한 스키마`cars`를 사용하여 `DynamoDB`라는의 테이블에 대한 참조를 가져옵니다`CarSchema`(아래에서 스키마 설명). 테이블 인스턴스를 생성한 후 테이블 인스턴스에 대해 작업을 수행할 수 있습니다. 다음 코드 조각은 `cars` 테이블에 대한 두 가지 예제 작업을 보여줍니다.

```
carsTable.putItem {
    item = Car(make = "Ford", model = "Model T", ...)
}

carsTable
   .queryPaginated {
        keyCondition = KeyFilter(partitionKey = "Peugeot")
   }
   .items()
   .collect { car -> println(car) }
```

이전 코드는 `cars` 테이블에 새 항목을 생성합니다. 이 코드는 클래스를 사용하여 `Car` 인스턴스를 인라인으로 생성합니다.이 `Car` 클래스의 정의는 아래와 같습니다. 그런 다음 코드는 `cars` 테이블에 파티션 키가 인 항목을 쿼리`Peugeot`하고 인쇄합니다. 작업은 [아래에 자세히 설명되어](#ddb-mapper-gs-invoke-ops) 있습니다.

## 클래스 주석을 사용하여 스키마 정의
<a name="ddb-mapper-gs-anno-schema-def"></a>

다양한 Kotlin 클래스의 경우 SDK는 Gradle용 DynamoDB Mapper Schema Generator 플러그인을 사용하여 빌드 시 스키마를 자동으로 생성할 수 있습니다. 스키마 생성기를 사용하면 SDK가 클래스를 검사하여 스키마를 유추하여 스키마를 수동으로 정의하는 데 수반되는 일부 표준 문안을 완화합니다. 추가 [주석 및 구성을 사용하여 생성되는 스키마를 사용자 지정할 수 있습니다](ddb-mapper-anno-schema-gen.md#ddb-mapper-anno-schema-gen-annotate). [플러그인 구성](ddb-mapper-anno-schema-gen.md#ddb-mapper-anno-schema-gen-conf-plugin) 

주석에서 스키마를 생성하려면 먼저 클래스에 및 로 주석을 달`@[DynamoDbItem](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)`고 모든 키에 `@[DynamoDbPartitionKey](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-partition-key/index.html)` 주석을 달아야 합니다`@[DynamoDbSortKey](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-sort-key/index.html)`. 다음 코드는 주석이 달린 `Car` 클래스를 보여줍니다.

```
// The annotations used in the Car class are used by the plugin to generate a schema.
@DynamoDbItem
data class Car(
    @DynamoDbPartitionKey
    val make: String,
    
    @DynamoDbSortKey
    val model: String,
    
    val initialYear: Int
)
```

빌드 후 자동으로 생성된를 참조할 수 있습니다`CarSchema`. 매퍼의 `getTable` 메서드에 있는 참조를 사용하여 다음과 같이 테이블 인스턴스를 가져올 수 있습니다.

```
import aws.sdk.kotlin.hll.dynamodbmapper.generatedschemas.CarSchema

// `CarSchema` is generated at build time.
val carsTable = mapper.getTable("cars", CarSchema)
```

또는 빌드 시 `[DynamoDbMapper](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-mapper/index.html)` 자동으로 생성되는의 확장 방법을 활용하여 테이블 인스턴스를 가져올 수 있습니다. 이 접근 방식을 사용하면 스키마를 이름으로 참조할 필요가 없습니다. 다음 그림과 같이 자동으로 생성된 `getCarsTable` 확장 메서드는 테이블 인스턴스에 대한 참조를 반환합니다.

```
val carsTable = mapper.getCarsTable("cars")
```

자세한 내용과 예는 [주석에서 스키마 생성](ddb-mapper-anno-schema-gen.md) 단원을 참조하십시오.

## 작업 호출
<a name="ddb-mapper-gs-invoke-ops"></a>

DynamoDB Mapper는 SDK의에서 사용할 수 있는 작업의 하위 집합을 지원합니다`DynamoDbClient`. 매퍼 작업의 이름은 SDK 클라이언트의 해당 작업과 동일합니다. 많은 매퍼 요청/응답 멤버는 SDK 클라이언트 멤버와 동일하지만 일부는 이름 변경, 다시 입력 또는 완전히 삭제되었습니다.

다음과 같이 DSL 구문을 사용하여 테이블 인스턴스에서 작업을 호출합니다.

```
import aws.sdk.kotlin.hll.dynamodbmapper.operations.putItem
import aws.sdk.kotlin.services.dynamodb.model.ReturnConsumedCapacity

val putResponse = carsTable.putItem {
    item = Car(make = "Ford", model = "Model T", ...)
    returnConsumedCapacity = ReturnConsumedCapacity.Total
}

println(putResponse.consumedCapacity)
```

명시적 요청 객체를 사용하여 작업을 호출할 수도 있습니다.

```
import aws.sdk.kotlin.hll.dynamodbmapper.operations.PutItemRequest
import aws.sdk.kotlin.services.dynamodb.model.ReturnConsumedCapacity

val putRequest = PutItemRequest<Car> {
    item = Car(make = "Ford", model = "Model T", ...)
    returnConsumedCapacity = ReturnConsumedCapacity.Total
}

val putResponse = carsTable.putItem(putRequest)
println(putResponse.consumedCapacity)
```

이전 두 코드 예제는 동일합니다.

### 페이지가 매겨진 응답 작업
<a name="ddb-mapper-gs-pagination"></a>

`query` 및와 같은 일부 작업은 너무 커서 단일 응답으로 반환할 수 없는 데이터 컬렉션을 반환할 수 `scan` 있습니다. 모든 객체가 처리되도록 DynamoDB Mapper는 DynamoDB를 즉시 호출하지 않고 대신 다음과 같은 작업 응답 유형의 `[Flow](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/)`를 반환하는 페이지 매김 메`Flow<ScanResponse<Car>>`서드를 제공합니다.

```
import aws.sdk.kotlin.hll.dynamodbmapper.operations.scanPaginated

val scanResponseFlow = carsTable.scanPaginated { }

scanResponseFlow.collect { response ->
    val items = response.items.orEmpty()
    println("Found page with ${items.size} items:")
    
    items.forEach { car -> println(car) }
}
```

종종 객체 흐름은 객체가 *포함된* 응답 흐름보다 비즈니스 로직에 더 유용합니다. 매퍼는 객체 흐름에 액세스하기 위해 페이지가 매겨진 응답에 대한 확장 메서드를 제공합니다. 예를 들어 다음 코드는 앞에서 설명한 `Flow<ScanResponse<Car>>` 것처럼 `Flow<Car>` 대신를 반환합니다.

```
import aws.sdk.kotlin.hll.dynamodbmapper.operations.items
import aws.sdk.kotlin.hll.dynamodbmapper.operations.scanPaginated

val carFlow = carsTable
    .scanPaginated { }
    .items()

carFlow.collect { car -> println(car) }
```