本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 开始使用 DynamoDB 映射器
<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")
}
```

\$1 *<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 映射器使用的 DynamoDB 客户端与 D 适用于 Kotlin 的 AWS SDK ynamoDB 进行交互。创建映射器[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)
```

前面的代码引用了`DynamoDB`名为的表，`cars`其架构由定义`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 映射器架构生成器插件自动生成架构。当您使用架构生成器时，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 映射器支持软件开发工具包上可用操作的子集。`DynamoDbClient`映射器操作的名称与 SDK 客户端上的对应操作相同。许多映射器 request/response 成员与他们的 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) }
}
```

通常，对象流比*包含*对象的响应流对业务逻辑更有用。映射器提供了一种用于访问对象流的分页响应的扩展方法。例如，以下代码返回 a `Flow<Car>` 而不是前面`Flow<ScanResponse<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) }
```