本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# DynamoDB API
<a name="HowItWorks.API"></a>

若要使用 Amazon DynamoDB，您的應用程式必須使用一些簡單的 API 操作。以下是這些操作的摘要，並依類別分組。

**注意**  
如需 API 操作的完整清單，請參閱 [Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/Welcome.html)。

**Topics**
+ [控制平面](#HowItWorks.API.ControlPlane)
+ [資料平面](#HowItWorks.API.DataPlane)
+ [DynamoDB Streams](#HowItWorks.API.Streams)
+ [交易](#HowItWorks.API.Transactions)

## 控制平面
<a name="HowItWorks.API.ControlPlane"></a>

*控制平面*操作可讓您建立及管理 DynamoDB 資料表。它們也可讓您使用索引、串流，以及相依於資料表的其他物件。
+  `CreateTable`：建立新的資料表。您可以選擇性地建立一或多個次要索引，並為資料表啟用 DynamoDB Streams。
+ `DescribeTable`：傳回資料表的相關資訊，例如其主索引鍵結構描述、輸送量設定、索引資訊。
+ `ListTables`：傳回您所有的資料表名稱清單。
+ `UpdateTable`：修改資料表或其索引的設定、在資料表上建立或移除新的索引，或修改資料表的 DynamoDB Streams 設定。
+ `DeleteTable`：從 DynamoDB 移除資料表及其所有相依物件。

## 資料平面
<a name="HowItWorks.API.DataPlane"></a>

*資料平面*操作可讓您對資料表中的資料執行建立、讀取、更新與刪除 (也稱為 *CRUD*) 動作。部分資料平面操作也可讓您從讀取資料。

您可以使用 [PartiQL：一種適用於 Amazon DynamoDB 的 SQL 相容查詢語言](ql-reference.md) 來執行這些 CRUD 操作，也可以使用 DynamoDB 的傳統 CRUD API 將每個操作分隔為不同的 API 呼叫。

### PartiQL - 一種 SQL 相容查詢語言
<a name="HowItWorks.API.DataPlane.partiql"></a>
+ `ExecuteStatement`：讀取資料表中的多個項目。您也可以寫入或更新資料表中的單一項目。在寫入或更新單一項目時，您必須指定主索引鍵屬性。
+ `BatchExecuteStatement`：從資料表寫入、更新或讀取多個項目。這比 `ExecuteStatement` 的效率高上好幾倍，因為您的應用程式只需要往返網路一次即可寫入或讀取項目。

### 傳統 API
<a name="HowItWorks.API.DataPlane.classic"></a>

#### 建立資料
<a name="HowItWorks.API.DataPlane.Create"></a>
+ `PutItem`：將單一項目寫入資料表。您必須指定主索引鍵屬性，但不必指定其他屬性。
+ `BatchWriteItem`：最多可將 25 個項目寫入資料表。這比呼叫 `PutItem` 的效率高上好幾倍，因為您的應用程式只需要往返網路一次即可寫入項目。

#### 讀取資料
<a name="HowItWorks.API.DataPlane.Read"></a>
+ `GetItem`：從資料表擷取單一項目。您必須指定所需項目的主索引鍵。您可以擷取整個項目，或只擷取其屬性子集。
+ `BatchGetItem`：最多可從一或多個資料表擷取 100 個項目。這比呼叫 `GetItem` 的效率高上好幾倍，因為您的應用程式只需要往返網路一次即可讀取項目。
+ `Query`：擷取所有具有特定分割區索引鍵的項目。您必須指定分割區索引鍵值。您可以擷取整個項目，或只擷取其屬性子集。您可以選擇性地將條件套用至排序索引鍵值，只擷取具有相同分割區索引鍵的資料子集。您可以在資料表上使用此操作，只要該資料表同時具有分割區索引鍵與排序索引鍵。您也可以在索引上使用此操作，只要該索引同時具有分割區索引鍵與排序索引鍵。
+ `Scan`：擷取指定資料表或索引中的所有項目。您可以擷取整個項目，或只擷取其屬性子集。您可以選擇性地套用篩選條件，只傳回您感興趣的值並捨棄其餘值。

#### 更新資料
<a name="HowItWorks.API.DataPlane.Update"></a>
+ `UpdateItem`：修改項目中的一或多個屬性。您必須指定要修改之項目的主索引鍵。您可以新增屬性，以及修改或移除現有的屬性。您也可以執行條件式更新，只在符合使用者定義的條件時，更新才會成功。您可以選擇性地實作原子計數器，遞增或遞減數字屬性，而不會影響其他寫入請求。

#### 刪除資料
<a name="HowItWorks.API.DataPlane.Delete"></a>
+ `DeleteItem`：從資料表刪除單一項目。您必須指定要刪除之項目的主索引鍵。
+ `BatchWriteItem`：最多可從一或多個資料表刪除 25 個項目。這比呼叫 `DeleteItem` 的效率高上好幾倍，因為您的應用程式只需要往返網路一次即可刪除項目。
**注意**  
您可以使用 `BatchWriteItem` 建立資料和刪除資料。

## DynamoDB Streams
<a name="HowItWorks.API.Streams"></a>

*DynamoDB Streams* 操作可讓您在資料表上啟用或停用串流，並允許存取串流中包含的資料修改紀錄。
+ `ListStreams`：傳回您所有的串流清單，或只傳回特定資料表的串流。
+ `DescribeStream`：傳回串流的相關資訊，例如其 Amazon Resource Name (ARN)，以及您的應用程式可開始讀取前幾個串流紀錄的位置。
+ `GetShardIterator`：傳回*碎片疊代運算*，這是您的應用程式從串流擷取紀錄所使用的資料結構。
+ `GetRecords`：使用指定的碎片疊代運算，擷取一或多個串流紀錄。

## 交易
<a name="HowItWorks.API.Transactions"></a>

*交易*提供了不可分割性、一致性、隔離性和耐久性 (ACID)，讓您能夠輕鬆地維持應用程式的資料正確度。

您可以使用 [PartiQL：一種適用於 Amazon DynamoDB 的 SQL 相容查詢語言](ql-reference.md) 來執行交易操作，也可以使用 DynamoDB 的傳統 CRUD API 將每個操作分隔為不同的 API 呼叫。

### PartiQL - 一種 SQL 相容查詢語言
<a name="HowItWorks.API.Transactions.DataPlane.partiql"></a>
+ `ExecuteTransaction`：允許對資料表內和跨資料表的多個項目進行保證全有或全無變更 CRUD 操作的批次操作。

### 傳統 API
<a name="HowItWorks.API.DataPlane.classic"></a>
+ `TransactWriteItems`：允許對資料表內和跨資料表的多個項目進行保證全有或全無變更的 `Put`、`Update` 和 `Delete` 操作的批次操作。
+ `TransactGetItems`：允許 `Get` 操作來從一或多個資料表擷取多個項目的批次操作。