本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 舊版低階 DynamoDB API (2011-12-05)
本節記錄舊版 DynamoDB 低階 API (2011-12-05) 中可用的操作。現保留此版本的低階 API，以便與現有應用程式回溯相容。
**新的應用程式應使用目前 API 版本 (2012-08-10)**。如需詳細資訊，請參閱 [DynamoDB API 參考](CurrentAPI.md)。
**注意**
建議您將應用程式移轉至最新的 API 版本 (2012-08-10)，因為新的 DynamoDB 功能不會向後移植到舊版的 API。
**Topics**
+ [BatchGetItem](API_BatchGetItem_v20111205.md)
+ [BatchWriteItem](API_BatchWriteItem_v20111205.md)
+ [CreateTable](API_CreateTable_v20111205.md)
+ [DeleteItem](API_DeleteItem_v20111205.md)
+ [DeleteTable](API_DeleteTable_v20111205.md)
+ [DescribeTables](API_DescribeTables_v20111205.md)
+ [GetItem](API_GetItem_v20111205.md)
+ [ListTables](API_ListTables_v20111205.md)
+ [PutItem](API_PutItem_v20111205.md)
+ [Query](API_Query_v20111205.md)
+ [Scan](API_Scan_v20111205.md)
+ [UpdateItem](API_UpdateItem_v20111205.md)
+ [UpdateTable](API_UpdateTable_v20111205.md)
# BatchGetItem
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
`BatchGetItem` 操作會使用多個資料表的主索引鍵從中傳回多個項目的屬性。單一操作最多可擷取的項目數為 100。此外，擷取的項目數受到 1 MB 大小限制。如果超過回應大小限制，或者因為超出資料表的佈建輸送量，或因為內部處理失敗而傳回部分結果，則 DynamoDB 會傳回 `UnprocessedKeys` 值，以便您重試從下一個要獲取的項目開始的操作。DynamoDB 會自動調整每個頁面傳回的項目數，以便強制執行此限制。例如，即使您要求擷取 100 個項目，但每一個別項目大小為 50 KB，系統也會傳回 20 個項目和適當的 `UnprocessedKeys` 值，以便您取得下一頁的結果。如有需要，應用程式可包含自身的邏輯，將結果頁面組合成一組。
如果因為請求中涉及的每個資料表上佈建輸送量不足而無法處理任何項目，則 DynamoDB 會傳回 `ProvisionedThroughputExceededException` 錯誤。
**注意**
根據預設，`BatchGetItem` 會對請求中每個資料表執行最終一致讀取。如果想改為一致性讀取，可以在每份資料表將 `ConsistentRead` 參數設定為 `true`。
`BatchGetItem` 會平行擷取項目，將回應延遲減至最低。
設計應用程式時，請注意 DynamoDB 不保證傳回的回應中的屬性順序。在 `AttributesToGet` 中包含請求中項目的主索引鍵值，以便協助按項目剖析回應。
如果請求項目不存在，則這些項目的回應中不會傳回任何內容。請求不存在項目會使用最小讀取容量單位，具體值根據讀取類型而定。如需更多詳細資訊，請參閱 [DynamoDB 項目大小和格式](CapacityUnitCalculations.md)。
## 請求
### 語法
```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.BatchGetItem
content-type: application/x-amz-json-1.0
{"RequestItems":
{"Table1":
{"Keys":
[{"HashKeyElement": {"S":"KeyValue1"}, "RangeKeyElement":{"N":"KeyValue2"}},
{"HashKeyElement": {"S":"KeyValue3"}, "RangeKeyElement":{"N":"KeyValue4"}},
{"HashKeyElement": {"S":"KeyValue5"}, "RangeKeyElement":{"N":"KeyValue6"}}],
"AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]},
"Table2":
{"Keys":
[{"HashKeyElement": {"S":"KeyValue4"}},
{"HashKeyElement": {"S":"KeyValue5"}}],
"AttributesToGet": ["AttributeName4", "AttributeName5", "AttributeName6"]
}
}
}
```
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| RequestItems | 要以主索引鍵取得的資料表名稱和對應項目的容器。在請求項目時，每個資料表名稱在每次操作僅能呼叫一次。類型：字串 預設：無 | 是 |
| Table | 包含所要取得的項目的資料表名稱。該項目只是一個字串，用以指定不帶標籤的現有資料表。 類型：字串 預設：無 | 是 |
| Table:Keys | 定義指定資料表中項目的主索引鍵值。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。 類型：金鑰 | 是 |
| Table:AttributesToGet | 指定資料表中的屬性名稱陣列。如果未指定屬性名稱，則會傳回所有屬性。如果有部分屬性未找到，則這些屬性不會出現在結果中。 類型：陣列 | 否 |
| Table:ConsistentRead | 如果設定為 `true`，則會發送一致性讀取，反之則會使用最終一致性。 類型：布林值 | 否 |
## 回應
### 語法
```
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 855
{"Responses":
{"Table1":
{"Items":
[{"AttributeName1": {"S":"AttributeValue"},
"AttributeName2": {"N":"AttributeValue"},
"AttributeName3": {"SS":["AttributeValue", "AttributeValue", "AttributeValue"]}
},
{"AttributeName1": {"S": "AttributeValue"},
"AttributeName2": {"S": "AttributeValue"},
"AttributeName3": {"NS": ["AttributeValue", "AttributeValue", "AttributeValue"]}
}],
"ConsumedCapacityUnits":1},
"Table2":
{"Items":
[{"AttributeName1": {"S":"AttributeValue"},
"AttributeName2": {"N":"AttributeValue"},
"AttributeName3": {"SS":["AttributeValue", "AttributeValue", "AttributeValue"]}
},
{"AttributeName1": {"S": "AttributeValue"},
"AttributeName2": {"S": "AttributeValue"},
"AttributeName3": {"NS": ["AttributeValue", "AttributeValue","AttributeValue"]}
}],
"ConsumedCapacityUnits":1}
},
"UnprocessedKeys":
{"Table3":
{"Keys":
[{"HashKeyElement": {"S":"KeyValue1"}, "RangeKeyElement":{"N":"KeyValue2"}},
{"HashKeyElement": {"S":"KeyValue3"}, "RangeKeyElement":{"N":"KeyValue4"}},
{"HashKeyElement": {"S":"KeyValue5"}, "RangeKeyElement":{"N":"KeyValue6"}}],
"AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]}
}
}
```
****
| 名稱 | 描述 |
| --- | --- |
| Responses | 資料表名稱以及資料表個別項目屬性。類型：映射 |
| Table | 包含項目的資料表名稱。該項目只是一個字串，用以指定不帶標籤的資料表。類型：字串 |
| Items | 符合操作參數的屬性名稱和值的容器。類型：屬性名稱映射，以及其資料類型和值。 |
| ConsumedCapacityUnits | 每個資料表使用的讀取容量單位數目。此值顯示套用至佈建輸送量的數字。請求不存在項目會使用最小讀取容量單位，具體值依讀取類型而定。如需更多資訊，請參閱[DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：數字 |
| UnprocessedKeys | 包含可能因回應大小達到限制，而未在目前回應中處理的資料表及其各自的索引鍵的陣列。`UnprocessedKeys` 值形式與 `RequestItems` 參數相同 (因此該值可直接提供給後續 `BatchGetItem` 操作)。如需詳細資訊，請參閱上述 `RequestItems` 參數。類型：陣列 |
| UnprocessedKeys: Table: Keys | 定義項目及項目相關聯屬性的主索引鍵屬性值。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。類型：屬性名稱值組陣列。 |
| UnprocessedKeys: Table: AttributesToGet | 指定資料表中的屬性名稱。如果未指定屬性名稱，則會傳回所有屬性。如果有部分屬性未找到，則這些屬性不會出現在結果中。 類型：屬性名稱陣列。 |
| UnprocessedKeys: Table: ConsistentRead | 如果設定為 `true`，則指定資料表會使用一致性讀取，反之則會使用最終一致讀取。 類型：布林值。 |
## 特殊錯誤
****
| 錯誤 | 描述 |
| --- | --- |
| ProvisionedThroughputExceededException | 已超出允許的佈建輸送量上限。 |
## 範例
下列範例顯示使用 BatchGetItem 操作的 HTTP POST 請求和回應。如需使用 AWS 開發套件的範例，請參閱 [在 DynamoDB 使用項目和屬性](WorkingWithItems.md)。
### 請求範例
下列範例請求兩個不同資料表的屬性。
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.BatchGetItem
content-type: application/x-amz-json-1.0
content-length: 409
{"RequestItems":
{"comp1":
{"Keys":
[{"HashKeyElement":{"S":"Casey"},"RangeKeyElement":{"N":"1319509152"}},
{"HashKeyElement":{"S":"Dave"},"RangeKeyElement":{"N":"1319509155"}},
{"HashKeyElement":{"S":"Riley"},"RangeKeyElement":{"N":"1319509158"}}],
"AttributesToGet":["user","status"]},
"comp2":
{"Keys":
[{"HashKeyElement":{"S":"Julie"}},{"HashKeyElement":{"S":"Mingus"}}],
"AttributesToGet":["user","friends"]}
}
}
```
### 回應範例
下列範例為回應。
```
HTTP/1.1 200 OK
x-amzn-RequestId: GTPQVRM4VJS792J1UFJTKUBVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 373
Date: Fri, 02 Sep 2011 23:07:39 GMT
{"Responses":
{"comp1":
{"Items":
[{"status":{"S":"online"},"user":{"S":"Casey"}},
{"status":{"S":"working"},"user":{"S":"Riley"}},
{"status":{"S":"running"},"user":{"S":"Dave"}}],
"ConsumedCapacityUnits":1.5},
"comp2":
{"Items":
[{"friends":{"SS":["Elisabeth", "Peter"]},"user":{"S":"Mingus"}},
{"friends":{"SS":["Dave", "Peter"]},"user":{"S":"Julie"}}],
"ConsumedCapacityUnits":1}
},
"UnprocessedKeys":{}
}
```
# BatchWriteItem
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
您可利用此操作，在單一呼叫中放入與刪除多個資料表的數個項目。
您可以使用 `PutItem` 上傳一個項目，並且使用 `DeleteItem` 刪除一個項目。不過，當您想上傳或刪除大量資料，例如從 Amazon EMR (Amazon EMR) 上傳大量資料，或將資料從另一個資料庫遷移至 DynamoDB，`BatchWriteItem` 提供了一種高效率的替代方法。
如果您使用 Java 之類的語言，則可以使用執行緒來平行上傳項目。這增加了應用程序處理執行緒的複雜性。其他語言不支持執行緒。例如，如果使用 PHP，則必須一次上傳或刪除一個項目。在這兩種情況下，`BatchWriteItem` 提供一種替代方法來平行處理指定的放入與刪除操作，讓您運用強大的執行緒集區方法，卻不會增加應用程式的複雜性。
請注意，`BatchWriteItem` 操作中指定的每一個放入和刪除會使用相同的容量單位。不過，由於 `BatchWriteItem` 平行執行指定操作，您會達到更低的延遲。刪除不存在項目上的操作會使用一個寫入容量單位。如需使用的容量單位的詳細資訊，請參閱 [在 DynamoDB 中使用資料表和資料](WorkingWithTables.md)。
使用 `BatchWriteItem` 時，請注意以下限制：
+ **單次請求中的操作上限：**最多可以指定總共 25 項放入或刪除操作，不過請求大小總計不得超過 1 MB (HTTP 承載)。
+ `BatchWriteItem` 操作僅可用於放入和刪除項目。您無法使用該操作來更新現有項目。
+ **不是非敗即成操作：**`BatchWriteItem` 當中指定的個別操作為非敗即成操作，不過 `BatchWriteItem` 整體而言是屬於最佳操作，而不是非敗即成操作。也就是說，在 `BatchWriteItem` 請求中，有些操作可能成功，有些操作可能失敗。失敗的操作會在回應中的 `UnprocessedItems` 欄位傳回。其中有些失敗可能肇因於超出為資料表所設定的佈建輸送量，或是例如網路錯誤的暫時性失敗。您可以調查並選擇性地重新傳送請求。一般而言，您會在迴圈中呼叫 `BatchWriteItem`，在每次更替中檢查未處理項目，並提交一個含有這些未處理項目的新的 `BatchWriteItem` 請求。
+ **不傳回任何項目：**`BatchWriteItem` 是設計來有效地上傳大量資料。這不會提供 `PutItem` 和 `DeleteItem` 的一些複雜性。例如，`DeleteItem` 支援要求主體文中的 `ReturnValues` 欄位請求回應中的刪除項目。`BatchWriteItem` 操作不會傳回回應中的任何項目。
+ 不同於 `PutItem` 和 `DeleteItem`，`BatchWriteItem` 不允許在操作中指定個別寫入請求的條件。
+ 屬性值不可為 Null；字串和二進位類型屬性的長度必須大於零；集合類型屬性不可為空白。具有空值的請求會遭到拒絕，並出現 `ValidationException`。
如果符合以下任一情況，DynamoDB 會拒絕整個批次寫入操作：
+ `BatchWriteItem` 請求中指定的一或多個資料表不存在。
+ 請求中的項目上指定的主索引鍵屬性不符合對應資料表的主索引鍵結構描述。
+ 嘗試在同一 `BatchWriteItem` 請求中的同一個項目上執行多項操作。例如，您不能在同一 `BatchWriteItem` 請求中放入和刪除同一個項目。
+ 請求大小總計超過 1 MB 的請求大小 (HTTP 承載) 限制。
+ 批次中任一個項目超過 64 KB 的項目大小限制。
## 請求
### 語法
```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.BatchGetItem
content-type: application/x-amz-json-1.0
{
"RequestItems" : RequestItems
}
RequestItems
{
"TableName1" : [ Request, Request, ... ],
"TableName2" : [ Request, Request, ... ],
...
}
Request ::=
PutRequest | DeleteRequest
PutRequest ::=
{
"PutRequest" : {
"Item" : {
"Attribute-Name1" : Attribute-Value,
"Attribute-Name2" : Attribute-Value,
...
}
}
}
DeleteRequest ::=
{
"DeleteRequest" : {
"Key" : PrimaryKey-Value
}
}
PrimaryKey-Value ::= HashTypePK | HashAndRangeTypePK
HashTypePK ::=
{
"HashKeyElement" : Attribute-Value
}
HashAndRangeTypePK
{
"HashKeyElement" : Attribute-Value,
"RangeKeyElement" : Attribute-Value,
}
Attribute-Value ::= String | Numeric| Binary | StringSet | NumericSet | BinarySet
Numeric ::=
{
"N": "Number"
}
String ::=
{
"S": "String"
}
Binary ::=
{
"B": "Base64 encoded binary data"
}
StringSet ::=
{
"SS": [ "String1", "String2", ... ]
}
NumberSet ::=
{
"NS": [ "Number1", "Number2", ... ]
}
BinarySet ::=
{
"BS": [ "Binary1", "Binary2", ... ]
}
```
要求主體中的 `RequestItems` JSON 物件會描述您要執行的操作。這些操作依資料表分組。您可以使用 `BatchWriteItem` 來更新或刪除多個資料表的數個項目。對於每個特定寫入請求，您必須確定請求類型 (`PutItem`、`DeleteItem`)，後面附上操作詳細資訊。
+ 對於 `PutRequest`，您要提供項目，也就是屬性及其值的清單。
+ 對於 `DeleteRequest`，您要提供主索引鍵名稱和值。
## 回應
### 語法
以下是回應中傳回的 JSON 內文語法。
```
{
"Responses" : ConsumedCapacityUnitsByTable
"UnprocessedItems" : RequestItems
}
ConsumedCapacityUnitsByTable
{
"TableName1" : { "ConsumedCapacityUnits", : NumericValue },
"TableName2" : { "ConsumedCapacityUnits", : NumericValue },
...
}
RequestItems
This syntax is identical to the one described in the JSON syntax in the request.
```
## 特殊錯誤
沒有此操作特定的錯誤。
## 範例
以下範例顯示 `BatchWriteItem` 操作的 HTTP POST 請求和回應。該請求指定在 Reply (回覆) 和 Thread (主題) 資料表上執行下列操作：
+ 在 Reply (回覆) 資料表中放入一個項目並刪除一個項目
+ 將一個項目放入 Thread (主題) 資料表
如需使用 AWS 開發套件的範例，請參閱 [在 DynamoDB 使用項目和屬性](WorkingWithItems.md)。
### 請求範例
```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.BatchGetItem
content-type: application/x-amz-json-1.0
{
"RequestItems":{
"Reply":[
{
"PutRequest":{
"Item":{
"ReplyDateTime":{
"S":"2012-04-03T11:04:47.034Z"
},
"Id":{
"S":"DynamoDB#DynamoDB Thread 5"
}
}
}
},
{
"DeleteRequest":{
"Key":{
"HashKeyElement":{
"S":"DynamoDB#DynamoDB Thread 4"
},
"RangeKeyElement":{
"S":"oops - accidental row"
}
}
}
}
],
"Thread":[
{
"PutRequest":{
"Item":{
"ForumName":{
"S":"DynamoDB"
},
"Subject":{
"S":"DynamoDB Thread 5"
}
}
}
}
]
}
}
```
### 回應範例
下列範例回應顯示 Thread (主題) 和 Reply (回覆) 資料表上的放入操作成功，以及 Reply (回覆) 資料表上的刪除操作失敗 (例如因超出資料表上的佈建輸送量而導致調節等原因)。在 JSON 回應中，請注意下列事項：
+ `Responses` 物件會顯示 `Thread` 和 `Reply` 資料表兩者都成功執行放入操作而使用一個容量單位。
+ `UnprocessedItems` 物件則會顯示 `Reply` 資料表失敗的刪除操作。然後，您可以發出新的 `BatchWriteItem` 呼叫來解決這些未處理的請求。
```
HTTP/1.1 200 OK
x-amzn-RequestId: G8M9ANLOE5QA26AEUHJKJE0ASBVV4KQNSO5AEMVJF66Q9ASUAAJG
Content-Type: application/x-amz-json-1.0
Content-Length: 536
Date: Thu, 05 Apr 2012 18:22:09 GMT
{
"Responses":{
"Thread":{
"ConsumedCapacityUnits":1.0
},
"Reply":{
"ConsumedCapacityUnits":1.0
}
},
"UnprocessedItems":{
"Reply":[
{
"DeleteRequest":{
"Key":{
"HashKeyElement":{
"S":"DynamoDB#DynamoDB Thread 4"
},
"RangeKeyElement":{
"S":"oops - accidental row"
}
}
}
}
]
}
}
```
# CreateTable
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
`CreateTable` 操作會將新的資料表新增到帳戶。
在與發出請求的 AWS 帳戶和接收請求的 AWS 區域 (例如 dynamodb.us-west-2.amazonaws.com) 相關聯的資料表當中，資料表名稱必須是唯一的。每個 DynamoDB 端點都是完全獨立的。例如，如果有兩個名為 MyTable 的資料表，一個在 dynamodb.us-west-2.amazonaws.com 中，另一個在 dynamodb.us-west-1.amazonaws.com 中，則兩者完全獨立，不會共用任何資料。
`CreateTable` 操作會觸發非同步工作流程以開始建立資料表。DynamoDB 會立即傳回資料表狀態 (`CREATING`)，直到資料表處於 `ACTIVE` 狀態。一旦資料表處於 `ACTIVE` 狀態，您便可執行資料平面操作。
使用 [DescribeTables](API_DescribeTables_v20111205.md) 操作來檢查資料表的狀態。
## 請求
### 語法
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.CreateTable
content-type: application/x-amz-json-1.0
{"TableName":"Table1",
"KeySchema":
{"HashKeyElement":{"AttributeName":"AttributeName1","AttributeType":"S"},
"RangeKeyElement":{"AttributeName":"AttributeName2","AttributeType":"N"}},
"ProvisionedThroughput":{"ReadCapacityUnits":5,"WriteCapacityUnits":10}
}
```
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| TableName | 要建立的資料表名稱。允許的字元為 a-z、A-Z、0-9、\$1 (底線)、- (破折號) 和 . (點)。名稱長度可介於 3 到 255 個字元之間。 類型：字串 | 是 |
| KeySchema | 資料表的主索引鍵 (簡單或複合) 結構。需要 `HashKeyElement` 的名稱值組，且可選用 `RangeKeyElement` 的名稱值組 (僅適用於複合主索引鍵)。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。主索引鍵元素名稱長度可以介於 1 到 255 個字元之間，且沒有字元限制。 AttributeType 的可能值為「S」(字串)、「N」(數字) 或「B」(二進位)。類型：複合主索引鍵的 `HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement` 映射。 | 是 |
| ProvisionedThroughput | 指定資料表的新輸送量，包括 ReadCapacityUnits 與 WriteCapacityUnits 的值。如需詳細資訊，請參閱 [DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 如需目前的最大/最小值，請參閱 [Amazon DynamoDB 中的配額](ServiceQuotas.md)。 類型：陣列 | 是 |
| ProvisionedThroughput: ReadCapacityUnits | 設定 DynamoDB 與其他操作平衡負載之前，所指定資料表每秒所需的最低一致性 `ReadCapacityUnits` 數目。 最終一致讀取操作比一致性讀取負擔更輕，因此每秒 50 次一致性 `ReadCapacityUnits` 的設定可提供每秒 100 次最終一致 `ReadCapacityUnits`。類型：數字 | 是 |
| ProvisionedThroughput: WriteCapacityUnits | 設定 DynamoDB 與其他操作平衡負載之前，所指定資料表每秒所需的最低 WriteCapacityUnits 數目。類型：數字 | 是 |
## 回應
### 語法
```
HTTP/1.1 200 OK
x-amzn-RequestId: CSOC7TJPLR0OOKIRLGOHVAICUFVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 311
Date: Tue, 12 Jul 2011 21:31:03 GMT
{"TableDescription":
{"CreationDateTime":1.310506263362E9,
"KeySchema":
{"HashKeyElement":{"AttributeName":"AttributeName1","AttributeType":"S"},
"RangeKeyElement":{"AttributeName":"AttributeName2","AttributeType":"N"}},
"ProvisionedThroughput":{"ReadCapacityUnits":5,"WriteCapacityUnits":10},
"TableName":"Table1",
"TableStatus":"CREATING"
}
}
```
****
| 名稱 | 描述 |
| --- | --- |
| TableDescription | 資料表屬性的容器。 |
| CreationDateTime | 建立資料表時的 [UNIX epoch 格式](http://www.epochconverter.com/)日期。類型：數字 |
| KeySchema | 資料表的主索引鍵 (簡單或複合) 結構。需要 `HashKeyElement` 的名稱值組，且可選用 `RangeKeyElement` 的名稱值組 (僅適用於複合主索引鍵)。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。類型：複合主索引鍵的 `HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement` 映射。 |
| ProvisionedThroughput | 指定資料表的輸送量，包括 `ReadCapacityUnits` 與 `WriteCapacityUnits` 的值。請參閱 [DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：陣列 |
| ProvisionedThroughput :ReadCapacityUnits | DynamoDB 與其他操作平衡負載之前，每秒所需的最低 `ReadCapacityUnits` 數目。類型：數字 |
| ProvisionedThroughput :WriteCapacityUnits | `WriteCapacityUnits` 與其他操作平衡負載之前，每秒所需的最低 `ReadCapacityUnits` 數目。類型：數字 |
| TableName | 已建立的資料表名稱。 類型：字串 |
| TableStatus | 資料表目前的狀態 (`CREATING`)。一旦資料表處於 `ACTIVE` 狀態，您便可將資料放入其中。使用 [DescribeTables](API_DescribeTables_v20111205.md) API 來檢查資料表狀態。類型：字串 |
## 特殊錯誤
****
| 錯誤 | 描述 |
| --- | --- |
| ResourceInUseException | 嘗試重新建立已存在的資料表。 |
| LimitExceededException | 同步資料表請求數 (`CREATING`、`DELETING` 或 `UPDATING` 狀態) 超出所允許的上限。 如需目前的最大/最小值，請參閱 [Amazon DynamoDB 中的配額](ServiceQuotas.md)。 . |
## 範例
以下範例會使用包含一個字串和數字的複合主索引鍵建立資料表。如需使用 AWS 開發套件的範例，請參閱 [在 DynamoDB 中使用資料表和資料](WorkingWithTables.md)。
### 請求範例
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.CreateTable
content-type: application/x-amz-json-1.0
{"TableName":"comp-table",
"KeySchema":
{"HashKeyElement":{"AttributeName":"user","AttributeType":"S"},
"RangeKeyElement":{"AttributeName":"time","AttributeType":"N"}},
"ProvisionedThroughput":{"ReadCapacityUnits":5,"WriteCapacityUnits":10}
}
```
### 回應範例
```
HTTP/1.1 200 OK
x-amzn-RequestId: CSOC7TJPLR0OOKIRLGOHVAICUFVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 311
Date: Tue, 12 Jul 2011 21:31:03 GMT
{"TableDescription":
{"CreationDateTime":1.310506263362E9,
"KeySchema":
{"HashKeyElement":{"AttributeName":"user","AttributeType":"S"},
"RangeKeyElement":{"AttributeName":"time","AttributeType":"N"}},
"ProvisionedThroughput":{"ReadCapacityUnits":5,"WriteCapacityUnits":10},
"TableName":"comp-table",
"TableStatus":"CREATING"
}
}
```
## 相關動作
+ [DescribeTables](API_DescribeTables_v20111205.md)
+ [DeleteTable](API_DeleteTable_v20111205.md)
# DeleteItem
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
依主索引鍵，刪除資料表中的單一項目。您可以執行條件式刪除操作，在項目存在或者項目具有預期的屬性值時予以刪除。
**注意**
如果指定 `DeleteItem` 而沒有屬性或值，則會刪除項目的所有屬性。
在未指定條件的情況下，`DeleteItem` 一律為等冪操作，在同一個項目或屬性上多次執行*不會*導致錯誤回應。
條件式刪除僅能用於在符合特定條件時刪除項目和屬性。如果符合條件，DynamoDB 會執行刪除。反之則不會刪除項目。
您可以在每次操作對一個屬性執行預期的條件式檢查。
## 請求
### 語法
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.DeleteItem
content-type: application/x-amz-json-1.0
{"TableName":"Table1",
"Key":
{"HashKeyElement":{"S":"AttributeValue1"},"RangeKeyElement":{"N":"AttributeValue2"}},
"Expected":{"AttributeName3":{"Value":{"S":"AttributeValue3"}}},
"ReturnValues":"ALL_OLD"}
}
```
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| TableName | 包含要刪除項目的資料表名稱。 類型：字串 | 是 |
| Key | 定義項目的主索引鍵。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。類型：`HashKeyElement` 對其值的映射和 `RangeKeyElement` 對其值的映射。 | 是 |
| Expected | 指定條件式刪除的屬性。`Expected` 參數可讓您提供屬性名稱，以及 DynamoDB 是否應該檢查屬性值在刪除前是否具有特定值。類型：屬性名稱映射。 | 否 |
| Expected:AttributeName | 條件式放置的屬性的名稱。類型：字串 | 否 |
| Expected:AttributeName: ExpectedAttributeValue | 使用此參數來指定屬性名稱值組的值是否已經存在。如果該項目的 Color (顏色) 屬性不存在，則下列 JSON 符號會刪除項目："Expected" :
{"Color":{"Exists":false}}
下列 JSON 符號會在刪除項目之前檢查名為 Color (顏色) 的屬性是否具有現有值 Yellow (黃色)："Expected" :
{"Color":{"Exists":true},{"Value":{"S":"Yellow"}}}
根據預設，如果使用 `Expected` 參數並提供 `Value`，DynamoDB 會假設屬性存在，且有要取代的目前值。所以您不必指定 `{"Exists":true}`，因為這是暗含的。您可以將請求縮短為："Expected" :
{"Color":{"Value":{"S":"Yellow"}}}
如果指定 `{"Exists":true}` 而無要檢查的屬性值，則 DynamoDB 會傳回錯誤。 | 否 |
| ReturnValues | 如果要在刪除前取得屬性名稱值組，請使用此參數。可能的參數值為 `NONE` (預設) 或 `ALL_OLD`。如果指定 `ALL_OLD`，則會傳回舊項目的內容。如果未提供此參數，或者參數為 `NONE`，則不會傳回任何內容。類型：字串 | 否 |
## 回應
### 語法
```
HTTP/1.1 200 OK
x-amzn-RequestId: CSOC7TJPLR0OOKIRLGOHVAICUFVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 353
Date: Tue, 12 Jul 2011 21:31:03 GMT
{"Attributes":
{"AttributeName3":{"SS":["AttributeValue3","AttributeValue4","AttributeValue5"]},
"AttributeName2":{"S":"AttributeValue2"},
"AttributeName1":{"N":"AttributeValue1"}
},
"ConsumedCapacityUnits":1
}
```
****
| 名稱 | 描述 |
| --- | --- |
| Attributes | 如果 `ReturnValues` 參數在請求中提供為 `ALL_OLD`，則 DynamoDB 會傳回屬性名稱值組陣列 (本質上為已刪除項目)。反之則會在回應包含空集合。類型：屬性名稱值組陣列。 |
| ConsumedCapacityUnits | 操作所使用的寫入容量單位數目。此值顯示套用至佈建輸送量的數字。刪除不存在項目上的請求會使用 1 個寫入容量單位。如需更多資訊，請參閱[DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：數字 |
## 特殊錯誤
****
| 錯誤 | 描述 |
| --- | --- |
| ConditionalCheckFailedException | 條件式檢查失敗。找不到預期的屬性值。 |
## 範例
### 請求範例
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.DeleteItem
content-type: application/x-amz-json-1.0
{"TableName":"comp-table",
"Key":
{"HashKeyElement":{"S":"Mingus"},"RangeKeyElement":{"N":"200"}},
"Expected":
{"status":{"Value":{"S":"shopping"}}},
"ReturnValues":"ALL_OLD"
}
```
### 回應範例
```
HTTP/1.1 200 OK
x-amzn-RequestId: U9809LI6BBFJA5N2R0TB0P017JVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 353
Date: Tue, 12 Jul 2011 22:31:23 GMT
{"Attributes":
{"friends":{"SS":["Dooley","Ben","Daisy"]},
"status":{"S":"shopping"},
"time":{"N":"200"},
"user":{"S":"Mingus"}
},
"ConsumedCapacityUnits":1
}
```
## 相關動作
+ [PutItem](API_PutItem_v20111205.md)
# DeleteTable
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
`DeleteTable` 操作會刪除資料表及其所有項目。在發出 `DeleteTable` 請求後，指定的資料表會處於 `DELETING` 狀態，直到 DynamoDB 完成刪除為止。如果資料表處於 `ACTIVE` 狀態，則可予以刪除。如果資料表處於 `CREATING` 或 `UPDATING` 狀態，則 DynamoDB 會傳回 `ResourceInUseException` 錯誤。如果指定的資料表不存在，則 DynamoDB 會傳回 `ResourceNotFoundException`。如果資料表已處於 `DELETING` 狀態，則不會傳回任何錯誤。
**注意**
DynamoDB 可能會繼續接受 `DELETING` 狀態的資料表的資料平面操作請求 (例如 `GetItem` 和 `PutItem`)，直到資料表刪除完成。
在與發出請求的 AWS 帳戶和接收請求的 AWS 區域 (例如 dynamodb.us-west-1.amazonaws.com) 相關聯的資料表當中，資料表必須是唯一的。每個 DynamoDB 端點都是完全獨立的。例如，如果有兩個名為 MyTable 的資料表，一個在 dynamodb.us-west-2.amazonaws.com 中，另一個在 dynamodb.us-west-1.amazonaws.com 中，則兩者完全獨立，不會共用任何資料；刪除一個資料表並不會同時刪除另一個。
使用 [DescribeTables](API_DescribeTables_v20111205.md) 操作來檢查資料表的狀態。
## 請求
### 語法
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.DeleteTable
content-type: application/x-amz-json-1.0
{"TableName":"Table1"}
```
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| TableName | 要刪除的資料表的名稱。 類型：字串 | 是 |
## 回應
### 語法
```
HTTP/1.1 200 OK
x-amzn-RequestId: 4HONCKIVH1BFUDQ1U68CTG3N27VV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 311
Date: Sun, 14 Aug 2011 22:56:22 GMT
{"TableDescription":
{"CreationDateTime":1.313362508446E9,
"KeySchema":
{"HashKeyElement":{"AttributeName":"user","AttributeType":"S"},
"RangeKeyElement":{"AttributeName":"time","AttributeType":"N"}},
"ProvisionedThroughput":{"ReadCapacityUnits":10,"WriteCapacityUnits":10},
"TableName":"Table1",
"TableStatus":"DELETING"
}
}
```
****
| 名稱 | 描述 |
| --- | --- |
| TableDescription | 資料表屬性的容器。 |
| CreationDateTime | 建立資料表時的日期。類型：數字 |
| KeySchema | 資料表的主索引鍵 (簡單或複合) 結構。需要 `HashKeyElement` 的名稱值組，且可選用 `RangeKeyElement` 的名稱值組 (僅適用於複合主索引鍵)。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。類型：複合主索引鍵的 `HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement` 映射。 |
| ProvisionedThroughput | 指定資料表的輸送量，包括 ReadCapacityUnits 與 WriteCapacityUnits 的值。請參閱 [DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 |
| ProvisionedThroughput: ReadCapacityUnits | DynamoDB 與其他操作平衡負載之前，所指定資料表每秒所需的最低 `ReadCapacityUnits` 數目。類型：數字 |
| ProvisionedThroughput: WriteCapacityUnits | DynamoDB 與其他操作平衡負載之前，所指定資料表每秒所需的最低 `WriteCapacityUnits` 數目。類型：數字 |
| TableName | 已刪除的資料表的名稱。 類型：字串 |
| TableStatus | 資料表目前的狀態 (DELETING)。一旦資料表遭刪除，後續對資料表的請求會傳回 resource not found。使用 [DescribeTables](API_DescribeTables_v20111205.md) 操作來檢查資料表的狀態。類型：字串 |
## 特殊錯誤
****
| 錯誤 | 描述 |
| --- | --- |
| ResourceInUseException | 資料表處於狀態 CREATING 或 UPDATING，而且無法刪除。 |
## 範例
### 請求範例
```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.DeleteTable
content-type: application/x-amz-json-1.0
content-length: 40
{"TableName":"favorite-movies-table"}
```
### 回應範例
```
HTTP/1.1 200 OK
x-amzn-RequestId: 4HONCKIVH1BFUDQ1U68CTG3N27VV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 160
Date: Sun, 14 Aug 2011 17:20:03 GMT
{"TableDescription":
{"CreationDateTime":1.313362508446E9,
"KeySchema":
{"HashKeyElement":{"AttributeName":"name","AttributeType":"S"}},
"TableName":"favorite-movies-table",
"TableStatus":"DELETING"
}
```
## 相關動作
+ [CreateTable](API_CreateTable_v20111205.md)
+ [DescribeTables](API_DescribeTables_v20111205.md)
# DescribeTables
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
傳回資料表相關資訊，包括資料表目前狀態、主索引鍵結構描述以及建立資料表的時間。DescribeTable 結果為最終一致性。如果在建立資料表過程中太早使用 DescribeTable，DynamoDB 會傳回 `ResourceNotFoundException`。如果在更新資料表過程中太早使用 DescribeTable，新值可能無法立即使用。
## 請求
### 語法
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.DescribeTable
content-type: application/x-amz-json-1.0
{"TableName":"Table1"}
```
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| TableName | 要描述的資料表的名稱。 類型：字串 | 是 |
## 回應
### 語法
```
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
Content-Length: 543
{"Table":
{"CreationDateTime":1.309988345372E9,
ItemCount:1,
"KeySchema":
{"HashKeyElement":{"AttributeName":"AttributeName1","AttributeType":"S"},
"RangeKeyElement":{"AttributeName":"AttributeName2","AttributeType":"N"}},
"ProvisionedThroughput":{"LastIncreaseDateTime": Date, "LastDecreaseDateTime": Date, "ReadCapacityUnits":10,"WriteCapacityUnits":10},
"TableName":"Table1",
"TableSizeBytes":1,
"TableStatus":"ACTIVE"
}
}
```
****
| 名稱 | 描述 |
| --- | --- |
| Table | 正在描述的資料表的容器。 類型：字串 |
| CreationDateTime | 建立資料表時的 [UNIX epoch 格式](http://www.epochconverter.com/)日期。 |
| ItemCount | 指定資料表中的項目數。DynamoDB 大約每六個小時會更新一次此值。此值可能不會反映最近的變更。 類型：數字 |
| KeySchema | 資料表的主索引鍵 (簡單或複合) 結構。需要 HashKeyElement 的名稱值組，且可選用 RangeKeyElement 的名稱值組 (僅適用於複合主索引鍵)。雜湊索引鍵大小上限為 2048 個位元組。範圍索引鍵大小上限為 1024 個位元組。此兩項限制皆為分別執行 (意即可出現雜湊 \$1 範圍 2048 \$1 1024 位元的合併索引鍵)。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。 |
| ProvisionedThroughput | 指定資料表的輸送量，包含 LastIncreaseDateTime (如適用)、LastDecreaseDateTime (如適用)、ReadCapacityUnits 和 WriteCapacityUnits 的值。如果資料表輸送量從未增加或減少，則 DynamoDB 不會傳回這些元素的值。請參閱 [DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。類型：陣列 |
| TableName | 所請求資料表的名稱。 類型：字串 |
| TableSizeBytes | 所指定資料表的總大小 (以位元組為單位)。DynamoDB 大約每六個小時會更新一次此值。此值可能不會反映最近的變更。 類型：數字 |
| TableStatus | 資料表目前的狀態 (CREATING、ACTIVE、DELETING 或 UPDATING)。一旦資料表處於 ACTIVE 狀態，您便可新增資料。 |
## 特殊錯誤
沒有此操作特定的錯誤。
## 範例
下列範例會顯示對名為 comp-table 的資料表使用 DescribeTable 操作的 HTTP POST 請求和回應。資料表具有複合主索引鍵。
### 請求範例
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.DescribeTable
content-type: application/x-amz-json-1.0
{"TableName":"users"}
```
### 回應範例
```
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 543
{"Table":
{"CreationDateTime":1.309988345372E9,
"ItemCount":23,
"KeySchema":
{"HashKeyElement":{"AttributeName":"user","AttributeType":"S"},
"RangeKeyElement":{"AttributeName":"time","AttributeType":"N"}},
"ProvisionedThroughput":{"LastIncreaseDateTime": 1.309988345384E9, "ReadCapacityUnits":10,"WriteCapacityUnits":10},
"TableName":"users",
"TableSizeBytes":949,
"TableStatus":"ACTIVE"
}
}
```
## 相關動作
+ [CreateTable](API_CreateTable_v20111205.md)
+ [DeleteTable](API_DeleteTable_v20111205.md)
+ [ListTables](API_ListTables_v20111205.md)
# GetItem
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
`GetItem` 操作會傳回與主索引鍵相符的項目的一組 `Attributes`。如果沒有符合的項目，則 `GetItem` 不會傳回任何資料。
`GetItem` 操作預設會執行最終一致讀取。如果應用程式不接受最終一致讀取，則請使用 `ConsistentRead`。此操作可能比標準讀取需要更長的時間，但一定會傳回上次更新的值。如需更多詳細資訊，請參閱 [DynamoDB 讀取一致性](HowItWorks.ReadConsistency.md)。
## 請求
### 語法
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.GetItem
content-type: application/x-amz-json-1.0
{"TableName":"Table1",
"Key":
{"HashKeyElement": {"S":"AttributeValue1"},
"RangeKeyElement": {"N":"AttributeValue2"}
},
"AttributesToGet":["AttributeName3","AttributeName4"],
"ConsistentRead":Boolean
}
```
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| TableName | 包含所請求項目的資料表的名稱。 類型：字串 | 是 |
| Key | 定義項目的主索引鍵值。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。類型：`HashKeyElement` 對其值的映射和 `RangeKeyElement` 對其值的映射。 | 是 |
| AttributesToGet | 屬性名稱陣列。如果未指定屬性名稱，則會傳回所有屬性。如果有部分屬性未找到，則這些屬性不會出現在結果中。類型：陣列 | 否 |
| ConsistentRead | 如果設定為 `true`，則會發送一致性讀取，反之則會使用最終一致性。類型：布林值 | 否 |
## 回應
### 語法
```
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 144
{"Item":{
"AttributeName3":{"S":"AttributeValue3"},
"AttributeName4":{"N":"AttributeValue4"},
"AttributeName5":{"B":"dmFsdWU="}
},
"ConsumedCapacityUnits": 0.5
}
```
****
| 名稱 | 描述 |
| --- | --- |
| Item | 包含所請求屬性。類型：屬性名稱值組映射。 |
| ConsumedCapacityUnits | 操作所使用的讀取容量單位數目。此值顯示套用至佈建輸送量的數字。請求不存在項目會使用最小讀取容量單位，具體值依讀取類型而定。如需更多資訊，請參閱[DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：數字 |
## 特殊錯誤
沒有此操作特定的錯誤。
## 範例
如需使用 AWS 開發套件的範例，請參閱 [在 DynamoDB 使用項目和屬性](WorkingWithItems.md)。
### 請求範例
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.GetItem
content-type: application/x-amz-json-1.0
{"TableName":"comptable",
"Key":
{"HashKeyElement":{"S":"Julie"},
"RangeKeyElement":{"N":"1307654345"}},
"AttributesToGet":["status","friends"],
"ConsistentRead":true
}
```
### 回應範例
請注意，ConsumedCapacityUnits 值為 1，因為選用參數 `ConsistentRead` 已設定為 `true`。如果 `ConsistentRead` 已設定為 `false` (或未指定)，則回應為最終一致性，且 ConsumedCapacityUnits 數值為 0.5。
```
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 72
{"Item":
{"friends":{"SS":["Lynda, Aaron"]},
"status":{"S":"online"}
},
"ConsumedCapacityUnits": 1
}
```
# ListTables
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
傳回與目前帳戶及端點相關聯之所有資料表陣列。
每個 DynamoDB 端點都是完全獨立的。例如，如果有兩個名為 MyTable 的資料表，一個在 dynamodb.us-west-2.amazonaws.com 中，另一個在 dynamodb.us-east-1.amazonaws.com 中，則兩者完全獨立，不會共用任何資料。ListTables 操作會針對接收請求的端點，傳回與發出請求之帳戶相關聯的所有資料表名稱。
## 請求
### 語法
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.ListTables
content-type: application/x-amz-json-1.0
{"ExclusiveStartTableName":"Table1","Limit":3}
```
根據預設，ListTables 操作會針對接收請求的端點，請求與發出請求之帳戶相關聯的所有資料表名稱。
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| Limit | 要傳回的資料表名稱上限數。 類型：整數 | 否 |
| ExclusiveStartTableName | 清單之首的資料表名稱。如果您已執行 ListTables 操作並收到 `LastEvaluatedTableName` 值，請在此處使用該值繼續清單。 類型：字串 | 否 |
## 回應
### 語法
```
HTTP/1.1 200 OK
x-amzn-RequestId: S1LEK2DPQP8OJNHVHL8OU2M7KRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 81
Date: Fri, 21 Oct 2011 20:35:38 GMT
{"TableNames":["Table1","Table2","Table3"], "LastEvaluatedTableName":"Table3"}
```
****
| 名稱 | 描述 |
| --- | --- |
| TableNames | 在目前端點上與目前帳戶相關聯的資料表名稱。 類型：陣列 |
| LastEvaluatedTableName | 目前清單中最後一個資料表的名稱，這只在帳戶和端點的部分資料表尚未傳回時才需要。如果已傳回所有資料表名稱，則回應中不存在此值。在新的請求中使用此值作為 `ExclusiveStartTableName` 來繼續清單，直到傳回所有資料表名稱。 類型：字串 |
## 特殊錯誤
沒有此操作特定的錯誤。
## 範例
下列範例顯示使用 ListTables 操作的 HTTP POST 請求和回應。
### 請求範例
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.ListTables
content-type: application/x-amz-json-1.0
{"ExclusiveStartTableName":"comp2","Limit":3}
```
### 回應範例
```
HTTP/1.1 200 OK
x-amzn-RequestId: S1LEK2DPQP8OJNHVHL8OU2M7KRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 81
Date: Fri, 21 Oct 2011 20:35:38 GMT
{"LastEvaluatedTableName":"comp5","TableNames":["comp3","comp4","comp5"]}
```
## 相關動作
+ [DescribeTables](API_DescribeTables_v20111205.md)
+ [CreateTable](API_CreateTable_v20111205.md)
+ [DeleteTable](API_DeleteTable_v20111205.md)
# PutItem
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
建立新項目，或以新項目取代舊項目 (包括全部屬性)。如果具有相同主索引鍵的指定資料表中已存在某項目，則新項目會完全取代現有項目。您可以執行條件式放置 (如果具有所指定主索引鍵的項目不存在，則插入新項目)，或者在現有項目具有某些屬性值時取代項目。
屬性值不得為 Null；字串和二進位類型屬性的長度必須大於零；集合類型屬性不可為空白。具有空值的請求會遭到拒絕，並出現 `ValidationException`。
**注意**
若要確保新項目不會取代現有項目，請使用條件式放置操作，針對主索引鍵屬性或屬性將 `Exists` 設定為 `false`。
如需有關使用 `PutItem` 的詳細資訊，請參閱 [在 DynamoDB 使用項目和屬性](WorkingWithItems.md)。
## 請求
### 語法
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.PutItem
content-type: application/x-amz-json-1.0
{"TableName":"Table1",
"Item":{
"AttributeName1":{"S":"AttributeValue1"},
"AttributeName2":{"N":"AttributeValue2"},
"AttributeName5":{"B":"dmFsdWU="}
},
"Expected":{"AttributeName3":{"Value": {"S":"AttributeValue"}, "Exists":Boolean}},
"ReturnValues":"ReturnValuesConstant"}
```
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| TableName | 要包含項目的資料表名稱。 類型：字串 | 是 |
| Item | 項目屬性映射，且必須包含定義項目的主索引鍵值。可提供其他屬性名稱值組給項目。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。類型：屬性值的屬性名稱映射。 | 是 |
| Expected | 指定條件式放置的屬性。`Expected` 參數可讓您提供屬性名稱，以及 DynamoDB 是否應該檢查屬性值是否已存在；或者屬性值是否存在且在變更之前有特定值。類型：屬性值的屬性名稱映射，以及映射是否存在。 | 否 |
| Expected:AttributeName | 條件式放置的屬性的名稱。類型：字串 | 否 |
| Expected:AttributeName: ExpectedAttributeValue | 使用此參數來指定屬性名稱值組的值是否已經存在。如果該項目的 Color (顏色) 屬性尚未存在，則下列 JSON 符號會取代項目："Expected" :
{"Color":{"Exists":false}}
下列 JSON 符號會在取代項目之前檢查名為 Color (顏色) 的屬性是否具有現有值 Yellow (黃色)："Expected" :
{"Color":{"Exists":true,{"Value":{"S":"Yellow"}}}
根據預設，如果使用 `Expected` 參數並提供 `Value`，DynamoDB 會假設屬性存在，且有要取代的目前值。所以您不必指定 `{"Exists":true}`，因為這是暗含的。您可以將請求縮短為："Expected" :
{"Color":{"Value":{"S":"Yellow"}}}
如果指定 `{"Exists":true}` 而無要檢查的屬性值，則 DynamoDB 會傳回錯誤。 | 否 |
| ReturnValues | 如果想在以 `PutItem` 請求更新屬性名稱值組之前取得屬性名稱值組，則請使用此參數。可能的參數值為 `NONE` (預設) 或 `ALL_OLD`。如果已指定 `ALL_OLD`，且 `PutItem` 覆寫屬性名稱值組，則會傳回舊項目的內容。如果未提供此參數，或者參數為 `NONE`，則不會傳回任何內容。類型：字串 | 否 |
## 回應
### 語法
下列語法範例假設請求指定 `ALL_OLD` 的 `ReturnValues` 參數，反之則回應只有 `ConsumedCapacityUnits` 元素。
```
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 85
{"Attributes":
{"AttributeName3":{"S":"AttributeValue3"},
"AttributeName2":{"SS":"AttributeValue2"},
"AttributeName1":{"SS":"AttributeValue1"},
},
"ConsumedCapacityUnits":1
}
```
****
| 名稱 | 描述 |
| --- | --- |
| Attributes | 執行放置操作之前的屬性值，但僅限於請求中指定 `ReturnValues` 參數為 `ALL_OLD` 的情況。類型：屬性名稱值組映射。 |
| ConsumedCapacityUnits | 操作所使用的寫入容量單位數目。此值顯示套用至佈建輸送量的數字。如需更多資訊，請參閱[DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：數字 |
## 特殊錯誤
****
| 錯誤 | 描述 |
| --- | --- |
| ConditionalCheckFailedException | 條件式檢查失敗。找不到預期的屬性值。 |
| ResourceNotFoundException | 找不到指定的項目或屬性。 |
## 範例
如需使用 AWS 開發套件的範例，請參閱 [在 DynamoDB 使用項目和屬性](WorkingWithItems.md)。
### 請求範例
```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.PutItem
content-type: application/x-amz-json-1.0
{"TableName":"comp5",
"Item":
{"time":{"N":"300"},
"feeling":{"S":"not surprised"},
"user":{"S":"Riley"}
},
"Expected":
{"feeling":{"Value":{"S":"surprised"},"Exists":true}}
"ReturnValues":"ALL_OLD"
}
```
### 回應範例
```
HTTP/1.1 200
x-amzn-RequestId: 8952fa74-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 84
{"Attributes":
{"feeling":{"S":"surprised"},
"time":{"N":"300"},
"user":{"S":"Riley"}},
"ConsumedCapacityUnits":1
}
```
## 相關動作
+ [UpdateItem](API_UpdateItem_v20111205.md)
+ [DeleteItem](API_DeleteItem_v20111205.md)
+ [GetItem](API_GetItem_v20111205.md)
+ [BatchGetItem](API_BatchGetItem_v20111205.md)
# Query
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
`Query` 操作以主索引鍵獲取一或多個項目的值及其屬性 (`Query` 僅適用於雜湊與範圍主索引鍵資料表)。您必須提供特定的 `HashKeyValue`，且能在主索引鍵的 `RangeKeyValue` 上使用比較運算子縮小查詢範圍。使用 `ScanIndexForward` 參數以範圍索引鍵取得正向或反向順序的結果。
未傳回結果的查詢會根據讀取類型使用最小讀取容量單位。
**注意**
如果符合查詢參數的項目總數超過 1MB 限制，則查詢會停止，並將結果傳回給使用者，附帶 `LastEvaluatedKey` 用以在後續操作中繼續查詢。查詢操作不同於掃描操作，一律不會傳回空的結果集*和* `LastEvaluatedKey`。只有在結果超過 1MB，或者您已使用 `Limit` 參數時，才會提供 `LastEvaluatedKey`。
使用 `ConsistentRead` 參數可設定一致性讀取的結果。
## 請求
### 語法
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.Query
content-type: application/x-amz-json-1.0
{"TableName":"Table1",
"Limit":2,
"ConsistentRead":true,
"HashKeyValue":{"S":"AttributeValue1":},
"RangeKeyCondition": {"AttributeValueList":[{"N":"AttributeValue2"}],"ComparisonOperator":"GT"}
"ScanIndexForward":true,
"ExclusiveStartKey":{
"HashKeyElement":{"S":"AttributeName1"},
"RangeKeyElement":{"N":"AttributeName2"}
},
"AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]},
}
```
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| TableName | 包含請求項目的資料表的名稱。 類型：字串 | 是 |
| AttributesToGet | 屬性名稱陣列。如果未指定屬性名稱，則會傳回所有屬性。如果有部分屬性未找到，則這些屬性不會出現在結果中。類型：陣列 | 否 |
| Limit | 要傳回的項目數上限 (不一定是相符項目數)。如果 DynamoDB 在查詢資料表時處理的項目數達上限，則會停止查詢，並傳回截至該時間點的相符值，附帶 `LastEvaluatedKey` 以套用於後續操作中繼續查詢。此外，如果在 DynamoDB 達到此限制之前結果集大小超過 1MB，則會停止查詢並傳回相符值，附帶 `LastEvaluatedKey` 以套用於後續操作中繼續查詢。類型：數字 | 否 |
| ConsistentRead | 如果設定為 `true`，則會發送一致性讀取，反之則會使用最終一致性。類型：布林值 | 否 |
| Count | 如果設定為 `true`，則 DynamoDB 會傳回符合查詢參數的項目總數，而不是相符項目及其屬性的清單。您可以套用 `Limit` 參數至僅計數查詢。 請勿在提供 `AttributesToGet` 清單之時將 `Count` 設定為 `true`，否則 DynamoDB 會傳回驗證錯誤。如需詳細資訊，請參閱 [計算結果中的項目](Query.Other.md#Query.Count)。類型：布林值 | 否 |
| HashKeyValue | 複合主索引鍵雜湊元件的屬性值。類型：字串、數字或二進位 | 是 |
| RangeKeyCondition | 屬性值容器以及用於查詢的比較運算子。查詢請求不需要 `RangeKeyCondition`。如果只提供 `HashKeyValue`，則 DynamoDB 會傳回具有指定雜湊索引鍵元素值的所有項目。類型：映射 | 否 |
| RangeKeyCondition: AttributeValueList | 查詢參數要評估的屬性值。除非已指定 `BETWEEN` 比較，否則 `AttributeValueList` 一律包含一個屬性值。對於 `BETWEEN` 比較，`AttributeValueList` 包含兩個屬性值。類型：`ComparisonOperator` 的 `AttributeValue` 映射。 | 否 |
| RangeKeyCondition: ComparisonOperator | 用於評估所提供的屬性的條件，例如等於、大於。以下是查詢操作的有效比較運算子。 大於、等於或小於的字串值比較是根據 ASCII 字元代碼值。例如，`a` 大於 `A`，`aa` 大於 `B`。如需代碼值的清單，請參閱 [http://en.wikipedia.org/wiki/ASCII\$1ASCII\$1printable\$1characters](http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters)。 針對 Binary，每當 DynamoDB 比較二進位值，例如在評估查詢表達式時，都會將二進位資料的每個位元組視為不帶正負號。 類型：字串或二進位 | 否 |
| | `EQ`：等於。 對於 `EQ`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不等於 `{"NS":["6", "2", "1"]}`。 | |
| | `LE`：小於或等於。 對於 `LE`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 | |
| | `LT`：小於。 對於 `LT`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 | |
| | `GE`：大於或等於。 對於 `GE`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 | |
| | `GT`：大於。 對於 `GT`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 | |
| | `BEGINS_WITH`：檢查字首。 對於 `BEGINS_WITH`，`AttributeValueList` 僅可包含 String 或 Binary 類型 (非 Number 或集合) 的一個 `AttributeValue`。比較的目標屬性必須是 String 或 Binary (非 Number 或集合)。 | |
| | `BETWEEN`：大於或等於第一個數值，並且小於或等於第二個數值。 對於 `BETWEEN`，`AttributeValueList` 必須包含 String、Number 或 Binary 類型 (非集合) 的兩個 `AttributeValue` 元素。如果目標數值大於或等於第一個元素，並且小於或等於第二個元素，則目標屬性相符。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不與 `{"N":"6"}` 比較。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 | |
| ScanIndexForward | 指定遞增或遞減的索引周遊。DynamoDB 傳回結果會反映由範圍索引鍵決定之所請求順序：如果資料類型為數字，則會依數值順序傳回結果，反之，周遊則是根據 ASCII 字元代碼值。類型：布林值預設為 `true` (遞增)。 | 否 |
| ExclusiveStartKey | 繼續先前查詢之項目的主索引鍵。如果因為結果集大小或 `Limit` 參數，導致查詢操作在查詢完成前中斷，較早的查詢可能提供此值為 `LastEvaluatedKey`。`LastEvaluatedKey` 可以在新的查詢請求中傳回，以便從該時間點繼續操作。類型：複合主索引鍵的 `HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement`。 | 否 |
## 回應
### 語法
```
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 308
{"Count":2,"Items":[{
"AttributeName1":{"S":"AttributeValue1"},
"AttributeName2":{"N":"AttributeValue2"},
"AttributeName3":{"S":"AttributeValue3"}
},{
"AttributeName1":{"S":"AttributeValue3"},
"AttributeName2":{"N":"AttributeValue4"},
"AttributeName3":{"S":"AttributeValue3"},
"AttributeName5":{"B":"dmFsdWU="}
}],
"LastEvaluatedKey":{"HashKeyElement":{"AttributeValue3":"S"},
"RangeKeyElement":{"AttributeValue4":"N"}
},
"ConsumedCapacityUnits":1
}
```
****
| 名稱 | 描述 |
| --- | --- |
| Items | 符合查詢參數的項目屬性。類型：屬性名稱映射，以及其資料類型和值。 |
| Count | 回應中的項目數。如需詳細資訊，請參閱 [計算結果中的項目](Query.Other.md#Query.Count)。 類型：數字 |
| LastEvaluatedKey | 查詢操作停止的項目的主索引鍵，包括先前的結果集。使用此值開始新操作，在新的請求中排除此值。當整個查詢結果集完成時 (意即操作已處理「最後一頁」)，`LastEvaluatedKey` 為 `null`。類型：複合主索引鍵的 `HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement`。 |
| ConsumedCapacityUnits | 操作所使用的讀取容量單位數目。此值顯示套用至佈建輸送量的數字。如需更多資訊，請參閱[DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：數字 |
## 特殊錯誤
****
| 錯誤 | 描述 |
| --- | --- |
| ResourceNotFoundException | 找不到指定的資料表。 |
## 範例
如需使用 AWS 開發套件的範例，請參閱 [在 DynamoDB 中查詢資料表](Query.md)。
### 請求範例
```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.Query
content-type: application/x-amz-json-1.0
{"TableName":"1-hash-rangetable",
"Limit":2,
"HashKeyValue":{"S":"John"},
"ScanIndexForward":false,
"ExclusiveStartKey":{
"HashKeyElement":{"S":"John"},
"RangeKeyElement":{"S":"The Matrix"}
}
}
```
### 回應範例
```
HTTP/1.1 200
x-amzn-RequestId: 3647e778-71eb-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 308
{"Count":2,"Items":[{
"fans":{"SS":["Jody","Jake"]},
"name":{"S":"John"},
"rating":{"S":"***"},
"title":{"S":"The End"}
},{
"fans":{"SS":["Jody","Jake"]},
"name":{"S":"John"},
"rating":{"S":"***"},
"title":{"S":"The Beatles"}
}],
"LastEvaluatedKey":{"HashKeyElement":{"S":"John"},"RangeKeyElement":{"S":"The Beatles"}},
"ConsumedCapacityUnits":1
}
```
### 請求範例
```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.Query
content-type: application/x-amz-json-1.0
{"TableName":"1-hash-rangetable",
"Limit":2,
"HashKeyValue":{"S":"Airplane"},
"RangeKeyCondition":{"AttributeValueList":[{"N":"1980"}],"ComparisonOperator":"EQ"},
"ScanIndexForward":false}
```
### 回應範例
```
HTTP/1.1 200
x-amzn-RequestId: 8b9ee1ad-774c-11e0-9172-d954e38f553a
content-type: application/x-amz-json-1.0
content-length: 119
{"Count":1,"Items":[{
"fans":{"SS":["Dave","Aaron"]},
"name":{"S":"Airplane"},
"rating":{"S":"***"},
"year":{"N":"1980"}
}],
"ConsumedCapacityUnits":1
}
```
## 相關動作
+ [Scan](API_Scan_v20111205.md)
# Scan
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
`Scan` 操作會執行資料表完整掃描來傳回一或多個項目及其屬性。提供 `ScanFilter` 以取得更特定的結果。
**注意**
如果已掃描項目總數超過 1MB 限制，則掃描會停止，並將結果傳回給使用者，附帶 `LastEvaluatedKey` 用以在後續操作中繼續掃描。結果還包括超出限制的項目數。掃描可能導致表內資料皆不符合篩選條件。
結果集為最終一致性。
## 請求
### 語法
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.Scan
content-type: application/x-amz-json-1.0
{"TableName":"Table1",
"Limit": 2,
"ScanFilter":{
"AttributeName1":{"AttributeValueList":[{"S":"AttributeValue"}],"ComparisonOperator":"EQ"}
},
"ExclusiveStartKey":{
"HashKeyElement":{"S":"AttributeName1"},
"RangeKeyElement":{"N":"AttributeName2"}
},
"AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]},
}
```
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| TableName | 包含請求項目的資料表的名稱。 類型：字串 | 是 |
| AttributesToGet | 屬性名稱陣列。如果未指定屬性名稱，則會傳回所有屬性。如果有部分屬性未找到，則這些屬性不會出現在結果中。類型：陣列 | 否 |
| Limit | 要評估的項目數上限 (不一定是相符的項目數)。如果 DynamoDB 在處理結果時處理的項目數達上限，則會停止工作，並傳回截至該時間點的相符值，附帶 `LastEvaluatedKey` 以套用於後續操作中繼續擷取項目。此外，如果在 DynamoDB 達到此限制之前已掃描的資料集大小超過 1MB，則會停止掃描，並傳回截至上限的相符值，附帶 `LastEvaluatedKey` 以套用於後續操作中繼續掃描。類型：數字 | 否 |
| Count | 如果設定為 `true`，則 DynamoDB 會傳回掃描操作的項目總數，即使操作沒有指派篩選條件的相符項目也一樣。您可以套用限制參數至僅計數查詢。 請勿在提供 `AttributesToGet` 清單之時將 `Count` 設定為 `true`，否則 DynamoDB 會傳回驗證錯誤。如需詳細資訊，請參閱 [計算結果中的項目](Scan.md#Scan.Count)。類型：布林值 | 否 |
| ScanFilter | 評估掃描結果，並僅傳回所需值。多個條件會視為 AND 操作：必須符合所有條件才會納入結果中。 類型：具有比較運算子的值的屬性名稱映射。 | 否 |
| ScanFilter:AttributeValueList | 用來評估篩選條件掃描結果的值和條件。類型：`Condition` 的 `AttributeValue` 映射。 | 否 |
| ScanFilter: ComparisonOperator | 用於評估所提供的屬性的條件，例如等於、大於。以下是掃描操作的有效比較運算子。 大於、等於或小於的字串值比較是根據 ASCII 字元代碼值。例如，`a` 大於 `A`，`aa` 大於 `B`。如需代碼值的清單，請參閱 [http://en.wikipedia.org/wiki/ASCII\$1ASCII\$1printable\$1characters](http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters)。 針對 Binary，每當 DynamoDB 比較二進位值，例如在評估查詢表達式時，都會將二進位資料的每個位元組視為不帶正負號。 類型：字串或二進位 | 否 |
| | `EQ`：等於。 對於 `EQ`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不等於 `{"NS":["6", "2", "1"]}`。 | |
| | `NE`：不等於。 對於 `NE`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不等於 `{"NS":["6", "2", "1"]}`。 | |
| | `LE`：小於或等於。 對於 `LE`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 | |
| | `LT`：小於。 對於 `LT`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 | |
| | `GE`：大於或等於。 對於 `GE`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 | |
| | `GT`：大於。 對於 `GT`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 | |
| | `NOT_NULL`：屬性存在。 | |
| | `NULL`：屬性不存在。 | |
| | `CONTAINS`：檢查子序列，或是集合中的數值。 對於 `CONTAINS`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果比較的目標屬性是字串，則操作會檢查相符子字串。如果比較的目標屬性是二進位，則操作會尋找與輸入相符的目標子序列。如果比較的目標屬性是集合 (SS、NS 或 BS)，則操作會檢查集合的成員 (不當作子字串)。 | |
| | `NOT_CONTAINS`：檢查子序列是否不存在，或者集合中的數值是否不存在。 對於 `NOT_CONTAINS`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果比較的目標屬性是字串，則操作會檢查相符子字串是否不存在。如果比較的目標屬性是二進位，則操作會檢查與輸入相符的目標子序列是否不存在。如果比較的目標屬性是集合 (SS、NS 或 BS)，則操作會檢查集合的成員 (不當作子字串) 是否不存在。 | |
| | `BEGINS_WITH`：檢查字首。 對於 `BEGINS_WITH`，`AttributeValueList` 僅可包含 String 或 Binary 類型 (非 Number 或集合) 的一個 `AttributeValue`。比較的目標屬性必須是 String 或 Binary (非 Number 或集合)。 | |
| | `IN`：檢查完全相符項目。 對於 `IN`，`AttributeValueList` 可以包含 String、Number 或 Binary 類型 (非集合) 的多個 `AttributeValue`。比較的目標屬性必須為相同的類型和確切數值才相符。String 一律不與 String 集合相符。 | |
| | `BETWEEN`：大於或等於第一個數值，並且小於或等於第二個數值。 對於 `BETWEEN`，`AttributeValueList` 必須包含 String、Number 或 Binary 類型 (非集合) 的兩個 `AttributeValue` 元素。如果目標數值大於或等於第一個元素，並且小於或等於第二個元素，則目標屬性相符。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不與 `{"N":"6"}` 比較。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 | |
| ExclusiveStartKey | 繼續先前掃描之項目的主索引鍵。如果因為結果集大小或 `Limit` 參數，導致掃描操作在整個資料表掃描完之前中斷，較早的掃描可能提供此值。`LastEvaluatedKey` 可以在新的掃描請求中傳回，以便從該時間點繼續操作。類型：複合主索引鍵的 `HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement`。 | 否 |
## 回應
### 語法
```
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 229
{"Count":2,"Items":[{
"AttributeName1":{"S":"AttributeValue1"},
"AttributeName2":{"S":"AttributeValue2"},
"AttributeName3":{"S":"AttributeValue3"}
},{
"AttributeName1":{"S":"AttributeValue4"},
"AttributeName2":{"S":"AttributeValue5"},
"AttributeName3":{"S":"AttributeValue6"},
"AttributeName5":{"B":"dmFsdWU="}
}],
"LastEvaluatedKey":
{"HashKeyElement":{"S":"AttributeName1"},
"RangeKeyElement":{"N":"AttributeName2"},
"ConsumedCapacityUnits":1,
"ScannedCount":2}
}
```
****
| 名稱 | 描述 |
| --- | --- |
| Items | 符合操作參數的屬性的容器。類型：屬性名稱映射，以及其資料類型和值。 |
| Count | 回應中的項目數。如需詳細資訊，請參閱 [計算結果中的項目](Scan.md#Scan.Count)。 類型：數字 |
| ScannedCount | 套用任何篩選條件之前的已完成掃描中項目數。`ScannedCount` 值很高，但 `Count` 結果很少或沒有，表示掃描操作不足。如需詳細資訊，請參閱 [計算結果中的項目](Scan.md#Scan.Count)。類型：數字 |
| LastEvaluatedKey | 停止掃描操作之項目的主索引鍵。在後續掃描操作中提供此值，以便從該時間點繼續操作。當整個掃描結果集完成時 (意即操作已處理「最後一頁」)，`LastEvaluatedKey` 為 `null`。 |
| ConsumedCapacityUnits | 操作所使用的讀取容量單位數目。此值顯示套用至佈建輸送量的數字。如需更多資訊，請參閱[DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：數字 |
## 特殊錯誤
****
| 錯誤 | 描述 |
| --- | --- |
| ResourceNotFoundException | 找不到指定的資料表。 |
## 範例
如需使用 AWS 開發套件的範例，請參閱 [掃描 DynamoDB 中的資料表](Scan.md)。
### 請求範例
```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.Scan
content-type: application/x-amz-json-1.0
{"TableName":"1-hash-rangetable","ScanFilter":{}}
```
### 回應範例
```
HTTP/1.1 200
x-amzn-RequestId: 4e8a5fa9-71e7-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 465
{"Count":4,"Items":[{
"date":{"S":"1980"},
"fans":{"SS":["Dave","Aaron"]},
"name":{"S":"Airplane"},
"rating":{"S":"***"}
},{
"date":{"S":"1999"},
"fans":{"SS":["Ziggy","Laura","Dean"]},
"name":{"S":"Matrix"},
"rating":{"S":"*****"}
},{
"date":{"S":"1976"},
"fans":{"SS":["Riley"]},"
name":{"S":"The Shaggy D.A."},
"rating":{"S":"**"}
},{
"date":{"S":"1985"},
"fans":{"SS":["Fox","Lloyd"]},
"name":{"S":"Back To The Future"},
"rating":{"S":"****"}
}],
"ConsumedCapacityUnits":0.5
"ScannedCount":4}
```
### 請求範例
```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.Scan
content-type: application/x-amz-json-1.0
content-length: 125
{"TableName":"comp5",
"ScanFilter":
{"time":
{"AttributeValueList":[{"N":"400"}],
"ComparisonOperator":"GT"}
}
}
```
### 回應範例
```
HTTP/1.1 200 OK
x-amzn-RequestId: PD1CQK9QCTERLTJP20VALJ60TRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 262
Date: Mon, 15 Aug 2011 16:52:02 GMT
{"Count":2,
"Items":[
{"friends":{"SS":["Dave","Ziggy","Barrie"]},
"status":{"S":"chatting"},
"time":{"N":"2000"},
"user":{"S":"Casey"}},
{"friends":{"SS":["Dave","Ziggy","Barrie"]},
"status":{"S":"chatting"},
"time":{"N":"2000"},
"user":{"S":"Fredy"}
}],
"ConsumedCapacityUnits":0.5
"ScannedCount":4
}
```
### 請求範例
```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.Scan
content-type: application/x-amz-json-1.0
{"TableName":"comp5",
"Limit":2,
"ScanFilter":
{"time":
{"AttributeValueList":[{"N":"400"}],
"ComparisonOperator":"GT"}
},
"ExclusiveStartKey":
{"HashKeyElement":{"S":"Fredy"},"RangeKeyElement":{"N":"2000"}}
}
```
### 回應範例
```
HTTP/1.1 200 OK
x-amzn-RequestId: PD1CQK9QCTERLTJP20VALJ60TRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 232
Date: Mon, 15 Aug 2011 16:52:02 GMT
{"Count":1,
"Items":[
{"friends":{"SS":["Jane","James","John"]},
"status":{"S":"exercising"},
"time":{"N":"2200"},
"user":{"S":"Roger"}}
],
"LastEvaluatedKey":{"HashKeyElement":{"S":"Riley"},"RangeKeyElement":{"N":"250"}},
"ConsumedCapacityUnits":0.5
"ScannedCount":2
}
```
## 相關動作
+ [Query](API_Query_v20111205.md)
+ [BatchGetItem](API_BatchGetItem_v20111205.md)
# UpdateItem
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
編輯現有項目的屬性。您可以執行條件式更新 (在新的屬性名稱值組不存在時插入新的，或者在現有名稱值組具有某些預期的屬性值時將其取代)。
**注意**
您無法使用 UpdateItem 更新主索引鍵屬性。但您可以刪除項目並使用 PutItem 建立具有新屬性的新項目。
UpdateItem 操作包含 `Action` 參數，該參數定義如何執行更新。您可以放入、刪除或新增屬性值。
屬性值不得為 Null；字串和二進位類型屬性的長度必須大於零；集合類型屬性不可為空白。具有空值的請求會遭到拒絕，並出現 `ValidationException`。
如果現有項目具有指定的主索引鍵：
+ **PUT：**新增指定的屬性。如果屬性存在，則會以新值取代。
+ **DELETE：**如果未指定任何值，則會移除屬性及其值。如果有指定一組值，則所指定集合中的值將從舊集合中移除。因此，如果屬性值包含 [a、b、c]，而刪除動作包含 [a、c]，則最後屬性值為 [b]。指定值類型必須符合現有值類型。指定空集合無效。
+ **ADD：**僅對數字使用新增動作，或者在目標屬性為集合 (包括字串集合) 時使用。如果目標屬性為單一字串值或純量二進位值，則 ADD 無法運作。指定的值會新增至數值 (現有的數值進行遞增或遞減)，或者新增為字串集合中的額外值。如果有指定一組值，則會將這些值新增至現有的集合中。例如，如果原始集合為 [1、2]，而提供的值為 [3]，則在新增操作之後，集合為 [1、2、3]，而非 [4、5]。如果已為集合屬性指定 Add 動作，且指定的屬性類型與現有集合類型不符，則會發生錯誤。
如果對不存在的屬性使用 ADD，則會將屬性及其值新增至項目。
如果沒有項目符合所指定的主索引鍵：
+ **PUT：**建立具有指定主索引鍵的新項目。然後新增指定屬性。
+ **DELETE：**不進行任何動作。
+ **ADD：**建立具有提供的主索引鍵和屬性值數字 (或一組數字) 的項目。不適用於字串或二進位類型。
**注意**
如果對更新前不存在的項目使用 `ADD` 增減數值，則 DynamoDB 會以 `0` 為初始值。此外，如果對更新前不存在的屬性 (但項目存在) 使用 `ADD` 增減數值來更新項目，則 DynamoDB 會以 `0` 為初始值。例如，您使用 `ADD` 將 `+3` 新增至更新前不存在的屬性。DynamoDB 使用 `0` 為初始值，而且更新後的值為 `3`。
如需使用此操作的詳細資訊，請參閱 [在 DynamoDB 使用項目和屬性](WorkingWithItems.md)。
## 請求
### 語法
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.UpdateItem
content-type: application/x-amz-json-1.0
{"TableName":"Table1",
"Key":
{"HashKeyElement":{"S":"AttributeValue1"},
"RangeKeyElement":{"N":"AttributeValue2"}},
"AttributeUpdates":{"AttributeName3":{"Value":{"S":"AttributeValue3_New"},"Action":"PUT"}},
"Expected":{"AttributeName3":{"Value":{"S":"AttributeValue3_Current"}}},
"ReturnValues":"ReturnValuesConstant"
}
```
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| TableName | 包含要更新項目的資料表的名稱。 類型：字串 | 是 |
| Key | 定義項目的主索引鍵。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。類型：`HashKeyElement` 對其值的映射和 `RangeKeyElement` 對其值的映射。 | 是 |
| AttributeUpdates | 新值的屬性名稱映射以及更新動作。屬性名稱指定要修改的屬性，且不能包含任何主索引鍵屬性。類型：屬性名稱映射、值，以及屬性更新動作。 | |
| AttributeUpdates:Action | 指定如何執行更新。可能值：`PUT` (預設)、`ADD` 或 `DELETE`。語義會在 UpdateItem 描述中說明。類型：字串預設：`PUT` | 否 |
| Expected | 指定條件式更新的屬性。`Expected` 參數可讓您提供屬性名稱，以及 DynamoDB 是否應該檢查屬性值是否已存在；或者屬性值是否存在且在變更之前有特定值。類型：屬性名稱映射。 | 否 |
| Expected:AttributeName | 條件式放置的屬性的名稱。類型：字串 | 否 |
| Expected:AttributeName: ExpectedAttributeValue | 使用此參數來指定屬性名稱值組的值是否已經存在。如果該項目的 Color (顏色) 屬性尚未存在，則下列 JSON 符號會更新項目："Expected" :
{"Color":{"Exists":false}}
下列 JSON 符號會在更新項目之前檢查名為 Color (顏色) 的屬性是否具有現有值 Yellow (黃色)："Expected" :
{"Color":{"Exists":true},{"Value":{"S":"Yellow"}}}
根據預設，如果使用 `Expected` 參數並提供 `Value`，DynamoDB 會假設屬性存在，且有要取代的目前值。所以您不必指定 `{"Exists":true}`，因為這是暗含的。您可以將請求縮短為："Expected" :
{"Color":{"Value":{"S":"Yellow"}}}
如果指定 `{"Exists":true}` 而無要檢查的屬性值，則 DynamoDB 會傳回錯誤。 | 否 |
| ReturnValues | 如果想在以 `UpdateItem` 請求更新屬性名稱值組之前取得屬性名稱值組，則請使用此參數。可能的參數值為 `NONE` (預設) 或者 `ALL_OLD`、`UPDATED_OLD`、`ALL_NEW` 或 `UPDATED_NEW`。如果已指定 `ALL_OLD`，且 `UpdateItem` 覆寫屬性名稱值組，則會傳回舊項目的內容。如果未提供此參數，或者參數為 `NONE`，則不會傳回任何內容。如果指定 `ALL_NEW`，則會傳回項目新版本的所有屬性。如果指定 `UPDATED_NEW`，則只會傳回已更新屬性的新版本。類型：字串 | 否 |
## 回應
### 語法
下列語法範例假設請求指定 `ALL_OLD` 的 `ReturnValues` 參數，反之則回應只有 `ConsumedCapacityUnits` 元素。
```
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 140
{"Attributes":{
"AttributeName1":{"S":"AttributeValue1"},
"AttributeName2":{"S":"AttributeValue2"},
"AttributeName3":{"S":"AttributeValue3"},
"AttributeName5":{"B":"dmFsdWU="}
},
"ConsumedCapacityUnits":1
}
```
****
| 名稱 | 描述 |
| --- | --- |
| Attributes | 屬性名稱值組映射，但僅限於 `ReturnValues` 參數在請求中被指定為 `NONE` 以外選項的情況。類型：屬性名稱值組映射。 |
| ConsumedCapacityUnits | 操作所使用的寫入容量單位數目。此值顯示套用至佈建輸送量的數字。如需更多資訊，請參閱[DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：數字 |
## 特殊錯誤
****
| 錯誤 | 描述 |
| --- | --- |
| ConditionalCheckFailedException | 條件式檢查失敗。屬性 ("\$1 name \$1") 值為 ("\$1 value \$1")，但預期為 ("\$1 expValue \$1") |
| ResourceNotFoundExceptions | 找不到指定的項目或屬性。 |
## 範例
如需使用 AWS 開發套件的範例，請參閱 [在 DynamoDB 使用項目和屬性](WorkingWithItems.md)。
### 請求範例
```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.UpdateItem
content-type: application/x-amz-json-1.0
{"TableName":"comp5",
"Key":
{"HashKeyElement":{"S":"Julie"},"RangeKeyElement":{"N":"1307654350"}},
"AttributeUpdates":
{"status":{"Value":{"S":"online"},
"Action":"PUT"}},
"Expected":{"status":{"Value":{"S":"offline"}}},
"ReturnValues":"ALL_NEW"
}
```
### 回應範例
```
HTTP/1.1 200 OK
x-amzn-RequestId: 5IMHO7F01Q9P7Q6QMKMMI3R3QRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 121
Date: Fri, 26 Aug 2011 21:05:00 GMT
{"Attributes":
{"friends":{"SS":["Lynda, Aaron"]},
"status":{"S":"online"},
"time":{"N":"1307654350"},
"user":{"S":"Julie"}},
"ConsumedCapacityUnits":1
}
```
## 相關動作
+ [PutItem](API_PutItem_v20111205.md)
+ [DeleteItem](API_DeleteItem_v20111205.md)
# UpdateTable
**重要**
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***
**如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**
## 描述
更新特定資料表的佈建輸送量。設定資料表的輸送量可協助您管理效能，此為 DynamoDB 佈建輸送量功能的一部分。如需更多詳細資訊，請參閱 [DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。
佈建輸送量數值可以根據 [Amazon DynamoDB 中的配額](ServiceQuotas.md) 中所列最大值和最小值來升級或降級。
資料表必須處於 `ACTIVE` 狀態，這項操作才會成功。UpdateTable 為非同步操作；執行操作時，資料表處於 `UPDATING` 狀態。資料表處於 `UPDATING` 狀態時，仍具有呼叫之前的佈建輸送量。只有資料表在 UpdateTable 操作後回到 `ACTIVE` 狀態時，新的佈建輸送量設定才會生效。
## 請求
### 語法
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.UpdateTable
content-type: application/x-amz-json-1.0
{"TableName":"Table1",
"ProvisionedThroughput":{"ReadCapacityUnits":5,"WriteCapacityUnits":15}
}
```
****
| 名稱 | 描述 | 必要 |
| --- | --- | --- |
| TableName | 要更新的資料表名稱。 類型：字串 | 是 |
| ProvisionedThroughput | 指定資料表的新輸送量，包括 `ReadCapacityUnits` 與 `WriteCapacityUnits` 的值。請參閱 [DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。類型：陣列 | 是 |
| ProvisionedThroughput :ReadCapacityUnits | 設定 DynamoDB 與其他操作平衡負載之前，所指定資料表每秒所需的最低一致性 `ReadCapacityUnits` 數目。 最終一致讀取操作比一致性讀取負擔更輕，因此每秒 50 次一致性 `ReadCapacityUnits` 的設定可提供每秒 100 次最終一致 `ReadCapacityUnits`。類型：數字 | 是 |
| ProvisionedThroughput :WriteCapacityUnits | 設定 DynamoDB 與其他操作平衡負載之前，所指定資料表每秒所需的最低 `WriteCapacityUnits` 數目。類型：數字 | 是 |
## 回應
### 語法
```
HTTP/1.1 200 OK
x-amzn-RequestId: CSOC7TJPLR0OOKIRLGOHVAICUFVV4KQNSO5AEMVJF66Q9ASUAAJG
Content-Type: application/json
Content-Length: 311
Date: Tue, 12 Jul 2011 21:31:03 GMT
{"TableDescription":
{"CreationDateTime":1.321657838135E9,
"KeySchema":
{"HashKeyElement":{"AttributeName":"AttributeValue1","AttributeType":"S"},
"RangeKeyElement":{"AttributeName":"AttributeValue2","AttributeType":"N"}},
"ProvisionedThroughput":
{"LastDecreaseDateTime":1.321661704489E9,
"LastIncreaseDateTime":1.321663607695E9,
"ReadCapacityUnits":5,
"WriteCapacityUnits":10},
"TableName":"Table1",
"TableStatus":"UPDATING"}}
```
****
| 名稱 | 描述 |
| --- | --- |
| CreationDateTime | 建立資料表時的日期。類型：數字 |
| KeySchema | 資料表的主索引鍵 (簡單或複合) 結構。需要 `HashKeyElement` 的名稱值組，且可選用 `RangeKeyElement` 的名稱值組 (僅適用於複合主索引鍵)。雜湊索引鍵大小上限為 2048 個位元組。範圍索引鍵大小上限為 1024 個位元組。此兩項限制皆為分別執行 (意即可出現雜湊 \$1 範圍 2048 \$1 1024 位元的合併索引鍵)。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。類型：複合主索引鍵的 `HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement` 映射。 |
| ProvisionedThroughput | 所指定資料表的目前輸送量設定，包括 `LastIncreaseDateTime` (如適用)、`LastDecreaseDateTime` (如適用) 的值。類型：陣列 |
| TableName | 已更新的資料表名稱。 類型：字串 |
| TableStatus | 資料表目前的狀態 (CREATING、ACTIVE、DELETING 或 UPDATING)，目前應該為 UPDATING。使用 [DescribeTables](API_DescribeTables_v20111205.md) 操作來查看資料表狀態。類型：字串 |
## 特殊錯誤
****
| 錯誤 | 描述 |
| --- | --- |
| ResourceNotFoundException | 找不到指定的資料表。 |
| ResourceInUseException | 資料表不處於 ACTIVE 狀態。 |
## 範例
### 請求範例
```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.UpdateTable
content-type: application/x-amz-json-1.0
{"TableName":"comp1",
"ProvisionedThroughput":{"ReadCapacityUnits":5,"WriteCapacityUnits":15}
}
```
### 回應範例
```
HTTP/1.1 200 OK
content-type: application/x-amz-json-1.0
content-length: 390
Date: Sat, 19 Nov 2011 00:46:47 GMT
{"TableDescription":
{"CreationDateTime":1.321657838135E9,
"KeySchema":
{"HashKeyElement":{"AttributeName":"user","AttributeType":"S"},
"RangeKeyElement":{"AttributeName":"time","AttributeType":"N"}},
"ProvisionedThroughput":
{"LastDecreaseDateTime":1.321661704489E9,
"LastIncreaseDateTime":1.321663607695E9,
"ReadCapacityUnits":5,
"WriteCapacityUnits":10},
"TableName":"comp1",
"TableStatus":"UPDATING"}
}
```
## 相關動作
+ [CreateTable](API_CreateTable_v20111205.md)
+ [DescribeTables](API_DescribeTables_v20111205.md)
+ [DeleteTable](API_DeleteTable_v20111205.md)