本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 AWS CLI 呼叫 Amazon RDS 資料 API
您可以使用 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 交易
您可以使用 `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 陳述式
您可以使用 `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 陳述式
您可以透過使用 `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 交易
您可以使用 `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 交易
您可以使用 `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"
}
```