# 使用 AWS CLI 调用 Amazon RDS 数据 API
您可以使用 AWS CLI 调用 RDS 数据 API（数据 API）。
以下示例将 AWS CLI 用于数据 API。有关更多信息，请参阅 [Data API 的 AWS CLI 参考](https://docs.aws.amazon.com/cli/latest/reference/rds-data/index.html)。
在每个示例中，将数据库集群的 Amazon 资源名称（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，Data Definition Language）语句会导致隐式提交。建议您在单独的 `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`（可选）– 一个值，指定当调用超过了数据 API 超时间隔（45 秒）后，是否继续运行语句。默认为 `--no-continue-after-timeout`。
对于数据定义语言（DDL）语句，我们建议在调用超时后继续运行语句，以避免错误以及数据结构损坏的可能性。
+ `--format-records-as "JSON"|"NONE"` – 一个可选值，它指定是否将结果集格式化为 JSON 字符串。默认值为 `"NONE"`。有关处理 JSON 结果集的使用信息，请参阅[处理 JSON 格式的 Amazon RDS 数据 API 查询结果](data-api-json.md)。
数据库集群为调用返回响应。
**注意**
响应大小限制为 1MiB。如果调用返回的响应数据超过 1MiB，则调用将终止。
例如，以下 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 语句在结束运行之前终止，则可能导致错误以及数据结构损坏。要在调用超过 RDS 数据 API 超时间隔（45 秒）后继续运行语句，请指定 `--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 请求的最大大小为 4MiB。如果请求超出此限制，数据 API 将返回错误并且不处理请求。此 4MiB 限制包括 HTTP 标头的大小和请求中的 JSON 符号。因此，可以包含的参数集数取决于因素的组合，例如 SQL 语句的大小和每个参数集的大小。
响应大小限制为 1MiB。如果调用返回的响应数据超过 1MiB，则调用将终止。
例如，以下 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"
}
```