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 l'API DynamoDB Enhanced Client
Il seguente tutorial presenta le nozioni di base necessarie per lavorare con l'API DynamoDB Enhanced Client.
## Aggiungi dipendenze
Per iniziare a utilizzare l'API DynamoDB Enhanced Client nel tuo progetto, aggiungi una dipendenza dall'artefatto Maven. `dynamodb-enhanced` Questo è illustrato negli esempi seguenti.
------
#### [ Maven ]
```
software.amazon.awssdk
bom
pom
import
software.amazon.awssdk
dynamodb-enhanced
...
```
Esegui una ricerca nell'archivio centrale di Maven per la [versione più recente](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) e sostituiscila ** con questo valore.
------
#### [ Gradle ]
```
repositories {
mavenCentral()
}
dependencies {
implementation(platform("software.amazon.awssdk:bom:"))
implementation("software.amazon.awssdk:dynamodb-enhanced")
...
}
```
Esegui una ricerca nell'archivio centrale di Maven per la [versione più recente](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) e sostituiscila con questo valore. **
------
# Genera un `TableSchema` da una classe di dati
A `[TableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/TableSchema.html)` consente al client avanzato di mappare i valori degli attributi DynamoDB da e verso le classi lato client. In questo tutorial, imparerai a conoscere `TableSchema` i file derivati da una classe di dati statici e generati dal codice utilizzando un builder.
## Usa una classe di dati annotata
L'SDK for Java 2.x include [un set di](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/annotations/package-summary.html) annotazioni che è possibile utilizzare con una classe di dati per generare `TableSchema` rapidamente un file per mappare le classi alle tabelle.
[Inizia creando una classe di dati conforme alle specifiche. JavaBean ](https://download.oracle.com/otn-pub/jcp/7224-javabeans-1.01-fr-spec-oth-JSpec/beans.101.pdf) La specifica richiede che una classe disponga di un costruttore pubblico senza argomenti e che disponga di getter e setter per ogni attributo della classe. Includi un'annotazione a livello di classe per indicare che la classe di dati è una. `DynamoDbBean` Inoltre, includi almeno un'`DynamoDbPartitionKey`annotazione sul getter o setter per l'attributo chiave primaria.
È possibile applicare [annotazioni a livello di attributo a](ddb-en-client-anno-index.md) getter o setter, ma non a entrambi.
**Nota**
Il termine `property` viene normalmente utilizzato per un valore incapsulato in un. JavaBean Tuttavia, questa guida utilizza `attribute` invece il termine, per coerenza con la terminologia utilizzata da DynamoDB.
La `Customer` classe seguente mostra le annotazioni che collegano la definizione della classe a una tabella DynamoDB.
### Classe `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 + "]";
}
}
```
Dopo aver creato una classe di dati annotata, usatela per creare la`TableSchema`, come mostrato nel seguente frammento.
```
static final TableSchema customerTableSchema = TableSchema.fromBean(Customer.class);
```
A `TableSchema` è progettato per essere statico e immutabile. Di solito puoi istanziarlo al momento del caricamento della classe.
Il metodo static `TableSchema.fromBean()` factory analizza il bean per generare la mappatura degli attributi (proprietà) delle classi di dati da e verso gli attributi DynamoDB.
Per un esempio di utilizzo di un modello di dati composto da diverse classi di dati, consultate la classe nella `Person` sezione. [Lavora con attributi che sono bean, mappe, elenchi e set](ddb-en-client-adv-features-nested.md)
## Usa un builder
Puoi saltare il costo dell'introspezione dei bean se definisci lo schema della tabella nel codice. Se codifichi lo schema, la tua classe non ha bisogno di seguire gli standard di JavaBean denominazione né di essere annotata. L'esempio seguente utilizza un generatore ed è equivalente all'esempio di `Customer` classe che utilizza le annotazioni.
```
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();
```
# Crea un client avanzato e `DynamoDbTable`
## Crea un client avanzato
La [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html)classe, o la sua controparte asincrona [DynamoDbEnhancedAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.html), è il punto di partenza per lavorare con l'API DynamoDB Enhanced Client.
Il client avanzato richiede uno standard per eseguire il lavoro. `[DynamoDbClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/DynamoDbClient.html)` L'API offre due modi per creare un'`DynamoDbEnhancedClient`istanza. La prima opzione, mostrata nel frammento seguente, crea uno standard `DynamoDbClient` con le impostazioni predefinite raccolte dalle impostazioni di configurazione.
```
DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.create();
```
Se desideri configurare il client standard sottostante, puoi fornirlo al metodo builder del client avanzato, come mostrato nel seguente frammento.
```
// 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();
```
## Creazione di un'Istanza `DynamoDbTable`
Pensate a [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)come alla rappresentazione lato client di una tabella DynamoDB che utilizza la funzionalità di mappatura fornita da a. `TableSchema` La `DynamoDbTable` classe fornisce metodi per le operazioni CRUD che consentono di interagire con una singola tabella DynamoDB.
`DynamoDbTable`è una classe generica che accetta un argomento di tipo singolo, sia che si tratti di una classe personalizzata o di un argomento `EnhancedDocument` quando si lavora con elementi di tipo documento. Questo tipo di argomento stabilisce la relazione tra la classe utilizzata e la singola tabella DynamoDB.
Utilizzate il metodo `table()` factory di `DynamoDbEnhancedClient` per creare un'`DynamoDbTable`istanza, come mostrato nel frammento seguente.
```
static final DynamoDbTable customerTable =
enhancedClient.table("Customer", TableSchema.fromBean(Customer.class));
```
`DynamoDbTable`le istanze sono candidate per essere utilizzate singleton perché sono immutabili e possono essere utilizzate in tutta l'applicazione.
Il codice ora ha una rappresentazione in memoria di una tabella DynamoDB che può funzionare con le istanze. `Customer` La tabella DynamoDB effettiva potrebbe esistere o meno. Se la tabella denominata esiste `Customer` già, puoi iniziare a eseguire operazioni CRUD su di essa. Se non esiste, utilizzate l'`DynamoDbTable`istanza per creare la tabella come illustrato nella sezione successiva.
# Se necessario, creare una tabella DynamoDB
Dopo aver creato un'`DynamoDbTable`istanza, utilizzala per creare una *sola volta* una tabella in DynamoDB.
## Crea un codice di esempio per la tabella
L'esempio seguente crea una tabella DynamoDB basata sulla `Customer` classe di dati.
Questo esempio crea una tabella DynamoDB con il `Customer` nome, identico al nome della classe, ma il nome della tabella può essere qualcos'altro. Qualunque sia il nome dato alla tabella, è necessario utilizzare questo nome in altre applicazioni per lavorare con la tabella. Fornite questo nome al `table()` metodo ogni volta che create un altro `DynamoDbTable` oggetto per lavorare con la tabella DynamoDB sottostante.
[Il parametro Java lambda`builder`, passato al `createTable` metodo consente di personalizzare la tabella.](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/CreateTableEnhancedRequest.Builder.html) In questo esempio, viene configurato il [throughput assegnato](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html#HowItWorks.ProvisionedThroughput.Manual). Se desideri utilizzare le impostazioni predefinite quando crei una tabella, salta il generatore, come mostrato nel frammento seguente.
```
customerTable.createTable();
```
Quando vengono utilizzate le impostazioni predefinite, i valori per il throughput assegnato non vengono impostati. [Al contrario, la modalità di fatturazione per la tabella è impostata su richiesta.](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadWriteCapacityMode.html#HowItWorks.OnDemand)
L'esempio utilizza anche un `[DynamoDbWaiter](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/waiters/DynamoDbWaiter.html)` prima di tentare di stampare il nome della tabella ricevuto nella risposta. La creazione di una tabella richiede del tempo. Pertanto, l'utilizzo di un cameriere significa che non è necessario scrivere una logica che interroghi il servizio DynamoDB per verificare se la tabella esiste prima di utilizzarla.
### Importazioni
```
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;
```
### Codice
```
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**
I nomi degli attributi di una tabella DynamoDB iniziano con una lettera minuscola quando la tabella viene generata da una classe di dati. Se desideri che il nome dell'attributo della tabella inizi con una lettera maiuscola, usa l'[`@DynamoDbAttribute(NAME)`annotazione](ddb-en-client-adv-features-inex-attr.md) e fornisci il nome che desideri come parametro.
# Esegui operazioni
Dopo aver creato la tabella, utilizzate l'`DynamoDbTable`istanza per eseguire operazioni sulla tabella DynamoDB.
Nell'esempio seguente, un singleton `DynamoDbTable` viene passato come parametro insieme a un'istanza della [classe di `Customer` dati](ddb-en-client-gs-tableschema.md#ddb-en-client-gs-tableschema-anno-bean-cust) per aggiungere un nuovo elemento alla tabella.
```
public static void putItemExample(DynamoDbTable customerTable, Customer customer){
logger.info(customer.toString());
customerTable.putItem(customer);
}
```
## Oggetto `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"));
```
Prima di inviare l'`customer`oggetto al servizio DynamoDB, registrate l'output del metodo `toString()` dell'oggetto per confrontarlo con quello inviato dal client avanzato.
```
Customer [id=1, name=Customer Name, email=customer@example.com, regDate=2023-07-03T10:15:30Z]
```
La registrazione a livello di cavo mostra il payload della richiesta generata. Il client avanzato ha generato la rappresentazione di basso livello dalla classe di dati. L'`regDate`attributo, che è un `Instant` tipo in Java, è rappresentato come una stringa DynamoDB.
```
{
"TableName": "Customer",
"Item": {
"registrationDate": {
"S": "2023-07-03T10:15:30Z"
},
"id": {
"S": "1"
},
"custName": {
"S": "Customer Name"
},
"email": {
"S": "customer@example.com"
}
}
}
```
# Lavora con una tabella esistente
La sezione precedente mostrava come creare una tabella DynamoDB a partire da una classe di dati Java. Se disponi già di una tabella esistente e desideri utilizzare le funzionalità del client avanzato, puoi creare una classe di dati Java per lavorare con la tabella. È necessario esaminare la tabella DynamoDB e aggiungere le annotazioni necessarie alla classe di dati.
Prima di lavorare con una tabella esistente, chiamate il metodo. `DynamoDbEnhanced.table()` Ciò è stato fatto nell'esempio precedente con la seguente dichiarazione.
```
DynamoDbTable customerTable = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class));
```
Dopo la restituzione dell'`DynamoDbTable`istanza, potete iniziare subito a lavorare con la tabella sottostante. Non è necessario ricreare la tabella chiamando il `DynamoDbTable.createTable()` metodo.
L'esempio seguente lo dimostra recuperando immediatamente un'`Customer`istanza dalla tabella 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**
Il nome della tabella utilizzato nel `table()` metodo deve corrispondere al nome della tabella DynamoDB esistente.