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

# 呼叫 Amazon RDS 資料 API
<a name="data-api.calling"></a>

在 Aurora 資料庫叢集啟用 Amazon RDS 資料 API (資料 API) 後，您可以使用資料 API 或 AWS CLI，在 Aurora 資料庫叢集執行 SQL 陳述式。資料 API 支援 AWS 開發套件支援的程式設計語言。如需詳細資訊，請參閱[在 AWS 上建置的工具](https://aws.amazon.com/tools/)。

**Topics**
+ [Amazon RDS 資料 API 操作參考](data-api-operations.md)
+ [使用 AWS CLI 呼叫 Amazon RDS 資料 API](data-api.calling.cli.md)
+ [透過 Python 應用程式呼叫 Amazon RDS 資料 API](data-api.calling.python.md)
+ [透過 Java 應用程式呼叫 Amazon RDS 資料 API](data-api.calling.java.md)
+ [控制資料 API 逾時行為](data-api-timeouts.md)

# Amazon RDS 資料 API 操作參考
<a name="data-api-operations"></a>

Amazon RDS 資料 API 會提供以下操作來執行 SQL 陳述式。


****  

|  資料 API 操作  |  AWS CLI 命令  |  Description  | 
| --- | --- | --- | 
|  [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html)  |  [https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html)  |  在資料庫上執行 SQL 陳述式。  | 
|  [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html)  |  [https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html)  |  透過對資料陣列執行批次 SQL 陳述式來進行大量更新和插入操作。您可以使用參數集陣列來執行資料處理語言 (DML) 陳述式。批次 SQL 陳述式可針對個別插入和更新陳述式提供明顯的效能改善。  | 

您可以使用任一操作來執行個別 SQL 陳述式或執行交易。針對交易，資料 API 會提供以下操作。


****  

|  資料 API 操作  |  AWS CLI 命令  |  Description  | 
| --- | --- | --- | 
|  [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html)  |  [https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html)  |  開始 SQL 交易。  | 
|  [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html)  |  [https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html)  |  結束 SQL 交易並遞交變更。  | 
|  [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html)  |  [https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html)  |  執行交易轉返。  | 

執行 SQL 陳述式和支援交易的操作具有下列常見的資料 API 參數和 AWS CLI 選項。有些操作支援其他參數或選項。


****  

|  資料 API 操作參數  |  AWS CLI 命令選項  |  必要  |  描述  | 
| --- | --- | --- | --- | 
|  `resourceArn`  |  `--resource-arn`  |  是  |  Aurora 資料庫叢集的 Amazon Resource Name (ARN)。叢集必須與叫用資料 API AWS 帳戶 的 IAM 角色或使用者位於相同的 中。若要存取不同帳戶中的叢集，請擔任該帳戶中的角色。  | 
|  `secretArn`  |  `--secret-arn`  |  是  |  用來允許存取資料庫叢集之秘密的名稱或 ARN。  | 

RDS 資料 API 支援 Aurora MySQL 的下列資料類型：
+ `TINYINT(1)`, `BOOLEAN`, `BOOL`
+ `TINYINT`
+ `SMALLINT` [`SIGNED` \$1 `UNSIGNED`]
+ `MEDIUMINT` [`SIGNED` \$1 `UNSIGNED`]
+ `INT` [`SIGNED` \$1 `UNSIGNED`]
+ `BIGINT` [`SIGNED` \$1 `UNSIGNED`]
+ `FLOAT`
+ `DOUBLE`
+ `VARCHAR`, `CHAR`, `TEXT`, `ENUM`
+ `VARBINARY`, `BINARY`, `BLOB`
+ `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`
+ `DECIMAL`
+ `JSON`
+ `BIT`, `BIT(N)` 

RDS 資料 API 支援下列 Aurora PostgreSQL 純量類型：
+ `BOOL`
+ `BYTEA`
+ `DATE`
+ `CIDR`
+ `DECIMAL`, `NUMERIC`
+ `ENUM`
+ `FLOAT8`, `DOUBLE PRECISION`
+ `INET`
+ `INT`, `INT4`, `SERIAL`
+ `INT2`, `SMALLINT`, `SMALLSERIAL`
+ `INT8`, `BIGINT`, `BIGSERIAL`
+ `JSONB`, `JSON`
+ `REAL`, `FLOAT`
+ `TEXT`, `CHAR(N)`, `VARCHAR`, `NAME`
+ `TIME`
+ `TIMESTAMP`
+ `UUID`
+ `VECTOR`

RDS 資料 API 支援下列 Aurora PostgreSQL 陣列類型：
+ `BOOL[]`, `BIT[]`
+ `DATE[]`
+ `DECIMAL[]`, `NUMERIC[]`
+ `FLOAT8[]`, `DOUBLE PRECISION[]`
+ `INT[]`, `INT4[]`
+ `INT2[]`
+ `INT8[]`, `BIGINT[]`
+ `JSON[]`
+ `REAL[]`, `FLOAT[]`
+ `TEXT[]`, `CHAR(N)[]`, `VARCHAR[]`, `NAME[]`
+ `TIME[]`
+ `TIMESTAMP[]`
+ `UUID[]`

您可以在對 `ExecuteStatement`和 進行資料 API 呼叫`BatchExecuteStatement`，以及在執行 AWS CLI 命令`execute-statement`和 時使用參數`batch-execute-statement`。若要使用參數，請在 `SqlParameter` 資料類型中指定名稱/值對。您使用 `Field` 資料類型來指定值。下表會將 Java Database Connectivity (JDBC) 資料類型映射至您在資料 API 呼叫中指定的資料類型。


****  

|  JDBC 資料類型  |  資料 API 資料類型  | 
| --- | --- | 
|  `INTEGER, TINYINT, SMALLINT, BIGINT`  |  `LONG` – 、 或 `STRING`  | 
|  `FLOAT, REAL, DOUBLE`  |  `DOUBLE`  | 
|  `DECIMAL`  |  `STRING`  | 
|  `BOOLEAN, BIT`  |  `BOOLEAN`  | 
|  `BLOB, BINARY, LONGVARBINARY, VARBINARY`  |  `BLOB`  | 
|  `CLOB`  |  `STRING`  | 
|  其他類型 (包含與日期和時間相關的類型)  |  `STRING`  | 

**注意**  
 您可以在 `LONG` 資料 API 呼叫中，針對資料庫傳回的 `STRING` 值指定 `LONG` 或資料類型。我們建議您這麼做，以避免失去極大數字的精確度，您在使用 JavaScript 時可能會發生這種情況。

某些類型 (例如 `DECIMAL` 和 `TIME`) 需要提示，以便資料 API 以正確的類型將 `String` 值傳遞給資料庫。若要使用提示，請在 `typeHint` 資料類型中包含 `SqlParameter` 的值。`typeHint` 可能的值如下：
+ `DATE` – 對應的 `String` 參數值以 `DATE` 類型的物件傳送至資料庫。接受的格式為 `YYYY-MM-DD`。
+ `DECIMAL` – 對應的 `String` 參數值以 `DECIMAL` 類型的物件傳送至資料庫。
+ `JSON` – 對應的 `String` 參數值以 `JSON` 類型的物件傳送至資料庫。
+ `TIME` – 對應的 `String` 參數值以 `TIME` 類型的物件傳送至資料庫。接受的格式為 `HH:MM:SS[.FFF]`。
+ `TIMESTAMP` – 對應的 `String` 參數值以 `TIMESTAMP` 類型的物件傳送至資料庫。接受的格式為 `YYYY-MM-DD HH:MM:SS[.FFF]`。
+  `UUID` – 對應的 `String` 參數值以 `UUID` 類型的物件傳送至資料庫。
**注意**  
目前，資料 API 不支援通用唯一識別符 (UUID) 的陣列。

**注意**  
 對於 Amazon Aurora PostgreSQL，資料 API 始終以 UTC 時區返回 Aurora PostgreSQL 資料類型 `TIMESTAMPTZ`。

# 使用 AWS CLI 呼叫 Amazon RDS 資料 API
<a name="data-api.calling.cli"></a>

您可以使用 AWS CLI 呼叫 RDS 資料 API(資料 API)。

下列範例會使用 AWS CLI 來呼叫資料 API。如需詳細資訊，請參閱[資料 API 的 AWS CLI 參考](https://docs.aws.amazon.com/cli/latest/reference/rds-data/index.html)。

在每個範例中，將資料庫叢集的 Amazon Resource Name (ARN) 取代為 Aurora 資料庫叢集的 ARN。同時也將秘密 ARN 取代為 Secrets Manager 中允許存取資料庫叢集的秘密 ARN。

**注意**  
AWS CLI 可以將回應設為 JSON 格式。

**Topics**
+ [開始 SQL 交易](#data-api.calling.cli.begin-transaction)
+ [執行 SQL 陳述式](#data-api.calling.cli.execute-statement)
+ [透過資料陣列來執行批次 SQL 陳述式](#data-api.calling.cli.batch-execute-statement)
+ [遞交 SQL 交易](#data-api.calling.cli.commit-transaction)
+ [復原 SQL 交易](#data-api.calling.cli.rollback-transaction)

## 開始 SQL 交易
<a name="data-api.calling.cli.begin-transaction"></a>

您可以使用 `aws rds-data begin-transaction` CLI 命令來開始 SQL 交易。此呼叫會傳回交易識別符。

**重要**  
在資料 API 內，如果三分鐘內沒有使用交易 ID 的任何呼叫，交易就會逾時。如果交易在遞交前就逾時，則資料 API 會自動將其復原。  
交易中的 MySQL 資料定義語言 (DDL) 陳述式會導致隱含遞交。我們建議您使用 `execute-statement` 選項在個別的 `--continue-after-timeout` 命令中執行每個 MySQL DDL 陳述式。

除了常用選項之外，還將指定 `--database` 選項，其提供資料庫的名稱。

例如，以下 CLI 命令會開始 SQL 交易。

對於 Linux、macOS 或 Unix：

```
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
```

在 Windows 中：

```
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
```

以下是回應的範例。

```
{
    "transactionId": "ABC1234567890xyz"
}
```

## 執行 SQL 陳述式
<a name="data-api.calling.cli.execute-statement"></a>

您可以使用 `aws rds-data execute-statement` CLI 命令來執行 SQL 陳述式。

您可以透過使用 `--transaction-id` 選項指定交易識別符，來在交易中執行 SQL 陳述式。您可以使用 `aws rds-data begin-transaction` CLI 命令來開始交易。您可以使用 `aws rds-data commit-transaction` CLI 命令來結束和遞交交易。

**重要**  
如果您沒有指定 `--transaction-id` 選項，系統就會自動遞交呼叫造成的變更。

除了常用的選項，請指定以下選項：
+ `--sql` (必要) – 在資料庫叢集上執行的 SQL 陳述式。
+ `--transaction-id` (選用) – 使用 `begin-transaction` CLI 命令開始的交易識別符。指定您要在其中包含 SQL 陳述式的交易 ID。
+ `--parameters` (選用) – SQL 陳述式的參數。
+ `--include-result-metadata | --no-include-result-metadata` (選用) – 此值會指出是否在結果中包含中繼資料。預設值為 `--no-include-result-metadata`。
+ `--database` (選用) – 資料庫的名稱。

  當您在先前請求中執行 `--sql "use database_name;"` 之後執行 SQL 陳述式時，`--database` 選項可能無法運作。建議您使用 `--database` 選項，而不是執行 `--sql "use database_name;"` 陳述式。
+ `--continue-after-timeout | --no-continue-after-timeout` (選用)：此值會指出在呼叫超過 45 秒的資料 API 逾時間隔後是否繼續執行陳述式。預設值為 `--no-continue-after-timeout`。

  對於資料定義語言 (DDL) 陳述式，我們建議在呼叫逾時後繼續執行陳述式，來避免錯誤和資料結構毀損的可能性。
+  `--format-records-as "JSON"|"NONE"` – 選用值，指定是否將結果集格式化為 JSON 字串。預設值為 `"NONE"`。如需處理 JSON 結果集的使用情況資訊，請參閱[以 JSON 格式處理 Amazon RDS 資料 API 查詢結果](data-api-json.md)。

資料庫叢集會傳回呼叫的回應。

**注意**  
回應大小限制為 1 MiB。若呼叫傳回的回應資料超過 1 MiB，系統就會終止呼叫。  
對於 Aurora Serverless v1，每秒請求數上限為 1,000。對於所有其他支援的資料庫，沒有限制。

例如，以下 CLI 命令會執行單一 SQL 陳述式並省略結果中的中繼資料 (預設值)。

對於 Linux、macOS 或 Unix：

```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "select * from mytable"
```

在 Windows 中：

```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "select * from mytable"
```

以下是回應的範例。

```
{
    "numberOfRecordsUpdated": 0,
    "records": [
        [
            {
                "longValue": 1
            },
            {
                "stringValue": "ValueOne"
            }
        ],
        [
            {
                "longValue": 2
            },
            {
                "stringValue": "ValueTwo"
            }
        ],
        [
            {
                "longValue": 3
            },
            {
                "stringValue": "ValueThree"
            }
        ]
    ]
}
```

以下 CLI 命令會透過指定 `--transaction-id` 選項來在交易中執行單一 SQL 陳述式。

對於 Linux、macOS 或 Unix：

```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
```

在 Windows 中：

```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
```

以下是回應的範例。

```
{
    "numberOfRecordsUpdated": 1
}
```

以下 CLI 命令會執行含參數的單一 SQL 陳述式。

對於 Linux、macOS 或 Unix：

```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
```

在 Windows 中：

```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
```

以下是回應的範例。

```
{
    "numberOfRecordsUpdated": 1
}
```

以下 CLI 命令會執行資料定義語言 (DDL) SQL 陳述式。DDL 陳述式會將 `job` 欄重新命名為欄 `role`。

**重要**  
對於 DDL 陳述式，我們建議在呼叫逾時後繼續執行陳述式。當 DDL 陳述式在完成執行前而終止時，可能會發生錯誤且資料結構可能毀損。若要在呼叫超過 45 秒的 RDS 資料 API 逾時間隔後繼續執行陳述式，請指定 `--continue-after-timeout` 選項。

對於 Linux、macOS 或 Unix：

```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
```

在 Windows 中：

```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
```

以下是回應的範例。

```
{
    "generatedFields": [],
    "numberOfRecordsUpdated": 0
}
```

**注意**  
Aurora PostgreSQL 不支援 `generatedFields` 資料。若要取得所產生欄位的值，請使用 `RETURNING` 子句。如需詳細資訊，請參閱 PostgreSQL 中的[從修改後的資料列傳回資料](https://www.postgresql.org/docs/10/dml-returning.html)。

## 透過資料陣列來執行批次 SQL 陳述式
<a name="data-api.calling.cli.batch-execute-statement"></a>

您可以透過使用 `aws rds-data batch-execute-statement` CLI 命令，透過資料陣列來執行批次 SQL 陳述式。您可以使用此命令來執行大量匯入或更新操作。

您可以透過使用 `--transaction-id` 選項指定交易識別符，來在交易中執行 SQL 陳述式。您可以透過使用 `aws rds-data begin-transaction` CLI 命令來開始交易。您可以透過使用 `aws rds-data commit-transaction` CLI 命令來結束和遞交交易。

**重要**  
如果您沒有指定 `--transaction-id` 選項，系統就會自動遞交呼叫造成的變更。

除了常用的選項，請指定以下選項：
+ `--sql` (必要) – 在資料庫叢集上執行的 SQL 陳述式。
**提示**  
 對於 MySQL 相容的陳述句，請不要在 `--sql` 參數結尾包含分號。結尾分號可能會導致語法錯誤。
+ `--transaction-id` (選用) – 使用 `begin-transaction` CLI 命令開始的交易識別符。指定您要在其中包含 SQL 陳述式的交易 ID。
+ `--parameter-set` (選用) – 批次操作的參數組。
+ `--database` (選用) – 資料庫的名稱。

資料庫叢集會傳回呼叫的回應。

**注意**  
參數組數目並無固定上限。不過，透過資料 API 提交的 HTTP 請求大小上限為 4 MiB。若請求超過此限制，資料 API 會傳回錯誤，不會處理請求。此 4 MiB 限制包括 HTTP 標頭的大小和請求中的 JSON 標記法。因此，您可包含的參數集數目取決於因素組合，例如 SQL 陳述式的大小和每個參數集的大小。  
回應大小限制為 1 MiB。若呼叫傳回的回應資料超過 1 MiB，系統就會終止呼叫。  
對於 Aurora Serverless v1，每秒請求數上限為 1,000。對於所有其他支援的資料庫，沒有限制。

例如，以下 CLI 命令會透過含參數組的資料陣列來執行批次 SQL 陳述式。

對於 Linux、macOS 或 Unix：

```
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" \
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
```

在 Windows 中：

```
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" ^
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
```

**注意**  
請勿在 `--parameter-sets` 選項中包含分行符號。

## 遞交 SQL 交易
<a name="data-api.calling.cli.commit-transaction"></a>

您可以使用 `aws rds-data commit-transaction` CLI 命令，來結束您透過 `aws rds-data begin-transaction` 開始的 SQL 交易和遞交變更。

除了常用的選項，請指定以下選項：
+ `--transaction-id` (必要) – 使用 `begin-transaction` CLI 命令開始的交易識別符。指定您要結束和遞交的交易 ID。

例如，以下 CLI 命令會結束 SQL 交易和遞交變更。

對於 Linux、macOS 或 Unix：

```
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"
```

在 Windows 中：

```
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"
```

以下是回應的範例。

```
{
    "transactionStatus": "Transaction Committed"
}
```

## 復原 SQL 交易
<a name="data-api.calling.cli.rollback-transaction"></a>

您可以使用 `aws rds-data rollback-transaction` CLI 命令，來復原您透過 `aws rds-data begin-transaction` 開始的 SQL 交易。復原交易會取消其變更。

**重要**  
如果交易 ID 已過期，系統會自動復原此交易。在這個情況下，指定此過期交易 ID 的 `aws rds-data rollback-transaction` 命令會傳回錯誤。

除了常用的選項，請指定以下選項：
+ `--transaction-id` (必要) – 使用 `begin-transaction` CLI 命令開始的交易識別符。指定您要復原的交易 ID。

例如，以下 AWS CLI 命令會復原 SQL 交易。

對於 Linux、macOS 或 Unix：

```
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"
```

在 Windows 中：

```
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"
```

以下是回應的範例。

```
{
    "transactionStatus": "Rollback Complete"
    }
```

# 透過 Python 應用程式呼叫 Amazon RDS 資料 API
<a name="data-api.calling.python"></a>

您可以透過 Python 應用程式呼叫 Amazon RDS 資料 API (資料 API)。

以下範例會使用適用於 Python 的 AWS 開發套件 (Boto)。如需 Boto 的更多詳細資訊，請參閱[適用於 Python 的 AWS 開發套件 (Boto 3) 文件](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)。

在每個範例中，將資料庫叢集的 Amazon Resource Name (ARN) 取代為 Aurora 資料庫叢集的 ARN。同時也將秘密 ARN 取代為 Secrets Manager 中允許存取資料庫叢集的秘密 ARN。

**Topics**
+ [執行 SQL 查詢](#data-api.calling.python.run-query)
+ [執行 DML SQL 陳述式](#data-api.calling.python.run-inert)
+ [執行 SQL 交易](#data-api.calling.python.run-transaction)

## 執行 SQL 查詢
<a name="data-api.calling.python.run-query"></a>

您可以執行 `SELECT` 陳述式並使用 Python 應用程式擷取結果。

以下範例會執行 SQL 查詢。

```
import boto3

rdsData = boto3.client('rds-data')

cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'

response1 = rdsData.execute_statement(
            resourceArn = cluster_arn,
            secretArn = secret_arn,
            database = 'mydb',
            sql = 'select * from employees limit 3')

print (response1['records'])
[
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'ROSALEZ'
        },
        {
            'stringValue': 'ALEJANDRO'
        },
        {
            'stringValue': '2016-02-15 04:34:33.0'
        }
    ],
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'DOE'
        },
        {
            'stringValue': 'JANE'
        },
        {
            'stringValue': '2014-05-09 04:34:33.0'
        }
    ],
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'STILES'
        },
        {
            'stringValue': 'JOHN'
        },
        {
            'stringValue': '2017-09-20 04:34:33.0'
        }
    ]
]
```

## 執行 DML SQL 陳述式
<a name="data-api.calling.python.run-inert"></a>

您可以執行資料處理語言 (DML) 陳述式來插入、更新或刪除資料庫中的資料。您也可以在 DML 陳述式中使用參數。

**重要**  
如果某個呼叫不包含 `transactionID` 參數而不屬於某個交易，則系統會自動遞交該呼叫造成的變更。

以下範例會執行插入 SQL 陳述式和使用參數。

```
import boto3

cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'

rdsData = boto3.client('rds-data')


param1 = {'name':'firstname', 'value':{'stringValue': 'JACKSON'}}
param2 = {'name':'lastname', 'value':{'stringValue': 'MATEO'}}
paramSet = [param1, param2]

response2 = rdsData.execute_statement(resourceArn=cluster_arn,
                                      secretArn=secret_arn,
                                      database='mydb',
                                      sql='insert into employees(first_name, last_name) VALUES(:firstname, :lastname)',
                                      parameters = paramSet)

print (response2["numberOfRecordsUpdated"])
```

## 執行 SQL 交易
<a name="data-api.calling.python.run-transaction"></a>

您可以開始 SQL 交易、執行一或多個 SQL 陳述式，接著使用 Python 應用程式遞交變更。

**重要**  
如果三分鐘內沒有使用交易 ID 的任何呼叫，交易就會逾時。如果交易在遞交前就逾時，則系統會自動將其復原。  
如果您沒有指定交易 ID，系統就會自動遞交呼叫造成的變更。

以下範例執行的 SQL 交易會在資料表中插入資料列。

```
import boto3

rdsData = boto3.client('rds-data')

cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'

tr = rdsData.begin_transaction(
     resourceArn = cluster_arn,
     secretArn = secret_arn,
     database = 'mydb')

response3 = rdsData.execute_statement(
     resourceArn = cluster_arn,
     secretArn = secret_arn,
     database = 'mydb',
     sql = 'insert into employees(first_name, last_name) values('XIULAN', 'WANG')',
     transactionId = tr['transactionId'])

cr = rdsData.commit_transaction(
     resourceArn = cluster_arn,
     secretArn = secret_arn,
     transactionId = tr['transactionId'])

cr['transactionStatus']
'Transaction Committed'

response3['numberOfRecordsUpdated']
1
```

**注意**  
如果您執行的是資料定義語言 (DDL) 陳述式，我們建議在呼叫逾時後繼續執行陳述式。當 DDL 陳述式在完成執行前而終止時，可能會發生錯誤且資料結構可能毀損。若要在呼叫超過 45 秒的 RDS 資料 API 逾時間隔後繼續執行陳述式，請將 `continueAfterTimeout` 參數設為 `true`。

# 透過 Java 應用程式呼叫 Amazon RDS 資料 API
<a name="data-api.calling.java"></a>

您可以透過 Java 應用程式呼叫 Amazon RDS 資料 API (資料 API)。

以下範例會使用適用於 Java 的 AWS 開發套件。如需詳細資訊，請參閱 [適用於 Java 的 AWS SDK 開發人員指南](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/welcome.html)。

在每個範例中，將資料庫叢集的 Amazon Resource Name (ARN) 取代為 Aurora 資料庫叢集的 ARN。同時也將秘密 ARN 取代為 Secrets Manager 中允許存取資料庫叢集的秘密 ARN。

**Topics**
+ [執行 SQL 查詢](#data-api.calling.java.run-query)
+ [執行 SQL 交易](#data-api.calling.java.run-transaction)
+ [執行批次 SQL 操作](#data-api.calling.java.run-batch)

## 執行 SQL 查詢
<a name="data-api.calling.java.run-query"></a>

您可以執行 `SELECT` 陳述式並使用 Java 應用程式擷取結果。

以下範例會執行 SQL 查詢。

```
package com.amazonaws.rdsdata.examples;

import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementResult;
import com.amazonaws.services.rdsdata.model.Field;

import java.util.List;

public class FetchResultsExample {
  public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
  public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";

  public static void main(String[] args) {
    AWSRDSData rdsData = AWSRDSDataClient.builder().build();

    ExecuteStatementRequest request = new ExecuteStatementRequest()
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withDatabase("mydb")
            .withSql("select * from mytable");

    ExecuteStatementResult result = rdsData.executeStatement(request);

    for (List<Field> fields: result.getRecords()) {
      String stringValue = fields.get(0).getStringValue();
      long numberValue = fields.get(1).getLongValue();

      System.out.println(String.format("Fetched row: string = %s, number = %d", stringValue, numberValue));
    }
  }
}
```

## 執行 SQL 交易
<a name="data-api.calling.java.run-transaction"></a>

您可以開始 SQL 交易、執行一或多個 SQL 陳述式，接著使用 Java 應用程式遞交變更。

**重要**  
如果三分鐘內沒有使用交易 ID 的任何呼叫，交易就會逾時。如果交易在遞交前就逾時，則系統會自動將其復原。  
如果您沒有指定交易 ID，系統就會自動遞交呼叫造成的變更。

以下範例會執行 SQL 交易。

```
package com.amazonaws.rdsdata.examples;

import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BeginTransactionRequest;
import com.amazonaws.services.rdsdata.model.BeginTransactionResult;
import com.amazonaws.services.rdsdata.model.CommitTransactionRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;

public class TransactionExample {
  public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
  public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";

  public static void main(String[] args) {
    AWSRDSData rdsData = AWSRDSDataClient.builder().build();

    BeginTransactionRequest beginTransactionRequest = new BeginTransactionRequest()
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withDatabase("mydb");
    BeginTransactionResult beginTransactionResult = rdsData.beginTransaction(beginTransactionRequest);
    String transactionId = beginTransactionResult.getTransactionId();

    ExecuteStatementRequest executeStatementRequest = new ExecuteStatementRequest()
            .withTransactionId(transactionId)
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withSql("INSERT INTO test_table VALUES ('hello world!')");
    rdsData.executeStatement(executeStatementRequest);

    CommitTransactionRequest commitTransactionRequest = new CommitTransactionRequest()
            .withTransactionId(transactionId)
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN);
    rdsData.commitTransaction(commitTransactionRequest);
  }
}
```

**注意**  
如果您執行的是資料定義語言 (DDL) 陳述式，我們建議在呼叫逾時後繼續執行陳述式。當 DDL 陳述式在完成執行前而終止時，可能會發生錯誤且資料結構可能毀損。若要在呼叫超過 45 秒的 RDS 資料 API 逾時間隔後繼續執行陳述式，請將 `continueAfterTimeout` 參數設為 `true`。

## 執行批次 SQL 操作
<a name="data-api.calling.java.run-batch"></a>

您可以使用 Java 應用程式，透過資料陣列來執行大量插入和更新操作。您可以使用參數集陣列來執行 DML 陳述式。

**重要**  
如果您沒有指定交易 ID，系統就會自動遞交呼叫造成的變更。

以下範例會執行批次插入操作。

```
package com.amazonaws.rdsdata.examples;

import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BatchExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.Field;
import com.amazonaws.services.rdsdata.model.SqlParameter;

import java.util.Arrays;

public class BatchExecuteExample {
  public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
  public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";

  public static void main(String[] args) {
      AWSRDSData rdsData = AWSRDSDataClient.builder().build();

    BatchExecuteStatementRequest request = new BatchExecuteStatementRequest()
            .withDatabase("test")
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withSql("INSERT INTO test_table2 VALUES (:string, :number)")
            .withParameterSets(Arrays.asList(
                    Arrays.asList(
                            new SqlParameter().withName("string").withValue(new Field().withStringValue("Hello")),
                            new SqlParameter().withName("number").withValue(new Field().withLongValue(1L))
                    ),
                    Arrays.asList(
                            new SqlParameter().withName("string").withValue(new Field().withStringValue("World")),
                            new SqlParameter().withName("number").withValue(new Field().withLongValue(2L))
                    )
            ));

    rdsData.batchExecuteStatement(request);
  }
}
```

# 控制資料 API 逾時行為
<a name="data-api-timeouts"></a>

 對資料 API 的所有呼叫都是同步。假設您執行的是執行 SQL 陳述式的資料 API 操作，例如 `INSERT` 或 `CREATE TABLE`。如果資料 API 呼叫成功傳回，則 SQL 處理會在呼叫傳回時完成。

 根據預設，如果操作未在 45 秒內完成處理，則資料 API 會取消操作並傳回逾時錯誤。在這種情況下，資料不會插入，資料表也不會建立，以此類推。

 您可以使用資料 API，來執行無法在 45 秒內完成的長時間執行操作。如果您預期對大型資料表執行大量 `INSERT` 或 DDL 操作之類的操作需要超過 45 秒，您可以指定 `ExecuteStatement` 操作的 `continueAfterTimeout` 參數。應用程式仍會收到逾時錯誤。不過，操作會繼續執行，不會取消。如需範例，請參閱「[執行 SQL 交易](data-api.calling.java.md#data-api.calling.java.run-transaction)」。

 如果程式設計語言 AWS 開發套件有自己的 API 呼叫或 HTTP 通訊端連線逾時期間，請確定所有這類逾時期間都超過 45 秒。對於某些 SDK，逾時期間預設為少於 45 秒。我們建議將任何 SDK 特定或用戶端特定逾時期間設定為至少一分鐘。這樣做可避免應用程式在資料 API 操作仍然成功完成時收到逾時錯誤的可能性。如此一來，您就可以確定是否要重試操作。

 例如，假設 SDK 將逾時錯誤傳回至應用程式，但資料 API 操作仍在資料 API 逾時間隔內完成。在這種情況下，重試操作可能會插入重複的資料，否則會產生不正確的結果。開發套件可能會自動重試操作，導致資料有誤，而不需要來自應用程式的任何動作。

 逾時間隔對於 Java 2 開發套件特別重要。在該開發套件中，API 呼叫逾時和 HTTP 通訊端逾時預設為 30 秒。以下是將這些逾時設為更高值的範例：

```
public RdsDataClient createRdsDataClient() {
    return RdsDataClient.builder()
        .region(Region.US_EAST_1) // Change this to your desired Region
        .overrideConfiguration(createOverrideConfiguration())
        .httpClientBuilder(createHttpClientBuilder())
        .credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider
        .build();
}

private static ClientOverrideConfiguration createOverrideConfiguration() {
    return ClientOverrideConfiguration.builder()
        .apiCallTimeout(Duration.ofSeconds(60))
        .build();
}
    
private HttpClientBuilder createHttpClientBuilder() {
    return ApacheHttpClient.builder() // Change this to your desired HttpClient
        .socketTimeout(Duration.ofSeconds(60));
}
```

 以下是使用異步資料用戶端的同等範例：

```
public static RdsDataAsyncClient createRdsDataAsyncClient() {
    return RdsDataAsyncClient.builder()
        .region(Region.US_EAST_1) // Change this to your desired Region
        .overrideConfiguration(createOverrideConfiguration())
        .credentialsProvider(defaultCredentialsProvider())  // Change this to your desired credentials provider
        .build();
}

private static ClientOverrideConfiguration createOverrideConfiguration() {
    return ClientOverrideConfiguration.builder()
        .apiCallAttemptTimeout(Duration.ofSeconds(60))
        .build();
}

private HttpClientBuilder createHttpClientBuilder() {
    return NettyNioAsyncHttpClient.builder() // Change this to your desired AsyncHttpClient
        .readTimeout(Duration.ofSeconds(60));
}
```