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

# 注釈からスキーマを生成する
<a name="ddb-mapper-anno-schema-gen"></a>

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

DynamoDB Mapper は、Kotlin クラスと DynamoDB 項目間のマッピングを定義するスキーマに依存します。Kotlin クラスは、スキーマジェネレーター Gradle プラグインを使用してスキーマの作成を駆動できます。

## プラグインを適用する
<a name="ddb-mapper-anno-schema-gen-plugin"></a>

クラスのコード生成スキーマを開始するには、アプリケーションのビルドスクリプトにプラグインを適用し、注釈モジュールへの依存関係を追加します。次の Gradle スクリプトスニペットは、コード生成に必要なセットアップを示しています。

({{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")
}
```

## プラグインを設定する
<a name="ddb-mapper-anno-schema-gen-conf-plugin"></a>

プラグインには、ビルドスクリプトで`dynamoDbMapper { ... }`プラグイン拡張機能を使用して適用できる多数の設定オプションが用意されています。


| オプション | オプションの説明 | 値 | 
| --- | --- | --- | 
| generateBuilderClasses | で注釈が付けられたクラスに対して DSL スタイルのビルダークラスを生成するかどうかを制御します `@DynamoDbItem` | `WHEN_REQUIRED` (デフォルト): ビルダークラスは、パブリックミュータブルメンバーのみで構成され、ゼロ引数コンストラクタを持つクラスでは生成されません<br />`ALWAYS`: ビルダークラスは常に生成されます | 
| visibility | 生成されたクラスの可視性を制御します | `PUBLIC` (デフォルト)<br />`INTERNAL` | 
| destinationPackage | 生成されたクラスのパッケージ名を指定します。 | `RELATIVE` (デフォルト): スキーマクラスは、注釈付きクラスを基準にしたサブパッケージで生成されます。デフォルトでは、サブパッケージの名前は `dynamodbmapper.generatedschemas` で、これは文字列パラメータを渡すことで設定できます。<br />`ABSOLUTE`: スキーマクラスは、アプリケーションのルートを基準にした絶対パッケージで生成されます。デフォルトでは、パッケージの名前は で`aws.sdk.kotlin.hll.dynamodbmapper.generatedschemas`、これは文字列パラメータを渡すことで設定できます。 | 
| generateGetTableExtension | `DynamoDbMapper.get${CLASS_NAME}Table` 拡張メソッドを生成するかどうかを制御します | `true` (デフォルト)<br />`false` | 

**Example コード生成プラグイン設定の例**  
次の例では、生成されたスキーマの送信先パッケージと可視性を設定します。  

```
// build.gradle.kts

import aws.sdk.kotlin.hll.dynamodbmapper.codegen.annotations.DestinationPackage
import aws.sdk.kotlin.hll.dynamodbmapper.codegen.annotations.Visibility
import aws.smithy.kotlin.runtime.ExperimentalApi

@OptIn(ExperimentalApi::class)
dynamoDbMapper {
    destinationPackage = DestinationPackage.RELATIVE("my.configured.package")
    visibility = Visibility.INTERNAL
}
```

## クラスに注釈を付ける
<a name="ddb-mapper-anno-schema-gen-annotate"></a>

スキーマジェネレーターは、クラス注釈を検索して、スキーマを生成するクラスを決定します。スキーマの生成をオプトインするには、 でクラスに注釈を付けます`@[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)`。

次のクラス定義は、スキーマ生成に必要な最小限の注釈を示しています。

**Example**  

```
@DynamoDbItem
data class Employee(
    @DynamoDbPartitionKey
    val id: Int,
    
    val name: String,
    val role: String,
)
```

### クラス注釈
<a name="ddb-mapper-anno-schema-gen-class-annos"></a>

スキーマの生成を制御するために、クラスには次の注釈が適用されます。
+ `@DynamoDbItem`: このクラス/インターフェイスがテーブル内の項目タイプを記述するように指定します。このタイプのすべてのパブリックプロパティは、明示的に無視されない限り、属性にマッピングされます。存在する場合、このクラスに対してスキーマが生成されます。
  + `converterName`: スキーマジェネレータプラグインによって作成されたスキーマではなく、カスタムスキーマを使用する必要があることを示すオプションのパラメータ。これはカスタム`ItemConverter`クラスの完全修飾名です。このセクションでは、カスタムスキーマを作成して使用する例[カスタム項目コンバーターを定義する](#ddb-mapper-anno-schema-custom)を示します。

### プロパティ注釈
<a name="ddb-mapper-anno-schema-gen-prop-annos"></a>

次の注釈をクラスプロパティに適用して、スキーマの生成を制御できます。
+ `@[https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/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)`: 項目のオプションのソートキーを指定します。
+ `@[DynamoDbIgnore](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-ignore/index.html)`: このクラスプロパティを DynamoDB Mapper によって Item 属性との間で変換しないように指定します。
+ `@[DynamoDbAttribute](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-attribute/index.html)`: このクラスプロパティのオプションカスタム属性名を指定します。

## カスタム項目コンバーターを定義する
<a name="ddb-mapper-anno-schema-custom"></a>

場合によっては、 クラスのカスタム項目コンバーターを定義できます。その理由の 1 つは、クラスがスキーマジェネレータプラグインでサポートされていないタイプを使用する場合です。例として、次のバージョンの `Employee` クラスを使用します。

```
import kotlin.uuid.Uuid

@DynamoDbItem
data class Employee(
    @DynamoDbPartitionKey
    var id: Int,
    
    var name: String,
    var role: String,
    var workstationId: Uuid
)
```

`Employee` クラスは、現在スキーマジェネレーターでサポートされていない `kotlin.uuid.Uuid`タイプを使用するようになりました。スキーマの生成が失敗し、エラー が発生します`Unsupported attribute type TypeRef(pkg=kotlin.uuid, shortName=Uuid, genericArgs=[], nullable=false)`。このエラーは、プラグインがこのクラスの項目コンバータを生成できないことを示します。したがって、独自の を記述する必要があります。

これを行うには、 クラス`[ItemConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.items/-item-converter/index.html)`に を実装し、新しい項目コンバータの完全修飾名を指定して`@DynamoDbItem`クラス注釈を変更します。

まず、 `kotlin.uuid.Uuid` クラス`[ValueConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.values/-value-converter/index.html)`に を実装します。

```
import aws.sdk.kotlin.hll.dynamodbmapper.values.ValueConverter
import aws.sdk.kotlin.services.dynamodb.model.AttributeValue
import kotlin.uuid.Uuid

public val UuidValueConverter = object : ValueConverter<Uuid> {
    override fun convertFrom(to: AttributeValue): Uuid = 
        Uuid.parseHex(to.asS())
        
    override fun convertTo(from: Uuid): AttributeValue = 
        AttributeValue.S(from.toHexString())
}
```

次に、 `Employee` クラス`ItemConverter`に を実装します。は、「workstationId」の属性記述子でこの新しい値コンバータ`ItemConverter`を使用します。

```
import aws.sdk.kotlin.hll.dynamodbmapper.items.AttributeDescriptor
import aws.sdk.kotlin.hll.dynamodbmapper.items.ItemConverter
import aws.sdk.kotlin.hll.dynamodbmapper.items.SimpleItemConverter
import aws.sdk.kotlin.hll.dynamodbmapper.values.scalars.IntConverter
import aws.sdk.kotlin.hll.dynamodbmapper.values.scalars.StringConverter

public object MyEmployeeConverter : ItemConverter<Employee> by SimpleItemConverter(
    builderFactory = { Employee() },
    build = { this },
    descriptors = arrayOf(
        AttributeDescriptor(
            "id",
            Employee::id,
            Employee::id::set,
            IntConverter,
        ),
        AttributeDescriptor(
            "name",
            Employee::name,
            Employee::name::set,
            StringConverter,
        ),
        AttributeDescriptor(
            "role",
            Employee::role,
            Employee::role::set,
            StringConverter
        ),
        AttributeDescriptor(
            "workstationId",
            Employee::workstationId,
            Employee::workstationId::set,
            UuidValueConverter
        )
    ),
)
```

項目コンバーターを定義したら、 クラスに適用できます。以下に示すように、完全修飾クラス名を指定することで、項目コンバータを参照するように`@[DynamoDbItem](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)`注釈を更新します。

```
import kotlin.uuid.Uuid

@DynamoDbItem("my.custom.item.converter.MyEmployeeConverter")
data class Employee(
    @DynamoDbPartitionKey
    var id: Int,
    
    var name: String,
    var role: String,
    var workstationId: Uuid
)
```

最後に、DynamoDB Mapper で クラスの使用を開始できます。