CUSTOMER_SCHEMA =
StaticTableSchema.builder(Customer.class)
.newItemSupplier(Customer::new)
.addAttribute(String.class, a -> a.name("name")
.getter(Customer::getName)
.setter(Customer::setName))
// Because we are flattening a component object, we supply a getter and setter so the
// mapper knows how to access it.
.flatten(GENERIC_RECORD_SCHEMA, Customer::getRecord, Customer::setRecord)
.build();
```
先前的靜態結構描述範例使用下列資料類別。
#### 資料類別
------
#### [ Standard data class ]
```
public class Customer {
private String name;
private GenericRecord record;
public String getName() { return this.name; }
public void setName(String name) { this.name = name; }
public GenericRecord getRecord() { return this.record; }
public void setRecord(GenericRecord record) { this.record = record; }
public class GenericRecord {
private String id;
private String createdDate;
public String getId() { return this.id; }
public void setId(String id) { this.id = id; }
public String getCreatedDate() { return this.createdDate; }
public void setCreatedDate(String createdDate) { this.createdDate = createdDate; }
}
```
------
#### [ Lombok ]
```
@Data
public class Customer {
private String name;
private GenericRecord record;
}
@Data
public class GenericRecord {
private String id;
private String createdDate;
}
```
------
您可以使用建置器模式，視需要水平化任意數量的不同合格類別。
## 對其他程式碼的影響
當您使用 `@DynamoDbFlatten` 屬性 （或`flatten()`建置器方法） 時，DynamoDB 中的項目會包含所撰寫物件的每個屬性的屬性。它還包含編寫物件的屬性。
相反地，如果您使用編寫的類別註釋資料類別，但不使用 `@DynamoDbFlatten`，則項目會與編寫的物件一起儲存為單一屬性。
例如，比較平面化中顯示的`Customer`類別與合成範例，包含和不包含`record`屬性的平面化。 [使用註釋的 Bean](#ddb-en-client-adv-features-flatmap-comp-anno)您可以使用 JSON 視覺化差異，如下表所示。
****
| 使用平面化 | 沒有扁平化 |
| --- | --- |
| 3 個屬性 | 2 個屬性 |
| {
"id": "1",
"createdDate": "today",
"name": "my name"
} | {
"id": "1",
"record": {
"createdDate": "today",
"name": "my name"
}
} |
如果您有其他程式碼存取預期尋找特定屬性的 DynamoDB 資料表，差異就變得很重要。
# 使用 Bean、地圖、清單和集合等屬性
Bean 定義，例如如下所示的`Person`類別，可能會定義參考具有其他屬性之類型的屬性 （或屬性）。例如，在 `Person`類別中， `mainAddress` 是一個屬性，是指定義其他值屬性的 `Address` Bean。 `addresses` 是指 Java Map，其元素是指 `Address` Bean。這些複雜類型可視為您在 DynamoDB 內容中用於其資料值的簡單屬性容器。
DynamoDB 是指巢狀元素的值屬性，例如地圖、清單或 Bean，做為*巢狀屬性*。[Amazon DynamoDB 開發人員指南](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)是指儲存形式的 Java 映射、清單或 Bean 做為*文件類型*。您在 Java 中用於其資料值的簡單屬性在 DynamoDB 中稱為*純量類型*。集合，其中包含相同類型的多個純量元素，稱為*集合類型*。
請務必了解，DynamoDB 增強型用戶端 API 會在儲存時將 Bean 的屬性轉換為 DynamoDB 映射文件類型。
## `Person` 類別
```
@DynamoDbBean
public class Person {
private Integer id;
private String firstName;
private String lastName;
private Integer age;
private Address mainAddress;
private Map addresses;
private List phoneNumbers;
private Set hobbies;
@DynamoDbPartitionKey
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getFirstName() {
return firstName;
}
public void setFirstName(String firstName) {
this.firstName = firstName;
}
public String getLastName() {
return lastName;
}
public void setLastName(String lastName) {
this.lastName = lastName;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
public Address getMainAddress() {
return mainAddress;
}
public void setMainAddress(Address mainAddress) {
this.mainAddress = mainAddress;
}
public Map getAddresses() {
return addresses;
}
public void setAddresses(Map addresses) {
this.addresses = addresses;
}
public List getPhoneNumbers() {
return phoneNumbers;
}
public void setPhoneNumbers(List phoneNumbers) {
this.phoneNumbers = phoneNumbers;
}
public Set getHobbies() {
return hobbies;
}
public void setHobbies(Set hobbies) {
this.hobbies = hobbies;
}
@Override
public String toString() {
return "Person{" +
"addresses=" + addresses +
", id=" + id +
", firstName='" + firstName + '\'' +
", lastName='" + lastName + '\'' +
", age=" + age +
", mainAddress=" + mainAddress +
", phoneNumbers=" + phoneNumbers +
", hobbies=" + hobbies +
'}';
}
}
```
## `Address` 類別
```
@DynamoDbBean
public class Address {
private String street;
private String city;
private String state;
private String zipCode;
public Address() {
}
public String getStreet() {
return this.street;
}
public String getCity() {
return this.city;
}
public String getState() {
return this.state;
}
public String getZipCode() {
return this.zipCode;
}
public void setStreet(String street) {
this.street = street;
}
public void setCity(String city) {
this.city = city;
}
public void setState(String state) {
this.state = state;
}
public void setZipCode(String zipCode) {
this.zipCode = zipCode;
}
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (o == null || getClass() != o.getClass()) return false;
Address address = (Address) o;
return Objects.equals(street, address.street) && Objects.equals(city, address.city) && Objects.equals(state, address.state) && Objects.equals(zipCode, address.zipCode);
}
@Override
public int hashCode() {
return Objects.hash(street, city, state, zipCode);
}
@Override
public String toString() {
return "Address{" +
"street='" + street + '\'' +
", city='" + city + '\'' +
", state='" + state + '\'' +
", zipCode='" + zipCode + '\'' +
'}';
}
}
```
## `PhoneNumber` 類別
```
@DynamoDbBean
public class PhoneNumber {
String type;
String number;
public String getType() {
return type;
}
public void setType(String type) {
this.type = type;
}
public String getNumber() {
return number;
}
public void setNumber(String number) {
this.number = number;
}
@Override
public String toString() {
return "PhoneNumber{" +
"type='" + type + '\'' +
", number='" + number + '\'' +
'}';
}
}
```
## 儲存複雜類型
### 使用標註的資料類別
您只需註釋自訂類別，即可儲存這些類別的巢狀屬性。先前顯示的`Address`類別和`PhoneNumber`類別只會以`@DynamoDbBean`註釋標註。當 DynamoDB 增強型用戶端 API 使用以下程式碼片段建置`Person`類別的資料表結構描述時，API 會探索 `Address`和 `PhoneNumber`類別的使用，並建置對應的映射以搭配 DynamoDB 使用。
```
TableSchema personTableSchema = TableSchema.fromBean(Person.class);
```
### 搭配建置器使用抽象結構描述
替代方法是針對每個巢狀 Bean 類別使用靜態資料表結構描述建置器，如下列程式碼所示。
`Address` 和 `PhoneNumber`類別的資料表結構描述抽象，因為它們無法與 DynamoDB 資料表搭配使用。這是因為它們缺少主索引鍵的定義。不過，它們會在 `Person`類別的資料表結構描述中用作巢狀結構描述。
在 定義的註解行 1 和 2 之後`PERSON_TABLE_SCHEMA`，您會看到使用抽象資料表結構描述的程式碼。在 `EnhanceType.documentOf(...)` 方法`documentOf`中使用 並不表示 方法傳回 `EnhancedDocument`類型的增強型文件 API。此內容中的 `documentOf(...)`方法會傳回 物件，該物件知道如何使用資料表結構描述引數將其類別引數對應至 DynamoDB 資料表屬性。
#### 靜態結構描述程式碼
```
// Abstract table schema that cannot be used to work with a DynamoDB table,
// but can be used as a nested schema.
public static final TableSchema TABLE_SCHEMA_ADDRESS = TableSchema.builder(Address.class)
.newItemSupplier(Address::new)
.addAttribute(String.class, a -> a.name("street")
.getter(Address::getStreet)
.setter(Address::setStreet))
.addAttribute(String.class, a -> a.name("city")
.getter(Address::getCity)
.setter(Address::setCity))
.addAttribute(String.class, a -> a.name("zipcode")
.getter(Address::getZipCode)
.setter(Address::setZipCode))
.addAttribute(String.class, a -> a.name("state")
.getter(Address::getState)
.setter(Address::setState))
.build();
// Abstract table schema that cannot be used to work with a DynamoDB table,
// but can be used as a nested schema.
public static final TableSchema TABLE_SCHEMA_PHONENUMBER = TableSchema.builder(PhoneNumber.class)
.newItemSupplier(PhoneNumber::new)
.addAttribute(String.class, a -> a.name("type")
.getter(PhoneNumber::getType)
.setter(PhoneNumber::setType))
.addAttribute(String.class, a -> a.name("number")
.getter(PhoneNumber::getNumber)
.setter(PhoneNumber::setNumber))
.build();
// A static table schema that can be used with a DynamoDB table.
// The table schema contains two nested schemas that are used to perform mapping to/from DynamoDB.
public static final TableSchema PERSON_TABLE_SCHEMA =
TableSchema.builder(Person.class)
.newItemSupplier(Person::new)
.addAttribute(Integer.class, a -> a.name("id")
.getter(Person::getId)
.setter(Person::setId)
.addTag(StaticAttributeTags.primaryPartitionKey()))
.addAttribute(String.class, a -> a.name("firstName")
.getter(Person::getFirstName)
.setter(Person::setFirstName))
.addAttribute(String.class, a -> a.name("lastName")
.getter(Person::getLastName)
.setter(Person::setLastName))
.addAttribute(Integer.class, a -> a.name("age")
.getter(Person::getAge)
.setter(Person::setAge))
.addAttribute(EnhancedType.documentOf(Address.class, TABLE_SCHEMA_ADDRESS), a -> a.name("mainAddress")
.getter(Person::getMainAddress)
.setter(Person::setMainAddress))
.addAttribute(EnhancedType.listOf(String.class), a -> a.name("hobbies")
.getter(Person::getHobbies)
.setter(Person::setHobbies))
.addAttribute(EnhancedType.mapOf(
EnhancedType.of(String.class),
// 1. Use mapping functionality of the Address table schema.
EnhancedType.documentOf(Address.class, TABLE_SCHEMA_ADDRESS)), a -> a.name("addresses")
.getter(Person::getAddresses)
.setter(Person::setAddresses))
.addAttribute(EnhancedType.listOf(
// 2. Use mapping functionality of the PhoneNumber table schema.
EnhancedType.documentOf(PhoneNumber.class, TABLE_SCHEMA_PHONENUMBER)), a -> a.name("phoneNumbers")
.getter(Person::getPhoneNumbers)
.setter(Person::setPhoneNumbers))
.build();
```
## 複雜類型的專案屬性
對於 `query()`和 `scan()`方法，您可以使用 `addNestedAttributeToProject()`和 等方法呼叫，指定要在結果中傳回的屬性`attributesToProject()`。DynamoDB 增強型用戶端 API 在傳送請求之前，會將 Java 方法呼叫參數轉換為[投影表達式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html)。
下列範例會將兩個項目填入`Person`資料表，然後執行三個掃描操作。
第一次掃描會存取資料表中的所有項目，以便將結果與其他掃描操作進行比較。
第二次掃描使用[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#addNestedAttributeToProject(software.amazon.awssdk.enhanced.dynamodb.NestedAttributeName)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#addNestedAttributeToProject(software.amazon.awssdk.enhanced.dynamodb.NestedAttributeName))建置器方法來僅傳回`street`屬性值。
第三個掃描操作使用[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#attributesToProject(java.lang.String...)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/ScanEnhancedRequest.Builder.html#attributesToProject(java.lang.String...))建置器方法來傳回第一層屬性 的資料`hobbies`。的屬性類型`hobbies`是清單。若要存取個別清單項目，請在清單上執行 `get()`操作。
```
personDynamoDbTable = getDynamoDbEnhancedClient().table("Person", PERSON_TABLE_SCHEMA);
PersonUtils.createPersonTable(personDynamoDbTable, getDynamoDbClient());
// Use a utility class to add items to the Person table.
List personList = PersonUtils.getItemsForCount(2);
// This utility method performs a put against DynamoDB to save the instances in the list argument.
PersonUtils.putCollection(getDynamoDbEnhancedClient(), personList, personDynamoDbTable);
// The first scan logs all items in the table to compare to the results of the subsequent scans.
final PageIterable allItems = personDynamoDbTable.scan();
allItems.items().forEach(p ->
// 1. Log what is in the table.
logger.info(p.toString()));
// Scan for nested attributes.
PageIterable streetScanResult = personDynamoDbTable.scan(b -> b
// Use the 'addNestedAttributeToProject()' or 'addNestedAttributesToProject()' to access data nested in maps in DynamoDB.
.addNestedAttributeToProject(
NestedAttributeName.create("addresses", "work", "street")
));
streetScanResult.items().forEach(p ->
//2. Log the results of requesting nested attributes.
logger.info(p.toString()));
// Scan for a top-level list attribute.
PageIterable hobbiesScanResult = personDynamoDbTable.scan(b -> b
// Use the 'attributesToProject()' method to access first-level attributes.
.attributesToProject("hobbies"));
hobbiesScanResult.items().forEach((p) -> {
// 3. Log the results of the request for the 'hobbies' attribute.
logger.info(p.toString());
// To access an item in a list, first get the parent attribute, 'hobbies', then access items in the list.
String hobby = p.getHobbies().get(1);
// 4. Log an item in the list.
logger.info(hobby);
});
```
```
// Logged results from comment line 1.
Person{id=2, firstName='first name 2', lastName='last name 2', age=11, addresses={work=Address{street='street 21', city='city 21', state='state 21', zipCode='33333'}, home=Address{street='street 2', city='city 2', state='state 2', zipCode='22222'}}, phoneNumbers=[PhoneNumber{type='home', number='222-222-2222'}, PhoneNumber{type='work', number='333-333-3333'}], hobbies=[hobby 2, hobby 21]}
Person{id=1, firstName='first name 1', lastName='last name 1', age=11, addresses={work=Address{street='street 11', city='city 11', state='state 11', zipCode='22222'}, home=Address{street='street 1', city='city 1', state='state 1', zipCode='11111'}}, phoneNumbers=[PhoneNumber{type='home', number='111-111-1111'}, PhoneNumber{type='work', number='222-222-2222'}], hobbies=[hobby 1, hobby 11]}
// Logged results from comment line 2.
Person{id=null, firstName='null', lastName='null', age=null, addresses={work=Address{street='street 21', city='null', state='null', zipCode='null'}}, phoneNumbers=null, hobbies=null}
Person{id=null, firstName='null', lastName='null', age=null, addresses={work=Address{street='street 11', city='null', state='null', zipCode='null'}}, phoneNumbers=null, hobbies=null}
// Logged results from comment lines 3 and 4.
Person{id=null, firstName='null', lastName='null', age=null, addresses=null, phoneNumbers=null, hobbies=[hobby 2, hobby 21]}
hobby 21
Person{id=null, firstName='null', lastName='null', age=null, addresses=null, phoneNumbers=null, hobbies=[hobby 1, hobby 11]}
hobby 11
```
**注意**
如果 `attributesToProject()`方法遵循任何其他新增您要投影之屬性的建置器方法，則提供給 的屬性名稱清單會`attributesToProject()`取代所有其他屬性名稱。
在下列程式碼片段中使用`ScanEnhancedRequest`執行個體執行的掃描，只會傳回愛好資料。
```
ScanEnhancedRequest lastOverwrites = ScanEnhancedRequest.builder()
.addNestedAttributeToProject(
NestedAttributeName.create("addresses", "work", "street"))
.addAttributeToProject("firstName")
// If the 'attributesToProject()' method follows other builder methods that add attributes for projection,
// its list of attributes replace all previous attributes.
.attributesToProject("hobbies")
.build();
PageIterable hobbiesOnlyResult = personDynamoDbTable.scan(lastOverwrites);
hobbiesOnlyResult.items().forEach(p ->
logger.info(p.toString()));
// Logged results.
Person{id=null, firstName='null', lastName='null', age=null, addresses=null, phoneNumbers=null, hobbies=[hobby 2, hobby 21]}
Person{id=null, firstName='null', lastName='null', age=null, addresses=null, phoneNumbers=null, hobbies=[hobby 1, hobby 11]}
```
下列程式碼片段會先使用 `attributesToProject()`方法。此排序會保留所有其他請求的屬性。
```
ScanEnhancedRequest attributesPreserved = ScanEnhancedRequest.builder()
// Use 'attributesToProject()' first so that the method call does not replace all other attributes
// that you want to project.
.attributesToProject("firstName")
.addNestedAttributeToProject(
NestedAttributeName.create("addresses", "work", "street"))
.addAttributeToProject("hobbies")
.build();
PageIterable allAttributesResult = personDynamoDbTable.scan(attributesPreserved);
allAttributesResult.items().forEach(p ->
logger.info(p.toString()));
// Logged results.
Person{id=null, firstName='first name 2', lastName='null', age=null, addresses={work=Address{street='street 21', city='null', state='null', zipCode='null'}}, phoneNumbers=null, hobbies=[hobby 2, hobby 21]}
Person{id=null, firstName='first name 1', lastName='null', age=null, addresses={work=Address{street='street 11', city='null', state='null', zipCode='null'}}, phoneNumbers=null, hobbies=[hobby 1, hobby 11]}
```
## 在表達式中使用複雜類型
您可以在表達式中使用複雜類型，例如篩選條件表達式和條件表達式，方法是使用取消參考運算子來導覽複雜類型的結構。對於物件和映射，請使用 `. (dot)`和 來列出元素 `[n]`（元素序號周圍的方括號）。您無法參考集合的個別元素，但您可以使用 [`contains`函數](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions)。
下列範例顯示掃描操作中使用的兩個篩選條件表達式。篩選條件表達式會指定您希望結果中項目的比對條件。此範例使用先前顯示的 `Address`、 `Person`和 `PhoneNumber`類別。
```
public void scanUsingFilterOfNestedAttr() {
// The following is a filter expression for an attribute that is a map of Address objects.
// By using this filter expression, the SDK returns Person objects that have an address
// with 'mailing' as a key and 'MS2' for a state value.
Expression addressFilter = Expression.builder()
.expression("addresses.#type.#field = :value")
.putExpressionName("#type", "mailing")
.putExpressionName("#field", "state")
.putExpressionValue(":value", AttributeValue.builder().s("MS2").build())
.build();
PageIterable addressFilterResults = personDynamoDbTable.scan(rb -> rb.
filterExpression(addressFilter));
addressFilterResults.items().stream().forEach(p -> logger.info("Person: {}", p));
assert addressFilterResults.items().stream().count() == 1;
// The following is a filter expression for an attribute that is a list of phone numbers.
// By using this filter expression, the SDK returns Person objects whose second phone number
// in the list has a type equal to 'cell'.
Expression phoneFilter = Expression.builder()
.expression("phoneNumbers[1].#type = :type")
.putExpressionName("#type", "type")
.putExpressionValue(":type", AttributeValue.builder().s("cell").build())
.build();
PageIterable phoneFilterResults = personDynamoDbTable.scan(rb -> rb
.filterExpression(phoneFilter)
.attributesToProject("id", "firstName", "lastName", "phoneNumbers")
);
phoneFilterResults.items().stream().forEach(p -> logger.info("Person: {}", p));
assert phoneFilterResults.items().stream().count() == 1;
assert phoneFilterResults.items().stream().findFirst().get().getPhoneNumbers().get(1).getType().equals("cell");
}
```
### 填入資料表的協助程式方法
```
public static void populateDatabase() {
Person person1 = new Person();
person1.setId(1);
person1.setFirstName("FirstName1");
person1.setLastName("LastName1");
Address billingAddr1 = new Address();
billingAddr1.setState("BS1");
billingAddr1.setCity("BillingTown1");
Address mailing1 = new Address();
mailing1.setState("MS1");
mailing1.setCity("MailingTown1");
person1.setAddresses(Map.of("billing", billingAddr1, "mailing", mailing1));
PhoneNumber pn1_1 = new PhoneNumber();
pn1_1.setType("work");
pn1_1.setNumber("111-111-1111");
PhoneNumber pn1_2 = new PhoneNumber();
pn1_2.setType("home");
pn1_2.setNumber("222-222-2222");
List phoneNumbers1 = List.of(pn1_1, pn1_2);
person1.setPhoneNumbers(phoneNumbers1);
personDynamoDbTable.putItem(person1);
Person person2 = person1;
person2.setId(2);
person2.setFirstName("FirstName2");
person2.setLastName("LastName2");
Address billingAddress2 = billingAddr1;
billingAddress2.setCity("BillingTown2");
billingAddress2.setState("BS2");
Address mailing2 = mailing1;
mailing2.setCity("MailingTown2");
mailing2.setState("MS2");
person2.setAddresses(Map.of("billing", billingAddress2, "mailing", mailing2));
PhoneNumber pn2_1 = new PhoneNumber();
pn2_1.setType("work");
pn2_1.setNumber("333-333-3333");
PhoneNumber pn2_2 = new PhoneNumber();
pn2_2.setType("cell");
pn2_2.setNumber("444-444-4444");
List phoneNumbers2 = List.of(pn2_1, pn2_2);
person2.setPhoneNumbers(phoneNumbers2);
personDynamoDbTable.putItem(person2);
}
```
### 資料庫中項目的 JSON 表示法
```
{
"id": 1,
"addresses": {
"billing": {
"city": "BillingTown1",
"state": "BS1",
"street": null,
"zipCode": null
},
"mailing": {
"city": "MailingTown1",
"state": "MS1",
"street": null,
"zipCode": null
}
},
"firstName": "FirstName1",
"lastName": "LastName1",
"phoneNumbers": [
{
"number": "111-111-1111",
"type": "work"
},
{
"number": "222-222-2222",
"type": "home"
}
]
}
{
"id": 2,
"addresses": {
"billing": {
"city": "BillingTown2",
"state": "BS2",
"street": null,
"zipCode": null
},
"mailing": {
"city": "MailingTown2",
"state": "MS2",
"street": null,
"zipCode": null
}
},
"firstName": "FirstName2",
"lastName": "LastName2",
"phoneNumbers": [
{
"number": "333-333-3333",
"type": "work"
},
{
"number": "444-444-4444",
"type": "cell"
}
]
}
```
## 更新包含複雜類型的項目
若要更新包含複雜類型的項目，您有兩種基本方法：
+ 方法 1：先擷取項目 （使用 `getItem`)、更新物件，然後呼叫 `DynamoDbTable#updateItem`。
+ 方法 2：不要擷取項目，但建構新的執行個體、設定您要更新的屬性，並透過`DynamoDbTable#updateItem`設定適當的 值將執行個體提交至 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/IgnoreNullsMode.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/IgnoreNullsMode.html) 。此方法不需要您在更新項目之前擷取該項目。
本節中顯示的範例使用先前顯示的 `Address`、 `Person`和 `PhoneNumber`類別。
### 更新方法 1：擷取，然後更新
透過使用此方法，您可以確保更新時不會遺失任何資料。DynamoDB 增強型用戶端 API 會使用儲存在 DynamoDB 中的項目的屬性重新建立 Bean，包括複雜類型的值。然後，您需要使用 getter 和 setter 來更新 bean。此方法的缺點是您先擷取項目所產生的成本。
下列範例示範，如果您在更新項目之前先擷取項目，則不會遺失任何資料。
```
public void retrieveThenUpdateExample() {
// Assume that we ran this code yesterday.
Person person = new Person();
person.setId(1);
person.setFirstName("FirstName");
person.setLastName("LastName");
Address mainAddress = new Address();
mainAddress.setStreet("123 MyStreet");
mainAddress.setCity("MyCity");
mainAddress.setState("MyState");
mainAddress.setZipCode("MyZipCode");
person.setMainAddress(mainAddress);
PhoneNumber homePhone = new PhoneNumber();
homePhone.setNumber("1111111");
homePhone.setType("HOME");
person.setPhoneNumbers(List.of(homePhone));
personDynamoDbTable.putItem(person);
// Assume that we are running this code now.
// First, retrieve the item
Person retrievedPerson = personDynamoDbTable.getItem(Key.builder().partitionValue(1).build());
// Make any updates.
retrievedPerson.getMainAddress().setCity("YourCity");
// Save the updated bean. 'updateItem' returns the bean as it appears after the update.
Person updatedPerson = personDynamoDbTable.updateItem(retrievedPerson);
// Verify for this example.
Address updatedMainAddress = updatedPerson.getMainAddress();
assert updatedMainAddress.getCity().equals("YourCity");
assert updatedMainAddress.getState().equals("MyState"); // Unchanged.
// The list of phone numbers remains; it was not set to null;
assert updatedPerson.getPhoneNumbers().size() == 1;
}
```
### 更新方法 2：使用`IgnoreNullsMode`列舉而不先擷取項目
若要更新 DynamoDB 中的項目，您可以提供只有要更新屬性的新物件，並將其他值保留為 null。使用此方法時，您需要了解 SDK 如何處理物件中的 null 值，以及如何控制行為。
若要指定您希望 SDK 忽略哪些 null 值屬性，請在建置 時提供`IgnoreNullsMode`列舉[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/UpdateItemEnhancedRequest.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/UpdateItemEnhancedRequest.Builder.html)。做為使用其中一個列舉值的範例，下列程式碼片段會使用 `IgnoreNullsMode.SCALAR_ONLY` 模式。
```
// Create a new Person object to update the existing item in DynamoDB.
Person personForUpdate = new Person();
personForUpdate.setId(1);
personForUpdate.setFirstName("updatedFirstName"); // 'firstName' is a top scalar property.
Address addressForUpdate = new Address();
addressForUpdate.setCity("updatedCity");
personForUpdate.setMainAddress(addressForUpdate);
personDynamoDbTable.updateItem(r -> r
.item(personForUpdate)
.ignoreNullsMode(IgnoreNullsMode.SCALAR_ONLY));
/* With IgnoreNullsMode.SCALAR_ONLY provided, The SDK ignores all null properties. The SDK adds or replaces
the 'firstName' property with the provided value, "updatedFirstName". The SDK updates the 'city' value of
'mainAddress', as long as the 'mainAddress' attribute already exists in DynamoDB.
In the background, the SDK generates an update expression that it sends in the request to DynamoDB.
The following JSON object is a simplified version of what it sends. Notice that the SDK includes the paths
to 'mainAddress.city' and 'firstName' in the SET clause of the update expression. No null values in
'personForUpdate' are included.
{
"TableName": "PersonTable",
"Key": {
"id": {
"N": "1"
}
},
"ReturnValues": "ALL_NEW",
"UpdateExpression": "SET #mainAddress.#city = :mainAddress_city, #firstName = :firstName",
"ExpressionAttributeNames": {
"#city": "city",
"#firstName": "firstName",
"#mainAddress": "mainAddress"
},
"ExpressionAttributeValues": {
":firstName": {
"S": "updatedFirstName"
},
":mainAddress_city": {
"S": "updatedCity"
}
}
}
Had we chosen 'IgnoreNullsMode.DEFAULT' instead of 'IgnoreNullsMode.SCALAR_ONLY', the SDK would have included
null values in the "ExpressionAttributeValues" section of the request as shown in the following snippet.
"ExpressionAttributeValues": {
":mainAddress": {
"M": {
"zipCode": {
"NULL": true
},
"city": {
"S": "updatedCity"
},
"street": {
"NULL": true
},
"state": {
"NULL": true
}
}
},
":firstName": {
"S": "updatedFirstName"
}
}
*/
```
Amazon DynamoDB 開發人員指南包含[更新表達式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)的詳細資訊。
#### `IgnoreNullsMode` 選項的說明
+ `IgnoreNullsMode.SCALAR_ONLY` - 使用此設定更新任何層級的純量屬性。SDK 建構的更新陳述式只會將非 Null 純量屬性傳送至 DynamoDB。SDK 會忽略 Bean 或 Map 的 null 值純量屬性，將儲存的值保留在 DynamoDB 中。
當您更新地圖或 Bean 的純量屬性時，地圖必須已存在於 DynamoDB 中。如果您將地圖或 Bean 新增至 DynamoDB 中物件尚未存在的物件，您會取得`DynamoDbException`具有訊息的 *更新表達式中提供的文件路徑無效，無法進行更新*。在更新任何屬性之前，您必須使用 `MAPS_ONLY` 模式來新增 Bean 或映射至 DynamoDB。
+ `IgnoreNullsMode.MAPS_ONLY` - 使用此設定來新增或取代 Bean 或 Map 的屬性。SDK 會取代或新增 物件中提供的任何地圖或 Bean。會忽略物件中為 null 的任何 Bean 或映射，保留 DynamoDB 中存在的映射。
+ `IgnoreNullsMode.DEFAULT` - 使用此設定，軟體開發套件永遠不會忽略 null 值。任何 null 層級的純量屬性都會更新為 null。SDK 會將物件中任何 null 值的 Bean、地圖、清單或設定屬性更新為 DynamoDB 中的 null。當您使用此模式時，或未提供模式，因為它是預設模式，您應該先擷取項目，以便 DynamoDB 中的值不會設定為 null，而此值在物件中提供更新，除非您的意圖是將值設定為 null。
在所有模式下，如果您提供具有非空清單或設定的物件`updateItem`給 ，則清單或集合會儲存到 DynamoDB。
#### 為什麼使用 模式？
當您為物件提供 Bean 或對應至 `updateItem`方法時，軟體開發套件無法判斷是否應該使用 Bean 中的屬性值 （或對應中的項目值） 來更新項目，或者整個 bean/map 是否應該取代儲存到 DynamoDB 的內容。
使用先前顯示項目先擷取的範例，讓我們嘗試更新 `city` 的屬性，`mainAddress`而不進行擷取。
```
/* The retrieval example saved the Person object with a 'mainAddress' property whose 'city' property value is "MyCity".
/* Note that we create a new Person with only the necessary information to update the city value
of the mainAddress. */
Person personForUpdate = new Person();
personForUpdate.setId(1);
// The update we want to make changes the city.
Address mainAddressForUpdate = new Address();
mainAddressForUpdate.setCity("YourCity");
personForUpdate.setMainAddress(mainAddressForUpdate);
// Lets' try the following:
Person updatedPerson = personDynamoDbTable.updateItem(personForUpdate);
/*
Since we haven't retrieved the item, we don't know if the 'mainAddress' property
already exists, so what update expression should the SDK generate?
A) Should it replace or add the 'mainAddress' with the provided object (setting all attributes to null other than city)
as shown in the following simplified JSON?
{
"TableName": "PersonTable",
"Key": {
"id": {
"N": "1"
}
},
"ReturnValues": "ALL_NEW",
"UpdateExpression": "SET #mainAddress = :mainAddress",
"ExpressionAttributeNames": {
"#mainAddress": "mainAddress"
},
"ExpressionAttributeValues": {
":mainAddress": {
"M": {
"zipCode": {
"NULL": true
},
"city": {
"S": "YourCity"
},
"street": {
"NULL": true
},
"state": {
"NULL": true
}
}
}
}
}
B) Or should it update only the 'city' attribute of an existing 'mainAddress' as shown in the following simplified JSON?
{
"TableName": "PersonTable",
"Key": {
"id": {
"N": "1"
}
},
"ReturnValues": "ALL_NEW",
"UpdateExpression": "SET #mainAddress.#city = :mainAddress_city",
"ExpressionAttributeNames": {
"#city": "city",
"#mainAddress": "mainAddress"
},
"ExpressionAttributeValues": {
":mainAddress_city": {
"S": "YourCity"
}
}
}
However, assume that we don't know if the 'mainAddress' already exists. If it doesn't exist, the SDK would try to update
an attribute of a non-existent map, which results in an exception.
In this particular case, we would likely select option B (SCALAR_ONLY) to retain the other values of the 'mainAddress'.
*/
```
下列兩個範例顯示 `MAPS_ONLY`和`SCALAR_ONLY`列舉值的使用。 `MAPS_ONLY` 新增地圖並`SCALAR_ONLY`更新地圖。
##### `IgnoreNullsMode.MAPS_ONLY` 範例
```
public void mapsOnlyModeExample() {
// Assume that we ran this code yesterday.
Person person = new Person();
person.setId(1);
person.setFirstName("FirstName");
personDynamoDbTable.putItem(person);
// Assume that we are running this code now.
/* Note that we create a new Person with only the necessary information to update the city value
of the mainAddress. */
Person personForUpdate = new Person();
personForUpdate.setId(1);
// The update we want to make changes the city.
Address mainAddressForUpdate = new Address();
mainAddressForUpdate.setCity("YourCity");
personForUpdate.setMainAddress(mainAddressForUpdate);
Person updatedPerson = personDynamoDbTable.updateItem(r -> r
.item(personForUpdate)
.ignoreNullsMode(IgnoreNullsMode.MAPS_ONLY)); // Since the mainAddress property does not exist, use MAPS_ONLY mode.
assert updatedPerson.getMainAddress().getCity().equals("YourCity");
assert updatedPerson.getMainAddress().getState() == null;
}
```
##### `IgnoreNullsMode.SCALAR_ONLY example`
```
public void scalarOnlyExample() {
// Assume that we ran this code yesterday.
Person person = new Person();
person.setId(1);
Address mainAddress = new Address();
mainAddress.setCity("MyCity");
mainAddress.setState("MyState");
person.setMainAddress(mainAddress);
personDynamoDbTable.putItem(person);
// Assume that we are running this code now.
/* Note that we create a new Person with only the necessary information to update the city value
of the mainAddress. */
Person personForUpdate = new Person();
personForUpdate.setId(1);
// The update we want to make changes the city.
Address mainAddressForUpdate = new Address();
mainAddressForUpdate.setCity("YourCity");
personForUpdate.setMainAddress(mainAddressForUpdate);
Person updatedPerson = personDynamoDbTable.updateItem(r -> r
.item(personForUpdate)
.ignoreNullsMode(IgnoreNullsMode.SCALAR_ONLY)); // SCALAR_ONLY mode ignores null properties in the in mainAddress.
assert updatedPerson.getMainAddress().getCity().equals("YourCity");
assert updatedPerson.getMainAddress().getState().equals("MyState"); // The state property remains the same.
}
```
請參閱下表，查看每個模式要忽略哪些 null 值。您通常可以使用 `SCALAR_ONLY`和 ，`MAPS_ONLY`但使用 Bean 或 Map 時除外。
**軟體開發套件`updateItem`會忽略每個模式的物件中的哪些 null 值屬性？**
| 屬性類型 | 在 SCALAR\$1ONLY 模式中 | 在 MAPS\$1ONLY 模式中 | 在 DEFAULT 模式中 |
| --- | --- | --- | --- |
| 最高純量 | 是 | 是 | 否 |
| Bean 或 Map | 是 | 是 | 否 |
| Bean 或地圖項目的純量值 | 是 1 | 否2 | 否 |
| 列出或設定 | 是 | 是 | 否 |
1這假設地圖已存在於 DynamoDB 中。您在物件中提供的 Bean 或對應的任何純量值，無論是否為 null，都需要 DynamoDB 中存在該值的路徑。SDK 在提交請求之前，會使用 dereference Operator `. (dot)` 建構屬性的路徑。
2 由於您使用 `MAPS_ONLY` 模式來完全取代或新增 Bean 或 Map，因此 Bean 或 Map 中的所有 null 值都會保留在儲存至 DynamoDB 的地圖中。
# 使用 保留空物件 `@DynamoDbPreserveEmptyObject`
如果您使用空白物件將 Bean 儲存到 Amazon DynamoDB，而且您希望 SDK 在擷取時重新建立空白物件，請使用 註釋內部 Bean 的 getter`@DynamoDbPreserveEmptyObject`。
為了說明註釋的運作方式，程式碼範例會使用下列兩個 Bean。
## 範例 Bean
下列資料類別包含兩個`InnerBean`欄位。getter 方法 `getInnerBeanWithoutAnno()`不會以 標註`@DynamoDbPreserveEmptyObject`。`getInnerBeanWithAnno()` 方法會加上註釋。
```
@DynamoDbBean
public class MyBean {
private String id;
private String name;
private InnerBean innerBeanWithoutAnno;
private InnerBean innerBeanWithAnno;
@DynamoDbPartitionKey
public String getId() { return id; }
public void setId(String id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public InnerBean getInnerBeanWithoutAnno() { return innerBeanWithoutAnno; }
public void setInnerBeanWithoutAnno(InnerBean innerBeanWithoutAnno) { this.innerBeanWithoutAnno = innerBeanWithoutAnno; }
@DynamoDbPreserveEmptyObject
public InnerBean getInnerBeanWithAnno() { return innerBeanWithAnno; }
public void setInnerBeanWithAnno(InnerBean innerBeanWithAnno) { this.innerBeanWithAnno = innerBeanWithAnno; }
@Override
public String toString() {
return new StringJoiner(", ", MyBean.class.getSimpleName() + "[", "]")
.add("innerBeanWithoutAnno=" + innerBeanWithoutAnno)
.add("innerBeanWithAnno=" + innerBeanWithAnno)
.add("id='" + id + "'")
.add("name='" + name + "'")
.toString();
}
}
```
下列`InnerBean`類別的執行個體是 的欄位，`MyBean`並在範例程式碼中初始化為空物件。
```
@DynamoDbBean
public class InnerBean {
private String innerBeanField;
public String getInnerBeanField() {
return innerBeanField;
}
public void setInnerBeanField(String innerBeanField) {
this.innerBeanField = innerBeanField;
}
@Override
public String toString() {
return "InnerBean{" +
"innerBeanField='" + innerBeanField + '\'' +
'}';
}
}
```
下列程式碼範例會將具有初始化內部 Bean 的`MyBean`物件儲存至 DynamoDB，然後擷取項目。記錄的輸出顯示 `innerBeanWithoutAnno` 未初始化，但`innerBeanWithAnno`已建立。
```
public MyBean preserveEmptyObjectAnnoUsingGetItemExample(DynamoDbTable myBeanTable) {
// Save an item to DynamoDB.
MyBean bean = new MyBean();
bean.setId("1");
bean.setInnerBeanWithoutAnno(new InnerBean()); // Instantiate the inner bean.
bean.setInnerBeanWithAnno(new InnerBean()); // Instantiate the inner bean.
myBeanTable.putItem(bean);
GetItemEnhancedRequest request = GetItemEnhancedRequest.builder()
.key(Key.builder().partitionValue("1").build())
.build();
MyBean myBean = myBeanTable.getItem(request);
logger.info(myBean.toString());
// Output 'MyBean[innerBeanWithoutAnno=null, innerBeanWithAnno=InnerBean{innerBeanField='null'}, id='1', name='null']'.
return myBean;
}
```
## 替代靜態結構描述
您可以使用下列`StaticTableSchema`版本的資料表結構描述來取代 Bean 上的註釋。
```
public static TableSchema buildStaticSchemas() {
StaticTableSchema innerBeanStaticTableSchema =
StaticTableSchema.builder(InnerBean.class)
.newItemSupplier(InnerBean::new)
.addAttribute(String.class, a -> a.name("innerBeanField")
.getter(InnerBean::getInnerBeanField)
.setter(InnerBean::setInnerBeanField))
.build();
return StaticTableSchema.builder(MyBean.class)
.newItemSupplier(MyBean::new)
.addAttribute(String.class, a -> a.name("id")
.getter(MyBean::getId)
.setter(MyBean::setId)
.addTag(primaryPartitionKey()))
.addAttribute(String.class, a -> a.name("name")
.getter(MyBean::getName)
.setter(MyBean::setName))
.addAttribute(EnhancedType.documentOf(InnerBean.class,
innerBeanStaticTableSchema),
a -> a.name("innerBean1")
.getter(MyBean::getInnerBeanWithoutAnno)
.setter(MyBean::setInnerBeanWithoutAnno))
.addAttribute(EnhancedType.documentOf(InnerBean.class,
innerBeanStaticTableSchema,
b -> b.preserveEmptyObject(true)),
a -> a.name("innerBean2")
.getter(MyBean::getInnerBeanWithAnno)
.setter(MyBean::setInnerBeanWithAnno))
.build();
}
```
# 避免儲存巢狀物件的 null 屬性
將資料類別物件儲存至 DynamoDB 時，您可以透過套用`@DynamoDbIgnoreNulls`註釋來略過巢狀物件的 null 屬性。相反地，具有 null 值的頂層屬性絕不會儲存到資料庫。
為了說明註釋的運作方式，程式碼範例會使用下列兩個 Bean。
## 範例 Bean
下列資料類別包含兩個`InnerBean`欄位。不會註釋 getter 方法 `getInnerBeanWithoutAnno()`。`getInnerBeanWithIgnoreNullsAnno()` 方法會以 標註`@DynamoDbIgnoreNulls`。
```
@DynamoDbBean
public class MyBean {
private String id;
private String name;
private InnerBean innerBeanWithoutAnno;
private InnerBean innerBeanWithIgnoreNullsAnno;
@DynamoDbPartitionKey
public String getId() { return id; }
public void setId(String id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public InnerBean getInnerBeanWithoutAnno() { return innerBeanWithoutAnno; }
public void setInnerBeanWithoutAnno(InnerBean innerBeanWithoutAnno) { this.innerBeanWithoutAnno = innerBeanWithoutAnno; }
@DynamoDbIgnoreNulls
public InnerBean getInnerBeanWithIgnoreNullsAnno() { return innerBeanWithIgnoreNullsAnno; }
public void setInnerBeanWithIgnoreNullsAnno(InnerBean innerBeanWithAnno) { this.innerBeanWithIgnoreNullsAnno = innerBeanWithAnno; }
@Override
public String toString() {
return new StringJoiner(", ", MyBean.class.getSimpleName() + "[", "]")
.add("innerBeanWithoutAnno=" + innerBeanWithoutAnno)
.add("innerBeanWithIgnoreNullsAnno=" + innerBeanWithIgnoreNullsAnno)
.add("id='" + id + "'")
.add("name='" + name + "'")
.toString();
}
}
```
下列`InnerBean`類別的執行個體是 的欄位，`MyBean`並用於下列範例程式碼。
```
@DynamoDbBean
public class InnerBean {
private String innerBeanFieldString;
private Integer innerBeanFieldInteger;
public String getInnerBeanFieldString() { return innerBeanFieldString; }
public void setInnerBeanFieldString(String innerBeanFieldString) { this.innerBeanFieldString = innerBeanFieldString; }
public Integer getInnerBeanFieldInteger() { return innerBeanFieldInteger; }
public void setInnerBeanFieldInteger(Integer innerBeanFieldInteger) { this.innerBeanFieldInteger = innerBeanFieldInteger; }
@Override
public String toString() {
return new StringJoiner(", ", InnerBean.class.getSimpleName() + "[", "]")
.add("innerBeanFieldString='" + innerBeanFieldString + "'")
.add("innerBeanFieldInteger=" + innerBeanFieldInteger)
.toString();
}
}
```
下列程式碼範例會建立 `InnerBean` 物件，並使用 值僅設定其兩個屬性的其中之一。
```
public void ignoreNullsAnnoUsingPutItemExample(DynamoDbTable myBeanTable) {
// Create an InnerBean object and give only one attribute a value.
InnerBean innerBeanOneAttributeSet = new InnerBean();
innerBeanOneAttributeSet.setInnerBeanFieldInteger(200);
// Create a MyBean instance and use the same InnerBean instance both for attributes.
MyBean bean = new MyBean();
bean.setId("1");
bean.setInnerBeanWithoutAnno(innerBeanOneAttributeSet);
bean.setInnerBeanWithIgnoreNullsAnno(innerBeanOneAttributeSet);
Map itemMap = myBeanTable.tableSchema().itemToMap(bean, true);
logger.info(itemMap.toString());
// Log the map that is sent to the database.
// {innerBeanWithIgnoreNullsAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200)}), id=AttributeValue(S=1), innerBeanWithoutAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200), innerBeanFieldString=AttributeValue(NUL=true)})}
// Save the MyBean object to the table.
myBeanTable.putItem(bean);
}
```
若要視覺化傳送至 DynamoDB 的低階資料，程式碼會在儲存`MyBean`物件之前記錄屬性映射。
記錄的輸出顯示`innerBeanWithIgnoreNullsAnno`輸出一個屬性，
```
innerBeanWithIgnoreNullsAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200)})
```
`innerBeanWithoutAnno` 執行個體會輸出兩個屬性。一個屬性的值為 200，另一個是 null 值的屬性。
```
innerBeanWithoutAnno=AttributeValue(M={innerBeanFieldInteger=AttributeValue(N=200), innerBeanFieldString=AttributeValue(NUL=true)})
```
## 屬性映射的 JSON 表示法
下列 JSON 表示法可讓您更輕鬆地查看儲存至 DynamoDB 的資料。
```
{
"id": {
"S": "1"
},
"innerBeanWithIgnoreNullsAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
}
}
},
"innerBeanWithoutAnno": {
"M": {
"innerBeanFieldInteger": {
"N": "200"
},
"innerBeanFieldString": {
"NULL": true
}
}
}
}
```
## 替代靜態結構描述
您可以使用下列`StaticTableSchema`版本的資料表結構描述來放置資料類別註釋。
```
public static TableSchema buildStaticSchemas() {
StaticTableSchema innerBeanStaticTableSchema =
StaticTableSchema.builder(InnerBean.class)
.newItemSupplier(InnerBean::new)
.addAttribute(String.class, a -> a.name("innerBeanFieldString")
.getter(InnerBean::getInnerBeanFieldString)
.setter(InnerBean::setInnerBeanFieldString))
.addAttribute(Integer.class, a -> a.name("innerBeanFieldInteger")
.getter(InnerBean::getInnerBeanFieldInteger)
.setter(InnerBean::setInnerBeanFieldInteger))
.build();
return StaticTableSchema.builder(MyBean.class)
.newItemSupplier(MyBean::new)
.addAttribute(String.class, a -> a.name("id")
.getter(MyBean::getId)
.setter(MyBean::setId)
.addTag(primaryPartitionKey()))
.addAttribute(String.class, a -> a.name("name")
.getter(MyBean::getName)
.setter(MyBean::setName))
.addAttribute(EnhancedType.documentOf(InnerBean.class,
innerBeanStaticTableSchema),
a -> a.name("innerBeanWithoutAnno")
.getter(MyBean::getInnerBeanWithoutAnno)
.setter(MyBean::setInnerBeanWithoutAnno))
.addAttribute(EnhancedType.documentOf(InnerBean.class,
innerBeanStaticTableSchema,
b -> b.ignoreNulls(true)),
a -> a.name("innerBeanWithIgnoreNullsAnno")
.getter(MyBean::getInnerBeanWithIgnoreNullsAnno)
.setter(MyBean::setInnerBeanWithIgnoreNullsAnno))
.build();
}
```
# 使用適用於 DynamoDB 的增強型文件 API 處理 JSON 文件
的[增強型文件 API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/package-summary.html) AWS SDK for Java 2.x 旨在使用沒有固定結構描述的文件導向資料。不過，它也可讓您使用自訂類別來映射個別屬性。
增強型文件 API 是 適用於 Java 的 AWS SDK v1.x [文件 API](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html) 的後續版本。
**Contents**
+ [開始使用增強型文件 API](ddb-en-client-doc-api-steps.md)
+ [建立 `DocumentTableSchema`和 `DynamoDbTable`](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema)
+ [建置增強型文件](ddb-en-client-doc-api-steps-create-ed.md)
+ [從 JSON 字串建置](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromJson)
+ [從個別元素建置](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts)
+ [執行 CRUD 操作](ddb-en-client-doc-api-steps-use.md)
+ [將增強型文件屬性作為自訂物件存取](ddb-en-client-doc-api-convert.md)
+ [使用`EnhancedDocument`不含 DynamoDB 的](ddb-en-client-doc-api-standalone.md)
# 開始使用增強型文件 API
增強型文件 API 需要與 DynamoDB 增強型用戶端 API 所需的相同[相依性](ddb-en-client-getting-started.md#ddb-en-client-gs-dep)。它還需要[`DynamoDbEnhancedClient`執行個體](ddb-en-client-getting-started-dynamodbTable.md#ddb-en-client-getting-started-dynamodbTable-eclient)，如本主題開頭所示。
由於增強型文件 API 的發行版本為 2.20.3 AWS SDK for Java 2.x，因此您需要該版本或更高版本。
## 建立 `DocumentTableSchema`和 `DynamoDbTable`
若要使用增強型文件 API 針對 DynamoDB 資料表叫用命令，請將資料表與用戶端 [DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html) 資源物件建立關聯。
增強型用戶端的 `table()`方法會建立`DynamoDbTable`執行個體，並需要 DynamoDB 資料表名稱和 的參數`DocumentTableSchema`。
[DocumentTableSchema](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/DocumentTableSchema.html) 的建置器需要主要索引鍵和一或多個屬性轉換器提供者。`AttributeConverterProvider.defaultProvider()` 方法提供[預設類型的](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/internal/converter/attribute/package-summary.html)轉換器。即使您提供自訂屬性轉換器提供者，也應該指定它。您可以將選用的次要索引鍵新增至建置器。
下列程式碼片段顯示程式碼，該程式碼會產生存放無結構描述`EnhancedDocument`物件的 DynamoDB `person`資料表的用戶端表示法。
```
DynamoDbTable documentDynamoDbTable =
enhancedClient.table("person",
TableSchema.documentSchemaBuilder()
// Specify the primary key attributes.
.addIndexPartitionKey(TableMetadata.primaryIndexName(),"id", AttributeValueType.S)
.addIndexSortKey(TableMetadata.primaryIndexName(), "lastName", AttributeValueType.S)
// Specify attribute converter providers. Minimally add the default one.
.attributeConverterProviders(AttributeConverterProvider.defaultProvider())
.build());
// Call documentTable.createTable() if "person" does not exist in DynamoDB.
// createTable() should be called only one time.
```
以下顯示本節中所用`person`物件的 JSON 表示法。
### JSON `person` 物件
```
{
"id": 1,
"firstName": "Richard",
"lastName": "Roe",
"age": 25,
"addresses":
{
"home": {
"zipCode": "00000",
"city": "Any Town",
"state": "FL",
"street": "123 Any Street"
},
"work": {
"zipCode": "00001",
"city": "Anywhere",
"state": "FL",
"street": "100 Main Street"
}
},
"hobbies": [
"Hobby 1",
"Hobby 2"
],
"phoneNumbers": [
{
"type": "Home",
"number": "555-0100"
},
{
"type": "Work",
"number": "555-0119"
}
]
}
```
# 建置增強型文件
`[EnhancedDocument](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html)` 代表文件類型物件，具有具有巢狀屬性的複雜結構。`EnhancedDocument` 需要最上層屬性，以符合為 指定的主索引鍵屬性`DocumentTableSchema`。其餘內容是任意的，可以包含頂層屬性和深度巢狀屬性。
您可以使用提供數種新增元素方式的建置器來建立`EnhancedDocument`執行個體。
## 從 JSON 字串建置
使用 JSON 字串，您可以在一個方法呼叫`EnhancedDocument`中建置 。下列程式碼片段`EnhancedDocument`會從`jsonPerson()`協助程式方法傳回的 JSON 字串建立 。`jsonPerson()` 方法會傳回先前顯示[的人員物件](ddb-en-client-doc-api-steps.md#ddb-en-client-doc-api-steps-createschema-obj)的 JSON 字串版本。
```
EnhancedDocument document =
EnhancedDocument.builder()
.json( jsonPerson() )
.build());
```
## 從個別元素建置
或者，您可以使用建置器的類型安全方法，從個別元件建置`EnhancedDocument`執行個體。
下列範例會建置`person`增強型文件，類似於上一個範例中從 JSON 字串建置的增強型文件。
```
/* Define the shape of an address map whose JSON representation looks like the following.
Use 'addressMapEnhancedType' in the following EnhancedDocument.builder() to simplify the code.
"home": {
"zipCode": "00000",
"city": "Any Town",
"state": "FL",
"street": "123 Any Street"
}*/
EnhancedType> addressMapEnhancedType =
EnhancedType.mapOf(EnhancedType.of(String.class), EnhancedType.of(String.class));
// Use the builder's typesafe methods to add elements to the enhanced document.
EnhancedDocument personDocument = EnhancedDocument.builder()
.putNumber("id", 50)
.putString("firstName", "Shirley")
.putString("lastName", "Rodriguez")
.putNumber("age", 53)
.putNull("nullAttribute")
.putJson("phoneNumbers", phoneNumbersJSONString())
/* Add the map of addresses whose JSON representation looks like the following.
{
"home": {
"zipCode": "00000",
"city": "Any Town",
"state": "FL",
"street": "123 Any Street"
}
} */
.putMap("addresses", getAddresses(), EnhancedType.of(String.class), addressMapEnhancedType)
.putList("hobbies", List.of("Theater", "Golf"), EnhancedType.of(String.class))
.build();
```
### 協助程式方法
```
private static String phoneNumbersJSONString() {
return " [" +
" {" +
" \"type\": \"Home\"," +
" \"number\": \"555-0140\"" +
" }," +
" {" +
" \"type\": \"Work\"," +
" \"number\": \"555-0155\"" +
" }" +
" ]";
}
private static Map> getAddresses() {
return Map.of(
"home", Map.of(
"zipCode", "00002",
"city", "Any Town",
"state", "ME",
"street", "123 Any Street"));
}
```
# 執行 CRUD 操作
定義`EnhancedDocument`執行個體之後，您可以將其儲存至 DynamoDB 資料表。下列程式碼片段使用從個別元素建立的 [personDocument](ddb-en-client-doc-api-steps-create-ed.md#ddb-en-client-doc-api-steps-create-ed-fromparts)。
```
documentDynamoDbTable.putItem(personDocument);
```
從 DynamoDB 讀取增強型文件執行個體後，您可以使用 getter 擷取個別屬性值，如下列程式碼片段所示，以存取從 儲存的資料`personDocument`。或者，您可以將完整內容擷取至 JSON 字串，如範例程式碼的最後部分所示。
```
// Read the item.
EnhancedDocument personDocFromDb = documentDynamoDbTable.getItem(Key.builder().partitionValue(50).build());
// Access top-level attributes.
logger.info("Name: {} {}", personDocFromDb.getString("firstName"), personDocFromDb.getString("lastName"));
// Name: Shirley Rodriguez
// Typesafe access of a deeply nested attribute. The addressMapEnhancedType shown previously defines the shape of an addresses map.
Map> addresses = personDocFromDb.getMap("addresses", EnhancedType.of(String.class), addressMapEnhancedType);
addresses.keySet().forEach(k -> logger.info(addresses.get(k).toString()));
// {zipCode=00002, city=Any Town, street=123 Any Street, state=ME}
// Alternatively, work with AttributeValue types checking along the way for deeply nested attributes.
Map addressesMap = personDocFromDb.getMapOfUnknownType("addresses");
addressesMap.keySet().forEach((String k) -> {
logger.info("Looking at data for [{}] address", k);
// Looking at data for [home] address
AttributeValue value = addressesMap.get(k);
AttributeValue cityValue = value.m().get("city");
if (cityValue != null) {
logger.info(cityValue.s());
// Any Town
}
});
List phoneNumbers = personDocFromDb.getListOfUnknownType("phoneNumbers");
phoneNumbers.forEach((AttributeValue av) -> {
if (av.hasM()) {
AttributeValue type = av.m().get("type");
if (type.s() != null) {
logger.info("Type of phone: {}", type.s());
// Type of phone: Home
// Type of phone: Work
}
}
});
String jsonPerson = personDocFromDb.toJson();
logger.info(jsonPerson);
// {"firstName":"Shirley","lastName":"Rodriguez","addresses":{"home":{"zipCode":"00002","city":"Any Town","street":"123 Any Street","state":"ME"}},"hobbies":["Theater","Golf"],
// "id":50,"nullAttribute":null,"age":53,"phoneNumbers":[{"number":"555-0140","type":"Home"},{"number":"555-0155","type":"Work"}]}
```
`EnhancedDocument` 執行個體可與 `[DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html)`或 [DynamoDbEnhancedClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.html) 的任何方法搭配使用，以取代映射的資料類別。
# 將增強型文件屬性作為自訂物件存取
除了提供 API 來讀取和寫入具有無結構描述結構的屬性之外，增強型文件 API 還可讓您在自訂類別的執行個體之間轉換屬性。
增強型文件 API 使用[控制屬性轉換](ddb-en-client-adv-features-conversion.md)區段中顯示的 `AttributeConverterProvider`和 `AttributeConverter`，作為 DynamoDB 增強型用戶端 API 的一部分。
在下列範例中，我們使用 `CustomAttributeConverterProvider`搭配其巢狀`AddressConverter`類別來轉換`Address`物件。
此範例顯示您可以混合來自 類別的資料，也可以混合來自視需要建置之結構的資料。此範例也顯示自訂類別可用於巢狀結構的任何層級。此範例中的`Address`物件是映射中使用的值。
```
public static void attributeToAddressClassMappingExample(DynamoDbEnhancedClient enhancedClient, DynamoDbClient standardClient) {
String tableName = "customer";
// Define the DynamoDbTable for an enhanced document.
// The schema builder provides methods for attribute converter providers and keys.
DynamoDbTable documentDynamoDbTable = enhancedClient.table(tableName,
DocumentTableSchema.builder()
// Add the CustomAttributeConverterProvider along with the default when you build the table schema.
.attributeConverterProviders(
List.of(
new CustomAttributeConverterProvider(),
AttributeConverterProvider.defaultProvider()))
.addIndexPartitionKey(TableMetadata.primaryIndexName(), "id", AttributeValueType.N)
.addIndexSortKey(TableMetadata.primaryIndexName(), "lastName", AttributeValueType.S)
.build());
// Create the DynamoDB table if needed.
documentDynamoDbTable.createTable();
waitForTableCreation(tableName, standardClient);
// The getAddressesForCustomMappingExample() helper method that provides 'addresses' shows the use of a custom Address class
// rather than using a Map to hold the address data.
Map addresses = getAddressesForCustomMappingExample();
// Build an EnhancedDocument instance to save an item with a mix of structures defined as needed and static classes.
EnhancedDocument personDocument = EnhancedDocument.builder()
.putNumber("id", 50)
.putString("firstName", "Shirley")
.putString("lastName", "Rodriguez")
.putNumber("age", 53)
.putNull("nullAttribute")
.putJson("phoneNumbers", phoneNumbersJSONString())
// Note the use of 'EnhancedType.of(Address.class)' instead of the more generic
// 'EnhancedType.mapOf(EnhancedType.of(String.class), EnhancedType.of(String.class))' that was used in a previous example.
.putMap("addresses", addresses, EnhancedType.of(String.class), EnhancedType.of(Address.class))
.putList("hobbies", List.of("Hobby 1", "Hobby 2"), EnhancedType.of(String.class))
.build();
// Save the item to DynamoDB.
documentDynamoDbTable.putItem(personDocument);
// Retrieve the item just saved.
EnhancedDocument srPerson = documentDynamoDbTable.getItem(Key.builder().partitionValue(50).sortValue("Rodriguez").build());
// Access the addresses attribute.
Map srAddresses = srPerson.get("addresses",
EnhancedType.mapOf(EnhancedType.of(String.class), EnhancedType.of(Address.class)));
srAddresses.keySet().forEach(k -> logger.info(addresses.get(k).toString()));
documentDynamoDbTable.deleteTable();
// The content logged to the console shows that the saved maps were converted to Address instances.
Address{street='123 Main Street', city='Any Town', state='NC', zipCode='00000'}
Address{street='100 Any Street', city='Any Town', state='NC', zipCode='00000'}
```
## `CustomAttributeConverterProvider`代碼
```
public class CustomAttributeConverterProvider implements AttributeConverterProvider {
private final Map, AttributeConverter> converterCache = ImmutableMap.of(
// 1. Add AddressConverter to the internal cache.
EnhancedType.of(Address.class), new AddressConverter());
public static CustomAttributeConverterProvider create() {
return new CustomAttributeConverterProvider();
}
// 2. The enhanced client queries the provider for attribute converters if it
// encounters a type that it does not know how to convert.
@SuppressWarnings("unchecked")
@Override
public AttributeConverter converterFor(EnhancedType enhancedType) {
return (AttributeConverter) converterCache.get(enhancedType);
}
// 3. Custom attribute converter
private class AddressConverter implements AttributeConverter {
// 4. Transform an Address object into a DynamoDB map.
@Override
public AttributeValue transformFrom(Address address) {
Map attributeValueMap = Map.of(
"street", AttributeValue.fromS(address.getStreet()),
"city", AttributeValue.fromS(address.getCity()),
"state", AttributeValue.fromS(address.getState()),
"zipCode", AttributeValue.fromS(address.getZipCode()));
return AttributeValue.fromM(attributeValueMap);
}
// 5. Transform the DynamoDB map attribute to an Address oject.
@Override
public Address transformTo(AttributeValue attributeValue) {
Map m = attributeValue.m();
Address address = new Address();
address.setStreet(m.get("street").s());
address.setCity(m.get("city").s());
address.setState(m.get("state").s());
address.setZipCode(m.get("zipCode").s());
return address;
}
@Override
public EnhancedType type() {
return EnhancedType.of(Address.class);
}
@Override
public AttributeValueType attributeValueType() {
return AttributeValueType.M;
}
}
}
```
## `Address` 類別
```
public class Address {
private String street;
private String city;
private String state;
private String zipCode;
public Address() {
}
public String getStreet() {
return this.street;
}
public String getCity() {
return this.city;
}
public String getState() {
return this.state;
}
public String getZipCode() {
return this.zipCode;
}
public void setStreet(String street) {
this.street = street;
}
public void setCity(String city) {
this.city = city;
}
public void setState(String state) {
this.state = state;
}
public void setZipCode(String zipCode) {
this.zipCode = zipCode;
}
}
```
## 提供地址的協助程式方法
下列協助程式方法提供使用自訂`Address`執行個體做為值的映射，而非一般`Map`執行個體做為值。
```
private static Map getAddressesForCustomMappingExample() {
Address homeAddress = new Address();
homeAddress.setStreet("100 Any Street");
homeAddress.setCity("Any Town");
homeAddress.setState("NC");
homeAddress.setZipCode("00000");
Address workAddress = new Address();
workAddress.setStreet("123 Main Street");
workAddress.setCity("Any Town");
workAddress.setState("NC");
workAddress.setZipCode("00000");
return Map.of("home", homeAddress,
"work", workAddress);
}
```
# 使用`EnhancedDocument`不含 DynamoDB 的
雖然您通常使用 執行個體`EnhancedDocument`來讀取和寫入文件類型的 DynamoDB 項目，但它也可以獨立於 DynamoDB 使用。
您可以使用 `EnhancedDocuments` 在 JSON 字串或自訂物件之間轉換為低階映射的 ，`AttributeValues`如下列範例所示。
```
public static void conversionWithoutDynamoDbExample() {
Address address = new Address();
address.setCity("my city");
address.setState("my state");
address.setStreet("my street");
address.setZipCode("00000");
// Build an EnhancedDocument instance for its conversion functionality alone.
EnhancedDocument addressEnhancedDoc = EnhancedDocument.builder()
// Important: You must specify attribute converter providers when you build an EnhancedDocument instance not used with a DynamoDB table.
.attributeConverterProviders(new CustomAttributeConverterProvider(), DefaultAttributeConverterProvider.create())
.put("addressDoc", address, Address.class)
.build();
// Convert address to a low-level item representation.
final Map addressAsAttributeMap = addressEnhancedDoc.getMapOfUnknownType("addressDoc");
logger.info("addressAsAttributeMap: {}", addressAsAttributeMap.toString());
// Convert address to a JSON string.
String addressAsJsonString = addressEnhancedDoc.getJson("addressDoc");
logger.info("addressAsJsonString: {}", addressAsJsonString);
// Convert addressEnhancedDoc back to an Address instance.
Address addressConverted = addressEnhancedDoc.get("addressDoc", Address.class);
logger.info("addressConverted: {}", addressConverted.toString());
}
/* Console output:
addressAsAttributeMap: {zipCode=AttributeValue(S=00000), state=AttributeValue(S=my state), street=AttributeValue(S=my street), city=AttributeValue(S=my city)}
addressAsJsonString: {"zipCode":"00000","state":"my state","street":"my street","city":"my city"}
addressConverted: Address{street='my street', city='my city', state='my state', zipCode='00000'}
*/
```
**注意**
當您使用獨立於 DynamoDB 資料表的增強型文件時，請務必在建置器上明確設定屬性轉換器提供者。
相反地，當增強型文件與 DynamoDB 資料表搭配使用時，文件資料表結構描述會提供轉換器提供者。
# 使用擴充功能自訂 DynamoDB 增強型用戶端操作
DynamoDB 增強型用戶端 API 支援外掛程式擴充功能，可提供映射操作以外的功能。延伸模組使用兩種勾點方法來修改讀取和寫入操作期間的資料：
+ `beforeWrite()` - 在寫入操作發生之前對其進行修改
+ `afterRead()` - 修改讀取操作發生後的結果
有些操作 （例如項目更新） 同時執行寫入和讀取，因此會呼叫這兩種勾點方法。
## 如何載入延伸模組
延伸項目會依照您在增強型用戶端建置器中指定的順序載入。負載順序可能很重要，因為一個延伸模組可以對先前延伸模組轉換的值採取行動。
根據預設，增強型用戶端會載入兩個延伸模組：
+ `[VersionedRecordExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/VersionedRecordExtension.html)` - 提供樂觀鎖定
+ `[AtomicCounterExtension](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/extensions/AtomicCounterExtension.html)` - 自動遞增計數器屬性
您可以使用增強型用戶端建置器覆寫預設行為，並載入任何延伸。如果您不想要預設副檔名，也可以不指定任何副檔名。
**重要**
如果您載入自己的擴充功能，增強型用戶端不會載入任何預設擴充功能。如果您想要任一預設延伸模組提供的行為，您需要將其明確新增至延伸模組清單。
下列範例顯示如何載入名為 `verifyChecksumExtension`的自訂延伸`VersionedRecordExtension`模組。此範例中`AtomicCounterExtension`不會載入 。
```
DynamoDbEnhancedClientExtension versionedRecordExtension = VersionedRecordExtension.builder().build();
DynamoDbEnhancedClient enhancedClient =
DynamoDbEnhancedClient.builder()
.dynamoDbClient(dynamoDbClient)
.extensions(versionedRecordExtension, verifyChecksumExtension)
.build();
```
## 可用的延伸模組詳細資訊和組態
下列各節提供 SDK 中每個可用延伸模組的詳細資訊。
### 使用 實作樂觀鎖定 `VersionedRecordExtension`
`VersionedRecordExtension` 延伸項目會在項目寫入資料庫時遞增和追蹤項目版本號碼，以提供樂觀的鎖定。如果實際持續項目的版本編號與應用程式上次讀取的值不符，則每個寫入都會新增一個條件，導致寫入失敗。
#### Configuration
若要指定要用來追蹤項目版本編號的屬性，請在資料表結構描述中標記數值屬性。
下列程式碼片段指定 `version` 屬性應保留項目版本編號。
```
@DynamoDbVersionAttribute
public Integer getVersion() {...};
public void setVersion(Integer version) {...};
```
等效的靜態資料表結構描述方法會顯示在下列程式碼片段中。
```
.addAttribute(Integer.class, a -> a.name("version")
.getter(Customer::getVersion)
.setter(Customer::setVersion)
// Apply the 'version' tag to the attribute.
.tags(VersionedRecordExtension.AttributeTags.versionAttribute())
```
#### 運作方式
使用 的樂觀鎖定對這些 `DynamoDbEnhancedClient`和 `DynamoDbTable`方法`VersionedRecordExtension`有下列影響：
**`putItem`**
新項目會獲指派初始版本值 0。這可以使用 設定`@DynamoDbVersionAttribute(startAt = X)`。
**`updateItem`**
如果您擷取項目、更新其一或多個屬性，並嘗試儲存變更，則只有在用戶端和伺服器端的版本編號相符時，操作才會成功。
如果成功，版本編號會自動遞增 1。這可以使用 設定`@DynamoDbVersionAttribute(incrementBy = X)`。
**`deleteItem`**
`DynamoDbVersionAttribute` 註釋沒有效果。刪除項目時，您必須手動新增條件表達式。
下列範例新增條件式表達式，以確保已刪除的項目是已讀取的項目。在下列範例中`recordVersion`， Bean 的 屬性以 標註`@DynamoDbVersionAttribute`。
```
// 1. Read the item and get its current version.
Customer item = customerTable.getItem(Key.builder().partitionValue("someId").build());
// `recordVersion` is the bean's attribute that is annotated with `@DynamoDbVersionAttribute`.
AttributeValue currentVersion = item.getRecordVersion();
// 2. Create conditional delete with the `currentVersion` value.
DeleteItemEnhancedRequest deleteItemRequest =
DeleteItemEnhancedRequest.builder()
.key(KEY)
.conditionExpression(Expression.builder()
.expression("recordVersion = :current_version_value")
.putExpressionValue(":current_version_value", currentVersion)
.build()).build();
customerTable.deleteItem(deleteItemRequest);
```
**`transactWriteItems`**
+ `addPutItem`：此方法具有與 相同的行為`putItem`。
+ `addUpdateItem`：此方法具有與 相同的行為`updateItem`。
+ `addDeleteItem`：此方法具有與 相同的行為`deleteItem`。
**`batchWriteItem`**
+ `addPutItem`：此方法具有與 相同的行為`putItem`。
+ `addDeleteItem`：此方法具有與 相同的行為`deleteItem`。
**注意**
DynamoDB 全域資料表在並行更新之間使用[「最後寫入器獲勝」對帳](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/V2globaltables_HowItWorks.html#V2globaltables_HowItWorks.consistency-modes)，其中 DynamoDB 會盡最大努力判斷最後寫入器。如果您使用全域資料表，此「上次寫入器獲勝」政策表示鎖定策略可能無法如預期運作，因為所有複本最終會根據 DynamoDB 決定的上次寫入收斂。
#### 如何停用
若要停用樂觀鎖定，請勿使用 `@DynamoDbVersionAttribute`註釋。
### 使用 實作計數器 `AtomicCounterExtension`
每次記錄寫入資料庫時，`AtomicCounterExtension`延伸項目都會遞增標記的數值屬性。您可以指定開始值和增量值。如果未指定任何值，則開始值會設為 0，而屬性的值會遞增 1。
#### Configuration
若要指定哪個屬性是計數器，請在資料表結構描述`Long`中標記 類型的屬性。
下列程式碼片段顯示 `counter` 屬性的預設開始值和增量值的使用方式。
```
@DynamoDbAtomicCounter
public Long getCounter() {...};
public void setCounter(Long counter) {...};
```
靜態資料表結構描述方法會顯示在下列程式碼片段中。原子計數器延伸使用 10 的開始值，每次寫入記錄時都會將值增加 5。
```
.addAttribute(Integer.class, a -> a.name("counter")
.getter(Customer::getCounter)
.setter(Customer::setCounter)
// Apply the 'atomicCounter' tag to the attribute with start and increment values.
.tags(StaticAttributeTags.atomicCounter(10L, 5L))
```
### 使用 新增時間戳記 `AutoGeneratedTimestampRecordExtension`
每次項目成功寫入資料庫時，`AutoGeneratedTimestampRecordExtension`延伸項目會自動`[Instant](https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html)`使用目前時間戳記更新 類型的標記屬性。預設不會載入此延伸模組。
#### Configuration
若要指定要使用目前時間戳記更新哪個屬性，請在資料表結構描述中標記 `Instant` 屬性。
`lastUpdate` 屬性是下列程式碼片段中延伸項目行為的目標。請注意， 屬性必須是 `Instant`類型的要求。
```
@DynamoDbAutoGeneratedTimestampAttribute
public Instant getLastUpdate() {...}
public void setLastUpdate(Instant lastUpdate) {...}
```
等效的靜態資料表結構描述方法會顯示在下列程式碼片段中。
```
.addAttribute(Instant.class, a -> a.name("lastUpdate")
.getter(Customer::getLastUpdate)
.setter(Customer::setLastUpdate)
// Applying the 'autoGeneratedTimestamp' tag to the attribute.
.tags(AutoGeneratedTimestampRecordExtension.AttributeTags.autoGeneratedTimestampAttribute())
```
### 使用 AutoGeneratedUuidExtension 產生 UUID
`AutoGeneratedUuidExtension` 新記錄寫入資料庫時，延伸項目會產生屬性的唯一 UUID （通用唯一識別符）。使用 Java JDK [UUID.randomUUID()](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html#randomUUID--) 方法，並套用到 類型的屬性`java.lang.String`。預設不會載入此延伸模組。
#### Configuration
`uniqueId` 屬性是下列程式碼片段中延伸項目行為的目標。
```
@AutoGeneratedUuidExtension
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
等效的靜態資料表結構描述方法會顯示在下列程式碼片段中。
```
.addAttribute(String.class, a -> a.name("uniqueId")
.getter(Customer::getUniqueId)
.setter(Customer::setUniqueId)
// Applying the 'autoGeneratedUuid' tag to the attribute.
.tags(AutoGeneratedUuidExtension.AttributeTags.autoGeneratedUuidAttribute())
```
如果您希望延伸模組僅針對 `putItem` 方法填入 UUID，而非針對 `updateItem`方法填入 UUID，請新增[更新行為](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/UpdateBehavior.html)註釋，如下列程式碼片段所示。
```
@AutoGeneratedUuidExtension
@DynamoDbUpdateBehavior(UpdateBehavior.WRITE_IF_NOT_EXISTS)
public String getUniqueId() {...}
public void setUniqueId(String uniqueId) {...}
```
如果您使用靜態資料表結構描述方法，請使用下列同等程式碼。
```
.addAttribute(String.class, a -> a.name("uniqueId")
.getter(Customer::getUniqueId)
.setter(Customer::setUniqueId)
// Applying the 'autoGeneratedUuid' tag to the attribute.
.tags(AutoGeneratedUuidExtension.AttributeTags.autoGeneratedUuidAttribute(),
StaticAttributeTags.updateBehavior(UpdateBehavior.WRITE_IF_NOT_EXISTS))
```
# 自訂延伸模組範例
您可以實作 `DynamoDbEnhancedClientExtension`界面來建立自訂擴充功能。下列自訂延伸類別顯示一種`beforeWrite()`方法，如果資料庫中的項目還沒有`registrationDate`更新表達式，則使用更新表達式來設定屬性。
```
public final class CustomExtension implements DynamoDbEnhancedClientExtension {
// 1. In a custom extension, use an UpdateExpression to define what action to take before
// an item is updated.
@Override
public WriteModification beforeWrite(DynamoDbExtensionContext.BeforeWrite context) {
if ( context.operationContext().tableName().equals("Customer")
&& context.operationName().equals(OperationName.UPDATE_ITEM)) {
return WriteModification.builder()
.updateExpression(createUpdateExpression())
.build();
}
return WriteModification.builder().build(); // Return an "empty" WriteModification instance if the extension should not be applied.
// In this case, if the code is not updating an item on the Customer table.
}
private static UpdateExpression createUpdateExpression() {
// 2. Use a SetAction, a subclass of UpdateAction, to provide the values in the update.
SetAction setAction =
SetAction.builder()
.path("registrationDate")
.value("if_not_exists(registrationDate, :regValue)")
.putExpressionValue(":regValue", AttributeValue.fromS(Instant.now().toString()))
.build();
// 3. Build the UpdateExpression with one or more UpdateAction.
return UpdateExpression.builder()
.addAction(setAction)
.build();
}
}
```
# 非同步使用 DynamoDB 增強型用戶端 API
如果您的應用程式需要非封鎖、非同步呼叫 DynamoDB，您可以使用 [DynamoDbEnhancedAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.html)。它類似於同步實作，但有下列主要差異：
1. 建置 時`DynamoDbEnhancedAsyncClient`，您必須提供標準用戶端的非同步版本 `DynamoDbAsyncClient`，如下列程式碼片段所示。
```
DynamoDbEnhancedAsyncClient enhancedClient =
DynamoDbEnhancedAsyncClient.builder()
.dynamoDbClient(dynamoDbAsyncClient)
.build();
```
1. 傳回單一資料物件的方法會傳回結果`CompletableFuture`的 ，而非僅傳回結果。然後，您的應用程式可以執行其他工作，而不必封鎖結果。下列程式碼片段顯示非同步`getItem()`方法。
```
CompletableFuture result = customerDynamoDbTable.getItem(customer);
// Perform other work here.
return result.join(); // Now block and wait for the result.
```
1. 傳回結果分頁清單的方法會傳回[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/pagination/sync/SdkIterable.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/pagination/sync/SdkIterable.html)同步針對相同方法`DynamoDbEnhanceClient`傳回的 ，[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/async/SdkPublisher.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/async/SdkPublisher.html)而不是 。然後，您的應用程式可以訂閱該發佈者的處理常式，以非同步方式處理結果，而無需封鎖。
```
PagePublisher results = customerDynamoDbTable.query(r -> r.queryConditional(keyEqualTo(k -> k.partitionValue("Smith"))));
results.subscribe(myCustomerResultsProcessor);
// Perform other work and let the processor handle the results asynchronously.
```
如需使用 的更完整範例`SdkPublisher API`，請參閱討論本指南非同步`scan()`方法一節中[的範例](ddb-en-client-use-multirecord.md#ddb-en-client-use-multirecord-scan-async)。
# 資料類別註釋
下表列出可用於資料類別的註釋，並提供本指南中資訊和範例的連結。資料表會依註釋名稱遞增字母順序排序。
**本指南中使用的資料類別註釋**
| 註釋名稱 | 註釋適用於 1 | 它的功能 | 本指南中顯示的位置 |
| --- | --- | --- | --- |
| DynamoDbAtomicCounter | 屬性 2 | 每次將記錄寫入資料庫時，都會遞增標記的數值屬性。 | [簡介和討論。](ddb-en-client-extensions.md#ddb-en-client-extensions-ACE) |
| DynamoDbAttribute | 屬性 | 定義或重新命名映射至 DynamoDB 資料表屬性的 Bean 屬性。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbAutoGeneratedTimestampAttribute | 屬性 | 每次項目成功寫入資料庫時，都會以目前時間戳記更新已標記的屬性 | [簡介和討論](ddb-en-client-extensions.md#ddb-en-client-extensions-AGTE)。 |
| DynamoDbAutoGeneratedUuid | 屬性 | 將新記錄寫入資料庫時，為屬性產生唯一的 UUID （通用唯一識別符）。 | [簡介和討論。](ddb-en-client-extensions.md#ddb-en-client-extensions-AGUE) |
| DynamoDbBean | class | 將資料類別標示為可映射至資料表結構描述。 | 請先在「開始使用」區段中的[客戶類別](ddb-en-client-gs-tableschema.md#ddb-en-client-gs-tableschema-anno-bean-cust)上使用 。本指南中會顯示數個用量。 |
| DynamoDbConvertedBy | 屬性 | 將自訂AttributeConverter與註釋屬性建立關聯。 | [初始討論和範例。](ddb-en-client-adv-features-conversion.md#ddb-en-client-adv-features-conversion-single) |
| DynamoDbFlatten | 屬性 | 扁平化個別 DynamoDB 資料類別的所有屬性，並將其新增為最上層屬性至讀取和寫入資料庫的記錄。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnore | 屬性 | 導致屬性保持未映射。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbIgnoreNulls | 屬性 | 防止儲存巢狀 DynamoDb 物件的 null 屬性。 | [討論和範例。](ddb-en-client-adv-features-ignore-null.md) |
| DynamoDbImmutable | class | 將不可變資料類別標記為可映射至資料表結構描述。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPartitionKey | 屬性 | 將屬性標記為 DynamoDb 資料表的主要分割區索引鍵 （雜湊索引鍵）。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbPreserveEmptyObject | 屬性 | 指定如果對應至註釋屬性的物件沒有資料，則應使用所有 null 欄位初始化物件。 | [討論和範例。](ddb-en-client-adv-features-empty.md) |
| DynamoDbSecondaryPartitionKey | 屬性 | 將屬性標記為全域次要索引的分割區索引鍵。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSecondarySortKey | 屬性 | 將屬性標記為全域或本機次要索引的選用排序索引鍵。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbSortKey | 屬性 | 將屬性標記為選用的主要排序索引鍵 （範圍索引鍵）。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) |
| DynamoDbUpdateBehavior | 屬性 | 指定在 UpdateItem 等 'update' 操作中更新此屬性時的行為。 | [簡介和範例。](ddb-en-client-adv-features-upd-behavior.md) |
| DynamoDbVersionAttribute | 屬性 | 遞增項目版本號碼。 | [簡介和討論。](ddb-en-client-extensions.md#ddb-en-client-extensions-VRE) |
1您可以將屬性層級註釋套用至 getter 或 setter，但不能同時套用兩者。本指南顯示 getter 上的註釋。
2 該術語`property`通常用於封裝在 JavaBean 資料類別中的值。不過，本指南會`attribute`改用 一詞，以符合 DynamoDB 所使用的術語。