使用 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 进行调用的示例,请参阅使用 Amazon CLI 调用 Data API

授予对 Amazon Redshift 数据 API 的访问权限

用户必须获得授权才能访问数据 API。您可以通过将托管策略(预定义的 Amazon Identity and Access Management (IAM) 策略)添加给用户,授予该用户访问数据 API 的权限。要查看托管策略允许和拒绝的权限,请参阅 IAM 控制台 (https://console.aws.amazon.com/iam/)。

Amazon Redshift 提供 AmazonRedshiftDataFullAccess 托管策略。此策略提供了对 Amazon Redshift 数据 API 操作的完全访问。此策略还允许在范围内访问特定的 Amazon Redshift、Amazon Secrets Manager 以及对 Amazon Redshift 集群进行身份验证和访问所需的 IAM API 操作。如果您使用 Amazon Secrets Manager 进行身份验证,策略允许使用 secretsmanager:GetSecretValue 操作来检索使用键 RedshiftDataFullAccess 标记的密钥。如果您使用临时凭证进行身份验证,则该策略允许将 redshift:GetClusterCredentials 操作用于集群中的任何数据库的数据库用户名 redshift_data_api_user。此用户名必须已在数据库中创建。

此外,您还可以创建自己的 IAM 策略,以允许对特定资源的访问。要创建策略,请使用 AmazonRedshiftDataFullAccess 策略作为起始模板。在创建策略后,将该策略添加到需要访问数据 API 的每个用户。

要对其他账户拥有的集群运行查询,拥有账户必须提供一个 IAM 角色,数据 API 可以在调用账户时代入该角色。例如,假设账户 B 拥有账户 A 需要访问的集群。账户 B 可以将 Amazon 托管策略 AmazonRedshiftDataFullAccess 附加到账户 B 的 IAM 角色。然后,账户 B 使用信任策略信任账户 A,如下所示:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::accountID-of-account-A:role/someRoleA" ] }, "Action": "sts:AssumeRole" } ] }

最后,账户 A 的 IAM 角色需要能够代入账户 B 的 IAM 角色。

{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::accountID-of-account-B:role/someRoleB" } }

以下链接提供了 IAM 用户指南中有关 Amazon Identity and Access Management 的更多信息。

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

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

要使用 Secrets Manager 存储凭证,您需要 SecretManagerReadWrite 托管策略权限。有关最低权限的更多信息,请参阅 Amazon Secrets Manager 用户指南中的使用 Amazon Secrets Manager 创建和管理密钥

要将凭证存储在 Amazon Redshift 集群的密钥中

  1. 使用 Amazon Secrets Manager 创建包含集群凭证的密钥:

    • 当您选择 Store a new secret(存储新密钥)时,选择 Credentials for Redshift cluster(Redshift 集群的凭证)。

    • User name(用户名)(数据库用户)、Password(密码)和 DB cluster (数据库集群)(集群标识符)的值存储在您的密钥中。

    • 使用键 RedshiftDataFullAccess 标记密钥。Amazon 托管策略 AmazonRedshiftDataFullAccess 只允许对使用键 RedshiftDataFullAccess 进行标记的密钥执行操作 secretsmanager:GetSecretValue

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

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

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

为数据 API 创建 Amazon VPC 终端节点 (Amazon PrivateLink)

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

您可以使用 Amazon VPC 终端节点调用数据 API。使用 Amazon VPC 终端节点可保留 Amazon VPC 中应用程序间的流量与Amazon网络中的 Data API,而无需使用公有 IP 地址。Amazon VPC 终端节点可帮助您遵守与管理公共互联网连接有关的合规性和法规要求。例如,如果您使用 Amazon VPC 终端节点,则可保持 Amazon EC2 实例上运行的应用程序和包含终端节点的 VPC 中的 Data API 之间的流量。

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

为 Data API 创建 Amazon VPC 终端节点

  1. 登录到Amazon Web Services Management Console并打开 Amazon VPC 控制台,网址:https://console.aws.amazon.com/vpc/

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

  3. Create Endpoint (创建终端节点) 页面上,为 Service category (服务类别) 选择 Amazon services (亚马逊云科技服务)。对于 Service Name(服务名称),选择 redshift-data (com.amazonaws.region.redshift-data)。

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

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

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

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

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

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

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

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

  8. 选择Create endpoint

创建终端节点后,选择 Amazon Web Services Management Console中的链接以查看终端节点详细信息。

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

您可以使用标准终端节点 (redshift-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 的信息,请参阅调用 Amazon Redshift 数据 API 时的注意事项

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

调用数据 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 或者 BatchExecuteStatementAPI 操作运行着相同的 IAM 角色或 IAM 用户的用户可以使用 CancelStatementDescribeStatementGetStatementResultListStatementsAPI 操作对同一个语句进行操作。

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

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

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

Amazon Secrets Manager

使用此方法,提供存储在 Amazon Secrets Manager 中的 secret-arn 密钥值。指定的密钥包含用于连接到数据库的凭证。您还可以为 cluster-identifier 提供值,它与密钥中的集群标识符匹配。

临时凭证

使用此方法,提供您的 cluster-identifierdatabasedb-user 值。

使用任何一种方法,您还可以提供 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 语句。

调用 Data API

您可以调用数据 API 或 Amazon CLI 在集群上运行 SQL 语句。运行 SQL 语句的主要操作是 ExecuteStatement。数据 API 支持 Amazon 开发工具包所支持的编程语言。有关它们的更多信息,请参阅用于在 Amazon 上构建的工具

要查看调用 Data API 的代码示例,请参阅 GitHub 中的 Redshift 数据 API入门。此存储库包含使用 Amazon Lambda 从 Amazon EC2、Amazon Glue Data Catalog 和 Amazon SageMaker 访问 Amazon Redshift 数据的示例。示例编程语言包括 Python、Go、Java 和 Javascript。

使用 Amazon CLI 调用 Data API

您可以使用 Amazon CLI 调用 Data API。

以下示例使用 Amazon CLI 调用数据 API。要运行示例,请编辑参数值以匹配您的环境。这些示例演示了一些数据 API 操作。有关更多信息,请参阅 Amazon CLI 命令参考

以下示例中的命令已被拆分和格式化以便于阅读。

要运行 SQL 语句

要运行 SQL 语句,请使用 aws redshift-data execute-statement Amazon CLI 命令。

以下 Amazon CLI 命令运行 SQL 语句并返回用于获取结果的标识符。此示例使用 Amazon Secrets Manager 身份验证方法。

aws redshift-data execute-statement --region us-west-2 --secret arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --sql "select * from stl_query limit 1" --database dev

以下为响应示例。

{ "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598323175.823, "Database": "dev", "Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814", "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:yanruiz-secret-hKgPWn" }

以下 Amazon CLI 命令运行 SQL 语句并返回用于获取结果的标识符。此示例使用临时凭证身份验证方法。

aws redshift-data execute-statement --region us-west-2 --db-user myuser --cluster-identifier mycluster-test --database dev --sql "select * from stl_query limit 1"

以下为响应示例。

{ "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598306924.632, "Database": "dev", "DbUser": "myuser", "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766" }

要运行带有参数的 SQL 语句

要运行 SQL 语句,请使用 aws redshift-data execute-statement Amazon CLI 命令。

以下 Amazon CLI 命令运行 SQL 语句并返回用于获取结果的标识符。此示例使用 Amazon Secrets Manager 身份验证方法。SQL 文本具有命名参数 colnamedistance。在这种情况下,表中的列名为 ratecode 并且谓词中使用的距离是 5。SQL 语句的命名参数值在 parameters 选项中指定。

aws redshift-data execute-statement --region us-west-2 --secret arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --sql "SELECT :colname, COUNT(*) FROM demo_table WHERE trip_distance > :distance" --parameters "[{\"name\": \"colname\", \"value\": \"ratecode\"}, \ {\"name\": \"distance\", \"value\": \"5\"}]" --database dev

以下为响应示例。

{ "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598323175.823, "Database": "dev", "Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814", "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:yanruiz-secret-hKgPWn" }

以下示例使用示例数据库中的 EVENT 表。有关 COPY 语法的更多信息,请参阅 Amazon Redshift 数据库开发人员指南中的 EVENT 表

如果您的数据库中没有 EVENT 表,则可以使用数据 API 创建一个,如下所示:

aws redshift-data execute-statement --database dev --cluster-id my-test-cluster --db-user awsuser --sql "create table event( eventid integer not null distkey, venueid smallint not null, catid smallint not null, dateid smallint not null sortkey, eventname varchar(200), starttime timestamp)"

以下命令将一个行插入 EVENT 表。

aws redshift-data execute-statement --database dev --cluster-id my-test-cluster --db-user awsuser --sql "insert into event values(:eventid, :venueid::smallint, :catid, :dateid, :eventname, :starttime)" --parameters "[{\"name\": \"eventid\", \"value\": \"1\"}, {\"name\": \"venueid\", \"value\": \"1\"}, {\"name\": \"catid\", \"value\": \"1\"}, {\"name\": \"dateid\", \"value\": \"1\"}, {\"name\": \"eventname\", \"value\": \"event 1\"}, {\"name\": \"starttime\", \"value\": \"2022-02-22\"}]"

以下命令将另一个行插入 EVENT 表。该示例演示以下内容:

  • 名为 id 参数在 SQL 文本中使用了四次。

  • 插入参数 starttime 时自动应用隐式类型转换。

  • venueid 列是转换为 SMALINT 数据类型的类型。

  • 表示 DATE 数据类型的字符串将隐式转换为 TIMESTAMP 数据类型。

  • 注释可以在 SQL 文本中使用。

aws redshift-data execute-statement --database dev --cluster-id my-test-cluster --db-user awsuser --sql "insert into event values(:id, :id::smallint, :id, :id, :eventname, :starttime) /*this is comment, and it won't apply parameterization for :id, :eventname or :starttime here*/" --parameters "[{\"name\": \"eventname\", \"value\": \"event 2\"}, {\"name\": \"starttime\", \"value\": \"2022-02-22\"}, {\"name\": \"id\", \"value\": \"2\"}]"

下面显示了两个插入的行:

eventid | venueid | catid | dateid | eventname | starttime ---------+---------+-------+--------+-----------+--------------------- 1 | 1 | 1 | 1 | event 1 | 2022-02-22 00:00:00 2 | 2 | 2 | 2 | event 2 | 2022-02-22 00:00:00

以下命令使用 WHERE 子句中的命名参数来检索 eventid1 的行。

aws redshift-data execute-statement --database dev --cluster-id my-test-cluster --db-user awsuser --sql "select * from event where eventid=:id" --parameters "[{\"name\": \"id\", \"value\": \"1\"}]"

运行以下命令以获取上一个 SQL 语句的 SQL 结果:

aws redshift-data get-statement-result --id 7529ad05-b905-4d71-9ec6-8b333836eb5a

提供以下结果:

{ "Records": [ [ { "longValue": 1 }, { "longValue": 1 }, { "longValue": 1 }, { "longValue": 1 }, { "stringValue": "event 1" }, { "stringValue": "2022-02-22 00:00:00.0" } ] ], "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "eventid", "length": 0, "name": "eventid", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "venueid", "length": 0, "name": "venueid", "nullable": 0, "precision": 5, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int2" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "catid", "length": 0, "name": "catid", "nullable": 0, "precision": 5, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int2" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "dateid", "length": 0, "name": "dateid", "nullable": 0, "precision": 5, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int2" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "eventname", "length": 0, "name": "eventname", "nullable": 1, "precision": 200, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "varchar" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "label": "starttime", "length": 0, "name": "starttime", "nullable": 1, "precision": 29, "scale": 6, "schemaName": "public", "tableName": "event", "typeName": "timestamp" } ], "TotalNumRows": 1 }

要运行多个 SQL 语句

要使用一个命令运行多个 SQL 语句,请使用 aws redshift-data batch-execute-statement Amazon CLI 命令。

以下 Amazon CLI 命令运行三个 SQL 语句并返回用于获取结果的标识符。此示例使用临时凭证身份验证方法。

aws redshift-data batch-execute-statement --region us-west-2 --db-user myuser --cluster-identifier mycluster-test --database dev --sqls "set timezone to BST" "select * from mytable" "select * from another_table"

以下为响应示例。

{ "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598306924.632, "Database": "dev", "DbUser": "myuser", "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766" }

要列出有关 SQL 语句的元数据

要列出有关 SQL 语句的元数据,请使用 aws redshift-data list-statements Amazon CLI 命令。运行此命令的授权基于调用者的 IAM 权限。

以下 Amazon CLI 命令列出了运行的 SQL 语句。

aws redshift-data list-statements --region us-west-2 --status ALL

以下为响应示例。

{ "Statements": [ { "CreatedAt": 1598306924.632, "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766", "QueryString": "select * from stl_query limit 1", "Status": "FINISHED", "UpdatedAt": 1598306926.667 }, { "CreatedAt": 1598311717.437, "Id": "e0ebd578-58b3-46cc-8e52-8163fd7e01aa", "QueryString": "select * from stl_query limit 1", "Status": "FAILED", "UpdatedAt": 1598311719.008 }, { "CreatedAt": 1598313683.65, "Id": "c361d4f7-8c53-4343-8c45-6b2b1166330c", "QueryString": "select * from stl_query limit 1", "Status": "ABORTED", "UpdatedAt": 1598313685.495 }, { "CreatedAt": 1598306653.333, "Id": "a512b7bd-98c7-45d5-985b-a715f3cfde7f", "QueryString": "select 1", "Status": "FINISHED", "UpdatedAt": 1598306653.992 } ] }

要描述有关 SQL 语句的元数据

要获取 SQL 语句的元数据描述,请使用 aws redshift-data describe-statement Amazon CLI 命令。运行此命令的授权基于调用者的 IAM 权限。

以下 Amazon CLI 命令描述 SQL 语句。

aws redshift-data describe-statement --id d9b6c0c9-0747-4bf4-b142-e8883122f766 --region us-west-2

以下为响应示例。

{ "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598306924.632, "Duration": 1095981511, "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766", "QueryString": "select * from stl_query limit 1", "RedshiftPid": 20859, "RedshiftQueryId": 48879, "ResultRows": 1, "ResultSize": 4489, "Status": "FINISHED", "UpdatedAt": 1598306926.667 }

以下是使用多个 SQL 语句运行 batch-execute-statement 命令后的 describe-statement 响应示例。

{ "ClusterIdentifier": "mayo", "CreatedAt": 1623979777.126, "Duration": 6591877, "HasResultSet": true, "Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652", "RedshiftPid": 31459, "RedshiftQueryId": 0, "ResultRows": 2, "ResultSize": 22, "Status": "FINISHED", "SubStatements": [ { "CreatedAt": 1623979777.274, "Duration": 3396637, "HasResultSet": true, "Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:1", "QueryString": "select 1;", "RedshiftQueryId": -1, "ResultRows": 1, "ResultSize": 11, "Status": "FINISHED", "UpdatedAt": 1623979777.903 }, { "CreatedAt": 1623979777.274, "Duration": 3195240, "HasResultSet": true, "Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2", "QueryString": "select 2;", "RedshiftQueryId": -1, "ResultRows": 1, "ResultSize": 11, "Status": "FINISHED", "UpdatedAt": 1623979778.076 } ], "UpdatedAt": 1623979778.183 }

要获取 SQL 语句的结果

要从运行的 SQL 语句中获取结果,请使用 redshift-data get-statement-result Amazon CLI 命令。您可以提供响应 execute-statement 或者 batch-execute-statement 而收到的 Id。可以在 describe-statement 的结果中检索 batch-execute-statement 运行的 SQL 语句的 Id 值,并以冒号和 b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2 等序列号为该值添加后缀。如果使用 batch-execute-statement 运行多个 SQL 语句,则每个 SQL 语句都有一个 Id 值,如 describe-statement 中所示。运行此命令的授权基于调用者的 IAM 权限。

以下语句返回 execute-statement 运行的 SQL 语句的结果。

aws redshift-data get-statement-result --id d9b6c0c9-0747-4bf4-b142-e8883122f766 --region us-west-2

以下语句返回 batch-execute-statement 运行的第二个 SQL 语句的结果。

aws redshift-data get-statement-result --id b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2 --region us-west-2

以下是 get-statement-result 调用的响应的示例。

{ "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "userid", "length": 0, "name": "userid", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "query", "length": 0, "name": "query", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "label", "length": 0, "name": "label", "nullable": 0, "precision": 320, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "bpchar" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "xid", "length": 0, "name": "xid", "nullable": 0, "precision": 19, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int8" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "pid", "length": 0, "name": "pid", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "database", "length": 0, "name": "database", "nullable": 0, "precision": 32, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "bpchar" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "querytxt", "length": 0, "name": "querytxt", "nullable": 0, "precision": 4000, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "bpchar" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "label": "starttime", "length": 0, "name": "starttime", "nullable": 0, "precision": 29, "scale": 6, "schemaName": "", "tableName": "stll_query", "typeName": "timestamp" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "label": "endtime", "length": 0, "name": "endtime", "nullable": 0, "precision": 29, "scale": 6, "schemaName": "", "tableName": "stll_query", "type": 93, "typeName": "timestamp" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "aborted", "length": 0, "name": "aborted", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "insert_pristine", "length": 0, "name": "insert_pristine", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "concurrency_scaling_status", "length": 0, "name": "concurrency_scaling_status", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" } ], "Records": [ [ { "longValue": 1 }, { "longValue": 3 }, { "stringValue": "health" }, { "longValue": 1023 }, { "longValue": 15279 }, { "stringValue": "dev" }, { "stringValue": "select system_status from stv_gui_status;" }, { "stringValue": "2020-08-21 17:33:51.88712" }, { "stringValue": "2020-08-21 17:33:52.974306" }, { "longValue": 0 }, { "longValue": 0 }, { "longValue": 6 } ] ], "TotalNumRows": 1 }

要描述表

要获取描述表的元数据,请使用 aws redshift-data describe-table Amazon CLI 命令。

以下 Amazon CLI 命令运行 SQL 语句并返回描述表的元数据。此示例使用 Amazon Secrets Manager 身份验证方法。

aws redshift-data describe-table --region us-west-2 --cluster-identifier mycluster-test --database dev --schema information_schema --table sql_features --secret arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn

以下为响应示例。

{ "ColumnList": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_id", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_name", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" } ] }

以下 Amazon CLI 命令运行描述表的 SQL 语句。此示例使用临时凭证身份验证方法。

aws redshift-data describe-table --region us-west-2 --db-user myuser --cluster-identifier mycluster-test --database dev --schema information_schema --table sql_features

以下为响应示例。

{ "ColumnList": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_id", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_name", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "sub_feature_id", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "sub_feature_name", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "is_supported", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "is_verified_by", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "comments", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" } ] }

要列出集群中的数据库

要列出集群中的数据库,请使用 aws redshift-data list-databases Amazon CLI 命令。

以下 Amazon CLI 命令运行 SQL 语句来列出数据库。此示例使用 Amazon Secrets Manager 身份验证方法。

aws redshift-data list-databases --region us-west-2 --secret arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --database dev

以下为响应示例。

{ "Databases": [ "dev" ] }

以下 Amazon CLI 命令运行 SQL 语句来列出数据库。此示例使用临时凭证身份验证方法。

aws redshift-data list-databases --region us-west-2 --db-user myuser --cluster-identifier mycluster-test --database dev

以下为响应示例。

{ "Databases": [ "dev" ] }

要列出数据库中的 schema

要列出数据库中的 schema,请使用 aws redshift-data list-schemas Amazon CLI 命令。

以下 Amazon CLI 命令运行 SQL 语句来列出数据库中的 schema。此示例使用 Amazon Secrets Manager 身份验证方法。

aws redshift-data list-schemas --region us-west-2 --secret arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --database dev

以下为响应示例。

{ "Schemas": [ "information_schema", "pg_catalog", "pg_internal", "public" ] }

以下 Amazon CLI 命令运行 SQL 语句来列出数据库中的 schema。此示例使用临时凭证身份验证方法。

aws redshift-data list-schemas --region us-west-2 --db-user mysuser --cluster-identifier mycluster-test --database dev

以下为响应示例。

{ "Schemas": [ "information_schema", "pg_catalog", "pg_internal", "public" ] }

要列出数据库中的表

要列出数据库中的表,请使用 aws redshift-data list-tables Amazon CLI 命令。

以下 Amazon CLI 命令运行 SQL 语句来列出数据库中的表。此示例使用 Amazon Secrets Manager 身份验证方法。

aws redshift-data list-tables --region us-west-2 --secret arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --database dev --schema information_schema

以下为响应示例。

{ "Tables": [ { "name": "sql_features", "schema": "information_schema", "type": "SYSTEM TABLE" }, { "name": "sql_implementation_info", "schema": "information_schema", "type": "SYSTEM TABLE" } }

以下 Amazon CLI 命令运行 SQL 语句来列出数据库中的表。此示例使用临时凭证身份验证方法。

aws redshift-data list-tables --region us-west-2 --db-user myuser --cluster-identifier mycluster-test --database dev --schema information_schema

以下为响应示例。

{ "Tables": [ { "name": "sql_features", "schema": "information_schema", "type": "SYSTEM TABLE" }, { "name": "sql_implementation_info", "schema": "information_schema", "type": "SYSTEM TABLE" } ] }

Amazon Redshift 数据 API 的问题排查

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

用于查询的包太大

如果您看到一条错误,指示查询的数据包过大,则为行返回的结果集通常过大。数据库返回的结果集中的 Data API 大小限制为每行 64 KB。

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

数据库响应超出大小限制

如果您看到一条错误,指示数据库响应超出了大小限制,则数据库返回的结果集的大小通常太大。数据库返回的结果集中的数据 API 限制为 100 MB。

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

使用 Amazon EventBridge 计划 Amazon Redshift 数据 API 操作

Amazon EventBridge 可帮助您响应您 Amazon 资源的状态更改。当您的资源的状态发生变化时,会自动向事件流发送事件。事件将发送到包含 Amazon Redshift 数据库的账户。您可以创建规则来匹配流中的选定事件并将它们路由到目标以采取操作。此外,您还可以使用规则对预定的计划采取操作。有关更多信息,请参阅 Amazon EventBridge 用户指南

要使用 EventBridge 计划数据 API 操作,关联的 IAM 角色必须信任 CloudWatch Events (events.amazonaws.com) 的委托人。此角色应附加相当于托管策略 AmazonEventBridgeFullAccess 的策略。它还应具有 AmazonRedshiftDataFullAccess 策略权限,这些权限由数据 API 管理。您可以在 IAM 控制台上创建具有这些权限的 IAM 角色。在 IAM 控制台上创建角色时,为 CloudWatch Events 选择 Amazon 服务可信任实体。有关创建 IAM 角色的更多信息,请参阅 IAM 用户指南中的为 Amazon 服务(控制台)创建一个角色

以下示例使用 Amazon CLI 创建用于运行 SQL 语句的 EventBridge 规则。

aws events put-rule --name test-redshift-data --schedule-expression "rate(1 minute)"

然后创建一个 EventBridge 目标,以按照规则中指定的计划运行。

aws events put-targets --cli-input-json file://data.json

输入 data.json 文件如下。

{ "Rule": "test-redshift-data", "EventBusName": "default", "Targets": [ { "Id": "2", "Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster", "RoleArn": "arn:aws:iam::123456789012:role/Administrator", "RedshiftDataParameters": { "Database": "dev", "DbUser": "root", "Sql": "select 1;", "StatementName": "test-scheduler-statement", "WithEvent": true } } ] }