# Visão geral do suporte a AWS SDKs para o DynamoDB
O diagrama a seguir fornece uma visão geral de alto nível da programação de aplicações do Amazon DynamoDB usando os AWS SDKs.
![\[Modelo de programação para usar o DynamoDB com SDKs da AWS.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/SDKSupport.png)
1. Você pode escrever uma aplicação usando um AWS SDK para a sua linguagem de programação.
1. Cada AWS SDK fornece uma ou mais interfaces programáticas para trabalhar com o DynamoDB. As interfaces específicas disponíveis dependem de qual linguagem de programação e AWS SDK você utiliza. Entre as opções estão:
+ [Interfaces de baixo nível que funcionam com o DynamoDB](Programming.SDKs.Interfaces.md#Programming.SDKs.Interfaces.LowLevel)
+ [Interfaces de documentos que funcionam com o DynamoDB](Programming.SDKs.Interfaces.md#Programming.SDKs.Interfaces.Document)
+ [Interfaces de persistência de objetos que funcionam com o DynamoDB](Programming.SDKs.Interfaces.md#Programming.SDKs.Interfaces.Mapper)
+ [Interfaces de alto nível](HigherLevelInterfaces.md)
1. O AWS SDKconstrói solicitações HTTP(S) para uso com a API de baixo nível do DynamoDB.
1. O AWS SDK envia a solicitação ao endpoint do DynamoDB.
1. O DynamoDB executa a solicitação. Se a solicitação for bem-sucedida, o DynamoDB retornará um código de resposta HTTP 200 (OK). Se a solicitação não for bem-sucedida, o DynamoDB retornará um código de erro HTTP e uma mensagem de erro.
1. O AWS SDK processa a resposta e a propaga de volta para sua aplicação.
Cada um dos AWS SDKsfornece serviços importantes à sua aplicação, incluindo os seguintes:
+ Formatação de solicitações HTTP(S) e serialização de parâmetros de solicitação.
+ Geração de uma assinatura criptográfica para cada solicitação.
+ Encaminhamento de solicitações a um endpoint do DynamoDB e recebimento de respostas do DynamoDB.
+ Extração dos resultados dessas respostas.
+ Implementação da lógica de novas tentativas básicas em caso de erros.
Não é necessário escrever código para qualquer uma dessas tarefas.
**nota**
Para obter mais informações sobre AWS SDKs, incluindo instruções de instalação e documentação, consulte [Ferramentas para a Amazon Web Services](https://aws.amazon.com/tools).
## Suporte SDK para endpoints baseados em contas da AWS
A AWS está implementando o suporte do SDK para endpoints baseados em contas da AWS para o DynamoDB, começando com o AWS SDK for Java V1 em 4 de setembro de 2024. Esses novos endpoints ajudam a AWS garantir alto desempenho e escalabilidade. Os SDKs atualizados usarão automaticamente os novos endpoints, que têm o formato `https://(account-id).ddb.(region).amazonaws.com`
Se você usar uma única instância de um cliente SDK para fazer solicitações para várias contas, sua aplicação terá menos oportunidades de reutilizar conexões. A AWS recomenda modificar as aplicações para se conectar a menos contas por instância do cliente SDK. Uma alternativa é configurar seu cliente SDK para continuar usando endpoints regionais por meio da configuração `ACCOUNT_ID_ENDPOINT_MODE`, conforme documentado no [https://docs.aws.amazon.com/sdkref/latest/guide/feature-account-endpoints.html](https://docs.aws.amazon.com/sdkref/latest/guide/feature-account-endpoints.html).
# Interfaces programáticas que funcionam com o DynamoDB
Cada [AWS SDK](https://aws.amazon.com/tools) fornece uma ou mais interfaces programáticas para trabalhar com o Amazon DynamoDB. Essas interfaces variam de wrappers simples de baixo nível do DynamoDB a camadas de persistência orientadas a objetos. As interfaces disponíveis variam dependendo do AWS SDK e da linguagem de programação que você utiliza.
![\[Interfaces programáticas disponíveis em diferentes SDKs da AWS para trabalhar com o DynamoDB.\]](http://docs.aws.amazon.com/pt_br/amazondynamodb/latest/developerguide/images/SDKSupport.SDKInterfaces.png)
A seção a seguir destaca algumas das interfaces disponíveis, usando o AWS SDK para Java como exemplo. (Nem todas as interfaces estão disponíveis em todos os AWS SDKs.)
**Topics**
+ [Interfaces de baixo nível que funcionam com o DynamoDB](#Programming.SDKs.Interfaces.LowLevel)
+ [Interfaces de documentos que funcionam com o DynamoDB](#Programming.SDKs.Interfaces.Document)
+ [Interfaces de persistência de objetos que funcionam com o DynamoDB](#Programming.SDKs.Interfaces.Mapper)
## Interfaces de baixo nível que funcionam com o DynamoDB
O AWS SDK de cada linguagem específica fornece uma interface de baixo nível para o Amazon DynamoDB, com métodos que se assemelham a solicitações de API de baixo nível do DynamoDB.
Em alguns casos, você precisará identificar os tipos de dados dos atributos usando [Descritores de tipo de dados](Programming.LowLevelAPI.md#Programming.LowLevelAPI.DataTypeDescriptors), como `S` para strings ou `N` para números.
**nota**
Uma interface de baixo nível está disponível no AWS SDK de cada linguagem específica.
O seguinte programa Java usa a interface de baixo nível do AWS SDK para Java.
### Exemplo de interface de baixo nível
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*
* To get an item from an Amazon DynamoDB table using the AWS SDK for Java V2,
* its better practice to use the
* Enhanced Client, see the EnhancedGetItem example.
*/
public class GetItem {
public static void main(String[] args) {
final String usage = """
Usage:
Where:
tableName - The Amazon DynamoDB table from which an item is retrieved (for example, Music3).\s
key - The key used in the Amazon DynamoDB table (for example, Artist).\s
keyval - The key value that represents the item to get (for example, Famous Band).
""";
if (args.length != 3) {
System.out.println(usage);
System.exit(1);
}
String tableName = args[0];
String key = args[1];
String keyVal = args[2];
System.out.format("Retrieving item \"%s\" from \"%s\"\n", keyVal, tableName);
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
getDynamoDBItem(ddb, tableName, key, keyVal);
ddb.close();
}
public static void getDynamoDBItem(DynamoDbClient ddb, String tableName, String key, String keyVal) {
HashMap keyToGet = new HashMap<>();
keyToGet.put(key, AttributeValue.builder()
.s(keyVal)
.build());
GetItemRequest request = GetItemRequest.builder()
.key(keyToGet)
.tableName(tableName)
.build();
try {
// If there is no matching item, GetItem does not return any data.
Map returnedItem = ddb.getItem(request).item();
if (returnedItem.isEmpty())
System.out.format("No item found with the key %s!\n", key);
else {
Set keys = returnedItem.keySet();
System.out.println("Amazon DynamoDB table attributes: \n");
for (String key1 : keys) {
System.out.format("%s: %s\n", key1, returnedItem.get(key1).toString());
}
}
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
}
```
## Interfaces de documentos que funcionam com o DynamoDB
Muitos AWS SDKs fornecem uma interface de documento, permitindo que você realize operações de plano de dados (criar, ler, atualizar, excluir) em tabelas e índices. Com uma interface de documento, você não precisa especificar [Descritores de tipo de dados](Programming.LowLevelAPI.md#Programming.LowLevelAPI.DataTypeDescriptors). Os tipos de dados estão implícitos pela semântica dos próprios dados. Estes AWS SDKs também fornecem métodos para converter facilmente documentos JSON de/em tipos de dados nativos do Amazon DynamoDB.
**nota**
Interfaces de documentos estão disponíveis nos AWS SDKs para [Java](https://aws.amazon.com/sdk-for-java), [.NET](https://aws.amazon.com/sdk-for-net), [Node.js](https://aws.amazon.com/sdk-for-node-js) e [JavaScript SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/).
O seguinte programa Java usa a interface de documento do AWS SDK para Java. O programa cria um objeto `Table` que representa a tabela `Music` e depois solicita que esse objeto use `GetItem` para recuperar uma música. Em seguida, o programa imprime o ano em que a canção foi lançada.
A classe `software.amazon.dynamodb.document.DynamoDB` implementa a interface de documento do DynamoDB. Observe como `DynamoDB` atua como um wrapper em torno do cliente de baixo nível (`AmazonDynamoDB`).
### Exemplo de interface de documentos
```
package com.amazonaws.codesamples.gsg;
import software.amazon.dynamodb.AmazonDynamoDB;
import software.amazon.dynamodb.AmazonDynamoDBClientBuilder;
import software.amazon.dynamodb.document.DynamoDB;
import software.amazon.dynamodb.document.GetItemOutcome;
import software.amazon.dynamodb.document.Table;
public class MusicDocumentDemo {
public static void main(String[] args) {
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB docClient = new DynamoDB(client);
Table table = docClient.getTable("Music");
GetItemOutcome outcome = table.getItemOutcome(
"Artist", "No One You Know",
"SongTitle", "Call Me Today");
int year = outcome.getItem().getInt("Year");
System.out.println("The song was released in " + year);
}
}
```
## Interfaces de persistência de objetos que funcionam com o DynamoDB
Alguns AWS SDKs fornecem uma interface de persistência de objetos em que você não realiza operações de plano de dados diretamente. Em vez disso, você cria objetos que representam itens em índices e tabelas do Amazon DynamoDB e interage apenas com esses objetos. Isso permite que você escreva um código centrado em objetos, em vez de um código centrado no banco de dados.
**nota**
Interfaces de persistência de objetos estão disponíveis nos AWS SDKs for Java e .NET. Para obter mais informações, consulte [Interfaces de programação de nível superior para o DynamoDB](HigherLevelInterfaces.md) para o DynamoDB.
### Exemplo de interface de persistência de objetos
```
import com.example.dynamodb.Customer;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
import software.amazon.awssdk.enhanced.dynamodb.Key;
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedRequest;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
```
```
import com.example.dynamodb.Customer;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
import software.amazon.awssdk.enhanced.dynamodb.Key;
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedRequest;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
/*
* Before running this code example, create an Amazon DynamoDB table named Customer with these columns:
* - id - the id of the record that is the key. Be sure one of the id values is `id101`
* - custName - the customer name
* - email - the email value
* - registrationDate - an instant value when the item was added to the table. These values
* need to be in the form of `YYYY-MM-DDTHH:mm:ssZ`, such as 2022-07-11T00:00:00Z
*
* Also, ensure that you have set up your development environment, including your credentials.
*
* For information, see this documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*/
public class EnhancedGetItem {
public static void main(String[] args) {
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(ddb)
.build();
getItem(enhancedClient);
ddb.close();
}
public static String getItem(DynamoDbEnhancedClient enhancedClient) {
Customer result = null;
try {
DynamoDbTable table = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class));
Key key = Key.builder()
.partitionValue("id101").sortValue("tred@noserver.com")
.build();
// Get the item by using the key.
result = table.getItem(
(GetItemEnhancedRequest.Builder requestBuilder) -> requestBuilder.key(key));
System.out.println("******* The description value is " + result.getCustName());
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
return result.getCustName();
}
}
```
# Interfaces de programação de nível superior para o DynamoDB
Os AWS SDKs fornecem aplicações com interfaces de baixo nível para trabalhar com o Amazon DynamoDB. Estes métodos e classes no lado do cliente correspondem diretamente à API de baixo nível do DynamoDB. No entanto, muitos desenvolvedores experimentam uma sensação de desconexão, ou *incompatibilidade de impedância*, quando precisam mapear tipos de dados complexos para itens em uma tabela de banco de dados. Com uma interface de banco de dados de baixo nível, os desenvolvedores precisam escrever métodos para a leitura ou a gravação de dados de objetos em tabelas de banco de dados e vice-versa. A quantidade de código extra necessária para cada combinação de tipo de objeto e tabela de banco de dados pode parecer esmagadora.
Para simplificar o desenvolvimento, os AWS SDKs for Java e .NET fornecem interfaces adicionais com níveis mais altos de abstração. As interfaces de nível superior para o DynamoDB permitem que você defina as relações entre objetos no seu programa e as tabelas de banco de dados que armazenam os dados desses objetos. Depois de definir esse mapeamento, você chama métodos de objeto simples, como `save`, `load` ou `delete`, e as operações de baixo nível do DynamoDB subjacente são invocadas automaticamente em seu nome. Isso permite que você escreva um código centrado em objetos, em vez de um código centrado no banco de dados.
Interfaces de programação de nível superior para o DynamoDB estão disponíveis nos AWS SDKs for Java e .NET.
**Java**
+ [Java 1.x: DynamoDBMapper](DynamoDBMapper.md)
+ [Java 2.x: Cliente Aprimorado do DynamoDB](DynamoDBEnhanced.md)
**.NET**
+ [Trabalhar com o modelo de documento do .NET no DynamoDB](DotNetSDKMidLevel.md)
+ [Trabalhar com o modelo de persistência de objetos do .NET e o DynamoDB](DotNetSDKHighLevel.md)
# Java 1.x: DynamoDBMapper
**nota**
O SDK para Java tem duas versões: 1.x e 2.x. O fim do suporte para a versão 1.x foi [anunciado](https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-java-v1-x-on-december-31-2025/) em 12 de janeiro de 2024. Ele está previsto para 31 de dezembro de 2025. Para novos desenvolvimentos, é altamente recomendável que você use a versão 2.x.
O AWS SDK para Java fornece uma classe `DynamoDBMapper`, permitindo mapear classes no lado do cliente para tabelas do Amazon DynamoDB. Para usar `DynamoDBMapper`, defina a relação entre os itens em uma tabela do DynamoDB e as instâncias de objeto correspondentes no seu código. A classe `DynamoDBMapper` permite que você realize várias operações de criação, leitura, atualização e exclusão (CRUD) em itens e execute consultas e verificações em tabelas.
**Topics**
+ [Classe DynamoDBMapper](DynamoDBMapper.Methods.md)
+ [Tipos de dados compatíveis com DynamoDBMapper para Java](DynamoDBMapper.DataTypes.md)
+ [Anotações Java para DynamoDB](DynamoDBMapper.Annotations.md)
+ [Definições de configuração opcionais para DynamoDBMapper](DynamoDBMapper.OptionalConfig.md)
+ [DynamoDB e bloqueio positivo com número de versão](DynamoDBMapper.OptimisticLocking.md)
+ [Mapear dados arbitrários no DynamoDB](DynamoDBMapper.ArbitraryDataMapping.md)
+ [Exemplos de DynamoDBMapper](DynamoDBMapper.Examples.md)
**nota**
A classe `DynamoDBMapper` não permite criar, atualizar ou excluir tabelas. Para realizar essas tarefas, use em vez disso a interface do SDK para Java de baixo nível.
O SDK para Java fornece um conjunto de tipos de anotações, para que você possa mapear suas classes em tabelas. Por exemplo, considere uma tabela `ProductCatalog` cujo `Id` seja a chave de partição.
```
ProductCatalog(Id, ...)
```
É possível mapear uma classe no seu aplicativo cliente para a tabela `ProductCatalog`, conforme mostrado no código Java a seguir. Este código define um objeto Java antigo simples (POJO) chamado `CatalogItem` que usa anotações para mapear campos de objeto em nomes de atributos do DynamoDB.
**Example**
```
package com.amazonaws.codesamples;
import java.util.Set;
import software.amazon.dynamodb.datamodeling.DynamoDBAttribute;
import software.amazon.dynamodb.datamodeling.DynamoDBHashKey;
import software.amazon.dynamodb.datamodeling.DynamoDBIgnore;
import software.amazon.dynamodb.datamodeling.DynamoDBTable;
@DynamoDBTable(tableName="ProductCatalog")
public class CatalogItem {
private Integer id;
private String title;
private String ISBN;
private Set bookAuthors;
private String someProp;
@DynamoDBHashKey(attributeName="Id")
public Integer getId() { return id; }
public void setId(Integer id) {this.id = id; }
@DynamoDBAttribute(attributeName="Title")
public String getTitle() {return title; }
public void setTitle(String title) { this.title = title; }
@DynamoDBAttribute(attributeName="ISBN")
public String getISBN() { return ISBN; }
public void setISBN(String ISBN) { this.ISBN = ISBN; }
@DynamoDBAttribute(attributeName="Authors")
public Set getBookAuthors() { return bookAuthors; }
public void setBookAuthors(Set bookAuthors) { this.bookAuthors = bookAuthors; }
@DynamoDBIgnore
public String getSomeProp() { return someProp; }
public void setSomeProp(String someProp) { this.someProp = someProp; }
}
```
No código anterior, a anotação `@DynamoDBTable` mapeia a classe `CatalogItem` para a tabela `ProductCatalog`. Você pode armazenar instâncias de classes individuais como itens na tabela. Na definição de classe, a anotação `@DynamoDBHashKey` mapeia a propriedade `Id` para a chave primária.
Por padrão, as propriedades da classe são mapeadas para os atributos com o mesmo nome na tabela. As propriedades `Title` e `ISBN` são mapeadas para os atributos com o mesmo nome na tabela.
A anotação `@DynamoDBAttribute` é opcional quando o nome do atributo do DynamoDB corresponde ao nome da propriedade declarada na classe. Quando esses nomes são diferentes, use essa anotação com o parâmetro `attributeName` para especificar a qual atributo do DynamoDB essa propriedade corresponde.
No exemplo anterior, a anotação `@DynamoDBAttribute` é adicionada a cada propriedade para garantir que os nomes de propriedades correspondam exatamente às tabelas criadas em uma etapa anterior e sejam consistentes com os nomes de atributos usados em outros exemplos de código neste guia.
Sua definição de classe pode ter propriedades que não são mapeadas para atributos na tabela. Para identificar essas propriedades, adicione a anotação `@DynamoDBIgnore`. No exemplo anterior, a propriedade `SomeProp` está marcada com a anotação `@DynamoDBIgnore`. Ao carregar uma instância `CatalogItem` na tabela, sua instância `DynamoDBMapper` não inclui a propriedade `SomeProp`. Além disso, o mapeador não retorna esse atributo quando você recupera um item da tabela.
Depois de definir sua classe de mapeamento, é possível usar métodos `DynamoDBMapper` para gravar uma instância dessa classe em um item correspondente na tabela `Catalog`. O exemplo de código a seguir demonstra essa técnica.
```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDBMapper mapper = new DynamoDBMapper(client);
CatalogItem item = new CatalogItem();
item.setId(102);
item.setTitle("Book 102 Title");
item.setISBN("222-2222222222");
item.setBookAuthors(new HashSet(Arrays.asList("Author 1", "Author 2")));
item.setSomeProp("Test");
mapper.save(item);
```
O exemplo de código a seguir mostra como recuperar o item e acessar alguns dos seus atributos.
```
CatalogItem partitionKey = new CatalogItem();
partitionKey.setId(102);
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withHashKeyValues(partitionKey);
List itemList = mapper.query(CatalogItem.class, queryExpression);
for (int i = 0; i < itemList.size(); i++) {
System.out.println(itemList.get(i).getTitle());
System.out.println(itemList.get(i).getBookAuthors());
}
```
`DynamoDBMapper`O oferece uma forma intuitiva e natural de trabalhar com dados do DynamoDB no Java. Ele também fornece uma série de recursos internos, como bloqueio otimista, transações ACID, valores de chave de partição e chave de classificação gerados automaticamente e versionamento de objetos.
# Classe DynamoDBMapper
A classe `DynamoDBMapper` é o ponto de entrada do Amazon DynamoDB. Ela dá acesso a um endpoint do DynamoDB e permite acessar seus dados em várias tabelas. Ela também permite realizar várias operações de criação, leitura, atualização e exclusão (CRUD) em itens e executar consultas e verificações em tabelas. Essa classe fornece os seguintes métodos para trabalhar com o DynamoDB.
Para acessar a documentação Javadoc correspondente, consulte [DynamoDBMapper](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html) no *Referência da API do AWS SDK para Java*.
**Topics**
+ [save](#DynamoDBMapper.Methods.save)
+ [balanceamento](#DynamoDBMapper.Methods.load)
+ [excluir](#DynamoDBMapper.Methods.delete)
+ [consultar](#DynamoDBMapper.Methods.query)
+ [queryPage](#DynamoDBMapper.Methods.queryPage)
+ [scan](#DynamoDBMapper.Methods.scan)
+ [scanPage](#DynamoDBMapper.Methods.scanPage)
+ [parallelScan](#DynamoDBMapper.Methods.parallelScan)
+ [batchSave](#DynamoDBMapper.Methods.batchSave)
+ [batchLoad](#DynamoDBMapper.Methods.batchLoad)
+ [batchDelete](#DynamoDBMapper.Methods.batchDelete)
+ [batchWrite](#DynamoDBMapper.Methods.batchWrite)
+ [transactionWrite](#DynamoDBMapper.Methods.transactionWrite)
+ [transactionLoad](#DynamoDBMapper.Methods.transactionLoad)
+ [contagem](#DynamoDBMapper.Methods.count)
+ [generateCreateTableRequest](#DynamoDBMapper.Methods.generateCreateTableRequest)
+ [createS3Link](#DynamoDBMapper.Methods.createS3Link)
+ [getS3ClientCache](#DynamoDBMapper.Methods.getS3ClientCache)
## save
Salva o objeto especificado na tabela. O objeto que você deseja salvar é o único parâmetro necessário para esse método. É possível fornecer parâmetros de configuração opcionais usando o objeto `DynamoDBMapperConfig`.
Se um item com a mesma chave primária não existir, esse método criará um novo item na tabela. Se existir um item com a mesma chave primária, ele atualizará o item existente. Se a chave de partição e a chave de classificação forem do tipo String e estiverem anotadas com `@DynamoDBAutoGeneratedKey`, elas receberão um identificador universal exclusivo (UUID) aleatório se não forem inicializadas. Campos de versão anotados com `@DynamoDBVersionAttribute` são incrementados em um. Além disso, se um campo de versão for atualizado ou se uma chave for gerada, o objeto transmitido será atualizado como resultado da operação.
Por padrão, somente atributos correspondentes às propriedades de classe mapeadas são atualizados. Quaisquer atributos existentes em um item não são afetados. No entanto, se você especificar `SaveBehavior.CLOBBER`, poderá forçar o item a ser completamente substituído.
```
DynamoDBMapperConfig config = DynamoDBMapperConfig.builder()
.withSaveBehavior(DynamoDBMapperConfig.SaveBehavior.CLOBBER).build();
mapper.save(item, config);
```
Se o versionamento estiver habilitado, as versões dos itens no lado do servidor e no lado do cliente deverão corresponder. No entanto, a versão não precisará corresponder se a opção `SaveBehavior.CLOBBER` for usada. Para obter mais informações sobre versionamento, consulte [DynamoDB e bloqueio positivo com número de versão](DynamoDBMapper.OptimisticLocking.md).
## balanceamento
Recupera um item de uma tabela. É necessário fornecer a chave primária do item que você deseja recuperar. É possível fornecer parâmetros de configuração opcionais usando o objeto `DynamoDBMapperConfig`. Por exemplo, você pode solicitar opcionalmente leituras altamente consistentes para garantir que esse método recupere apenas os valores de itens mais recentes, como mostra a seguinte instrução Java.
```
DynamoDBMapperConfig config = DynamoDBMapperConfig.builder()
.withConsistentReads(DynamoDBMapperConfig.ConsistentReads.CONSISTENT).build();
CatalogItem item = mapper.load(CatalogItem.class, item.getId(), config);
```
Por padrão, o DynamoDB retorna o item que possui valores finais consistentes. Para obter informações sobre o modelo de consistência eventual do DynamoDB, consulte [Consistência de leitura do DynamoDB](HowItWorks.ReadConsistency.md).
## excluir
Exclui um item da tabela. Você deve transmitir uma instância do objeto da classe mapeada.
Se o versionamento estiver habilitado, as versões dos itens no lado do servidor e no lado do cliente deverão corresponder. No entanto, a versão não precisará corresponder se a opção `SaveBehavior.CLOBBER` for usada. Para obter mais informações sobre versionamento, consulte [DynamoDB e bloqueio positivo com número de versão](DynamoDBMapper.OptimisticLocking.md).
## consultar
Consulta uma tabela ou um índice secundário.
Vamos supor que você tenha uma tabela, `Reply`, que armazena as respostas de tópicos de fórum. Cada assunto de tópico pode ter 0 ou mais respostas. A chave primária da tabela `Reply` consiste nos campos `Id` e `ReplyDateTime`, em que `Id` é a chave de partição e `ReplyDateTime` é a chave de classificação da chave primária.
```
Reply ( Id, ReplyDateTime, ... )
```
Vamos supor que você tenha criado um mapeamento entre uma classe `Reply` e a tabela `Reply` correspondente no DynamoDB. O código Java a seguir usa `DynamoDBMapper` para localizar todas as respostas nas últimas duas semanas para um assunto de tópico específico.
**Example**
```
String forumName = "&DDB;";
String forumSubject = "&DDB; Thread 1";
String partitionKey = forumName + "#" + forumSubject;
long twoWeeksAgoMilli = (new Date()).getTime() - (14L*24L*60L*60L*1000L);
Date twoWeeksAgo = new Date();
twoWeeksAgo.setTime(twoWeeksAgoMilli);
SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");
String twoWeeksAgoStr = df.format(twoWeeksAgo);
Map eav = new HashMap();
eav.put(":v1", new AttributeValue().withS(partitionKey));
eav.put(":v2",new AttributeValue().withS(twoWeeksAgoStr.toString()));
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withKeyConditionExpression("Id = :v1 and ReplyDateTime > :v2")
.withExpressionAttributeValues(eav);
List latestReplies = mapper.query(Reply.class, queryExpression);
```
A consulta retorna uma coleção de objetos `Reply`.
Por padrão, o método `query` retorna uma coleção de "carregamento preguiçoso". Ele inicialmente retorna apenas uma página de resultados e, em seguida, faz uma chamada de serviço para a próxima página, se necessário. Para obter todos os itens correspondentes, faça uma iteração na coleção `latestReplies`.
Observe que chamar o método `size()` na coleção carregará todos os resultados para fornecer uma contagem precisa. Isso pode fazer com que uma grande quantidade de throughput provisionado seja consumida, e em uma tabela muito grande pode até esgotar toda a memória na JVM.
Para consultar um índice, você deve primeiro modelá-lo como uma classe de mapeador. Suponha que a tabela `Reply` tenha um índice global secundário chamado *PostedBy-Message-Index*. A chave de partição para esse índice é `PostedBy`, e a chave de classificação é `Message`. A definição de classe para um item no índice seria semelhante ao seguinte.
```
@DynamoDBTable(tableName="Reply")
public class PostedByMessage {
private String postedBy;
private String message;
@DynamoDBIndexHashKey(globalSecondaryIndexName = "PostedBy-Message-Index", attributeName = "PostedBy")
public String getPostedBy() { return postedBy; }
public void setPostedBy(String postedBy) { this.postedBy = postedBy; }
@DynamoDBIndexRangeKey(globalSecondaryIndexName = "PostedBy-Message-Index", attributeName = "Message")
public String getMessage() { return message; }
public void setMessage(String message) { this.message = message; }
// Additional properties go here.
}
```
A anotação `@DynamoDBTable` indica que esse índice está associado à tabela `Reply`. A anotação `@DynamoDBIndexHashKey` representa a chave de partição (*PostedBy*) do índice, enquanto `@DynamoDBIndexRangeKey` representa a chave de classificação (*Message*) do índice.
Agora, você pode usar `DynamoDBMapper` para consultar o índice, recuperando um subconjunto das mensagens que foram postadas por um usuário específico. Você não precisará especificar o nome do índice se não tiver mapeamentos conflitantes entre tabelas e índices e se os mapeamentos já tiverem sido feitos no mapeador. O mapeador vai inferir com base na chave primária e na chave de classificação. O código a seguir consulta um índice secundário global. Como um índice secundário global oferece suporte para leituras finais consistentes, mas não para leituras altamente consistentes, é necessário especificar `withConsistentRead(false)`.
```
HashMap eav = new HashMap();
eav.put(":v1", new AttributeValue().withS("User A"));
eav.put(":v2", new AttributeValue().withS("DynamoDB"));
DynamoDBQueryExpression queryExpression = new DynamoDBQueryExpression()
.withIndexName("PostedBy-Message-Index")
.withConsistentRead(false)
.withKeyConditionExpression("PostedBy = :v1 and begins_with(Message, :v2)")
.withExpressionAttributeValues(eav);
List iList = mapper.query(PostedByMessage.class, queryExpression);
```
A consulta retorna uma coleção de objetos `PostedByMessage`.
## queryPage
Consulta uma tabela ou um índice secundário e retorna uma única página de resultados correspondentes. Como acontece com o método `query`, você deve especificar um valor de chave de partição e um filtro de consulta que seja aplicado ao atributo de chave de classificação. No entanto, `queryPage` retorna somente a primeira "página" de dados, ou seja, a quantidade de dados que caberá em 1 MB
## scan
Verifica uma tabela ou um índice secundário inteiro. Você tem a opção de especificar uma `FilterExpression` para filtrar o conjunto de resultados.
Vamos supor que você tenha uma tabela, `Reply`, que armazena as respostas de tópicos de fórum. Cada assunto de tópico pode ter 0 ou mais respostas. A chave primária da tabela `Reply` consiste nos campos `Id` e `ReplyDateTime`, em que `Id` é a chave de partição e `ReplyDateTime` é a chave de classificação da chave primária.
```
Reply ( Id, ReplyDateTime, ... )
```
Se você mapeou uma classe Java para a tabela `Reply`, será possível usar `DynamoDBMapper` para verificar essa tabela. Por exemplo, o código Java a seguir verifica a tabela `Reply` inteira, retornando somente as respostas de um determinado ano.
**Example**
```
HashMap eav = new HashMap();
eav.put(":v1", new AttributeValue().withS("2015"));
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withFilterExpression("begins_with(ReplyDateTime,:v1)")
.withExpressionAttributeValues(eav);
List replies = mapper.scan(Reply.class, scanExpression);
```
Por padrão, o método `scan` retorna uma coleção de "carregamento preguiçoso". Ele inicialmente retorna apenas uma página de resultados e, em seguida, faz uma chamada de serviço para a próxima página, se necessário. Para obter todos os itens correspondentes, faça uma iteração na coleção `replies`.
Observe que chamar o método `size()` na coleção carregará todos os resultados para fornecer uma contagem precisa. Isso pode fazer com que uma grande quantidade de throughput provisionado seja consumida, e em uma tabela muito grande pode até esgotar toda a memória na JVM.
Para verificar um índice, você deve primeiro modelá-lo como uma classe de mapeador. Suponha que a tabela `Reply` tenha um índice global secundário chamado `PostedBy-Message-Index`. A chave de partição para esse índice é `PostedBy`, e a chave de classificação é `Message`. Uma classe de mapeador para esse índice é mostrada na seção [consultar](#DynamoDBMapper.Methods.query). Ela usa as anotações `@DynamoDBIndexHashKey` e `@DynamoDBIndexRangeKey` para especificar a chave de classificação e a chave de partição do índice.
O código de exemplo a seguir verifica `PostedBy-Message-Index`. Ele não usa um filtro de verificação e, portanto, todos os itens no índice são retornados para você.
```
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withIndexName("PostedBy-Message-Index")
.withConsistentRead(false);
List iList = mapper.scan(PostedByMessage.class, scanExpression);
Iterator indexItems = iList.iterator();
```
## scanPage
Verifica uma tabela ou um índice secundário e retorna uma única página de resultados correspondentes. Como com o método `scan`, você pode especificar opcionalmente um `FilterExpression` para filtrar o conjunto de resultados. No entanto, `scanPage` retorna somente a primeira “página” de dados, ou seja, a quantidade de dados que cabe em 1 MB.
## parallelScan
Realiza uma verificação paralela de uma tabela ou de um índice secundário inteiro. Você especifica um número de segmentos lógicos para a tabela, juntamente com uma expressão de verificação para filtrar os resultados. O `parallelScan` divide a tarefa de verificação entre vários operadores, um para cada segmento lógico. Por sua vez, esses operadores processam os dados em paralelo e retornam os resultados.
O exemplo de código Java a seguir realiza uma verificação paralela na tabela `Product`.
```
int numberOfThreads = 4;
Map eav = new HashMap();
eav.put(":n", new AttributeValue().withN("100"));
DynamoDBScanExpression scanExpression = new DynamoDBScanExpression()
.withFilterExpression("Price <= :n")
.withExpressionAttributeValues(eav);
List scanResult = mapper.parallelScan(Product.class, scanExpression, numberOfThreads);
```
## batchSave
Salva os objetos em uma ou mais tabelas usando uma ou mais chamadas para o método `AmazonDynamoDB.batchWriteItem`. Esse método não fornece garantias de transação.
O código Java a seguir salva dois itens (livros) na tabela `ProductCatalog`.
```
Book book1 = new Book();
book1.setId(901);
book1.setProductCategory("Book");
book1.setTitle("Book 901 Title");
Book book2 = new Book();
book2.setId(902);
book2.setProductCategory("Book");
book2.setTitle("Book 902 Title");
mapper.batchSave(Arrays.asList(book1, book2));
```
## batchLoad
Recupera vários itens de uma ou mais tabelas usando suas chaves primárias.
O seguinte código Java recupera dois itens de duas tabelas diferentes.
```
ArrayList