本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

\$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 Mapper 使用 適用於 Kotlin 的 AWS SDK的 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)
```

先前的程式碼會使用 定義的結構描述，取得 中`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 類別，開發套件可以使用適用於 Gradle 的 DynamoDB Mapper 結構描述產生器外掛程式，在建置時間自動產生結構描述。當您使用結構描述產生器時，軟體開發套件會檢查您的類別來推斷結構描述，這會緩解手動定義結構描述時涉及的一些樣板。您可以使用其他[註釋](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 支援開發套件 上可用操作的子集`DynamoDbClient`。Mapper 操作的名稱與 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<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) }
```