本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 適用於 DynamoDB 的 Java 註釋 本節說明可用於將類別和屬性映射至 Amazon DynamoDB 中資料表和屬性的註釋。 如需對應的 Javadoc 文件，請參閱《[適用於 Java 的 AWS SDK API 參考](https://docs.aws.amazon.com/sdk-for-java/latest/reference/)》中的[註釋類型摘要](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/package-summary.html)。 **注意** 在下列註釋中，只需要 `DynamoDBTable` 和 `DynamoDBHashKey`。 **Topics** + [DynamoDBAttribute](#DynamoDBMapper.Annotations.DynamoDBAttribute) + [DynamoDBAutoGeneratedKey](#DynamoDBMapper.Annotations.DynamoDBAutoGeneratedKey) + [DynamoDBAutoGeneratedTimestamp](#DynamoDBMapper.Annotations.DynamoDBAutoGeneratedTimestamp) + [DynamoDBDocument](#DynamoDBMapper.Annotations.DynamoDBDocument) + [DynamoDBHashKey](#DynamoDBMapper.Annotations.DynamoDBHashKey) + [DynamoDBIgnore](#DynamoDBMapper.Annotations.DynamoDBIgnore) + [DynamoDBIndexHashKey](#DynamoDBMapper.Annotations.DynamoDBIndexHashKey) + [DynamoDBIndexRangeKey](#DynamoDBMapper.Annotations.DynamoDBIndexRangeKey) + [DynamoDBRangeKey](#DynamoDBMapper.Annotations.DynamoDBRangeKey) + [DynamoDBTable](#DynamoDBMapper.Annotations.DynamoDBTable) + [DynamoDBTypeConverted](#DynamoDBMapper.Annotations.DynamoDBTypeConverted) + [DynamoDBTyped](#DynamoDBMapper.Annotations.DynamoDBTyped) + [DynamoDBVersionAttribute](#DynamoDBMapper.Annotations.DynamoDBVersionAttribute) ## DynamoDBAttribute 將屬性映射至資料表屬性。每個類別屬性預設會映射至同名的項目屬性。不過，如果名稱不同，您可以使用此註釋將屬性 (property) 映射至屬性 (attribute)。在下列 Java 程式碼片段中，`DynamoDBAttribute` 會將 `BookAuthors` 屬性映射至資料表中的 `Authors` 屬性名稱。 ``` @DynamoDBAttribute(attributeName = "Authors") public List getBookAuthors() { return BookAuthors; } public void setBookAuthors(List BookAuthors) { this.BookAuthors = BookAuthors; } ``` 將物件儲存至資料表時，`DynamoDBMapper` 使用 `Authors` 做為屬性名稱。 ## DynamoDBAutoGeneratedKey 將分割區索引鍵或排序索引鍵屬性標示為自動產生。儲存這些屬性時，`DynamoDBMapper`​ 會產生隨機 [​UUID](http://docs.oracle.com/javase/6/docs/api/java/util/UUID.html)。只有字串屬性才能標示為自動產生的索引鍵。 以下是示範使用自動產生索引鍵參數的範例。 ``` @DynamoDBTable(tableName="AutoGeneratedKeysExample") public class AutoGeneratedKeys { private String id; private String payload; @DynamoDBHashKey(attributeName = "Id") @DynamoDBAutoGeneratedKey public String getId() { return id; } public void setId(String id) { this.id = id; } @DynamoDBAttribute(attributeName="payload") public String getPayload() { return this.payload; } public void setPayload(String payload) { this.payload = payload; } public static void saveItem() { AutoGeneratedKeys obj = new AutoGeneratedKeys(); obj.setPayload("abc123"); // id field is null at this point DynamoDBMapper mapper = new DynamoDBMapper(dynamoDBClient); mapper.save(obj); System.out.println("Object was saved with id " + obj.getId()); } } ``` ## DynamoDBAutoGeneratedTimestamp 自動產生時間戳記。 ``` @DynamoDBAutoGeneratedTimestamp(strategy=DynamoDBAutoGenerateStrategy.ALWAYS) public Date getLastUpdatedDate() { return lastUpdatedDate; } public void setLastUpdatedDate(Date lastUpdatedDate) { this.lastUpdatedDate = lastUpdatedDate; } ``` 或者，可以透過提供策略屬性來定義自動產生策略。預設值為 `ALWAYS`。 ## DynamoDBDocument 指出類別可以序列化為 Amazon DynamoDB 文件。 例如，假設您要將 JSON 文件映射至 Map (`M`) 類型的 DynamoDB 屬性。下列程式碼範例定義包含 Map 類型之巢狀屬性 (Pictures) 的項目。 ``` public class ProductCatalogItem { private Integer id; //partition key private Pictures pictures; /* ...other attributes omitted... */ @DynamoDBHashKey(attributeName="Id") public Integer getId() { return id;} public void setId(Integer id) {this.id = id;} @DynamoDBAttribute(attributeName="Pictures") public Pictures getPictures() { return pictures;} public void setPictures(Pictures pictures) {this.pictures = pictures;} // Additional properties go here. @DynamoDBDocument public static class Pictures { private String frontView; private String rearView; private String sideView; @DynamoDBAttribute(attributeName = "FrontView") public String getFrontView() { return frontView; } public void setFrontView(String frontView) { this.frontView = frontView; } @DynamoDBAttribute(attributeName = "RearView") public String getRearView() { return rearView; } public void setRearView(String rearView) { this.rearView = rearView; } @DynamoDBAttribute(attributeName = "SideView") public String getSideView() { return sideView; } public void setSideView(String sideView) { this.sideView = sideView; } } } ``` 然後您就可儲存新的 `ProductCatalog` 項目，並具有 `Pictures`，如下列範例所示。 ``` ProductCatalogItem item = new ProductCatalogItem(); Pictures pix = new Pictures(); pix.setFrontView("http://example.com/products/123_front.jpg"); pix.setRearView("http://example.com/products/123_rear.jpg"); pix.setSideView("http://example.com/products/123_left_side.jpg"); item.setPictures(pix); item.setId(123); mapper.save(item); ``` 產生的 `ProductCatalog`項目看起來將會如下 (JSON 格式)。 ``` { "Id" : 123 "Pictures" : { "SideView" : "http://example.com/products/123_left_side.jpg", "RearView" : "http://example.com/products/123_rear.jpg", "FrontView" : "http://example.com/products/123_front.jpg" } } ``` ## DynamoDBHashKey 將類別屬性映射至資料表的分割區索引鍵。此屬性必須是純量字串、數字或二進位類型的其中之一。此屬性不能是集合類型。 假設您的 `ProductCatalog` 資料表將 `Id` 作為主索引鍵。下列 Java 程式碼定義 `CatalogItem` 類別，並使用 `@DynamoDBHashKey` 標籤將其 `Id` 屬性映射至 `ProductCatalog` 資料表的主索引鍵。 ``` @DynamoDBTable(tableName="ProductCatalog") public class CatalogItem { private Integer Id; @DynamoDBHashKey(attributeName="Id") public Integer getId() { return Id; } public void setId(Integer Id) { this.Id = Id; } // Additional properties go here. } ``` ## DynamoDBIgnore 指出應該忽略相關聯屬性的 `DynamoDBMapper` 執行個體。將資料儲存至資料表時，`DynamoDBMapper` 不會將此屬性儲存至資料表。 套用至 getter 方法或非模組化屬性的類別欄位。若該註釋是直接套用至類別欄位，則必須在相同的類別宣告相對應的 getter 和 setter。 ## DynamoDBIndexHashKey 將類別屬性映射至全域次要索引的分割區索引鍵。此屬性必須是純量字串、數字或二進位類型的其中之一。此屬性不能是集合類型。 如果您需要對全域次要索引進行 `Query`，請使用此註釋。您必須指定索引名稱 (`globalSecondaryIndexName`)。如果類別屬性的名稱與索引的分割區索引鍵不同，您也必須指定該索引屬性的名稱 (`attributeName`)。 ## DynamoDBIndexRangeKey 將類別屬性映射至全域次要索引或本機次要索引的排序索引鍵。此屬性必須是純量字串、數字或二進位類型的其中之一。此屬性不能是集合類型。 如果您需要對本機次要索引或全域次要索引進行 `Query`，並且想要使用索引的排序索引鍵來縮小您結果的範圍，請使用此註釋。您必須指定索引名稱 (`globalSecondaryIndexName` 或 `localSecondaryIndexName`)。如果類別屬性的名稱與索引的排序索引鍵不同，您也必須指定該索引屬性的名稱 (`attributeName`)。 ## DynamoDBRangeKey 將類別屬性映射至資料表的排序索引鍵。此屬性必須是純量字串、數字或二進位類型的其中之一。它不能是集合類型。 如果主索引鍵是複合 (分割區索引鍵和排序索引鍵)，您可以使用此標籤，將類別欄位映射至排序索引鍵。例如，假設您的 `Reply` 資料表存放論壇主題回覆。每個對話都可以有許多回覆。因此，此資料表的主索引鍵是 `ThreadId` 和 `ReplyDateTime`。分割區索引鍵是 `ThreadId`，而排序索引鍵是 `ReplyDateTime`。 下列 Java 程式碼定義 `Reply` 類別，並將它映射至 `Reply` 資料表。它會使用 `@DynamoDBHashKey` 和 `@DynamoDBRangeKey` 標籤來識別映射至主索引鍵的類別屬性。 ``` @DynamoDBTable(tableName="Reply") public class Reply { private Integer id; private String replyDateTime; @DynamoDBHashKey(attributeName="Id") public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } @DynamoDBRangeKey(attributeName="ReplyDateTime") public String getReplyDateTime() { return replyDateTime; } public void setReplyDateTime(String replyDateTime) { this.replyDateTime = replyDateTime; } // Additional properties go here. } ``` ## DynamoDBTable 識別 DynamoDB 中的目標資料表。下列 Java 程式碼定義 `Developer` 類別，並將它映射至 DynamoDB 中的 `People` 資料表。 ``` @DynamoDBTable(tableName="People") public class Developer { ...} ``` `@DynamoDBTable` 註釋可以予以繼承。任何繼承自 `Developer` 類別的新類別也會映射至 `People` 資料表。例如，假設您建立繼承自 `Lead` 類別的 `Developer` 類別。因為您已將 `Developer` 類別映射至 `People` 資料表，所以也會將 `Lead` 類別物件存放至相同的資料表。 `@DynamoDBTable` 也可以予以覆寫。任何繼承自 `Developer` 類別的新類別預設會映射至相同的 `People` 資料表。不過，您可以覆寫此預設映射。例如，如果您建立繼承自 `Developer` 類別的類別，則可以新增 `@DynamoDBTable` 註釋，明確地將它映射至另一個資料表，如下列 Java 程式碼範例所示。 ``` @DynamoDBTable(tableName="Managers") public class Manager extends Developer { ...} ``` ## DynamoDBTypeConverted 將屬性標示為使用自訂類型轉換器的註釋。可以標註於使用者定義的註釋，以將其他屬性傳遞給 `DynamoDBTypeConverter`。 `DynamoDBTypeConverter` 介面可讓您將自己的任意資料類型映射至 DynamoDB 原生支援的資料類型。如需詳細資訊，請參閱[在 DynamoDB 中映射任意資料](DynamoDBMapper.ArbitraryDataMapping.md)。 ## DynamoDBTyped 覆寫標準屬性類型繫結的註釋。如果套用標準類型的預設屬性繫結，則該類型不需要註釋。 ## DynamoDBVersionAttribute 識別用於存放樂觀鎖定版本編號的類別屬性。`DynamoDBMapper`​ 在儲存新的項目時會將版本編號指派給此屬性，並在每次您更新項目時予以遞增。僅支援數字純量類型。如需資料類型的詳細資訊，請參閱 [資料類型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)。如需版本控制的詳細資訊，請參閱「[含版本編號的 DynamoDB 及樂觀鎖定](DynamoDBMapper.OptimisticLocking.md)」。