使用适用于 Aurora Serverless 的 Data API - Amazon Aurora
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用适用于 Aurora Serverless 的 Data API

通过使用适用于 Aurora Serverless 的 Data API,您可以使用 Web 服务接口连接到 Aurora Serverless 数据库集群。Data API 不需要与数据库集群的持久连接。相反,它提供了安全 HTTP 终端节点以及与 AWS 开发工具包的集成。您可以使用终端节点运行 SQL 语句,而无需管理连接。

对 Data API 的所有调用都是同步的。默认情况下,如果调用未在 45 秒内完成处理,就会超时。但是,在调用超时后,您可以使用 continueAfterTimeout 参数继续运行 SQL 语句。有关示例,请参阅运行 SQL 事务

用户无需在调用 Data API 时传递凭证,因为 Data API 会使用存储在 AWS Secrets Manager 中的数据库凭证。要在 Secrets Manager 中存储凭证,用户必须获得使用 Secrets Manager 和 Data API 的适当权限。有关向用户授权的更多信息,请参阅授予对 Data API 的访问权限

您还可以使用 Data API 将 Aurora Serverless 与其他 AWS 应用程序(如 AWS Lambda、AWS AppSync 和 AWS Cloud9)集成。该 API 提供了一种更安全的方式来使用 AWS Lambda。通过此方式,您无需配置 Lambda 函数来访问 Virtual Private Cloud (VPC) 中的资源,即可访问数据库集群。有关更多信息,请参阅 AWS LambdaAWS AppSyncAWS Cloud9

您可以在创建 Aurora Serverless 集群时启用 Data API。您也可以稍后修改配置。有关更多信息,请参阅启用 Data API

启用 Data API 后,您也可以使用 Aurora Serverless 的查询编辑器。有关更多信息,请参阅 使用 Aurora Serverless 的查询编辑器

Data API 可用性

Data API 仅适用于以下 Aurora Serverless 数据库集群:

  • 与 MySQL 版本 5.6 兼容的 Aurora

  • 与 MySQL 版本 5.7 兼容的 Aurora

  • Aurora 与 PostgreSQL 版本 10.7 的兼容性

下表显示了目前 Data API 可用于 Aurora Serverless 的 AWS 区域。要在这些区域中访问 Data API,请使用 HTTPS 协议。

区域 链接
亚太区域(新加坡) rds-data.ap-southeast-1.amazonaws.com
亚太区域(悉尼) rds-data.ap-southeast-2.amazonaws.com
亚太区域(东京) rds-data.ap-northeast-1.amazonaws.com
亚太地区(孟买) rds-data.ap-south-1.amazonaws.com
欧洲(法兰克福) rds-data.eu-central-1.amazonaws.com
欧洲(爱尔兰) rds-data.eu-west-1.amazonaws.com
欧洲(伦敦) rds-data.eu-west-2.amazonaws.com
欧洲(巴黎) rds-data.eu-west-3.amazonaws.com
美国东部(弗吉尼亚北部) rds-data.us-east-1.amazonaws.com
美国东部(俄亥俄州) rds-data.us-east-2.amazonaws.com
美国西部(加利福尼亚北部) rds-data.us-west-1.amazonaws.com
美国西部(俄勒冈) rds-data.us-west-2.amazonaws.com

授予对 Data API 的访问权限

用户只有在获得授权的情况下才能调用 Data API 操作。您可以通过附加定义用户权限的 AWS Identity and Access Management (IAM) 策略,授予用户使用 Data API 的权限。如果您使用的是 IAM 角色,您还可以将策略附加到角色。AWS 托管策略 AmazonRDSDataFullAccess 包含了使用 RDS Data API 的权限。

AmazonRDSDataFullAccess 策略还包含允许用户从 AWS Secrets Manager 获取密钥值的权限。用户需要使用 Secrets Manager 来存储他们在调用 Data API 时可以使用的密钥。使用密钥意味着用户不需要在调用 Data API 时提供其目标资源的数据库凭证。Data API 会透明地调用 Secrets Manager,后者会允许(或拒绝)用户的密钥请求。有关如何设置与 Data API 一起使用的密钥的信息,请参阅在 AWS Secrets Manager 中存储数据库凭证

AmazonRDSDataFullAccess 策略提供了对资源的完全访问权限(通过 Data API 进行访问)。您可以通过定义指定资源的 Amazon 资源名称 (ARN) 的策略来缩小范围。

例如,以下策略显示了用户访问数据库集群(由其 ARN 标识)的 Data API 所需的最低权限的示例。该策略包含用户访问 Secrets Manager 和获取数据库实例授权所需的权限。

{ "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(如示例所示),而不是通配符 (*)。

使用基于标签的授权

Data API 和 Secrets Manager 都支持基于标签的授权。标签是用附加的字符串值标记资源(如 RDS 集群)的键值对,例如:

  • environment:production

  • environment:development

您可以出于成本分配、操作支持、访问控制及许多其他原因,为资源应用标签。(如果您的资源上还没有标签,并且您想要应用标签,您可以在为 Amazon RDS 资源添加标签中了解更多信息。) 您可以在策略语句中使用标签来限制对使用这些标签进行标记的 RDS 集群的访问。例如,Aurora 数据库集群可能包含将其环境标识为生产环境或开发环境的标签。

以下示例说明如何在策略语句中使用标签。这条语句要求在 Data API 请求中传递的集群和密钥都包含 environment:production 标签。

策略的应用方式如下:当用户使用 Data API 进行调用时,请求被发送到服务。Data API 首先验证在请求中传递的集群 ARN 是否包含 environment:production 标签。然后,它会调用 Secrets Manager 以在请求中检索用户密钥的值。Secrets Manager 也会验证用户的密钥是否包含 environment:production 标签。如果包含,Data API 将使用检索到的值作为用户的数据库密码。最后,如果此密码正确,则会为用户成功调用 Data API 请求。

{ "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:*" ], "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:*", "Condition": { "StringEquals": { "aws:ResourceTag/environment": [ "production" ] } } } ] }

该示例分别显示了针对 Data API 和 Secrets Manager 的 rds-datasecretsmanager 操作。不过,您可以通过多种不同的方式组合操作和定义标签条件,以支持您的特定使用案例。有关更多信息,请参阅为 Secrets Manager 使用基于身份的策略(IAM 策略)

在策略的 "Condition" 元素中,您可以从以下选项中选择标签键:

  • aws:TagKeys

  • aws:ResourceTag/${TagKey}

要了解有关资源标签以及如何使用 aws:TagKeys 的更多信息,请参阅使用资源标签控制对 AWS 资源的访问

注意

Data API 和 AWS Secrets Manager 都会对用户进行授权。如果您不具有策略中定义的所有操作的权限,则会收到 AccessDeniedException 错误。

在 AWS Secrets Manager 中存储数据库凭证

调用 Data API 时,您可以使用 Secrets Manager 中的密钥传递 Aurora Serverless 数据库集群的凭证。要通过此方式传递凭证,您需要指定密钥的名称或密钥的 Amazon 资源名称 (ARN)。

在密钥中存储数据库集群凭证

  1. 使用 Secrets Manager 创建包含 Aurora 数据库集群凭证的密钥。

    有关说明,请参阅 AWS Secrets Manager 用户指南 中的创建基本密钥

  2. 使用 Secrets Manager 控制台查看您创建的密钥的详细信息,或运行 aws secretsmanager describe-secret AWS CLI 命令。

    记下密钥的名称和 ARN。您可以将其用于对 Data API 的调用中。

有关使用 Secrets Manager 的更多信息,请参阅 AWS Secrets Manager 用户指南

要了解 Amazon Aurora 如何管理身份和访问管理,请参阅 Amazon Aurora 如何使用 IAM

有关创建 IAM 策略的更多信息,请参阅 IAM 用户指南中的创建 IAM 策略。有关将 IAM 策略添加到用户的信息,请参阅 IAM 用户指南 中的添加和删除 IAM 身份权限

启用 Data API

要使用 Data API,请为 Aurora Serverless 数据库集群启用它。您可以在创建或修改数据库集群时启用 Data API。

在创建或修改 Aurora Serverless 数据库集群时,您可以使用 RDS 控制台启用 Data API。在创建 Aurora Serverless 数据库集群时,您可以在 RDS 控制台的 Connectivity (连接) 部分中启用 Data API 以实现该目的。在修改 Aurora Serverless 数据库集群时,您可以在 RDS 控制台的 Network & Security (网络与安全) 部分中启用 Data API 以实现该目的。

以下屏幕截图显示了在修改 Aurora Serverless 数据库集群时启用的 Data API


                            使用控制台为 Aurora Serverless 数据库集群启用 Data API

有关说明,请参阅创建 Aurora Serverless 数据库集群修改 Aurora Serverless 数据库集群

如果使用 AWS CLI 命令创建或修改 Aurora Serverless 数据库集群,将在指定 -enable-http-endpoint 时启用 Data API。

您可以使用以下 AWS CLI 命令指定 -enable-http-endpoint

以下示例修改 sample-cluster 以启用 Data 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

在使用 Amazon RDS API 操作创建或修改 Aurora Serverless 数据库集群时,您可以将 EnableHttpEndpoint 值设置为 true 以启用 Data API。

您可以使用以下 API 操作设置 EnableHttpEndpoint 值:

为 Data API 创建 Amazon VPC 终端节点 (AWS PrivateLink)

借助 Amazon VPC,您可以在 Virtual Private Cloud (VPC) 中启动 AWS 资源(例如 Aurora 数据库集群和应用程序)。AWS PrivateLink 在 Amazon 网络上提供了 VPC 和 AWS 服务之间的私有连接,这种连接具有高度的安全性。通过使用 AWS PrivateLink,您可以创建 Amazon VPC 终端节点,这可让您根据 Amazon VPC 跨不同的账号和 VPC 连接到服务。有关 AWS PrivateLink 的更多信息,请参阅 Amazon Virtual Private Cloud 用户指南 中的 VPC 终端节点服务 (AWS PrivateLink)

您可以使用 Amazon VPC 终端节点调用 Data API。使用 Amazon VPC 终端节点可保持 Amazon VPC 中的应用程序和 AWS 网络中的 Data API 之间的流量,而无需使用公有 IP 地址。Amazon VPC 终端节点可帮助您满足与限制公共 Internet 连接相关的合规性和法规要求。例如,如果您使用 Amazon VPC 终端节点,则可保持 Amazon EC2 实例上运行的应用程序和包含终端节点的 VPC 中的 Data API 之间的流量。

创建 Amazon VPC 终端节点后,便能开始使用此终端节点,而无需在应用程序中进行任何代码或配置更改。

为 Data API 创建 Amazon VPC 终端节点

  1. 登录 AWS 管理控制台 并通过以下网址打开 Amazon VPC 控制台:https://console.amazonaws.cn/vpc/

  2. 选择 Endpoints (终端节点),然后选择 Create Endpoint (创建终端节点)

  3. Create Endpoint (创建终端节点) 页面上,对于 Service category (服务类别),选择 AWS services (AWS 服务)。对于 Service Name (服务名称),请选择 rds-data。​

    
                            为 Data API 创建 Amazon VPC 终端节点
  4. 对于 VPC,选择要在其中创建终端节点的 VPC。

    选择包含用于进行 Data API 调用的应用程序的 VPC。

  5. 对于 Subnets (子网),请为运行应用程序的 AWS 服务所使用的每个可用区 (AZ) 选择子网。

    
                            为 Amazon VPC 终端节点选择子网

    要创建 Amazon VPC 终端节点,请指定终端节点可在其中访问的私有 IP 地址范围。为此,请为每个可用区选择子网。执行此操作会将 VPC 终端节点限制为特定于每个可用区的私有 IP 地址范围,并且还会在每个可用区中创建一个 Amazon VPC 终端节点。

  6. 对于 Enable DNS Name (启用 DNS 名称),选择 Enable for this endpoint (为此终端节点启用)

    
                            为 Amazon VPC 终端节点启用 DNS 名称

    私有 DNS 会将标准 Data API DNS 主机名 (https://rds-data.region.amazonaws.com) 解析为与特定于 Amazon VPC 终端节点的 DNS 主机名关联的私有 IP 地址。因此,您可以使用 AWS CLI 或 AWS 开发工具包访问 Data API VPC 终端节点,而无需进行任何代码或配置更改来更新 Data API 终端节点 URL。

  7. 对于 Security group (安全组),选择要与 Amazon VPC 终端节点关联的安全组。

    选择允许访问运行应用程序的 AWS 服务的安全组。例如,如果 Amazon EC2 实例正在运行您的应用程序,请选择允许访问 Amazon EC2 实例的安全组。利用安全组,您可以控制从 VPC 中的资源发送到 Amazon VPC 终端节点的流量。

  8. 对于 Policy (策略),选择 Full Access (完全访问) 以允许 Amazon VPC 中的任何人通过此终端节点访问 Data API。或者,选择 Custom (自定义) 以指定限制访问的策略。

    如果选择 Custom (自定义),请在策略创建工具中输入策略。

  9. 选择Create endpoint

创建终端节点后,选择 AWS 管理控制台中的链接以查看终端节点详细信息。


                    链接到 Amazon VPC 终端节点详细信息

终端节点 Details (详细信息) 选项卡将显示在创建 Amazon VPC 终端节点时生成的 DNS 主机名。


                    链接到 Amazon VPC 终端节点详细信息

您可以使用标准终端节点 (rds-data.region.amazonaws.com) 或特定于 VPC 的终端节点之一来调用 Amazon VPC 中的 Data API。标准 Data API 终端节点将自动路由到 Amazon VPC 终端节点。发生此路由的原因是,在创建 Amazon VPC 终端节点时启用了私有 DNS 主机名。

在 Data API 调用中使用 Amazon VPC 终端节点时,应用程序和 Data API 之间的所有流量将在包含它们的 Amazon VPC 中保留。可以将 Amazon VPC 终端节点用于任何类型的 Data API 调用。有关调用 Data API 的信息,请参阅调用 Data API

调用 Data API

在为 Aurora Serverless 数据库集群启用 Data API 后,您可以调用 Data API 或 AWS CLI 以对数据库集群运行 SQL 语句。Data API 支持 AWS 开发工具包所支持的编程语言。有关更多信息,请参阅用于在 AWS 上进行构建的工具

注意

目前,Data API 不支持通用唯一标识符 (UUID) 数组。

Data API 提供了以下操作以执行 SQL 语句。

Data API 操作

AWS CLI command

描述

ExecuteStatement

aws rds-data execute-statement

对数据库运行 SQL 语句。

BatchExecuteStatement

aws rds-data batch-execute-statement

对数据数组运行批处理 SQL 语句,以执行批量更新和插入操作。您可以使用参数集数组运行 DML 语句。相比单个插入和更新语句,批处理 SQL 语句可提供显著的性能改进。

您可以运行这两个操作以单独执行 SQL 语句,也可以在事务中运行这些操作。Data API 提供了以下操作来支持事务。

Data API 操作

AWS CLI command

描述

BeginTransaction

aws rds-data begin-transaction

开始 SQL 事务。

CommitTransaction

aws rds-data commit-transaction

结束 SQL 事务并提交更改。

RollbackTransaction

aws rds-data rollback-transaction

执行事务回滚。

执行 SQL 语句和支持事务的操作具有以下常用 Data API 参数和 AWS CLI 选项。某些操作支持其他参数或选项。

Data API 操作参数

AWS CLI 命令选项

是否必需

描述

resourceArn

--resource-arn

Aurora Serverless 数据库集群的 Amazon 资源名称 (ARN)。

secretArn

--secret-arn

允许访问数据库集群的密钥的名称或 ARN。

您可以在对 ExecuteStatementBatchExecuteStatement 的 Data API 调用中使用参数,或在运行 AWS CLI 命令 execute-statementbatch-execute-statement 时使用。要使用参数,请在 SqlParameter 数据类型中指定名称/值对。您可以使用 Field 数据类型指定值。下表将 Java 数据库连接 (JDBC) 数据类型映射到您在 Data API 调用中指定的数据类型。

JDBC 数据类型

Data API 数据类型

INTEGER, TINYINT, SMALLINT, BIGINT

LONG

FLOAT, REAL, DOUBLE

DOUBLE

DECIMAL

STRING

BOOLEAN, BIT

BOOLEAN

BLOB, BINARY, LONGVARBINARY, VARBINARY

BLOB

CLOB

STRING

其他类型(包括与日期和时间有关的类型)

STRING

对于某些特定类型(如 DECIMALTIME),可能需要一个提示来指示 Data API 应将 String 值作为另一种类型传递给数据库。您可以通过在 SqlParameter 数据类型中包含 typeHint 中的值来实现这一点。typeHint 的可能值如下所示:

  • DECIMAL – 相应的 String 参数值作为 DECIMAL 类型的对象发送到数据库。

  • TIMESTAMP – 相应的 String 参数值作为 TIMESTAMP 类型的对象发送到数据库。接受的格式为 YYYY-MM-DD HH:MM:SS[.FFF]

  • TIME – 相应的 String 参数值作为 TIME 类型的对象发送到数据库。接受的格式为 HH:MM:SS[.FFF]

  • DATE – 相应的 String 参数值作为 DATE 类型的对象发送到数据库。接受的格式为 YYYY-MM-DD

注意

对于 Amazon Aurora PostgreSQL,Data API 始终以 UTC 时区返回 Aurora PostgreSQL 数据类型 TIMESTAMPTZ

注意

这些示例并不详尽。

使用 AWS CLI 调用 Data API

您可以使用 AWS Command Line Interface (AWS CLI) 调用 Data API。

以下示例将 AWS CLI 用于 Data API。有关更多信息,请参阅 Data API 的 AWS Command Line Interface 参考

在每个示例中,将数据库集群 ARN 替换为您的 Aurora Serverless 数据库集群的 ARN。另外,将密钥 ARN 替换为 Secrets Manager 中允许访问该数据库集群的密钥的 ARN。

注意

AWS CLI 可以使用 JSON 设置响应格式。

启动 SQL 事务

您可以使用 aws rds-data begin-transaction CLI 命令启动 SQL 事务。调用会返回事务标识符。

重要

如果三分钟之内没有任何调用使用其事务 ID,事务将超时。如果事务在提交之前超时,则会自动回滚。

事务内的 DDL 语句会导致隐式提交。我们建议您在单独的 execute-statement 命令中,采用 --continue-after-timeout 选项运行每个 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(可选)– 数据库的名称。

  • --continue-after-timeout | --no-continue-after-timeout(可选)– 指定在调用超时后是否继续运行语句的值。默认值为 --no-continue-after-timeout

    对于数据定义语言 (DDL) 语句,我们建议在调用超时后继续运行语句,以避免错误以及数据结构损坏的可能性。

数据库集群为调用返回响应。

注意

响应大小限制为 1 MB。如果调用返回的响应数据超过 1 MB,则调用将终止。

每秒的最大请求数为 1,000。

例如,以下 CLI 命令运行单个 SQL 语句,并在结果中省略元数据(默认设置)。

对于 Linux、macOS 或 Unix:

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

对于 Windows:

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

以下为响应示例。

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

以下 CLI 命令通过指定 --transaction-id 选项,在事务中运行单个 SQL 语句。

对于 Linux、macOS 或 Unix:

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

对于 Windows:

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

以下为响应示例。

{ "numberOfRecordsUpdated": 1 }

以下 CLI 命令使用参数运行单个 SQL 语句。

对于 Linux、macOS 或 Unix:

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

对于 Windows:

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

以下为响应示例。

{ "numberOfRecordsUpdated": 1 }

以下 CLI 命令运行数据定义语言 (DDL) SQL 语句。DDL 语句将列 job 重命名为列 role

重要

对于 DDL 语句,我们建议在调用超时后继续运行语句。如果 DDL 语句在结束运行之前终止,则可能导致错误以及数据结构损坏。要在调用超时后继续运行语句,请指定 --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 文档中的从已修改的行返回数据

对数据数组运行批处理 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 语句。

  • --transaction-id(可选)– 使用 begin-transaction CLI 命令开始的事务的标识符。指定您希望包含 SQL 语句的事务的事务 ID。

  • --parameter-set(可选)– 批处理操作的参数集。

  • --database(可选)– 数据库的名称。

数据库集群返回调用的响应。

注意

响应大小限制为 1 MB。如果调用返回的响应数据超过 1 MB,则调用将终止。

每秒的最大请求数为 1,000。

例如,以下 CLI 命令采用参数集对数据数组运行批处理 SQL 语句。

对于 Linux、macOS 或 Unix:

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

对于 Windows:

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

--parameter-sets 选项中请勿包括换行符。

提交 SQL 事务

通过使用 aws rds-data commit-transaction CLI 命令,您可以结束使用 aws rds-data begin-transaction 开始的 SQL 事务并提交更改。

除常用选项之外,还可指定以下选项:

  • --transaction-id(必需)– 使用 begin-transaction CLI 命令开始的事务的标识符。指定您希望结束并提交的事务的事务 ID。

例如,以下 CLI 命令结束 SQL 事务并提交更改。

对于 Linux、macOS 或 Unix:

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

对于 Windows:

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

以下为响应示例。

{ "transactionStatus": "Transaction Committed" }

回滚 SQL 事务

通过使用 aws rds-data rollback-transaction CLI 命令,您可以回滚使用 aws rds-data begin-transaction 开始的 SQL 事务。回滚事务会取消其更改。

重要

如果事务 ID 已过期,事务将自动回滚。在此情况下,指定已过期事务 ID 的 aws rds-data rollback-transaction 命令将返回错误。

除常用选项之外,还可指定以下选项:

  • --transaction-id(必需)– 使用 begin-transaction CLI 命令开始的事务的标识符。指定您希望回滚的事务的事务 ID。

例如,以下 AWS CLI 命令回滚 SQL 事务。

对于 Linux、macOS 或 Unix:

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

对于 Windows:

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

以下为响应示例。

{ "transactionStatus": "Rollback Complete" }

从 Python 应用程序调用 Data API

您可以从 Python 应用程序调用 Data API。

以下示例使用适用于 Python 的 AWS 开发工具包 (Boto)。有关 Boto 的更多信息,请参阅适用于 Python 的 AWS 开发工具包 (Boto 3 ) 文档

在每个示例中,将数据库集群的 Amazon 资源名称 (ARN) 替换为您的 Aurora Serverless 数据库集群的 ARN。另外,将密钥 ARN 替换为 Secrets Manager 中允许访问该数据库集群的密钥的 ARN。

运行 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 语句在结束运行之前终止,则可能导致错误以及数据结构损坏。要在调用超时后继续运行语句,请将 continueAfterTimeout 参数设置为 true

从 Java 应用程序调用 Data API

您可以从 Java 应用程序调用 Data API。

以下示例使用适用于 Java 的 AWS 开发工具包。有关更多信息,请参阅AWS SDK for Java Developer Guide

在每个示例中,将数据库集群的 Amazon 资源名称 (ARN) 替换为您的 Aurora Serverless 数据库集群的 ARN。另外,将密钥 ARN 替换为 Secrets Manager 中允许访问该数据库集群的密钥的 ARN。

运行 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<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 事务

您可以通过 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 语句在结束运行之前终止,则可能导致错误以及数据结构损坏。要在调用超时后继续运行语句,请将 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); } }

使用适用于 Data API 的 Java 客户端库

您可以下载并使用适用于 Data API 的 Java 客户端库。此 Java 客户端库提供了使用 Data API 的另一种方法。使用该库,您可以将客户端类映射到 Data API 的请求和响应。这种映射支持可以简化与某些特定 Java 类型(如 DateTimeBigDecimal)的集成。

下载适用于 Data API 的 Java 客户端库

Data API Java 客户端库是 GitHub 中是开源的,位于以下位置:

https://github.com/awslabs/rds-data-api-client-library-java

您可以从源文件手动构建该库,但最佳实践是使用 Apache Maven 依赖项管理来使用该库。将以下依赖项添加到 Maven POM 文件中:

<dependency> <groupId>software.amazon.rdsdata</groupId> <artifactId>rds-data-api-client-library-java</artifactId> <version>1.0.4</version> </dependency>

Java 客户端库示例

在下面,您可以找到一些使用 Data API Java 客户端库的常见示例。这些示例假设您有一个包含两列(accountIdname)的表 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)") .withParams(account1, account2) .execute();

在某些情况下,使用简单值作为输入参数会更容易。可以使用以下语法来做到这一点。

client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)") .withParam("accountId", 3) .withParam("name", "Zhang") .execute();

下面是另一个使用简单值作为输入参数的示例。

client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos") .execute();

当返回结果时,客户端库提供到 DTO 的自动映射。以下示例展示了如何将结果映射到您的 DTO。

List<Account> 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);

解决 Data API 问题

使用以下部分(标题为常见错误消息)帮助解决 Data API 问题。

未找到事务 <transaction_ID>

在此情况下,找不到 Data API 调用中指定的事务 ID。导致此问题的原因几乎总是下列原因之一:

  • BeginTransaction 调用未创建指定的事务 ID。

  • 指定的事务 ID 已过期。

    如果在 3 分钟内没有调用使用事务 ID,则事务将过期。

要解决此问题,请确保您的调用具有有效的事务 ID。另请确保每个事务调用在最后一个事务调用之后的 3 分钟内运行。

有关运行事务的信息,请参阅调用 Data API

用于查询的包太大

在此情况下,为行返回的结果集太大。数据库返回的结果集中的 Data API 大小限制为每行 64 KB。

要解决此问题,请确保结果集中的每一行都小于或等于 64 KB。

数据库响应超出大小限制

在此情况下,数据库返回的结果集太大。数据库返回的结果集中的 Data API 限制为 1 MB。

要解决此问题,请确保对 Data API 的调用返回 1 MB 或更少数据。如果需要返回 1 MB 以上的数据,您可以在查询中将多个 ExecuteStatement 调用与 LIMIT 子句结合使用。

有关 LIMIT 子句的更多信息,请参阅 MySQL 文档中的 SELECT 语法

没有为集群 <cluster_ID> 启用 HttpEndpoint

导致此问题的原因几乎总是下列原因之一:

  • 未为 Aurora Serverless 数据库集群启用 Data API。要将 Data API 与 Aurora Serverless 数据库集群结合使用,必须为该数据库集群启用 Data API。

  • 在为数据库集群启用 Data API 之后,已重命名该数据库集群。

如果尚未为数据库集群启用 Data API,请启用它。

如果在为数据库集群启用 Data API 后重命名了数据库集群,请禁用 Data API,然后再次启用它。

有关启用 Data API 的信息,请参阅启用 Data API