Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Commencez à utiliser DynamoDB Mapper
<a name="ddb-mapper-get-started"></a>

****  
**DynamoDB Mapper est une version préliminaire pour les développeurs. Les fonctionnalités ne sont pas complètes et sont susceptibles d'être modifiées.**

Le didacticiel suivant présente les composants de base de DynamoDB Mapper et montre comment les utiliser dans votre code.

## Ajouter des dépendances
<a name="ddb-mapper-get-started-deps"></a>

Pour commencer à utiliser DynamoDB Mapper dans votre projet Gradle, ajoutez un plugin et deux dépendances à votre fichier. `build.gradle.kts`

(Vous pouvez accéder au *X.Y.Z* lien pour voir la dernière version disponible.)

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

\$1Remplacez *<Version>* par la dernière version du SDK. Pour trouver la dernière version du SDK, consultez la [dernière version sur GitHub](https://github.com/awslabs/aws-sdk-kotlin/releases/latest).

**Note**  
Certaines de ces dépendances sont facultatives si vous prévoyez de définir des schémas manuellement. Consultez [Définition manuelle de schémas](ddb-mapper-code-schemas.md) pour plus d'informations et pour découvrir l'ensemble réduit de dépendances.

## Création et utilisation d'un mappeur
<a name="ddb-mapper-get-started-mapper"></a>

Le mappeur DynamoDB utilise le client DynamoDB pour AWS SDK pour Kotlin interagir avec DynamoDB. Vous devez fournir une instance entièrement configurée lorsque vous créez une [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)instance de mappeur, comme indiqué dans l'extrait de code suivant :

```
import aws.sdk.kotlin.hll.dynamodbmapper.DynamoDbMapper
import aws.sdk.kotlin.services.dynamodb.DynamoDbClient

val client = DynamoDbClient.fromEnvironment()
val mapper = DynamoDbMapper(client)
```

**Note**  
`DynamoDbMapper`ne prend pas en charge les opérations de création de tables. Utilisez le `DynamoDbClient` pour créer des tables.

Après avoir créé l'instance du mappeur, vous pouvez l'utiliser pour obtenir l'instance de table comme indiqué ci-dessous :

```
val carsTable = mapper.getTable("cars", CarSchema)
```

Le code précédent obtient une référence à une table `DynamoDB` nommée `cars` avec un schéma défini par `CarSchema` (nous discutons des schémas ci-dessous). Après avoir créé une instance de table, vous pouvez effectuer des opérations sur celle-ci. L'extrait de code suivant montre deux exemples d'opérations sur la `cars` table :

```
carsTable.putItem {
    item = Car(make = "Ford", model = "Model T", ...)
}

carsTable
   .queryPaginated {
        keyCondition = KeyFilter(partitionKey = "Peugeot")
   }
   .items()
   .collect { car -> println(car) }
```

Le code précédent crée un nouvel élément dans le `cars` tableau. Le code crée une `Car` instance en ligne à l'aide de la `Car` classe, dont la définition est présentée ci-dessous. Ensuite, le code interroge la `cars` table pour les éléments dont la clé de partition est la clé `Peugeot` et les imprime. Les opérations sont [décrites plus en détail ci-dessous](#ddb-mapper-gs-invoke-ops).

## Définir un schéma avec des annotations de classe
<a name="ddb-mapper-gs-anno-schema-def"></a>

Pour diverses classes Kotlin, le SDK peut générer automatiquement des schémas au moment de la construction à l'aide du plugin DynamoDB Mapper Schema Generator pour Gradle. Lorsque vous utilisez le générateur de schéma, le SDK inspecte vos classes pour en déduire le schéma, ce qui simplifie en partie la complexité liée à la définition manuelle des schémas. Vous pouvez personnaliser le schéma généré à l'aide d'[annotations](ddb-mapper-anno-schema-gen.md#ddb-mapper-anno-schema-gen-annotate) et de [configurations](ddb-mapper-anno-schema-gen.md#ddb-mapper-anno-schema-gen-conf-plugin) supplémentaires.

Pour générer un schéma à partir d'annotations, commencez par annoter vos classes avec `@[DynamoDbItem](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)` et toutes les touches. `@[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)` Le code suivant montre la `Car` classe annotée :

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

Après la construction, vous pouvez vous référer à la génération automatique`CarSchema`. Vous pouvez utiliser la référence dans la `getTable` méthode du mappeur pour obtenir une instance de table, comme indiqué ci-dessous :

```
import aws.sdk.kotlin.hll.dynamodbmapper.generatedschemas.CarSchema

// `CarSchema` is generated at build time.
val carsTable = mapper.getTable("cars", CarSchema)
```

Vous pouvez également obtenir l'instance de table en tirant parti d'une méthode d'extension générée automatiquement au moment de la construction. `[DynamoDbMapper](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-mapper/index.html)` En utilisant cette approche, vous n'avez pas besoin de faire référence au schéma par son nom. Comme indiqué ci-dessous, la méthode d'`getCarsTable`extension générée automatiquement renvoie une référence à l'instance de table :

```
val carsTable = mapper.getCarsTable("cars")
```

Pour obtenir des détails et des exemples, consultez [Génération d'un schéma à partir d'annotations](ddb-mapper-anno-schema-gen.md).

## Opérations d'appel
<a name="ddb-mapper-gs-invoke-ops"></a>

DynamoDB Mapper prend en charge un sous-ensemble des opérations disponibles sur les SDK. `DynamoDbClient` Les opérations de mappage portent le même nom que leurs homologues sur le client SDK. De nombreux request/response membres du mappeur sont identiques à leurs homologues clients du SDK, bien que certains aient été renommés, retapés ou complètement supprimés.

Vous invoquez une opération sur une instance de table à l'aide d'une syntaxe DSL, comme illustré ci-dessous :

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

Vous pouvez également invoquer une opération en utilisant un objet de requête explicite :

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

Les deux exemples de code précédents sont équivalents.

### Travailler avec des réponses paginées
<a name="ddb-mapper-gs-pagination"></a>

Certaines opérations, comme `query` et `scan` peuvent renvoyer des ensembles de données qui peuvent être trop volumineux pour être renvoyés en une seule réponse. Pour garantir le traitement de tous les objets, DynamoDB Mapper fournit des méthodes de pagination qui n'appellent pas DynamoDB immédiatement, mais renvoient `[Flow](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/)` une réponse du type de réponse à l'opération, comme illustré ci-dessous : `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) }
}
```

Souvent, un flux d'objets est plus utile à la logique métier qu'un flux de réponses *contenant des* objets. Le mappeur fournit une méthode d'extension des réponses paginées pour accéder au flux d'objets. Par exemple, le code suivant renvoie un `Flow<Car>` plutôt qu'un `Flow<ScanResponse<Car>>` comme indiqué précédemment :

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