Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Empiece a utilizar la API de cliente mejorado de DynamoDB
El siguiente tutorial presenta los aspectos básicos necesarios para trabajar con la API de cliente mejorado de DynamoDB.
## agregar dependencias de API
Para empezar a trabajar con la API de cliente mejorado de DynamoDB en su proyecto, añada una dependencia al artefacto de Maven `dynamodb-enhanced`. Esto se muestra en el ejemplo siguiente.
------
#### [ Maven ]
```
software.amazon.awssdk
bom
pom
import
software.amazon.awssdk
dynamodb-enhanced
...
```
Realice una búsqueda en el repositorio central de Maven para encontrar la [última versión](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) y ** sustitúyala por este valor.
------
#### [ Gradle ]
```
repositories {
mavenCentral()
}
dependencies {
implementation(platform("software.amazon.awssdk:bom:"))
implementation("software.amazon.awssdk:dynamodb-enhanced")
...
}
```
Realice una búsqueda en el repositorio central de Maven para encontrar la [última versión](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) y sustitúyala por este ** valor.
------
# Generación de un `TableSchema` partir de una clase de datos
Un `[TableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/TableSchema.html)` permite al cliente mejorado asignar valores de atributos de DynamoDB hacia y desde las clases del cliente. En este tutorial, conocerá los `TableSchema` derivados de una clase de datos estáticos y generadas a partir de código mediante un generador.
## Utilice una clase de datos anotada
El SDK para Java 2.x incluye un [conjunto de anotaciones](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/annotations/package-summary.html) que puede utilizar con una clase de datos para generar rápidamente un `TableSchema` para asignar sus clases a tablas.
Comience por crear una clase de datos que se ajuste a la [JavaBean especificación](https://download.oracle.com/otn-pub/jcp/7224-javabeans-1.01-fr-spec-oth-JSpec/beans.101.pdf). La especificación requiere que una clase tenga un constructor público sin argumentos, además de getters y setters para cada atributo de la clase. Incluya una anotación a nivel de clase para indicar que la clase de datos es una `DynamoDbBean`. Además, como mínimo, incluya una anotación `DynamoDbPartitionKey` en el getter o setter para el atributo de clave principal.
Puede aplicar [anotaciones de nivel de atributo](ddb-en-client-anno-index.md) a getters o setters, pero no a ambos.
**nota**
El término `property` se usa normalmente para un valor encapsulado en un. JavaBean Sin embargo, en esta guía se utiliza el término `attribute` en su lugar para mantener la coherencia con la terminología utilizada por DynamoDB.
La clase siguiente `Customer` muestra anotaciones que vinculan la definición de clase a una tabla de DynamoDB.
### Clase `Customer`
```
package org.example.tests.model;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSortKey;
import java.time.Instant;
@DynamoDbBean
public class Customer {
private String id;
private String name;
private String email;
private Instant regDate;
@DynamoDbPartitionKey
public String getId() { return this.id; }
public void setId(String id) { this.id = id; }
public String getCustName() { return this.name; }
public void setCustName(String name) { this.name = name; }
@DynamoDbSortKey
public String getEmail() { return this.email; }
public void setEmail(String email) { this.email = email; }
public Instant getRegistrationDate() { return this.regDate; }
public void setRegistrationDate(Instant registrationDate) { this.regDate = registrationDate; }
@Override
public String toString() {
return "Customer [id=" + id + ", name=" + name + ", email=" + email
+ ", regDate=" + regDate + "]";
}
}
```
Una vez creada una clase de datos anotada, utilícela para crear el `TableSchema`, como se muestra en el siguiente fragmento.
```
static final TableSchema customerTableSchema = TableSchema.fromBean(Customer.class);
```
Un `TableSchema` se diseña para ser estático e inmutable. Por lo general, puede instanciarlo en el momento de cargar la clase.
El método de fábrica estático `TableSchema.fromBean()` introspecciona el objeto bean para generar la asignación de atributos (propiedades) de la clase de datos a y desde los atributos de DynamoDB.
Para ver un ejemplo de cómo trabajar con un modelo de datos compuesto por varias clases de datos, consulte la clase `Person` en la sección [Uso de atributos que son beans, mapas, listas y conjuntos](ddb-en-client-adv-features-nested.md).
## Uso de un constructor
Puede saltarse el coste de la introspección de objetos bean si define el esquema de la tabla en código. Si codificas el esquema, no es necesario que tu clase siga los estándares de JavaBean nomenclatura ni que esté anotada. El siguiente ejemplo utiliza un constructor y es equivalente al ejemplo de clase `Customer` que utiliza anotaciones.
```
static final TableSchema customerTableSchema =
TableSchema.builder(Customer.class)
.newItemSupplier(Customer::new)
.addAttribute(String.class, a -> a.name("id")
.getter(Customer::getId)
.setter(Customer::setId)
.tags(StaticAttributeTags.primaryPartitionKey()))
.addAttribute(String.class, a -> a.name("email")
.getter(Customer::getEmail)
.setter(Customer::setEmail)
.tags(StaticAttributeTags.primarySortKey()))
.addAttribute(String.class, a -> a.name("name")
.getter(Customer::getCustName)
.setter(Customer::setCustName))
.addAttribute(Instant.class, a -> a.name("registrationDate")
.getter(Customer::getRegistrationDate)
.setter(Customer::setRegistrationDate))
.build();
```
# Crear un cliente mejorado y una `DynamoDbTable`
## Crear un cliente mejorado
La [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html)clase o su contraparte asíncrona [DynamoDbEnhancedAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.html), es el punto de partida para trabajar con la API de cliente mejorada de DynamoDB.
El cliente mejorado requiere un `[DynamoDbClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/DynamoDbClient.html)` estándar para hacer el trabajo. La API ofrece dos formas de crear una instancia de `DynamoDbEnhancedClient`. La primera opción, que se muestra en el siguiente fragmento, crea un `DynamoDbClient` estándar con los ajustes predeterminados tomados de la configuración.
```
DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.create();
```
Si desea configurar el cliente estándar subyacente, puede suministrarlo al método constructor del cliente mejorado como se muestra en el siguiente fragmento.
```
// Configure an instance of the standard DynamoDbClient.
DynamoDbClient standardClient = DynamoDbClient.builder()
.region(Region.US_EAST_1)
.credentialsProvider(ProfileCredentialsProvider.create())
.build();
// Use the configured standard client with the enhanced client.
DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(standardClient)
.build();
```
## Crear una instancia de `DynamoDbTable`
Piense en una [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html) como la representación del cliente de una tabla de DynamoDB que utiliza la funcionalidad de mapeo proporcionada por un `TableSchema`. La clase `DynamoDbTable` proporciona métodos para las operaciones CRUD que permiten interactuar con una sola tabla de DynamoDB.
`DynamoDbTable` es una clase genérica que toma un único argumento de tipo, ya sea una clase personalizada o un `EnhancedDocument` cuando se trabaja con elementos de tipo documento. Este tipo de argumento establece la relación entre la clase que utiliza y la tabla única de DynamoDB.
Siga el método de fábrica `table()` del `DynamoDbEnhancedClient` para crear una instancia `DynamoDbTable`, como se muestra en el siguiente fragmento.
```
static final DynamoDbTable customerTable =
enhancedClient.table("Customer", TableSchema.fromBean(Customer.class));
```
Las instancias de `DynamoDbTable` son aptas para ser únicas porque son inmutables y se pueden usar en toda la aplicación.
El código ahora tiene una representación en memoria de una tabla de DynamoDB que puede funcionar con instancias `Customer`. La tabla de DynamoDB real puede existir o no. Si la tabla nombrada `Customer` ya existe, puede empezar a realizar operaciones de CRUD en ella. Si no existe, utilice la instancia de `DynamoDbTable` para crear la tabla, tal y como se explica en la siguiente sección.
# Cree una tabla de DynamoDB si es necesario
Después de crear una instancia `DynamoDbTable`, úsela para crear una tabla de DynamoDB por *única vez*.
## Crear código de ejemplo de tabla
En el siguiente ejemplo, se crea una tabla de DynamoDB basada en la clase de datos `Customer`.
En este ejemplo se crea una tabla DynamoDB con el nombre `Customer` —idéntico al nombre de la clase— pero el nombre de la tabla puede ser otro. Sea cual sea el nombre que dé a la tabla, debe usar este nombre en otras aplicaciones para trabajar con la tabla. Proporcione este nombre al método `table()` cada vez que cree otro objeto `DynamoDbTable` para trabajar con la tabla de DynamoDB subyacente.
El parámetro lambda de Java, `builder`, que se pasa al método `createTable`, permite [personalizar la tabla](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/CreateTableEnhancedRequest.Builder.html). En este ejemplo, se configura el [rendimiento aprovisionado](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html#HowItWorks.ProvisionedThroughput.Manual). Si desea utilizar la configuración predeterminada al crear una tabla, omita el generador, tal y como se muestra en el siguiente fragmento.
```
customerTable.createTable();
```
Cuando se utiliza la configuración predeterminada, no se establecen los valores del rendimiento aprovisionado. En su lugar, el modo de facturación de la tabla se establece como [bajo demanda](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html#HowItWorks.OnDemand).
En el ejemplo también se utiliza una `[DynamoDbWaiter](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/waiters/DynamoDbWaiter.html)` antes de intentar imprimir el nombre de la tabla recibido en la respuesta. Crear una tabla lleva algún tiempo. Por lo tanto, utilizar un 'waiter' significa que no tiene que escribir lógica que consulte el servicio de DynamoDB para verificar si la tabla existe antes de su uso.
### Importaciones
```
import com.example.dynamodb.Customer;
import software.amazon.awssdk.core.internal.waiters.ResponseOrException;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
import software.amazon.awssdk.enhanced.dynamodb.model.CreateTableEnhancedRequest;
import software.amazon.awssdk.services.dynamodb.model.DescribeTableResponse;
import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;
```
### Código
```
public static void createCustomerTable(DynamoDbTable customerTable, DynamoDbClient standardClient) {
// Create the DynamoDB table using the 'customerTable' DynamoDbTable instance.
customerTable.createTable(builder -> builder
.provisionedThroughput(b -> b
.readCapacityUnits(10L)
.writeCapacityUnits(10L)
.build())
);
// The DynamoDbClient instance (named 'standardClient') passed to the builder for the DynamoDbWaiter is the same instance
// that was passed to the builder of the DynamoDbEnhancedClient instance that we created previously.
// By using the same instance, it ensures that the same Region that was configured on the standard DynamoDbClient
// instance is used for other service clients that accept a DynamoDbClient during construction.
try (DynamoDbWaiter waiter = DynamoDbWaiter.builder().client(standardClient).build()) { // DynamoDbWaiter is Autocloseable
ResponseOrException response = waiter
.waitUntilTableExists(builder -> builder.tableName("Customer").build())
.matched();
DescribeTableResponse tableDescription = response.response().orElseThrow(
() -> new RuntimeException("Customer table was not created."));
// The actual error can be inspected in response.exception()
logger.info("Customer table was created.");
}
}
```
**nota**
Los nombres de los atributos de una tabla de DynamoDB comienzan con una letra minúscula cuando la tabla se genera a partir de una clase de datos. Si desea que el nombre del atributo de la tabla comience con una letra mayúscula, utilice la [anotación `@DynamoDbAttribute(NAME)`](ddb-en-client-adv-features-inex-attr.md) y proporcione el nombre que desee como parámetro.
# Realizar operaciones
Una vez creada la tabla, utilice la instancia `DynamoDbTable` para las operaciones en la tabla de DynamoDB.
En el siguiente ejemplo, se pasa un singleton `DynamoDbTable` como parámetro junto con una [instancia de clase de datos `Customer`](ddb-en-client-gs-tableschema.md#ddb-en-client-gs-tableschema-anno-bean-cust) para añadir un nuevo elemento a la tabla.
```
public static void putItemExample(DynamoDbTable customerTable, Customer customer){
logger.info(customer.toString());
customerTable.putItem(customer);
}
```
## Objeto `Customer`
```
Customer customer = new Customer();
customer.setId("1");
customer.setCustName("Customer Name");
customer.setEmail("customer@example.com");
customer.setRegistrationDate(Instant.parse("2023-07-03T10:15:30.00Z"));
```
Antes de enviar el objeto `customer` al servicio DynamoDB, registre el resultado del método del objeto `toString()` para compararlo con lo que envía el cliente mejorado.
```
Customer [id=1, name=Customer Name, email=customer@example.com, regDate=2023-07-03T10:15:30Z]
```
El registro a nivel de cable muestra la carga útil de la solicitud generada. El cliente mejorado generó la representación de bajo nivel a partir de la clase de datos. El atributo `regDate`, que es un tipo `Instant` en Java, se representa como una cadena de DynamoDB.
```
{
"TableName": "Customer",
"Item": {
"registrationDate": {
"S": "2023-07-03T10:15:30Z"
},
"id": {
"S": "1"
},
"custName": {
"S": "Customer Name"
},
"email": {
"S": "customer@example.com"
}
}
}
```
# Trabajar con una tabla existente
En la sección anterior se muestra cómo crear una tabla de DynamoDB a partir de una clase de datos de Java. Si ya tiene una tabla existente y desea utilizar las características del cliente mejorado, puede crear una clase de datos de Java para que funcione con la tabla. Debe examinar la tabla de DynamoDB y añadir las anotaciones necesarias a la clase de datos.
Antes de trabajar con una tabla existente, llame al método `DynamoDbEnhanced.table()`. Esto se hizo en el ejemplo anterior con la instrucción siguiente.
```
DynamoDbTable customerTable = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class));
```
Una vez devuelta la instancia `DynamoDbTable`, puede empezar a trabajar de inmediato con la tabla subyacente. No es necesario volver a crear la tabla llamando al método `DynamoDbTable.createTable()`.
El siguiente ejemplo lo demuestra mediante la recuperación inmediata de una instancia `Customer` de la tabla de DynamoDB.
```
DynamoDbTable customerTable = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class));
// The Customer table exists already and has an item with a primary key value of "1" and a sort key value of "customer@example.com".
customerTable.getItem(
Key.builder().
partitionValue("1").
sortValue("customer@example.com").build());
```
**importante**
El nombre de la tabla utilizado en el método `table()` debe coincidir con el nombre de la tabla de DynamoDB existente.