翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# DynamoDB Mapper の使用を開始する
<a name="ddb-mapper-get-started"></a>

****  
**DynamoDB Mapper はデベロッパープレビューリリースです。機能は完了しておらず、変更される可能性があります。**

次のチュートリアルでは、DynamoDB Mapper の基本コンポーネントを紹介し、コードで使用する方法を示します。

## 依存関係を追加する
<a name="ddb-mapper-get-started-deps"></a>

Gradle プロジェクトで DynamoDB Mapper の使用を開始するには、プラグインと 2 つの依存関係を `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`テーブルに対する 2 つのオペレーションの例を示しています。

```
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)
```

前の 2 つのコード例は同等です。

### ページ分割されたレスポンスを使用する
<a name="ddb-mapper-gs-pagination"></a>

`query` や などの一部のオペレーションでは、1 回のレスポンスで返すには大きすぎる可能性のあるデータ収集を返`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) }
```