# 调用 Amazon RDS 数据 API
<a name="data-api.calling"></a>

在 Aurora 数据库集群上启用 Amazon RDS 数据 API（数据 API）后，您可以使用数据 API 或 AWS CLI 在 Aurora 数据库集群上运行 SQL 语句。数据 API 支持 AWS SDK 所支持的编程语言。有关更多信息，请参阅[用于在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 语句。


****  

|  Data API 操作  |  AWS CLI command  |  描述  | 
| --- | --- | --- | 
|  [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 提供了以下操作。


****  

|  Data API 操作  |  AWS CLI command  |  描述  | 
| --- | --- | --- | 
|  [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 语句和支持事务的操作具有以下常用 Data API 参数和 AWS CLI 选项。某些操作支持其他参数或选项。


****  

|  Data API 操作参数  |  AWS CLI 命令选项  |  必需  |  描述  | 
| --- | --- | --- | --- | 
|  `resourceArn`  |  `--resource-arn`  |  是  |  Aurora 数据库集群的 Amazon 资源名称（ARN）。集群必须与调用数据 API 的 IAM 角色或用户位于相同的 AWS 账户中。要使用其它账户访问集群，请代入该账户中的角色。  | 
|  `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` 和 `BatchExecuteStatement` 的 Data API 调用中使用参数，或在运行 AWS CLI 命令 `execute-statement` 和 `batch-execute-statement` 时使用。要使用参数，请在 `SqlParameter` 数据类型中指定名称/值对。您可以使用 `Field` 数据类型指定值。下表将 Java 数据库连接 (JDBC) 数据类型映射到您在 Data API 调用中指定的数据类型。


****  

|  JDBC 数据类型  |  Data API 数据类型  | 
| --- | --- | 
|  `INTEGER, TINYINT, SMALLINT, BIGINT`  |  `LONG` – 、 或 `STRING`  | 
|  `FLOAT, REAL, DOUBLE`  |  `DOUBLE`  | 
|  `DECIMAL`  |  `STRING`  | 
|  `BOOLEAN, BIT`  |  `BOOLEAN`  | 
|  `BLOB, BINARY, LONGVARBINARY, VARBINARY`  |  `BLOB`  | 
|  `CLOB`  |  `STRING`  | 
|  其他类型（包括与日期和时间有关的类型）  |  `STRING`  | 

**注意**  
 您可以在 Data API 调用中为数据库返回的 `LONG` 值指定 `LONG` 或 `STRING` 数据类型。建议您这样操作，以避免在使用 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。有关更多信息，请参阅 [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 事务
<a name="data-api.calling.cli.begin-transaction"></a>

您可以使用 `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 语句
<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`（可选）– 一个值，指定当调用超过了数据 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，则调用将终止。  
对于 Aurora Serverless v1，每秒最大请求数为 1000。对于所有其它受支持的数据库，没有限制。

例如，以下 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 语句
<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 请求的最大大小为 4MiB。如果请求超出此限制，数据 API 将返回错误并且不处理请求。此 4MiB 限制包括 HTTP 标头的大小和请求中的 JSON 符号。因此，可以包含的参数集数取决于因素的组合，例如 SQL 语句的大小和每个参数集的大小。  
响应大小限制为 1MiB。如果调用返回的响应数据超过 1MiB，则调用将终止。  
对于 Aurora Serverless v1，每秒最大请求数为 1000。对于所有其它受支持的数据库，没有限制。

例如，以下 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 资源名称（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>

您可以通过 Python 应用程序开始 SQL 事务、运行一个或多个 SQL 语句，然后提交更改。

**重要**  
如果三分钟之内没有任何调用使用其事务 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 语句在结束运行之前终止，则可能导致错误以及数据结构损坏。要在调用超过 RDS 数据 API 超时间隔（45 秒）后继续运行语句，请将 `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 资源名称（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>

您可以通过 Java 应用程序开始 SQL 事务、运行一个或多个 SQL 语句，然后提交更改。

**重要**  
如果三分钟之内没有任何调用使用其事务 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 语句在结束运行之前终止，则可能导致错误以及数据结构损坏。要在调用超过 RDS 数据 API 超时间隔（45 秒）后继续运行语句，请将 `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>

 对 Data API 的所有调用都是同步的。假设您执行了一个数据 API 操作，该操作运行 SQL 语句，例如 `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 SDK 对 API 调用或 HTTP 套接字连接有自己的超时时间，请确保所有这些超时时间都超过 45 秒。对于某些 SDK，超时时间默认为小于 45 秒。我们建议将任何特定于 SDK 或特定于客户端的超时时间设置为至少 1 分钟。采用这种方法，您可以避免虽然数据 API 操作成功完成，但应用程序仍可能收到超时错误。这样您就可以确定是否要重试操作。

 例如，假设 SDK 向您的应用程序返回超时错误，但是数据 API 操作仍在数据 API 超时间隔内完成。在这种情况下，重试该操作可能会插入重复的数据或以其他方式生成不正确的结果。SDK 可能会自动重试该操作，从而导致数据不正确，虽然您的应用程序没有执行任何操作。

 对于 Java 2 SDK 来说，超时间隔尤其重要。在该 SDK 中，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));
}
```