# 使用 Amazon RDS 数据 API
通过 RDS 数据 API（数据 API），您可以将 Web 服务接口用于 Aurora 数据库集群。数据 API 不需要与数据库集群的持久连接。相反，它提供了安全 HTTP 端点以及与 AWS 开发工具包的集成。您可以使用端点运行 SQL 语句，而无需管理连接。
用户无需在调用数据 API 时传递凭证，因为数据 API 会使用存储在 AWS Secrets Manager 中的数据库凭证。要在 Secrets Manager 中存储凭证，用户必须获得使用 Secrets Manager 以及数据 API 的适当权限。有关向用户授权的更多信息，请参阅 [授予对 Amazon RDS 数据 API 的访问权限](data-api.access.md)。
您还可以使用数据 API 将 Amazon Aurora 与其他 AWS 应用程序（如 AWS Lambda、AWS AppSync 和 AWS Cloud9）集成。数据 API 提供了一种更安全的方式来使用 AWS Lambda。通过此方式，您无需配置 Lambda 函数来访问虚拟私有云（VPC）中的资源，即可访问数据库集群。有关更多信息，请参阅 [AWS Lambda](https://aws.amazon.com/lambda/)、[AWS AppSync](https://aws.amazon.com/appsync/) 和 [AWS Cloud9](https://aws.amazon.com/cloud9/)。
您可以在创建 Aurora 数据库集群时启用数据 API。您也可以稍后修改配置。有关更多信息，请参阅 [启用 Amazon RDS 数据 API](data-api.enabling.md)。
启用数据 API 后，还可以使用查询编辑器运行即席查询，而无需配置查询工具在 VPC 中访问 Aurora。有关更多信息，请参阅 [使用 Aurora 查询编辑器](query-editor.md)。
**Topics**
+ [Amazon RDS 数据 API 的区域和版本可用性](data-api.regions.md)
+ [将 IPv6 与 Amazon RDS Data API 结合使用](data-api.ipv6.md)
+ [Amazon RDS 数据 API 的限制](data-api.limitations.md)
+ [Aurora Serverless v2、预置集群与 Aurora Serverless v1 集群的 Amazon RDS 数据 API 行为比较](data-api.differences.md)
+ [授予对 Amazon RDS 数据 API 的访问权限](data-api.access.md)
+ [启用 Amazon RDS 数据 API](data-api.enabling.md)
+ [为 Amazon RDS 数据 API 创建 Amazon VPC 端点（AWS PrivateLink）](data-api.vpc-endpoint.md)
+ [调用 Amazon RDS 数据 API](data-api.calling.md)
+ [使用适用于 RDS 数据 API 的 Java 客户端库](data-api.java-client-library.md)
+ [处理 JSON 格式的 Amazon RDS 数据 API 查询结果](data-api-json.md)
+ [Amazon RDS 数据 API 故障排除](data-api.troubleshooting.md)
+ [使用 AWS CloudTrail 记录 Amazon RDS 数据 API 调用](logging-using-cloudtrail-data-api.md)
+ [使用性能详情监控 RDS 数据 API 查询](monitoring-using-performance-insights-data-api.md)
# Amazon RDS 数据 API 的区域和版本可用性
有关适用于数据 API 的区域和引擎版本的信息，请参阅以下部分。
| 集群类型 | 区域和版本可用性 |
| --- | --- |
| Aurora PostgreSQL 预调配和 Serverless v2 | [适用于 Aurora PostgreSQL Serverless v2 和预调配的数据 API](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg) |
| Aurora MySQL 预调配和 Serverless v2 | [适用于 Aurora MySQL Serverless v2 和预调配的数据 API](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.ams) |
| Aurora PostgreSQL Serverless v1 | [适用于 Aurora PostgreSQL Serverless v1 的数据 API](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg-sv1) |
| Aurora MySQL Serverless v1 | [适用于 Aurora MySQL Serverless v1 的数据 API](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.amy) |
如果在通过命令行界面或 API 访问数据 API 时需要经过 FIPS 140-2 验证的加密模块，请使用 FIPS 端点。有关可用的 FIPS 端点的更多信息，请参阅[《美国联邦信息处理标准（FIPS）第 140-2 版》](https://aws.amazon.com/compliance/fips/)。
# 将 IPv6 与 Amazon RDS Data API 结合使用
Amazon RDS Data API 支持通过双栈端点实现 IPv6 连接。这样，您就可以使用 IPv6 地址连接到 Data API，同时保持与 IPv4 的向后兼容性。
## IPv6 端点支持
Data API 提供同时支持 IPv4 和 IPv6 连接的双栈端点。这些端点使用 `.aws` 域而不是传统 `.amazonaws.com` 域。
### 可用的端点类型
公共双栈端点
格式：`rds-data.region.api.aws`
示例：`rds-data.us-east-1.api.aws`
FIPS 双栈端点
格式：`rds-data-fips.region.api.aws`
示例：`rds-data-fips.us-east-1.api.aws`
PrivateLink IPv6 端点
可通过支持 IPv6 的 VPC 端点使用
允许在 VPC 内进行私有 IPv6 连接
### 仅 IPv4 传统端点
现有 `.amazonaws.com` 端点继续支持仅 IPv4 连接：
+ `rds-data.region.amazonaws.com`
+ `rds-data-fips.region.amazonaws.com`
**注意**
传统端点保持不变，以确保与现有应用程序的向后兼容。
## 使用 IPv6 端点
要将 IPv6 与 Data API 配合使用，请更新您的应用程序以使用新的双栈端点。您的应用程序将自动使用 IPv6（若可用），或者回退到 IPv4。
有关在您的 VPC 中设置 IPv6 的一般指南，请参阅《Amazon VPC 用户指南》**中的[迁移到 IPv6](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6.html)。
您可以通过两种方式配置 IPv6 端点：
+ **使用环境变量**：在 IPv6 环境中设置 `AWS_USE_DUALSTACK_ENDPOINT=true`。AWS CLI 和 AWS SDK 将自动构造相应的 `api.aws` 端点，而无需您手动指定端点 URL。
+ **使用显式端点 URL**：直接在 AWS CLI 命令或 SDK 配置中指定双栈端点 URL，如下例所示。
### AWS CLI 配置
通过指定端点 URL 将 AWS CLI 配置为使用 IPv6 端点：
对于 Linux、macOS 或 Unix：
```
aws rds-data execute-statement \
--endpoint-url https://rds-data.us-east-1.api.aws \
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" \
--database "mydb" \
--sql "SELECT * FROM users LIMIT 10"
```
对于：Windows
```
aws rds-data execute-statement ^
--endpoint-url https://rds-data.us-east-1.api.aws ^
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" ^
--database "mydb" ^
--sql "SELECT * FROM users LIMIT 10"
```
### AWS SDK 配置
将 AWS SDK 配置为使用双栈端点：
------
#### [ Python ]
```
import boto3
# Create RDS Data API client with IPv6 dual-stack endpoint
client = boto3.client(
'rds-data',
endpoint_url='https://rds-data.us-east-1.api.aws'
)
# Execute a SQL statement
response = client.execute_statement(
resourceArn='arn:aws:rds:us-east-1:123456789012:cluster:my-cluster',
secretArn='arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret',
database='mydb',
sql='SELECT * FROM users LIMIT 10'
)
print(response['records'])
```
------
#### [ Java ]
```
import software.amazon.awssdk.services.rdsdata.RdsDataClient;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementRequest;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementResponse;
import java.net.URI;
// Create RDS Data API client with IPv6 dual-stack endpoint
RdsDataClient client = RdsDataClient.builder()
.endpointOverride(URI.create("https://rds-data.us-east-1.api.aws"))
.build();
// Execute a SQL statement
ExecuteStatementRequest request = ExecuteStatementRequest.builder()
.resourceArn("arn:aws:rds:us-east-1:123456789012:cluster:my-cluster")
.secretArn("arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret")
.database("mydb")
.sql("SELECT * FROM users LIMIT 10")
.build();
ExecuteStatementResponse response = client.executeStatement(request);
System.out.println(response.records());
```
------
#### [ JavaScript ]
```
const { RDSDataClient, ExecuteStatementCommand } = require("@aws-sdk/client-rds-data");
// Create RDS Data API client with IPv6 dual-stack endpoint
const client = new RDSDataClient({
endpoint: "https://rds-data.us-east-1.api.aws"
});
// Execute a SQL statement
const command = new ExecuteStatementCommand({
resourceArn: "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster",
secretArn: "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret",
database: "mydb",
sql: "SELECT * FROM users LIMIT 10"
});
const response = await client.send(command);
console.log(response.records);
```
------
## 将 AWS PrivateLink 与 IPv6 结合使用
您可以为数据 API 创建 VPC 端点，这些端点在您的 VPC 内支持 IPv6 连接。有关为 Data API 创建 VPC 端点的详细说明，请参阅[为 Amazon RDS 数据 API 创建 Amazon VPC 端点（AWS PrivateLink）](data-api.vpc-endpoint.md)。
在创建支持 IPv6 的 VPC 端点时，请确保：
+ 您的 VPC 和子网配置为支持 IPv6
+ 安全组允许 IPv6 流量通过所需的端口（HTTPS 通常为 443）
+ 网络 ACL 配置为允许 IPv6 流量
## 迁移注意事项
在迁移到 IPv6 端点时，请考虑以下事项：
+ **逐步迁移**：您可以通过一次更新一个应用程序的端点 URL 来逐步迁移应用程序。
+ **网络兼容性**：在迁移之前，请确保您的网络基础设施支持 IPv6。
+ **安全策略**：如果需要，更新安全组规则和网络 ACL 以允许 IPv6 流量。
+ **监控**：更新监控和日志配置以处理 IPv6 地址。
**注意**
**数据库连接地址**：将 IPv6 端点用于数据 API 时，底层数据库连接和数据库日志仍将显示 IPv4 地址。这是预期行为，不会影响启用 IPv6 的应用程序的功能。
## 排查 IPv6 连接性问题
如果 IPv6 连接出现问题，请检查以下各项：
网络配置
确认您的网络支持 IPv6，并且 IPv6 路由配置正确。
DNS 解析
确保您的 DNS 解析器可以解析双栈端点的 AAAA 记录。
安全组
更新安全组规则以允许所需端口上的 IPv6 流量（HTTPS 通常为 443）。
客户端库
确认您的 HTTP 客户端库支持 IPv6 和双栈连接。
# Amazon RDS 数据 API 的限制
RDS 数据 API 存在以下限制：
+ 您只能对数据库集群中的写入器实例执行数据 API 查询。但是，写入器实例可以接受写入和读取查询。
+ 使用 Aurora Global Database，您可以在主数据库集群和辅助数据库集群上均启用数据 API。但是，辅助集群在提升为主集群之前，没有写入器实例。数据 API 需要访问写入器实例才能进行查询处理，即使是读取查询也是如此。因此，当辅助集群缺少写入器实例时，发送到辅助集群的读取和写入查询会失败。在辅助集群得到提升并具有可用的写入器实例后，对该数据库实例的数据 API 查询会成功。
+ T 数据库实例类不支持数据 API。
+ 对于 Aurora Serverless v2 和预调配数据库集群，RDS 数据 API 不支持某些数据类型。有关受支持类型的列表，请参阅[Aurora Serverless v2、预置集群与 Aurora Serverless v1 集群的 Amazon RDS 数据 API 行为比较](data-api.differences.md)。
+ 对于 Aurora PostgreSQL 版本 14 和更高版本的数据库，数据 API 仅支持使用 `scram-sha-256` 进行密码加密。
+ 响应大小限制为 1MiB。如果调用返回的响应数据超过 1MiB，则调用将终止。
+ 对于 Aurora Serverless v1，每秒最大请求数为 1000。对于所有其它受支持的数据库，没有限制。
+ 数据库返回的结果集中的 Data API 大小限制为每行 64 KB。确保结果集中的每一行都小于或等于 64 KB。
# Aurora Serverless v2、预置集群与 Aurora Serverless v1 集群的 Amazon RDS 数据 API 行为比较
Amazon RDS 数据 API 的最新增强功能，使得数据 API 可用于使用最新版本 PostgreSQL 或 MySQL 引擎的集群。这些集群可以配置为使用 Aurora Serverless v2 或预置实例类，例如 `db.r6g` 或 `db.r6i`。
以下部分描述了在 Aurora Serverless v2、预置数据库集群和 Aurora Serverless v1 数据库集群上 Amazon RDS 数据 API 的区别。Aurora Serverless v1数据库集群使用 `serverless` 引擎模式。预置数据库集群使用 `provisioned` 引擎模式。Aurora Serverless v2 数据库集群还使用 `provisioned` 引擎模式，并包含一个或多个使用 `db.serverless` 实例类的 Aurora Serverless v2 数据库实例。
## 每秒最大请求数
**Aurora Serverless v1**
数据 API 每秒最多可以发出 1000 个请求。
**Aurora Serverless v2**
数据 API 每秒可以发出的请求数量没有限制。
## 在现有数据库上启用或禁用 Amazon RDS 数据 API
**Aurora Serverless v1**
+ **使用 Amazon RDS API**– 使用 `ModifyCluster` 操作，并为 `EnableHttpEndpoint` 参数指定 `True` 或 `False`（如果适用）。
+ **使用 AWS CLI** – 使用带有 `--enable-http-endpoint` 或 `--no-enable-http-endpoint` 选项的 `modify-db-cluster` 操作（如果适用）。
**Aurora Serverless v2**
+ **使用 Amazon RDS API** – 使用 `EnableHttpEndpoint` 和 `DisableHttpEndpoint` 操作。
+ **使用 AWS CLI**：使用 `enable-http-endpoint` 和 `disable-http-endpoint` 操作。
## CloudTrail 事件
**Aurora Serverless v1**
来自数据 API 调用的事件是管理事件。默认情况下，这些事件会自动包含在跟踪记录中。有关更多信息，请参阅 [从 AWS CloudTrail 跟踪记录中排除数据 API 事件（仅限 Aurora Serverless v1）](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.excluding-cloudtrail-events)。
**Aurora Serverless v2**
来自数据 API 调用的事件是数据事件。默认情况下，这些事件会自动排除在跟踪记录之外。有关更多信息，请参阅 [在 AWS CloudTrail 跟踪记录中包含数据 API 事件](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.including-cloudtrail-events)。
## 多语句支持
**Aurora Serverless v1**
+ 对于 Aurora MySQL，不支持多语句。
+ 对于 Aurora PostgreSQL，多语句仅返回第一个查询响应。
**Aurora Serverless v2**
不支持多语句。尝试在单个 API 调用中执行多条语句会返回 `“An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.”`。要执行多条语句，请使用单独的 `ExecuteStatement` API 调用或使用 `BatchExecuteStatement` API 进行批处理。
以下示例显示了 API 调用在尝试执行多条语句时产生的错误消息。
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table; Select * FROM next_table;
"An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.
```
以下示例使用单独 `ExecuteStatement` API 调用执行多条语句。
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table;"
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM next_table;"
```
## 对于同一事务 ID 的并发请求
**Aurora Serverless v1**
后续请求将等到当前请求完成。如果等待时间过长，应用程序需要处理超时错误。
**Aurora Serverless v2**
数据 API 收到多个具有相同事务 ID 的请求时，会立即返回以下错误：
`DatabaseErrorException: Transaction is still running a query`
此错误会在两种情况下发生：
+ 您的应用程序使用相同的事务 ID 发出异步请求（如 JavaScript promise）。
+ 之前使用相同事务 ID 的请求仍在处理中。
以下示例显示与 `promise.all()` 并行执行的所有请求。
```
const api_calls = [];
for (let i = 0; i < 10; i++) {
api_calls.push(
client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
)
);
}
await Promise.all(api_calls);
```
要解决此错误，请等待当前请求完成，然后再发送具有相同事务 ID 的另一个请求，或者删除事务 ID 以允许并行请求。
以下示例显示的 API 调用使用了具有相同事务 ID 的顺序执行。
```
for (let i = 0; i < 10; i++) {
await client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
).promise()
);
}
```
## BatchExecuteStatement 行为
有关 `BatchExecuteStatement` 的更多信息，请参阅 [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html)。
**Aurora Serverless v1**
更新结果中生成的字段对象包括插入的值。
**Aurora Serverless v2**
+ 对于 Aurora MySQL，更新结果中生成的字段对象包括插入的值。
+ 对于 Aurora PostgreSQL，生成的字段对象为空。
## ExecuteSQL 行为
有关 `ExecuteSQL` 的更多信息，请参阅 [ExecuteSQL](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteSql.html)。
**Aurora Serverless v1**
`ExecuteSQL` 操作已弃用。
**Aurora Serverless v2**
不支持 `ExecuteSQL` 操作。
## ExecuteStatement 行为
有关 `ExecuteStatement` 的更多信息，请参阅 [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html)。
**Aurora Serverless v1**
`ExecuteStatement` 参数支持检索多维数组列和所有高级数据类型。
**Aurora Serverless v2**
`ExecuteStatement` 参数不支持多维数组列。它也不支持某些 PostgreSQL 数据类型，包括几何类型和货币类型。数据 API 在遇到不支持的数据类型时，会返回以下错误：`UnsupportedResultException: The result contains the unsupported data type data_type`。
要解决此问题，请将不支持的数据类型强制转换为 `TEXT`。以下示例将不支持的数据类型转换为 `TEXT`。
```
SELECT custom_type::TEXT FROM my_table;--
ORSELECT CAST(custom_type AS TEXT) FROM my_table;
```
有关各个 Aurora 数据库引擎支持的数据类型的列表，请参阅[数据 API 操作参考](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html#data-api-operations)。
## Schema 参数行为
**Aurora Serverless v1**
不支持 `Schema` 参数。当您在 API 调用中时包含 `Schema` 参数时，数据 API 会忽略该参数。
**Aurora Serverless v2**
`Schema` 参数已弃用。当您在 API 调用中时包含 `Schema` 参数时，数据 API 会返回以下错误：`ValidationException: The schema parameter isn't supported`。以下示例显示返回 `ValidationException` 错误的数据 API 调用。
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--schema "your_schema" \
--sql "SELECT * FROM your_table LIMIT 10"
```
要解决此问题，请删除 API 调用中的 `Schema` 参数。
以下示例显示删除了 `Schema` 参数的数据 API 调用。
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table LIMIT 10"
```
# 授予对 Amazon RDS 数据 API 的访问权限
用户只有在获得授权的情况下才能调用 Amazon RDS 数据 API（数据 API）操作。您可以通过附加定义用户权限的 AWS Identity and Access Management（IAM）策略，授予用户使用数据 API 的权限。如果您使用的是 IAM 角色，您还可以将策略附加到角色。AWS 托管式策略 `AmazonRDSDataFullAccess` 包含数据 API 的权限。
`AmazonRDSDataFullAccess` 策略还包含允许用户从 AWS Secrets Manager 获取密钥值的权限。用户需要使用 Secrets Manager 来存储他们在调用数据 API 时可以使用的密钥。使用密钥意味着用户不需要在调用数据 API 时提供其目标资源的数据库凭证。数据 API 会透明地调用 Secrets Manager，后者会允许（或拒绝）用户的密钥请求。有关如何设置与数据 API 一起使用的密钥的信息，请参阅[在 AWS Secrets Manager 中存储数据库凭证](#data-api.secrets)。
`AmazonRDSDataFullAccess` 策略提供对资源的完全访问权限（通过数据 API 进行访问）。您可以通过定义指定资源的 Amazon 资源名称（ARN）的策略来缩小范围。
例如，以下策略显示了用户访问数据库集群（由其 ARN 标识）的数据 API 所需的最低权限的示例。该策略包含用户访问 Secrets Manager 和获取数据库实例授权所需的权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerDbCredentialsAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*"
},
{
"Sid": "RDSDataServiceAccess",
"Effect": "Allow",
"Action": [
"rds-data:BatchExecuteStatement",
"rds-data:BeginTransaction",
"rds-data:CommitTransaction",
"rds-data:ExecuteStatement",
"rds-data:RollbackTransaction"
],
"Resource": "arn:aws:rds:us-east-2:111122223333:cluster:prod"
}
]
}
```
------
建议您为策略语句中的 "Resources" 元素使用具体的 ARN（如示例所示），而不是通配符 (\$1)。
## 使用基于标签的授权
RDS 数据 API（数据 API）和 Secrets Manager 都支持基于标签的授权。*标签*是用附加的字符串值标记资源（如 RDS 集群）的键值对，例如：
+ `environment:production`
+ `environment:development`
您可以出于成本分配、操作支持、访问控制及许多其他原因，为资源应用标签。（如果您的资源上还没有标签，并且您想要应用标签，您可以在[为 Amazon RDS 资源添加标签](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_Tagging.html)中了解更多信息。） 您可以在策略语句中使用标签来限制对使用这些标签进行标记的 RDS 集群的访问。例如，Aurora 数据库集群可能包含将其环境标识为生产环境或开发环境的标签。
以下示例说明如何在策略语句中使用标签。这条语句要求在 Data API 请求中传递的集群和密钥都包含 `environment:production` 标签。
策略的应用方式如下：当用户使用数据 API 进行调用时，请求被发送到服务。数据 API 首先验证在请求中传递的集群 ARN 是否包含 `environment:production` 标签。然后，它会调用 Secrets Manager 以在请求中检索用户密钥的值。Secrets Manager 还会验证用户的密钥是否已使用 `environment:production` 进行标记。如果包含，Data API 将使用检索到的值作为用户的数据库密码。最后，如果此密码正确，则会为用户成功调用 Data API 请求。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerDbCredentialsAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": [
"production"
]
}
}
},
{
"Sid": "RDSDataServiceAccess",
"Effect": "Allow",
"Action": [
"rds-data:*"
],
"Resource": "arn:aws:rds:us-east-2:111122223333:cluster:*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": [
"production"
]
}
}
}
]
}
```
------
该示例分别显示了针对数据 API 和 Secrets Manager 的 `rds-data` 和 `secretsmanager` 操作。不过，您可以通过多种不同的方式组合操作和定义标签条件，以支持您的特定使用案例。有关更多信息，请参阅[为 Secrets Manager 使用基于身份的策略（IAM 策略）](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html#permissions_grant-limited-condition)。
在策略的 "Condition" 元素中，您可以从以下选项中选择标签键：
+ `aws:TagKeys`
+ `aws:ResourceTag/${TagKey}`
要了解有关资源标签以及如何使用 `aws:TagKeys` 的更多信息，请参阅[使用资源标签控制对 AWS 资源的访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-tag-keys)。
**注意**
数据 API 和 AWS Secrets Manager 都会对用户进行授权。如果您不具有策略中定义的所有操作的权限，则会收到 `AccessDeniedException` 错误。
## 在 AWS Secrets Manager 中存储数据库凭证
调用 Amazon RDS 数据 API（数据 API）时，您可以使用 Secrets Manager 中的密钥传递 Aurora 数据库集群的凭证。要通过此方式传递凭证，您需要指定密钥的名称或密钥的 Amazon 资源名称（ARN）。
**在密钥中存储数据库集群凭证**
1. 使用 Secrets Manager 创建包含 Aurora 数据库集群凭证的密钥。
有关说明，请参阅《AWS Secrets Manager 用户指南》**中的[创建数据库密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_database_secret.html)。
1. 使用 Secrets Manager 控制台查看您创建的密钥的详细信息，或运行 `aws secretsmanager describe-secret` AWS CLI 命令。
记下密钥的名称和 ARN。您可以将其用于对数据 API 的调用中。
有关使用 Secrets Manager 的更多信息，请参阅 [AWS Secrets Manager 用户指南](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。
要了解 Amazon Aurora 如何管理身份和访问管理，请参阅 [Amazon Aurora 如何使用 IAM](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/security_iam_service-with-iam.html)。
有关创建 IAM 策略的更多信息，请参阅 *IAM 用户指南*中的[创建 IAM 策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)。有关将 IAM 策略添加到用户的信息，请参阅《IAM 用户指南》** 中的[添加和删除 IAM 身份权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。
# 启用 Amazon RDS 数据 API
要使用 Amazon RDS 数据 API（数据 API），请为 Aurora 数据库集群启用它。您可以在创建或修改数据库集群时启用数据 API。
**注意**
数据 API 是否适用于您的集群取决于您的 Aurora 版本、数据库引擎和 AWS 区域。对于较早的 Aurora 版本，数据 API 仅适用于 Aurora Serverless v1 集群。对于较新的 Aurora 版本，数据 API 适用于同时使用预调配和 Aurora Serverless v2 实例的集群。要检查您的集群是否可以使用数据 API，请参阅[支持 RDS 数据 API 的区域和 Aurora 数据库引擎](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md)。
**Topics**
+ [在创建数据库时启用 RDS 数据 API](#data-api.enabling.creating)
+ [在现有数据库上启用 RDS 数据 API](#data-api.enabling.modifying)
## 在创建数据库时启用 RDS 数据 API
在创建支持 RDS 数据 API（数据 API）的数据库时，您可以启用此功能。以下过程描述了在使用 AWS 管理控制台、AWS CLI 或 RDS API 时如何执行此操作。
### 控制台
要在创建数据库集群时启用数据 API，请在**创建数据库**页面的**连接**部分中选中**启用 RDS 数据 API** 复选框，如以下屏幕截图所示。
![\[“创建数据库”页面上的“连接”部分，“启用 RDS 数据 API”复选框处于选中状态。\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-on-create.png)
有关如何创建可使用 RDS 数据 API 的 Aurora 数据库集群的说明，请参阅以下内容：
+ 对于 Aurora Serverless v2 和预调配集群：[创建 Amazon Aurora 数据库集群](Aurora.CreateInstance.md)
+ 对于 Aurora Serverless v1 – [创建 Aurora Serverless v1 数据库集群](aurora-serverless.create.md)
### AWS CLI
要在创建 Aurora 数据库集群时启用数据 API，请运行带 `--enable-http-endpoint` 选项的 [create-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-cluster.html) AWS CLI 命令。
以下示例创建一个启用了数据 API 的 Aurora PostgreSQL 数据库集群。
对于 Linux、macOS 或 Unix：
```
aws rds create-db-cluster \
--db-cluster-identifier my_pg_cluster \
--engine aurora-postgresql \
--enable-http-endpoint
```
对于：Windows
```
aws rds create-db-cluster ^
--db-cluster-identifier my_pg_cluster ^
--engine aurora-postgresql ^
--enable-http-endpoint
```
### RDS API
要在创建 Aurora 数据库集群时启用数据 API，请使用 [CreateDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBCluster.html) 操作，并将 `EnableHttpEndpoint` 参数的值设置为 `true`。
## 在现有数据库上启用 RDS 数据 API
您可以修改支持 RDS 数据 API（数据 API）的数据库集群以启用或禁用此功能。
**Topics**
+ [启用或禁用数据 API（Aurora Serverless v2 和预调配）](#data-api.enabling.modifying.all)
+ [启用或禁用数据 API（仅限 Aurora Serverless v1）](#data-api.enabling.modifying.sv1)
### 启用或禁用数据 API（Aurora Serverless v2 和预调配）
使用以下过程可在 Aurora Serverless v2 和预调配数据库上启用或禁用数据 API。要在 Aurora Serverless v1 数据库上启用或禁用数据 API，请使用[启用或禁用数据 API（仅限 Aurora Serverless v1）](#data-api.enabling.modifying.sv1)中的过程。
#### 控制台
您可以使用 RDS 控制台为支持此功能的数据库集群启用或禁用数据 API。为此，请打开要启用或禁用数据 API 的数据库的集群详细信息页面上，然后在**连接和安全**选项卡上，转到 **RDS 数据 API** 部分。此部分显示数据 API 的状态，并允许您启用或禁用它。
以下屏幕截图显示 **RDS 数据 API** 未启用。
![\[数据库集群详细信息页面的“连接和安全”选项卡上的“RDS 数据 API”部分。数据 API 的状态显示为已禁用，并显示“启用 RDS 数据 API”按钮。\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-from-details.png)
#### AWS CLI
要在现有数据库上启用或禁用数据 API，请运行 [enable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/enable-http-endpoint.html) 或 [disable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/disable-http-endpoint.html) AWS CLI 命令，然后指定数据库集群的 ARN。
以下示例启用数据 API。
对于 Linux、macOS 或 Unix：
```
aws rds enable-http-endpoint \
--resource-arn cluster_arn
```
对于：Windows
```
aws rds enable-http-endpoint ^
--resource-arn cluster_arn
```
#### RDS API
要在现有数据库上启用或禁用数据 API，请使用 [EnableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_EnableHttpEndpoint.html) 和 [DisableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DisableHttpEndpoint.html) 操作。
### 启用或禁用数据 API（仅限 Aurora Serverless v1）
使用以下步骤在现有 Aurora Serverless v1 数据库上启用或禁用数据 API。要在 Aurora Serverless v2 和预调配数据库上启用或禁用数据 API，请使用[启用或禁用数据 API（Aurora Serverless v2 和预调配）](#data-api.enabling.modifying.all)中的过程。
#### 控制台
在修改 Aurora Serverless v1 数据库集群时，您可以在 RDS 控制台的**连接**部分中启用数据 API。
以下屏幕截图显示了在修改 Aurora 数据库集群时启用的**数据 API**。
![\[“修改数据库集群”页面上的“连接”部分，“数据 API”复选框处于选中状态。\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/images/data-api-modify-serverlessv1.png)
有关如何修改 Aurora Serverless v1 数据库集群的说明，请参阅[修改 Aurora Serverless v1 数据库集群](aurora-serverless.modifying.md)。
#### AWS CLI
要启用或禁用数据 API，请运行 [modify-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-cluster.html) AWS CLI 命令，并使用 `--enable-http-endpoint` 或 `--no-enable-http-endpoint`（如果适用）。
以下示例在 `sample-cluster` 上启用数据 API。
对于 Linux、macOS 或 Unix：
```
aws rds modify-db-cluster \
--db-cluster-identifier sample-cluster \
--enable-http-endpoint
```
对于：Windows
```
aws rds modify-db-cluster ^
--db-cluster-identifier sample-cluster ^
--enable-http-endpoint
```
#### RDS API
要启用数据 API，请使用 [ModifyDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBCluster.html) 操作，并将 `EnableHttpEndpoint` 的值设置为 `true` 或 `false`（如果适用）。
# 为 Amazon RDS 数据 API 创建 Amazon VPC 端点（AWS PrivateLink）
借助 Amazon VPC，您可以在 Virtual Private Cloud (VPC) 中启动AWS资源（例如 Aurora 数据库集群和应用程序）。AWS PrivateLink 在亚马逊网络上提供了 VPC 和AWS服务之间的私有连接，这种连接具有高度的安全性。通过使用 AWS PrivateLink，您可以创建 Amazon VPC 端点，这可让您根据 Amazon VPC 跨不同的账号和 VPC 连接到服务。有关 AWS PrivateLink 的更多信息，请参阅《Amazon Virtual Private Cloud 用户指南》**中的 [VPC 端点服务（AWS PrivateLink）](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html)。
您可以使用 Amazon VPC 端点调用 RDS 数据 API（数据 API）。使用 Amazon VPC 端点可保持 Amazon VPC 中的应用程序与 AWS 网络中数据 API 间的流量，而无需使用公有 IP 地址。Amazon VPC 端点可帮助您遵守与管理公共互联网连接有关的合规性和法规要求。例如，如果您使用 Amazon VPC 端点，则可保持 Amazon EC2 实例上运行的应用程序和包含端点的 VPC 中的数据 API 之间的流量。
创建 Amazon VPC 端点后，便能开始使用此端点，而无需在应用程序中进行任何代码或配置更改。
**为数据 API 创建 Amazon VPC 端点**
1. 登录到AWS 管理控制台并打开 Amazon VPC 控制台，网址：[https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)。
1. 选择**端点**，然后选择**创建端点**。
1. 在 **Create Endpoint (创建端点)** 页面上，为 **Service category (服务类别)** 选择 **AWS services ( 服务)**。对于 **Service Name (服务名称)**，请选择 **rds-data**。
![\[为数据 API 创建 Amazon VPC 端点\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/images/data-api-create-endpoint.png)
1. 对于 **VPC**，选择要在其中创建端点的 VPC。
选择包含用于进行 Data API 调用的应用程序的 VPC。
1. 对于 **Subnets**（子网），请为运行应用程序的 AWS 服务所使用的每个可用区 (AZ) 选择子网。
![\[为 Amazon VPC 端点选择子网\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-subnets.png)
要创建 Amazon VPC 端点，请指定端点可在其中访问的私有 IP 地址范围。为此，请为每个可用区选择子网。执行此操作会将 VPC 端点限制为特定于每个可用区的私有 IP 地址范围，并且还会在每个可用区中创建一个 Amazon VPC 端点。
1. 对于 **Enable DNS Name (启用 DNS 名称)**，选择 **Enable for this endpoint (为此端点启用)**。
![\[为 Amazon VPC 端点启用 DNS 名称\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-enable-endpoint.png)
私有 DNS 会将标准 Data API DNS 主机名 (`https://rds-data.region.amazonaws.com`) 解析为与特定于 Amazon VPC 端点的 DNS 主机名关联的私有 IP 地址。因此，您可以使用 AWS CLI 或 AWS SDK 访问数据 API VPC 端点，而无需进行任何代码或配置更改来更新数据 API 的端点 URL。
1. 对于**安全组**，选择要与 Amazon VPC 端点关联的安全组。
选择允许访问运行应用程序的 AWS 服务的安全组。例如，如果 Amazon EC2 实例正在运行您的应用程序，请选择允许访问 Amazon EC2 实例的安全组。利用安全组，您可以控制从 VPC 中的资源发送到 Amazon VPC 端点的流量。
1. 对于 **Policy (策略)**，选择 **Full Access (完全访问)** 以允许 Amazon VPC 中的任何人通过此端点访问 Data API。或者，选择 **Custom (自定义)** 以指定限制访问的策略。
如果选择 **Custom (自定义)**，请在策略创建工具中输入策略。
1. 选择**Create endpoint**。
创建端点后，选择 AWS 管理控制台中的链接以查看端点详细信息。
![\[链接到 Amazon VPC 端点详细信息\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-link-to-details.png)
端点 **Details (详细信息)** 选项卡将显示在创建 Amazon VPC 端点时生成的 DNS 主机名。
![\[链接到 Amazon VPC 终端节点详细信息\]](http://docs.aws.amazon.com/zh_cn/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-dns-names.png)
您可以使用标准端点 (`rds-data.region.amazonaws.com`) 或特定于 VPC 的端点之一来调用 Amazon VPC 中的 Data API。标准 Data API 端点将自动路由到 Amazon VPC 端点。发生此路由的原因是，在创建 Amazon VPC 端点时启用了私有 DNS 主机名。
在数据 API 调用中使用 Amazon VPC 端点时，应用程序和数据 API 之间的所有流量将保留在包含它们的 Amazon VPC 中。可以将 Amazon VPC 端点用于任何类型的 Data API 调用。有关调用数据 API 的信息，请参阅[调用 Amazon RDS 数据 API](data-api.calling.md)。
# 调用 Amazon RDS 数据 API
在 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 操作参考
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
您可以使用 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，则调用将终止。
对于 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 语句
您可以通过使用 `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 事务
通过使用 `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"
}
```
# 从 Python 应用程序调用 Amazon RDS 数据 API
您可以从 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 查询
您可以运行 `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 语句
您可以运行数据操作语言 (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 事务
您可以通过 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
您可以从 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 查询
您可以运行 `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 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 事务
您可以通过 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 操作
您可以使用 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 超时行为
对 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));
}
```
# 使用适用于 RDS 数据 API 的 Java 客户端库
您可以下载并使用适用于 RDS 数据 API（数据 API）的 Java 客户端库。此 Java 客户端库提供了使用数据 API 的另一种方法。使用该库，您可以将客户端类映射到数据 API 的请求和响应。这种映射支持可以简化与某些特定 Java 类型（如 `Date`、`Time` 和 `BigDecimal`）的集成。
## 下载适用于 Data API 的 Java 客户端库
Data API Java 客户端库是 GitHub 中是开源的，位于以下位置：
[ https://github.com/awslabs/rds-data-api-client-library-java](https://github.com/awslabs/rds-data-api-client-library-java)
您可以从源文件手动构建该库，但最佳实践是使用 Apache Maven 依赖项管理来使用该库。将以下依赖项添加到 Maven POM 文件中。
对于与 AWS SDK 2.x 兼容的版本 2.x，请使用以下命令：
```
software.amazon.rdsdata
rds-data-api-client-library-java
2.0.0
```
对于与 AWS SDK 1.x 兼容的版本 1.x，请使用以下命令：
```
software.amazon.rdsdata
rds-data-api-client-library-java
1.0.8
```
## Java 客户端库示例
在下面，您可以找到一些使用 Data API Java 客户端库的常见示例。这些示例假设您有一个包含两列（`accountId` 和 `name`）的表 `accounts`。您还拥有以下数据传输对象 (DTO)。
```
public class Account {
int accountId;
String name;
// getters and setters omitted
}
```
该客户端库使您可以将 DTO 作为输入参数进行传递。以下示例演示了如何将客户 DTO 映射到输入参数集。
```
var account1 = new Account(1, "John");
var account2 = new Account(2, "Mary");
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParamSets(account1, account2)
.execute();
```
在某些情况下，使用简单值作为输入参数会更容易。可以使用以下语法来做到这一点。
```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParameter("accountId", 3)
.withParameter("name", "Zhang")
.execute();
```
下面是另一个使用简单值作为输入参数的示例。
```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos")
.execute();
```
当返回结果时，客户端库提供到 DTO 的自动映射。以下示例演示了如何将结果映射到您的 DTO。
```
List result = client.forSql("SELECT * FROM accounts")
.execute()
.mapToList(Account.class);
Account result = client.forSql("SELECT * FROM accounts WHERE account_id = 1")
.execute()
.mapToSingle(Account.class);
```
在很多情况下，数据库结果集只包含一个值。为了简化检索此类结果的过程，客户端库提供了以下 API：
```
int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
.execute()
.singleValue(Integer.class);
```
**注意**
`mapToList` 函数将 SQL 结果集转换为用户定义的对象列表。我们不支持在对 Java 客户端库的 `ExecuteStatement` 调用中使用 `.withFormatRecordsAs(RecordsFormatType.JSON)` 语句，因为它具有相同的目的。有关更多信息，请参阅 [处理 JSON 格式的 Amazon RDS 数据 API 查询结果](data-api-json.md)。
# 处理 JSON 格式的 Amazon RDS 数据 API 查询结果
当您调用 `ExecuteStatement` 操作时，可以选择将查询结果作为 JSON 格式的字符串返回。这样，您就可以使用编程语言的 JSON 解析功能来解释和重新格式化结果集。这样做有助于避免编写额外的代码来循环浏览结果集并解释每个列值。
要请求 JSON 格式的结果集，您需要传递值为 `JSON` 的可选 `formatRecordsAs` 参数。JSON 格式的结果集将在 `ExecuteStatementResponse` 结构的 `formattedRecords` 字段中返回。
`BatchExecuteStatement` 操作不返回结果集。因此，JSON 选项不适用于该操作。
要自定义 JSON 哈希结构中的键，请在结果集中定义列别名。为此，您可以使用 SQL 查询的列列表中的 `AS` 子句。
您可以使用 JSON 功能使结果集更易于阅读，并将其内容映射到特定于语言的框架。由于 ASCII 编码的结果集的卷大于默认表示形式，因此如果查询返回大量的行或较大的列值，占用的内存超过应用程序可用的内存，则您可以选择默认表示形式。
**Topics**
+ [检索 JSON 格式的查询结果](#data-api-json-querying)
+ [数据类型映射](#data-api-json-datatypes)
+ [故障排除](#data-api-json-troubleshooting)
+ [示例](#data-api-json-examples)
## 检索 JSON 格式的查询结果
要以 JSON 字符串的形式接收结果集，请在 `ExecuteStatement` 调用中包括 `.withFormatRecordsAs(RecordsFormatType.JSON)`。返回值在 `formattedRecords` 字段中以 JSON 字符串的形式返回。在本例中，`columnMetadata` 为 `null`。列标签是表示每行的对象的键。这些列名称在结果集中的每一行都会重复出现。列值是带引号的字符串、数值或表示 `true`、`false` 或 `null` 的特殊值。JSON 响应中不会保留列元数据，例如长度约束以及数字和字符串的精确类型。
如果您省略 `.withFormatRecordsAs()` 调用或指定 `NONE` 的参数，系统将使用 `Records` 和 `columnMetadata` 字段以二进制格式返回结果集。
## 数据类型映射
结果集中的 SQL 值映射到一组较小的 JSON 类型。这些值在 JSON 中表示为字符串、数字和一些特殊常量，例如 `true`、`false` 和`null`。您可以根据编程语言的不同，使用强类型或弱类型将这些值转换为应用程序中的变量。
****
| JDBC 数据类型 | JSON 数据类型 |
| --- | --- |
| `INTEGER`, `TINYINT`, `SMALLINT`, `BIGINT` | 默认情况下为数字。如果 `LongReturnType` 选项设置为 `STRING`，则为字符串。 |
| `FLOAT`, `REAL`, `DOUBLE` | 数字 |
| `DECIMAL` | 默认情况下为字符串。如果 `DecimalReturnType` 选项设置为 `DOUBLE_OR_LONG`，则为数字。 |
| `STRING` | 字符串 |
| `BOOLEAN`, `BIT` | 布尔值 |
| `BLOB`, `BINARY`, `VARBINARY`, `LONGVARBINARY` | base64 编码的字符串。 |
| `CLOB` | 字符串 |
| `ARRAY` | 数组 |
| `NULL` | `null` |
| 其他类型（包括与日期和时间有关的类型） | 字符串 |
## 故障排除
JSON 响应限制为 10 兆字节。如果响应超过此限制，则您的程序会收到 `BadRequestException` 错误。在这种情况下，您可以使用以下方法之一解决该错误：
+ 减少结果集中的行数。为此，请添加 `LIMIT` 子句。您可以通过提交多个带有 `LIMIT` 和 `OFFSET` 子句的查询，将一个大型结果集拆分为多个较小的结果集。
如果结果集中包含被应用程序逻辑筛选掉的行，您可以通过在 `WHERE` 子句中添加更多条件，从结果集中删除这些行。
+ 减少结果集中的列数。为此，请从查询的选择列表中删除项目。
+ 通过在查询中使用列别名来缩短列标签。对于结果集中的每一行，每个列名都会在 JSON 字符串中重复出现。因此，具有长列名和许多行的查询结果可能会超过大小限制。特别是，对复杂的表达式使用列别名，以避免在 JSON 字符串中重复整个表达式。
+ 虽然在 SQL 中可以使用列别名来生成具有多个同名列的结果集，但在 JSON 中不允许有重复的键名。如果您请求 JSON 格式的结果集，并且多个列具有相同名称，则 RDS Data API 将返回错误。因此，请确保所有列标签都具有唯一的名称。
## 示例
以下 Java 示例演示了如何调用 `ExecuteStatement` 并将响应作为 JSON 格式的字符串，然后解释结果集。用适当的值替换 *databaseName*、*secretStoreArn* 和 *clusterArn* 参数。
以下 Java 示例演示了一个在结果集中返回十进制数值的查询。`assertThat` 调用会测试响应的字段是否具有基于 JSON 结果集规则的预期属性。
该示例适用于以下架构和示例数据：
```
create table test_simplified_json (a float);
insert into test_simplified_json values(10.0);
```
```
public void JSON_result_set_demo() {
var sql = "select * from test_simplified_json";
var request = new ExecuteStatementRequest()
.withDatabase(databaseName)
.withSecretArn(secretStoreArn)
.withResourceArn(clusterArn)
.withSql(sql)
.withFormatRecordsAs(RecordsFormatType.JSON);
var result = rdsdataClient.executeStatement(request);
}
```
之前程序中的 `formattedRecords` 字段的值为：
```
[{"a":10.0}]
```
由于存在 JSON 结果集，响应中的 `Records` 和 `ColumnMetadata` 字段均为 null。
以下 Java 示例演示了一个在结果集中返回整数数值的查询。该示例调用 `getFormattedRecords` 以仅返回 JSON 格式的字符串，并忽略其他空白或为 null 的响应字段。该示例将结果反序列化为一个表示记录列表的结构。每条记录都有一些字段，字段名称对应于结果集中的列别名。此技术简化了解析结果集的代码。您的应用程序不必循环浏览结果集的行和列并将每个值转换为适当类型。
该示例适用于以下架构和示例数据：
```
create table test_simplified_json (a int);
insert into test_simplified_json values(17);
```
```
public void JSON_deserialization_demo() {
var sql = "select * from test_simplified_json";
var request = new ExecuteStatementRequest()
.withDatabase(databaseName)
.withSecretArn(secretStoreArn)
.withResourceArn(clusterArn)
.withSql(sql)
.withFormatRecordsAs(RecordsFormatType.JSON);
var result = rdsdataClient.executeStatement(request)
.getFormattedRecords();
/* Turn the result set into a Java object, a list of records.
Each record has a field 'a' corresponding to the column
labelled 'a' in the result set. */
private static class Record { public int a; }
var recordsList = new ObjectMapper().readValue(
response, new TypeReference>() {
});
}
```
之前程序中的 `formattedRecords` 字段的值为：
```
[{"a":17}]
```
要检索结果行 0 的 `a` 列，应用程序将引用 `recordsList.get(0).a`。
相比之下，以下 Java 示例显示了在不使用 JSON 格式的情况下，构建保存结果集的数据结构所需的代码类型。在这种情况下，结果集的每一行都包含一些字段，其中包含有关单个用户的信息。构建表示结果集的数据结构需要循环浏览这些行。对于每一行，代码会检索每个字段的值，执行适当的类型转换，并将结果分配给表示该行的对象中的相应字段。然后，代码将表示每个用户的对象添加到表示整个结果集的数据结构中。如果将查询更改为重新排序、添加或删除结果集中的字段，则也必须更改应用程序代码。
```
/* Verbose result-parsing code that doesn't use the JSON result set format */
for (var row: response.getRecords()) {
var user = User.builder()
.userId(row.get(0).getLongValue())
.firstName(row.get(1).getStringValue())
.lastName(row.get(2).getStringValue())
.dob(Instant.parse(row.get(3).getStringValue()))
.build();
result.add(user);
}
```
以下示例值显示了具有不同列数、列别名和列数据类型的结果集的 `formattedRecords` 字段的值。
如果结果集包含多行，则每一行都表示为一个作为数组元素的对象。结果集中的每一列都成为对象中的一个键。这些键在结果集中的每一行都会重复出现。因此，对于包含许多行和列的结果集，您可能需要定义短列别名，以避免超出整个响应的长度限制。
该示例适用于以下架构和示例数据：
```
create table sample_names (id int, name varchar(128));
insert into sample_names values (0, "Jane"), (1, "Mohan"), (2, "Maria"), (3, "Bruce"), (4, "Jasmine");
```
```
[{"id":0,"name":"Jane"},{"id":1,"name":"Mohan"},
{"id":2,"name":"Maria"},{"id":3,"name":"Bruce"},{"id":4,"name":"Jasmine"}]
```
如果结果集中的某一列被定义为表达式，则该表达式的文本将成为 JSON 键。因此，为查询的选择列表中的每个表达式定义一个描述性列别名通常很方便。例如，以下查询在其选择列表中包含诸如函数调用和算术运算之类的表达式。
```
select count(*), max(id), 4+7 from sample_names;
```
这些表达式将作为键传递到 JSON 结果集。
```
[{"count(*)":5,"max(id)":4,"4+7":11}]
```
添加带有描述性标签的 `AS` 列可以简化 JSON 结果集中键的解释。
```
select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;
```
在修订后的 SQL 查询中，使用由 `AS` 子句定义的列标签作为键名。
```
[{"rows":5,"largest_id":4,"addition_result":11}]
```
JSON 字符串中每个键值对的值可以是带引号的字符串。该字符串可能包含 Unicode 字符。如果该字符串包含转义序列或者 `"` 或 `\` 字符，则这些字符前面必须有反斜杠转义字符。以下 JSON 字符串示例演示了这些可能性。例如，`string_with_escape_sequences` 结果包含特殊字符：退格符、换行符、回车符、制表符、换页符和 `\`。
```
[{"quoted_string":"hello"}]
[{"unicode_string":"邓不利多"}]
[{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}]
```
JSON 字符串中每个键值对的值也可以表示一个数字。该数字可能是整数、浮点值、负值或以指数表示法表示的值。以下 JSON 字符串示例演示了这些可能性。
```
[{"integer_value":17}]
[{"float_value":10.0}]
[{"negative_value":-9223372036854775808,"positive_value":9223372036854775807}]
[{"very_small_floating_point_value":4.9E-324,"very_large_floating_point_value":1.7976931348623157E308}]
```
布尔值和 null 值用不带引号的特殊关键字 `true`、`false` 和 `null` 表示。以下 JSON 字符串示例演示了这些可能性。
```
[{"boolean_value_1":true,"boolean_value_2":false}]
[{"unknown_value":null}]
```
如果选择 BLOB 类型的值，则结果将在 JSON 字符串中表示为 base64 编码值。要将值转换回原始表示形式，可以使用应用程序语言中的相应解码函数。例如，在 Java 中调用函数 `Base64.getDecoder().decode()`。以下示例输出显示了选择 `hello world` 的 BLOB 值并将结果集作为 JSON 字符串返回的结果。
```
[{"blob_column":"aGVsbG8gd29ybGQ="}]
```
以下 Python 示例展示了如何访问调用 Python `execute_statement` 函数的结果中的值。结果集是字段 `response['formattedRecords']` 中的字符串值。该代码通过调用 `json.loads` 函数，将 JSON 字符串转换为数据结构。然后，结果集的每一行都是数据结构中的一个列表元素，在每一行中，您可以按名称引用结果集的每个字段。
```
import json
result = json.loads(response['formattedRecords'])
print (result[0]["id"])
```
以下 JavaScript 示例展示了如何访问调用 JavaScript `executeStatement` 函数的结果中的值。结果集是字段 `response.formattedRecords` 中的字符串值。该代码通过调用 `JSON.parse` 函数，将 JSON 字符串转换为数据结构。然后，结果集的每一行都是数据结构中的一个数组元素，在每一行中，您可以按名称引用结果集的每个字段。
```
```
# Amazon RDS 数据 API 故障排除
使用以下部分（标题为常见错误消息）帮助解决 Amazon RDS 数据 API（数据 API）问题。
**Topics**
+ [未找到事务 ](#data-api.troubleshooting.tran-id-not-found)
+ [用于查询的包太大](#data-api.troubleshooting.packet-too-large)
+ [数据库响应超出大小限制](#data-api.troubleshooting.response-size-too-large)
+ [没有为集群 启用 HttpEndpoint](#data-api.troubleshooting.http-endpoint-not-enabled)
+ [DatabaseErrorException：事务仍在运行查询](#data-api.troubleshooting.txn-concurrent-requests-rejected)
+ [不支持的结果异常](#data-api.troubleshooting.unsupported-result)
+ [不支持多语句](#data-api.troubleshooting.multi-statements)
+ [不支持架构参数](#data-api.troubleshooting.schema-parameter)
+ [IPv6 连接问题](#data-api.troubleshooting.ipv6-connectivity)
## 未找到事务
在此情况下，找不到 Data API 调用中指定的事务 ID。错误消息提供了导致此问题的原因，是以下原因之一：
+ 事务可能已过期。
确保每个事务调用在上一个事务调用之后的 3 分钟内运行。
也可能是指定的事务 ID 不是由 [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html) 调用创建的。确保您的调用具有有效的事务 ID。
+ 之前的一次调用导致您的事务终止。
交易已经由您的`CommitTransaction`或者`RollbackTransaction`调用。
+ 由于之前的调用发生错误，事务已中止。
检查您之前的电话是否引发了任何异常。
有关运行事务的信息，请参阅[调用 Amazon RDS 数据 API](data-api.calling.md)。
## 用于查询的包太大
在此情况下，为行返回的结果集太大。数据库返回的结果集中的 Data API 大小限制为每行 64 KB。
要解决此问题，请确保结果集中的每一行都小于或等于 64 KB。
## 数据库响应超出大小限制
在此情况下，数据库返回的结果集太大。数据库返回的结果集中的 Data API 限制为 1MiB。
要解决此问题，请确保对数据 API 的调用返回 1MiB 或更少数据。如果需要返回 1MiB 以上的数据，您可以在查询中将多个 [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) 调用与 `LIMIT` 子句结合使用。
有关 `LIMIT` 子句的更多信息，请参阅 MySQL 文档中的 [SELECT 语法](https://dev.mysql.com/doc/refman/8.0/en/select.html)。
## 没有为集群 启用 HttpEndpoint
请查看以下可能导致该问题的原因：
+ Aurora 数据库集群不支持数据 API。有关 RDS 数据 API 支持的数据库集群类型的信息，请参阅[Amazon RDS 数据 API 的区域和版本可用性](data-api.regions.md)。
+ 未为 Aurora 数据库集群启用数据 API。要将数据 API 与 Aurora 数据库集群结合使用，必须为该数据库集群启用数据 API。有关启用数据 API 的信息，请参阅[启用 Amazon RDS 数据 API](data-api.enabling.md)。
+ 在为数据库集群启用数据 API 之后，已重命名该数据库集群。在这种情况下，请关闭该集群的数据 API，然后再次启用它。
+ 您指定的 ARN 与集群的 ARN 不完全匹配。请检查从另一个源返回的 ARN 或由程序逻辑构造的 ARN 是否与集群的 ARN 完全匹配。例如，请确保您使用的 ARN 的所有字母字符的大小写正确。
## DatabaseErrorException：事务仍在运行查询
如果您的应用程序发送了带有事务 ID 的请求，而该事务当前正在处理另一个请求，则 Data API 会立即将此错误返回给您的应用程序。如果您的应用程序使用诸如 Javascript 中的“promises”之类的机制发出异步请求，则可能会出现这种情况。
要解决此问题，请等到上一个请求完成，然后重试该请求。您可以继续重试，直到错误不再出现，或者应用程序收到其他类型的错误。
这种情况可能发生在 Aurora Serverless v2 的 Data API 和预配置实例中。在 Aurora Serverless v1 的 Data API 中，对同一事务 ID 的后续请求会自动等待上一个请求完成。但是，由于之前的请求花费了太长时间，这种过时的行为可能会出现超时。如果您要移植发出并发请求的过时 Data API 应用程序，请修改异常处理逻辑以处理这种新错误。
## 不支持的结果异常
数据 API 并不支持全部的数据类型。当您执行返回不支持的数据类型的查询时，就会发生此错误。
要解决此问题，请将不支持的数据类型强制转换为 `TEXT`。例如：
```
SELECT custom_type::TEXT FROM my_table;
-- OR
SELECT CAST(custom_type AS TEXT) FROM my_table;
```
## 不支持多语句
Aurora Serverless v2 和预置集群的数据 API 不支持多语句。尝试在单个 API 调用中执行多条语句会导致此错误。
要执行多条语句，请使用单独的 `ExecuteStatement` API 调用或使用 `BatchExecuteStatement` API 进行批处理。
## 不支持架构参数
Aurora Serverless v1 会静默忽略架构参数。但是，Aurora Serverless v2 和预置集群会显式拒绝包含架构参数的 API 调用。
要解决此问题，请在使用 Aurora Serverless v2 或预置集群时，从对数据 API 的所有调用中移除架构参数。
## IPv6 连接问题
如果您在使用 IPv6 端点连接到 Data API 时遇到问题，请检查以下潜在原因：
+ **网络不支持 IPv6**：确认您的网络基础设施支持 IPv6，并且 IPv6 路由配置正确。
+ **DNS 解析问题**：确保您的 DNS 解析器可以解析双栈端点（例如 `rds-data.us-east-1.api.aws`）的 AAAA 记录。
+ **安全组配置**：更新安全组规则以允许端口 443（HTTPS）上的 IPv6 流量。为 IPv6 CIDR 数据块添加规则（例如，`::/0` 表示所有 IPv6 地址）。
+ **网络 ACL 配置**：确保网络 ACL 允许 IPv6 流量通过所需的端口。
+ **客户端库兼容性**：确认您的 HTTP 客户端库和 AWS SDK 支持 IPv6 和双栈连接。
+ **VPC 端点配置**：如果使用 PrivateLink，请确保将您的 VPC 端点配置为支持 IPv6，并且关联的子网已分配 IPv6 CIDR 数据块。
要对 IPv6 连接问题进行故障排除，请执行以下操作：
1. 使用仅限 IPv4 的端点（`.amazonaws.com`）测试连接，以验证问题是否特定于 IPv6。
1. 使用网络诊断工具验证 IPv6 与双栈端点的连接。
1. 使用 IPv6 端点时，请查看 CloudTrail 日志中是否存在任何身份验证或授权错误。
1. 验证您的应用程序是否已正确配置为使用新的双栈端点 URL。
# 使用 AWS CloudTrail 记录 Amazon RDS 数据 API 调用
RDS 数据 API（数据 API）已与 AWS CloudTrail 集成，后者是一项提供数据 API 中由用户、角色或 AWS 服务所采取操作的记录的服务。CloudTrail 将对数据 API 的所有 API 调用作为事件捕获，包括来自 Amazon RDS 控制台的调用和对数据 API 操作的代码调用。如果您创建跟踪，可以使 CloudTrail 事件持续传送到 Amazon S3 存储桶（包括数据 API 的事件）。通过使用 CloudTrail 收集的数据，您可以确定大量的信息。此信息包括向数据 API 发出了什么请求、发出请求的 IP 地址、何人发出的请求、请求的发出时间以及其他详细信息。
要了解有关 CloudTrail 的更多信息，请参阅 [AWS CloudTrail 用户指南](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)。
## 在 CloudTrail 中使用数据 API 信息
在您创建 AWS 账户时，将在该账户上启用 CloudTrail。当数据 API 中发生受支持的活动（管理事件）时，该活动将记录在 CloudTrail 事件中，并与其它 AWS 服务事件一同保存在**事件历史记录**中。您可以在 AWS 账户中查看、搜索和下载最新管理事件。有关更多信息，请参阅《AWS CloudTrail 用户指南》的[使用 CloudTrail 事件历史记录](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html)**。
要持续记录 AWS 账户中的事件（包括数据 API 的事件），请创建跟踪。通过*跟踪*，CloudTrail 可将日志文件传送至 Amazon S3 存储桶。预设情况下，在控制台中创建跟踪时，此跟踪应用于所有 AWS 区域。此跟踪记录来自 AWS 分区中的所有 AWS 区域的事件，并将日志文件传送至您指定的 Amazon S3 存储桶。此外，您可以配置其他 AWS 服务，进一步分析在 CloudTrail 日志中收集的事件数据并采取行动。有关更多信息，请参阅《AWS CloudTrail 用户指南》**中的以下主题：
+ [创建跟踪记录概述](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [CloudTrail 支持的服务和集成](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations)
+ [为 CloudTrail 配置 Amazon SNS 通知](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html)
+ [从多个区域接收 CloudTrail 日志文件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html)和[从多个账户中接收 CloudTrail 日志文件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)
所有数据 API 操作都由 CloudTrail 记录并记载在 [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html) 中。例如，对 `BatchExecuteStatement`、`BeginTransaction`、`CommitTransaction` 和 `ExecuteStatement` 操作的调用将在 CloudTrail 日志文件中生成条目。
每个事件或日志条目都包含有关生成请求的人员信息。身份信息有助于您确定以下内容：
+ 请求是使用根凭证还是用户凭证发出的。
+ 请求是使用角色还是联合用户的临时安全凭证发出的。
+ 请求是否由其他 AWS 服务发出。
有关更多信息，请参阅 [CloudTrail userIdentity 元素](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)。
## 在 AWS CloudTrail 跟踪记录中包含和排除数据 API 事件
大多数的 Data API 用户依赖 AWS CloudTrail 跟踪记录中的事件来提供 Data API 操作的记录。事件数据不会在对数据 API 的请求中显示数据库名称、架构名称或 SQL 语句。但是，了解哪位用户在给定时间对特定数据库集群进行了某种类型的调用，可以帮助检测异常访问模式。
### 在 AWS CloudTrail 跟踪记录中包含数据 API 事件
对于 Aurora PostgreSQL Serverless v2 和预调配数据库，以下数据 API 操作将作为*数据事件*记录到 AWS CloudTrail 中。[数据事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events)是大容量数据面板 API 操作，CloudTrail 默认情况下不记录这些操作。记录数据事件将收取额外费用。有关 CloudTrail 定价的信息，请参阅 [AWS CloudTrail 定价](https://aws.amazon.com/cloudtrail/pricing/)。
+ [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html)
+ [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html)
+ [CommitTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html)
+ [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html)
+ [RollbackTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html)
您可以使用 CloudTrail 控制台、AWS CLI 或 CloudTrail API 操作来记录这些数据 API 操作。在 CloudTrail 控制台中，为数据事件类型选择 **RDS 数据 API - 数据库集群**。有关更多信息，请参阅《AWS CloudTrail 用户指南》**中的[使用 AWS 管理控制台记录数据事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-with-the-AWS-CLI)。
使用 AWS CLI，运行 `aws cloudtrail put-event-selectors` 命令来记录跟踪记录的这些数据 API 操作。要记录数据库集群上的所有数据 API 事件，请为资源类型指定 `AWS::RDS::DBCluster`。以下示例记录了数据库集群上的所有数据 API 事件。有关更多信息，请参阅《AWS CloudTrail 用户指南》**中的[使用 AWS Command Line Interface 记录数据事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail-by-using-the-aws-cli.html)。
```
aws cloudtrail put-event-selectors --trail-name trail_name --advanced-event-selectors \
'{
"Name": "RDS Data API Selector",
"FieldSelectors": [
{
"Field": "eventCategory",
"Equals": [
"Data"
]
},
{
"Field": "resources.type",
"Equals": [
"AWS::RDS::DBCluster"
]
}
]
}'
```
您可以将高级事件选择器配置为对 `readOnly`、`eventName,` 和 `resources.ARN` 字段进行额外筛选。有关这些字段的更多信息，请参阅 [AdvancedFieldSelector](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html)。
### 从 AWS CloudTrail 跟踪记录中排除数据 API 事件（仅限 Aurora Serverless v1）
对于 Aurora Serverless v1，数据 API 事件是管理事件。默认情况下，所有数据 API 事件都包含在 AWS CloudTrail 跟踪记录中。但是，由于数据 API 可能生成大量事件，因此您可以从 CloudTrail 跟踪记录中排除这些事件。**排除 Amazon RDS 数据 API 事件**设置将所有数据 API 事件排除在跟踪记录之外。您无法排除特定的数据 API 事件。
要从跟踪记录中排除 Data API 事件，请执行以下操作：
+ [创建跟踪记录](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-a-trail-using-the-console-first-time.html)或者[更新跟踪记录](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-update-a-trail-console.html)时，在 CloudTrail 控制台中选择 **Exclude Amazon RDS Data API events (排除 Amazon RDS Data API 事件)** 设置。
+ 在 CloudTrail API 中，使用 [PutEventSelectors](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_PutEventSelectors.html) 操作。如果您使用的是高级事件选择器，则可以通过将 `eventSource` 字段设置为不等于 `rdsdata.amazonaws.com` 来排除 Data API 事件。如果您使用的是基本事件选择器，则可以通过将 `ExcludeManagementEventSources` 属性的值设置为 `rdsdata.amazonaws.com` 来排除 Data API 事件。有关更多信息，请参阅《AWS CloudTrail 用户指南》**中的[使用 AWS Command Line Interface 记录事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html#creating-mgmt-event-selectors-with-the-AWS-CLI)。
**警告**
从 CloudTrail 日志中排除 Data API 事件可能会掩盖 Data API 操作。请谨慎赋予委托人执行此操作所需的 `cloudtrail:PutEventSelectors` 权限。
您可以随时更改跟踪记录的控制台设置或事件选择器，以关闭此排除。随后，跟踪记录将开始记录 Data API 事件。但是，它无法恢复在排除生效期间发生的 Data API 事件。
使用控制台或 API 排除 Data API 事件时，生成的 CloudTrail `PutEventSelectors` API 操作也会记录在 CloudTrail 日志中。如果 Data API 事件未显示在 CloudTrail 日志中，请查找 `PutEventSelectors` 属性设置为 `ExcludeManagementEventSources` 的 `rdsdata.amazonaws.com` 事件。
有关更多信息，请参阅 *AWS CloudTrail 用户指南*中的[记录管理事件以便进行跟踪记录](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html)。
## 了解数据 API 日志文件条目
*跟踪*是一种配置，可用于将事件作为日志文件传送到您指定的 Amazon S3 存储桶。CloudTrail 日志文件包含一个或多个记录条目。一个*事件*表示来自任何源的一个请求，包括有关所请求的操作、操作的日期和时间、请求参数等方面的信息。CloudTrail 日志文件不是公有 API 调用的有序堆栈跟踪，因此它们不会按任何特定顺序显示。
**Aurora PostgreSQL Serverless v2 和预调配**
以下示例显示一个 CloudTrail 日志条目，该条目演示 Aurora PostgreSQL Serverless v2 和预调配数据库的 `ExecuteStatement` 操作。对于这些数据库，所有数据 API 事件都是数据事件，其中事件源为 **rdsdataapi.amazonaws.com**，事件类型为 **Rds 数据服务**。
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdataapi.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "Rds Data Service",
"recipientAccountId": "123456789012"
}
```
**Aurora Serverless v1**
以下示例显示了前面的示例 CloudTrail 日志条目对于 Aurora Serverless v1 的显示方式。对于 Aurora Serverless v1，所有事件都是管理事件，其中事件源为 **rdsdata.amazonaws.com**，事件类型为 **AwsApiCall**。
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdata.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "AwsApiCall",
"recipientAccountId": "123456789012"
}
```
# 使用性能详情监控 RDS 数据 API 查询
如果 Aurora 集群正在运行 Aurora Serverless v2 或预调配实例，则可以将性能详情与 RDS 数据 API 结合使用。
有关如何将性能详情与 Aurora 结合使用的更多信息，请参阅[在 Amazon Aurora 上使用性能详情监控数据库负载](USER_PerfInsights.md)。
## 如何在性能详情中表示 RDS 数据 API 查询
借助数据 API，Aurora 集群会根据您从应用程序中提交的数据 API 调用来处理查询。作为其内部工作的一部分，数据库 API 还会执行一些 SQL 语句，例如取消超过超时阈值的查询。这两种 SQL 操作都显示在性能详情统计数据和图表中。
+ 对于您提交到 Aurora 集群的数据 API 查询，API 控制面板中的**主机**字段标记为 **RDS 数据 API**。对于 Aurora PostgreSQL，**application\$1name** 字段的值为 `rds-data-api`。使用**热门主机**或**热门应用程序**作为维度来分析数据库负载时，请查找这些标签。
+ 数据 API 为管理数据库的各个方面（例如连接池和查询超时）而运行的所有内部查询都标有前缀 **RDS 数据 API**。示例：`/* RDS Data API */ select * from my_table;` 当您将**热门 SQL** 作为维度来分析数据库负载时，请查找这些前缀。语句标有 SQL 注释 `/* RDS Data API */`。