As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Comece a usar o DynamoDB Mapper
<a name="ddb-mapper-get-started"></a>

****  
**O DynamoDB Mapper é uma versão prévia para desenvolvedores. O recurso não está completo e está sujeito a alterações.**

O tutorial a seguir apresenta os componentes básicos do DynamoDB Mapper e mostra como usá-lo em seu código.

## Adicionar dependências
<a name="ddb-mapper-get-started-deps"></a>

Para começar a trabalhar com o DynamoDB Mapper em seu projeto Gradle, adicione um plug-in e duas dependências ao seu arquivo. `build.gradle.kts`

(Você pode navegar até o *X.Y.Z* link para ver a versão mais recente disponível.)

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

*<Version>*\$1Substitua pela versão mais recente do SDK. Para encontrar a versão mais recente do SDK, verifique a [versão mais recente em GitHub](https://github.com/awslabs/aws-sdk-kotlin/releases/latest).

**nota**  
Algumas dessas dependências são opcionais se você planeja definir esquemas manualmente. Consulte [Defina esquemas manualmente](ddb-mapper-code-schemas.md) para obter mais informações e o conjunto reduzido de dependências.

## Crie e use um mapeador
<a name="ddb-mapper-get-started-mapper"></a>

O DynamoDB Mapper usa o cliente do DynamoDB para interagir com AWS SDK para Kotlin o DynamoDB. Você precisa fornecer uma instância totalmente configurada ao criar uma [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)instância de mapeador, conforme mostrado no seguinte trecho de código:

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

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

**nota**  
`DynamoDbMapper`não suporta operações de criação de tabelas. Use o `DynamoDbClient` para criar tabelas.

Depois de criar a instância do mapeador, você pode usá-la para obter a instância da tabela, conforme mostrado a seguir:

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

O código anterior faz referência a uma tabela `DynamoDB` nomeada `cars` com um esquema definido por `CarSchema` (discutiremos os esquemas abaixo). Depois de criar uma instância de tabela, você pode realizar operações nela. O trecho de código a seguir mostra dois exemplos de operações na `cars` tabela:

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

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

O código anterior cria um novo item na `cars` tabela. O código cria uma `Car` instância em linha usando a `Car` classe, cuja definição é mostrada abaixo. Em seguida, o código consulta a `cars` tabela em busca de itens cuja chave de partição esteja `Peugeot` e os imprime. As operações são [descritas com mais detalhes abaixo](#ddb-mapper-gs-invoke-ops).

## Defina um esquema com anotações de classe
<a name="ddb-mapper-gs-anno-schema-def"></a>

Para várias classes do Kotlin, o SDK pode gerar esquemas automaticamente no momento da compilação usando o plug-in do DynamoDB Mapper Schema Generator para Gradle. Quando você usa o gerador de esquemas, o SDK inspeciona suas classes para inferir o esquema, o que alivia parte do clichê envolvido na definição manual de esquemas. [Você pode personalizar o esquema gerado usando [anotações e configurações adicionais.](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)

Para gerar um esquema a partir de anotações, primeiro anote suas classes com `@[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 quaisquer chaves com 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)` O código a seguir mostra a classe anotada`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
)
```

Depois de construir, você pode consultar o gerado automaticamente`CarSchema`. Você pode usar a referência no `getTable` método do mapeador para obter uma instância de tabela, conforme mostrado a seguir:

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

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

Como alternativa, você pode obter a instância da tabela aproveitando um método de extensão `[DynamoDbMapper](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-mapper/index.html)` que é gerado automaticamente no momento da criação. Ao usar essa abordagem, você não precisa se referir ao esquema pelo nome. Conforme mostrado a seguir, o método de `getCarsTable` extensão gerado automaticamente retorna uma referência à instância da tabela:

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

Consulte [Gere um esquema a partir de anotações](ddb-mapper-anno-schema-gen.md) para obter mais detalhes e exemplos.

## Invocar operações
<a name="ddb-mapper-gs-invoke-ops"></a>

O DynamoDB Mapper suporta um subconjunto das operações disponíveis nos SDKs. `DynamoDbClient` As operações do Mapper são nomeadas da mesma forma que suas contrapartes no cliente SDK. Muitos request/response membros do mapeador são iguais aos seus colegas clientes do SDK, embora alguns tenham sido renomeados, digitados novamente ou totalmente eliminados.

Você invoca uma operação em uma instância de tabela usando uma sintaxe DSL, conforme mostrado a seguir:

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

Você também pode invocar uma operação usando um objeto de solicitação explícito:

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

Os dois exemplos de código anteriores são equivalentes.

### Trabalhe com respostas paginadas
<a name="ddb-mapper-gs-pagination"></a>

Algumas operações, como `query` e `scan` podem retornar, coleções de dados que podem ser grandes demais para serem retornadas em uma única resposta. Para garantir que todos os objetos sejam processados, o DynamoDB Mapper fornece métodos de paginação, que não chamam o DynamoDB imediatamente, mas retornam a do tipo de resposta da operação, como `[Flow](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/)` mostrado a seguir: `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) }
}
```

Muitas vezes, um fluxo de objetos é mais útil para a lógica de negócios do que um fluxo de respostas *contendo* objetos. O mapeador fornece um método de extensão em respostas paginadas para acessar o fluxo de objetos. Por exemplo, o código a seguir retorna um `Flow<Car>` em vez de um`Flow<ScanResponse<Car>>`, conforme mostrado anteriormente:

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