Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

# Inizia a usare DynamoDB Mapper
<a name="ddb-mapper-get-started"></a>

****  
**DynamoDB Mapper è una versione di anteprima per sviluppatori. Non è completa di funzionalità ed è soggetta a modifiche.**

Il seguente tutorial introduce i componenti di base di DynamoDB Mapper e mostra come utilizzarli nel codice.

## Aggiungi dipendenze
<a name="ddb-mapper-get-started-deps"></a>

Per iniziare a utilizzare DynamoDB Mapper nel tuo progetto Gradle, aggiungi un plugin e due dipendenze al tuo file. `build.gradle.kts`

(Puoi accedere al {{X.Y.Z}} link per vedere l'ultima versione disponibile.)

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

\*Sostituisci {{<Version>}} con l'ultima versione dell'SDK. Per trovare la versione più recente dell'SDK, controlla l'[ultima](https://github.com/awslabs/aws-sdk-kotlin/releases/latest) versione su. GitHub

**Nota**  
Alcune di queste dipendenze sono opzionali se prevedi di definire gli schemi manualmente. Vedi [Definizione manuale degli schemi](ddb-mapper-code-schemas.md) per ulteriori informazioni e per il set ridotto di dipendenze.

## Crea e usa un mappatore
<a name="ddb-mapper-get-started-mapper"></a>

DynamoDB Mapper utilizza il client DynamoDB per AWS SDK per Kotlin interagire con DynamoDB. È necessario fornire un'istanza completamente configurata quando si crea un'[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)istanza mapper, come mostrato nel seguente frammento di codice:

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

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

**Nota**  
`DynamoDbMapper`non supporta le operazioni di creazione di tabelle. Usa il `DynamoDbClient` per creare tabelle.

Dopo aver creato l'istanza mapper, puoi usarla per ottenere l'istanza della tabella come mostrato di seguito:

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

Il codice precedente ottiene un riferimento a una tabella `DynamoDB` denominata `cars` con uno schema definito da `CarSchema` (discuteremo gli schemi di seguito). Dopo aver creato un'istanza di tabella, è possibile eseguire operazioni su di essa. Il seguente frammento di codice mostra due operazioni di esempio sulla `cars` tabella:

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

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

Il codice precedente crea un nuovo elemento nella `cars` tabella. Il codice crea un'`Car`istanza in linea utilizzando la `Car` classe, la cui definizione è mostrata di seguito. Successivamente, il codice interroga la `cars` tabella per individuare gli elementi la cui chiave di partizione è `Peugeot` e li stampa. Le operazioni sono [descritte più dettagliatamente di](#ddb-mapper-gs-invoke-ops) seguito.

## Definire uno schema con annotazioni di classe
<a name="ddb-mapper-gs-anno-schema-def"></a>

Per una varietà di classi Kotlin, l'SDK può generare automaticamente schemi in fase di compilazione utilizzando il plug-in DynamoDB Mapper Schema Generator per Gradle. Quando si utilizza il generatore di schemi, l'SDK ispeziona le classi per dedurne lo schema, il che riduce alcuni degli aspetti fondamentali legati alla definizione manuale degli schemi. [[È possibile personalizzare lo schema generato utilizzando annotazioni e configurazioni aggiuntive.](ddb-mapper-anno-schema-gen.md#ddb-mapper-anno-schema-gen-conf-plugin)](ddb-mapper-anno-schema-gen.md#ddb-mapper-anno-schema-gen-annotate)

Per generare uno schema dalle annotazioni, annota prima le classi con `@[DynamoDbItem](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)` e tutte le chiavi con e. `@[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)` Il codice seguente mostra la classe `Car` annotata:

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

Dopo la creazione, puoi fare riferimento a quella `CarSchema` generata automaticamente. È possibile utilizzare il riferimento nel `getTable` metodo del mapper per ottenere un'istanza di tabella come mostrato di seguito:

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

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

In alternativa, potete ottenere l'istanza della tabella sfruttando un metodo di estensione generato automaticamente in fase di compilazione. `[DynamoDbMapper](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-mapper/index.html)` Utilizzando questo approccio, non è necessario fare riferimento allo schema per nome. Come illustrato di seguito, il metodo di `getCarsTable` estensione generato automaticamente restituisce un riferimento all'istanza della tabella:

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

Per maggiori informazioni ed esempi, consulta [Genera uno schema dalle annotazioni](ddb-mapper-anno-schema-gen.md).

## Operazioni di richiamo
<a name="ddb-mapper-gs-invoke-ops"></a>

DynamoDB Mapper supporta un sottoinsieme delle operazioni disponibili sugli SDK. `DynamoDbClient` Le operazioni Mapper hanno lo stesso nome delle loro controparti sul client SDK. Molti request/response membri di mapper sono uguali ai loro omologhi client SDK, sebbene alcuni siano stati rinominati, ridigitati o eliminati del tutto.

Si richiama un'operazione su un'istanza di tabella utilizzando una sintassi DSL come illustrato di seguito:

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

È inoltre possibile richiamare un'operazione utilizzando un oggetto di richiesta esplicito:

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

I due esempi di codice precedenti sono equivalenti.

### Lavora con risposte impaginate
<a name="ddb-mapper-gs-pagination"></a>

Alcune operazioni come `query` e `scan` possono restituire raccolte di dati che potrebbero essere troppo grandi per essere restituite in un'unica risposta. Per garantire che tutti gli oggetti vengano elaborati, DynamoDB Mapper fornisce metodi di impaginazione, che non chiamano DynamoDB immediatamente, ma restituiscono invece `[Flow](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/)` un tipo di risposta all'operazione, come mostrato di seguito: `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) }
}
```

*Spesso, un flusso di oggetti è più utile per la logica aziendale rispetto a un flusso di risposte contenenti oggetti.* Il mapper fornisce un metodo di estensione delle risposte impaginate per accedere al flusso di oggetti. Ad esempio, il codice seguente restituisce a `Flow<Car>` anziché a `Flow<ScanResponse<Car>>` come mostrato in precedenza:

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