DynamoDB Mapper の使用を開始する

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

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

依存関係を追加する

Gradle プロジェクトで DynamoDB Mapper の使用を開始するには、プラグインと 2 つの依存関係を build.gradle.kts ファイルに追加します。

（X.Y.Z リンクに移動して、利用可能な最新バージョンを確認できます）。

// build.gradle.kts
val sdkVersion: String = X.Y.Z

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 で最新リリースを確認してください。

注記

スキーマを手動で定義する場合は、これらの依存関係の一部はオプションです。依存関係の詳細と削減されたセットスキーマを手動で定義するについては、「」を参照してください。

マッパーを作成して使用する

DynamoDB Mapper は、 AWS SDK for Kotlin DynamoDB クライアントを使用して DynamoDB とやり取りします。次のコードスニペットに示すように、マッパーDynamoDbClientインスタンスを作成するときに、完全に設定されたインスタンスを指定する必要があります。

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し、それらを出力します。オペレーションの詳細については、以下で説明します。

クラス注釈を使用してスキーマを定義する

さまざまな Kotlin クラスの場合、SDK は Gradle 用の DynamoDB Mapper Schema Generator プラグインを使用して、ビルド時にスキーマを自動的に生成できます。スキーマジェネレーターを使用すると、SDK はクラスを検査してスキーマを推測します。これにより、スキーマの手動定義に関連するボイラープレートの一部が軽減されます。追加の注釈と設定を使用して、生成されるスキーマをカスタマイズできます。

注釈からスキーマを生成するには、まず でクラスに注釈を付け@DynamoDbItem、 @DynamoDbPartitionKeyと でキーに注釈を付けます@DynamoDbSortKey。次のコードは、注釈付き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自動的に生成される の拡張機能メソッドを利用して、テーブルインスタンスを取得することもできます。このアプローチを使用すると、スキーマを名前で参照する必要はありません。以下に示すように、自動生成されたgetCarsTable拡張メソッドはテーブルインスタンスへの参照を返します。

val carsTable = mapper.getCarsTable("cars")

詳細と例については、「注釈からスキーマを生成する」を参照してください。

呼び出しオペレーション

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 つのコード例は同等です。

ページ分割されたレスポンスを使用する

query や などの一部のオペレーションでは、1 回のレスポンスで返すには大きすぎる可能性のあるデータ収集を返scanすことができます。すべてのオブジェクトが処理されるようにするために、DynamoDB Mapper はページ分割メソッドを提供します。このメソッドは DynamoDB 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) }