使用項目：Java

您可以使用 適用於 Java 的 AWS SDK 文件 API 對資料表中的 Amazon DynamoDB 項目，執行一般的建立、讀取、更新與刪除 (CRUD) 操作。

本節包含 Java 範例，執行數個 Java 文件 API 項目動作及數個完整的工作範例。

放入項目

putItem 方法會將項目存放在資料表中。若已有該項目，其會取代整個項目。若不希望取代整個項目，而是只想要更新特定的屬性，可以使用 updateItem 方法。如需詳細資訊，請參閱 更新項目。

指定選用參數

除了必要的參數之外，您也可為 putItem 方法指定選用的參數。例如，下列 Java 程式碼範例會使用選用參數來指定上傳項目的條件。若無法滿足指定的條件，適用於 Java 的 AWS SDK會擲回 ConditionalCheckFailedException。程式碼範例在 putItem 方法中指定了下列選用參數：

下列範例會使用這些選用參數，新增新的書籍項目。

Item item = new Item()
    .withPrimaryKey("Id", 104)
    .withString("Title", "Book 104 Title")
    .withString("ISBN", "444-4444444444")
    .withNumber("Price", 20)
    .withStringSet("Authors",
        new HashSet<String>(Arrays.asList("Author1", "Author2")));

Map<String, Object> expressionAttributeValues = new HashMap<String, Object>();
expressionAttributeValues.put(":val", "444-4444444444");

PutItemOutcome outcome = table.putItem(
    item,
    "ISBN = :val", // ConditionExpression parameter
    null,          // ExpressionAttributeNames parameter - we're not using it for this example
    expressionAttributeValues);

PutItem 與 JSON 文件

您可以將 JSON 文件以屬性形式存放在 DynamoDB 資料表中。若要執行此作業，請使用 Item 的 withJSON 方法。此方法會剖析 JSON 文件，並將每個元素映射到原生的 DynamoDB 資料類型。

假設您希望存放下列 JSON 文件，其包含可完成特定產品訂單的廠商。

{
    "V01": {
        "Name": "Acme Books",
        "Offices": [ "Seattle" ]
    },
    "V02": {
        "Name": "New Publishers, Inc.",
        "Offices": ["London", "New York"
        ]
    },
    "V03": {
        "Name": "Better Buy Books",
        "Offices": [ "Tokyo", "Los Angeles", "Sydney"
        ]
    }
}

您可以使用 withJSON 方法，將此存放在 ProductCatalog 表，放在名為 VendorInfo 的 Map 屬性中。下列 Java 程式碼範例會示範如何執行此作業。

// Convert the document into a String.  Must escape all double-quotes.
String vendorDocument = "{"
    + "    \"V01\": {"
    + "        \"Name\": \"Acme Books\","
    + "        \"Offices\": [ \"Seattle\" ]"
    + "    },"
    + "    \"V02\": {"
    + "        \"Name\": \"New Publishers, Inc.\","
    + "        \"Offices\": [ \"London\", \"New York\"" + "]" + "},"
    + "    \"V03\": {"
    + "        \"Name\": \"Better Buy Books\","
    +          "\"Offices\": [ \"Tokyo\", \"Los Angeles\", \"Sydney\""
    + "            ]"
    + "        }"
    + "    }";

Item item = new Item()
    .withPrimaryKey("Id", 210)
    .withString("Title", "Book 210 Title")
    .withString("ISBN", "210-2102102102")
    .withNumber("Price", 30)
    .withJSON("VendorInfo", vendorDocument);

PutItemOutcome outcome = table.putItem(item); 

取得項目

若要擷取單一項目，請使用 getItem 物件的 Table 方法。請遵循下列步驟：

下列 Java 程式碼範例示範上述步驟。程式碼會取得具有指定分割區索引鍵的項目。

AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);

Table table = dynamoDB.getTable("ProductCatalog");

Item item = table.getItem("Id", 210);

指定選用參數

除了必要的參數之外，您也可為 getItem 方法指定選用的參數。例如，下列 Java 程式碼範例使用選用方法，只擷取特定的屬性清單，以及指定高度一致性讀取。(若要進一步了解讀取一致性，請參閱「DynamoDB 讀取一致性」。)

您可以使用 ProjectionExpression，只擷取特定的屬性或元素，而非整個項目。ProjectionExpression 可以使用文件路徑，指定最上層或巢狀屬性。如需詳細資訊，請參閱 在 DynamoDB 中使用投影表達式。

getItem 方法的參數不會讓您指定讀取一致性。但您可以建立 GetItemSpec，它會提供低階 GetItem 操作輸入的完整存取。以下程式碼範例會建立 GetItemSpec，然後使用該規格做為 getItem 方法的輸入。

GetItemSpec spec = new GetItemSpec()
    .withPrimaryKey("Id", 206)
    .withProjectionExpression("Id, Title, RelatedItems[0], Reviews.FiveStar")
    .withConsistentRead(true);

Item item = table.getItem(spec);

System.out.println(item.toJSONPretty());

若要將 Item 以可供人閱讀的格式印出，請使用 toJSONPretty 方法。上個範例的輸出類似這樣。

{
  "RelatedItems" : [ 341 ],
  "Reviews" : {
    "FiveStar" : [ "Excellent! Can't recommend it highly enough! Buy it!", "Do yourself a favor and buy this" ]
  },
  "Id" : 123,
  "Title" : "20-Bicycle 123"
}

GetItem 與 JSON 文件

在 PutItem 與 JSON 文件 一節中，您將 JSON 文件存放在名為 VendorInfo 的 Map 屬性中。您可以使用 getItem 方法擷取 JSON 格式的整份文件。或者可以使用文件路徑標記法擷取文件中的部分元素。下列 Java 程式碼範例會示範這些技術。

GetItemSpec spec = new GetItemSpec()
    .withPrimaryKey("Id", 210);

System.out.println("All vendor info:");
spec.withProjectionExpression("VendorInfo");
System.out.println(table.getItem(spec).toJSON());

System.out.println("A single vendor:");
spec.withProjectionExpression("VendorInfo.V03");
System.out.println(table.getItem(spec).toJSON());

System.out.println("First office location for this vendor:");
spec.withProjectionExpression("VendorInfo.V03.Offices[0]");
System.out.println(table.getItem(spec).toJSON());
 

上個範例的輸出類似這樣。

All vendor info:
{"VendorInfo":{"V03":{"Name":"Better Buy Books","Offices":["Tokyo","Los Angeles","Sydney"]},"V02":{"Name":"New Publishers, Inc.","Offices":["London","New York"]},"V01":{"Name":"Acme Books","Offices":["Seattle"]}}}
A single vendor:
{"VendorInfo":{"V03":{"Name":"Better Buy Books","Offices":["Tokyo","Los Angeles","Sydney"]}}}
First office location for a single vendor:
{"VendorInfo":{"V03":{"Offices":["Tokyo"]}}}

GetItemSpec spec = new GetItemSpec()
    .withPrimaryKey("Id", 210)
    .withProjectionExpression("VendorInfo.V01, Title, Price");

Item item = table.getItem(spec);
System.out.println(item.toJSON());

{"VendorInfo":{"V01":{"Name":"Acme Books","Offices":["Seattle"]}},"Price":30,"Title":"Book 210 Title"}

批次寫入：放入和刪除多個項目

批次寫入表示在一個批次中放入和刪除多個項目。您可利用 batchWriteItem 方法，在單一呼叫中對來自一或多個資料表的多個項目執行放入與刪除操作。以下為使用 適用於 Java 的 AWS SDK Document API 寫入或刪除多重項目的步驟。

下列 Java 程式碼範例示範上述步驟。範例會在兩份資料表上執行 batchWriteItem 操作：Forum 和 Thread。對應的 TableWriteItems 物件會定義下列動作：

該程式碼接著會呼叫 batchWriteItem 來執行操作。

AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);

TableWriteItems forumTableWriteItems = new TableWriteItems("Forum")
    .withItemsToPut(
        new Item()
            .withPrimaryKey("Name", "Amazon RDS")
            .withNumber("Threads", 0));

TableWriteItems threadTableWriteItems = new TableWriteItems("Thread")
    .withItemsToPut(
        new Item()
            .withPrimaryKey("ForumName","Amazon RDS","Subject","Amazon RDS Thread 1")
    .withHashAndRangeKeysToDelete("ForumName","Some partition key value", "Amazon S3", "Some sort key value");

BatchWriteItemOutcome outcome = dynamoDB.batchWriteItem(forumTableWriteItems, threadTableWriteItems);

// Code for checking unprocessed items is omitted in this example

如需運作範例，請參閱 範例：使用 適用於 Java 的 AWS SDK Document API 進行批次寫入操作。

批次取得：取得多個項目

您可利用 batchGetItem 方法，從一或多個資料表擷取多個項目。若要擷取單一項目，可以使用 getItem 方法。

請遵循下列步驟：

下列 Java 程式碼範例示範上述步驟。本範例會從 Forum 表擷取兩個項目，從 Thread 表擷取三個項目。

AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);

    TableKeysAndAttributes forumTableKeysAndAttributes = new TableKeysAndAttributes(forumTableName);
    forumTableKeysAndAttributes.addHashOnlyPrimaryKeys("Name",
    "Amazon S3",
    "Amazon DynamoDB");

TableKeysAndAttributes threadTableKeysAndAttributes = new TableKeysAndAttributes(threadTableName);
threadTableKeysAndAttributes.addHashAndRangePrimaryKeys("ForumName", "Subject",
    "Amazon DynamoDB","DynamoDB Thread 1",
    "Amazon DynamoDB","DynamoDB Thread 2",
    "Amazon S3","S3 Thread 1");

BatchGetItemOutcome outcome = dynamoDB.batchGetItem(
    forumTableKeysAndAttributes, threadTableKeysAndAttributes);

for (String tableName : outcome.getTableItems().keySet()) {
    System.out.println("Items in table " + tableName);
    List<Item> items = outcome.getTableItems().get(tableName);
    for (Item item : items) {
        System.out.println(item);
    }
} 

指定選用參數

除了必要的參數之外，您也可在使用 batchGetItem 時指定選用的參數。例如，您可為每個定義的 ProjectionExpression 提供 TableKeysAndAttributes。您如此即可指定要從資料表擷取的屬性。

下列程式碼範例會從 Forum 表擷取兩個項目。withProjectionExpression 參數會指定只擷取 Threads 屬性。

TableKeysAndAttributes forumTableKeysAndAttributes = new TableKeysAndAttributes("Forum")
    .withProjectionExpression("Threads");

forumTableKeysAndAttributes.addHashOnlyPrimaryKeys("Name",
    "Amazon S3",
    "Amazon DynamoDB");

BatchGetItemOutcome outcome = dynamoDB.batchGetItem(forumTableKeysAndAttributes);

更新項目

updateItem 物件的 Table 方法可更新現有的屬性值、新增新的屬性，或是從現有項目中刪除屬性。

updateItem 方法的行為如下：

請遵循下列步驟：

下列 Java 程式碼範例示範上述工作。程式碼會更新 ProductCatalog 表中的書籍項目。其會將新的作者新增到 Authors 集合中，並刪除現有的 ISBN 屬性。它也會將價格減一。

ExpressionAttributeValues 映射內容會用於 UpdateExpression 中。預留位置 :val1 與 :val2，會於執行時期由 Authors 和 Price 的實際值取代。

AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);

Table table = dynamoDB.getTable("ProductCatalog");

Map<String, String> expressionAttributeNames = new HashMap<String, String>();
expressionAttributeNames.put("#A", "Authors");
expressionAttributeNames.put("#P", "Price");
expressionAttributeNames.put("#I", "ISBN");

Map<String, Object> expressionAttributeValues = new HashMap<String, Object>();
expressionAttributeValues.put(":val1",
    new HashSet<String>(Arrays.asList("Author YY","Author ZZ")));
expressionAttributeValues.put(":val2", 1);   //Price

UpdateItemOutcome outcome =  table.updateItem(
    "Id",          // key attribute name
    101,           // key attribute value
    "add #A :val1 set #P = #P - :val2 remove #I", // UpdateExpression
    expressionAttributeNames,
    expressionAttributeValues);

指定選用參數

除了必要的參數之外，您也可以為 updateItem 方法指定選用參數，包括必須滿足才會發生更新的條件。若無法滿足指定的條件，適用於 Java 的 AWS SDK會擲回 ConditionalCheckFailedException。例如，下列 Java 程式碼範例會依據條件，將書籍項目的價格更新為 25。其會指定 ConditionExpression，指出只有在現有價格為 20 時才更新價格。

Table table = dynamoDB.getTable("ProductCatalog");

Map<String, String> expressionAttributeNames = new HashMap<String, String>();
expressionAttributeNames.put("#P", "Price");

Map<String, Object> expressionAttributeValues = new HashMap<String, Object>();
expressionAttributeValues.put(":val1", 25);  // update Price to 25...
expressionAttributeValues.put(":val2", 20);  //...but only if existing Price is 20

UpdateItemOutcome outcome = table.updateItem(
    new PrimaryKey("Id",101),
    "set #P = :val1", // UpdateExpression
    "#P = :val2",     // ConditionExpression
    expressionAttributeNames,
    expressionAttributeValues);

原子計數器

您可以使用 updateItem 來實作原子計數器以增加或減少現有屬性的值，卻不干擾其他寫入請求。若要增加原子計數器，請於使用 UpdateExpression 時搭配 set 動作，將數值新增到類型為 Number 的現有屬性。

下列範例示範這項作業，將 Quantity 屬性加 1。其也同時示範在 ExpressionAttributeNames 中使用 UpdateExpression 參數。

Table table = dynamoDB.getTable("ProductCatalog");

Map<String,String> expressionAttributeNames = new HashMap<String,String>();
expressionAttributeNames.put("#p", "PageCount");

Map<String,Object> expressionAttributeValues = new HashMap<String,Object>();
expressionAttributeValues.put(":val", 1);

UpdateItemOutcome outcome = table.updateItem(
    "Id", 121,
    "set #p = #p + :val",
    expressionAttributeNames,
    expressionAttributeValues);

刪除項目

deleteItem 方法會從資料表刪除項目。您必須提供要刪除項目的主索引鍵。

請遵循下列步驟：

下列 Java 範例示範這些任務。

AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
DynamoDB dynamoDB = new DynamoDB(client);

Table table = dynamoDB.getTable("ProductCatalog");

DeleteItemOutcome outcome = table.deleteItem("Id", 101);

指定選用參數

您可以為 deleteItem 指定選用參數。例如，下列 Java 程式碼範例指定 ConditionExpression，指出只有當書籍不再出版時 (InPublication 屬性為 false)，才能刪除 ProductCatalog 中的書籍項目。

Map<String,Object> expressionAttributeValues = new HashMap<String,Object>();
expressionAttributeValues.put(":val", false);

DeleteItemOutcome outcome = table.deleteItem("Id",103,
    "InPublication = :val",
    null, // ExpressionAttributeNames - not used in this example
    expressionAttributeValues);