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

使用 Amazon Redshift 数据 API

您可以使用内置的 Amazon Redshift 数据 API 访问您的 Amazon Redshift 数据库。使用此 API,您可以通过基于 Web 服务的应用程序(包括 Amazon Lambda、Amazon SageMaker 笔记本和 Amazon Cloud9)访问 Amazon Redshift 数据。有关这些应用程序的更多信息,请参阅 Amazon LambdaAmazon SageMakerAmazon Cloud9

数据 API 不需要与集群的持久连接。相反,它提供了安全 HTTP 终端节点以及与 Amazon 开发工具包的集成。您可以使用终端节点运行 SQL 语句,而无需管理连接。对数据 API 的调用是异步的。

数据 API 使用存储在 Amazon Secrets Manager 中的凭证或临时数据库凭证。您无需使用任何一种授权方法在 API 调用中传递密码。有关 Amazon Secrets Manager 的更多信息,请参阅 Amazon Secrets Manager 用户指南中的什么是 Amazon Secrets Manager?

有关数据 API 操作的更多信息,请参阅 Amazon Redshift 数据 API 参考

使用 Amazon Redshift 数据 API

在您使用 Amazon Redshift 数据 API 之前,请查看以下步骤:

  1. 确定您作为数据 API 的调用者是否获得授权。有关 授权的更多信息,请参阅授予对 Amazon Redshift 数据 API 的访问权限

  2. 确定是否计划使用来自 Secrets Manager 的身份验证凭据或临时凭证调用数据 API。有关更多信息,请参阅在调用 Amazon Redshift 数据 API 时选择身份验证凭证

  3. 如果您将 Secrets Manager 用于身份验证凭证,请设置密码。有关更多信息,请参阅在 Amazon Secrets Manager 中存储数据库凭证

  4. 查看调用数据 API 时的注意事项和限制。有关更多信息,请参阅调用 Amazon Redshift 数据 API 时的注意事项

  5. 从 Amazon Command Line Interface (Amazon CLI)、您自己的代码中调用数据 API,或使用 Amazon Redshift 控制台中的查询编辑器。有关从 Amazon CLI 进行调用的示例,请参阅调用 Data API

调用 Amazon Redshift 数据 API 时的注意事项

调用数据 API 时,请注意以下事项:

  • 有关提供了数据 API 的 Amazon Web Services 区域的列表,请参阅《Amazon Web Services 一般参考》中为 Redshift 数据 API 列出的端点。

  • 查询的最长持续时间为 24 小时。

  • 每个 Amazon Redshift 集群的活动查询(STARTEDSUBMITTED 查询)最大数为 200 个。

  • 查询结果的最大大小为 100 MB。如果调用返回的响应数据超过 100 MB,则调用将结束。

  • 查询结果的最长保留时间为 24 小时。

  • 最大查询语句大小为 100 KB。

  • 数据 API 可用于查询以下节点类型的单节点和多节点集群:

    • dc2.large

    • dc2.8xlarge

    • ds2.xlarge

    • ds2.8xlarge

    • ra3.xlplus

    • ra3.4xlarge

    • ra3.16xlarge

  • 集群必须在基于 Amazon VPC 服务的 Virtual Private Cloud (VPC) 中。

  • 预设情况下,具有与 ExecuteStatement 或者 BatchExecuteStatement API 操作运行者相同的 IAM 角色或 IAM 用户的用户可以使用 CancelStatementDescribeStatementGetStatementResultListStatements API 操作对同一个语句进行操作。要从另一个 IAM 用户对同一 SQL 语句执行操作,该用户必须能够代入运行 SQL 语句的用户的 IAM 角色。有关如何代入角色的更多信息,请参阅授予对 Amazon Redshift 数据 API 的访问权限

  • BatchExecuteStatement API 操作的 Sqls 参数中的 SQL 语句将作为单个事务运行。它们按数组的顺序连续运行。后续的 SQL 语句要等到数组中的前一条语句完成后才会开始。如果任何 SQL 语句失败,由于它们作为一个事务运行,所有工作都将回滚。

在调用 Amazon Redshift 数据 API 时选择身份验证凭证

当您调用数据 API 时,您对某些 API 操作使用以下身份验证方法之一。每种方法都需要不同的参数组合。

Amazon Secrets Manager

使用此方法,提供存储在 Amazon Secrets Manager 中的 secret-arn 密钥值。指定的密钥包含用于连接到您指定的 database 的凭证。在连接到集群时,还可以提供数据库名称以及与密钥中的集群匹配的集群标识符。在连接到无服务器工作组时,也要提供数据库名称。

临时凭证

利用此方法,在连接到集群时,需要指定集群标识符、数据库名称和数据库用户名。此外,需具有调用 redshift:GetClusterCredentials 操作的权限。在连接到无服务器工作组时,需指定数据库名称。

使用任何一种方法,您还可以提供 region 值,该值指定您的集群所在的 Amazon 区域。

调用 Amazon Redshift 数据 API 时映射 JDBC 数据类型

下表将 Java 数据库连接 (JDBC) 数据类型映射到您在数据 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

字符串值将传递到 Amazon Redshift 数据库并隐式转换为数据库数据类型。

注意

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

在调用 Amazon Redshift 数据 API 时运行带有参数的 SQL 语句

您可以通过使用 SQL 语句部分的参数调用数据 API 操作来控制提交到数据库引擎的 SQL 文本。命名参数提供了一种灵活的方式来传入参数,而无需在 SQL 文本中对参数进行硬编码。它们可以帮助您重复使用 SQL 文本并避免 SQL 注入问题。

以下示例显示 execute statement Amazon CLI 命令的 parameters 字段的命名参数。

--parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"

使用命名参数时,请注意以下事项:

  • 命名参数可以按任意顺序排列,并且参数可以在 SQL 文本中多次使用。前面示例中显示的参数选项,值 1Seattle 插入到表列 idaddress 中。在 SQL 文本中,您可以按如下方式指定命名参数:

    --sql "insert into mytable values (:id, :address)"
  • SQL 运行时,数据将隐式转换为数据类型。有关数据类型转换的更多信息,请参阅 Amazon Redshift 数据库开发人员指南中的数据类型

  • 您不能将值设置为 NULL。数据 API 将其解释为文本字符串 NULL。以下示例将 id 替换为文本字符串 null。不是 SQL NULL 值。

    --parameters "[{\"name\": \"id\", \"value\": \"null\"}]"
  • 无法设置零长度值。数据 API SQL 语句失败。下面的示例尝试设置 id 长度值为零,导致 SQL 语句失败。

    --parameters "[{\"name\": \"id\", \"value\": \"\"}]"
  • 不能在带有参数的 SQL 语句中设置表名。数据 API 遵循 JDBC PreparedStatement 的规则。

  • describe statement 操作的输出返回 SQL 语句的查询参数。

  • execute-statement 操作支持带有参数的 SQL 语句。