从补丁 198 开始，Amazon Redshift 将不再支持创建新的 Python UDF。现有的 Python UDF 将继续正常运行至 2026 年 6 月 30 日。有关更多信息，请参阅[博客文章](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/)。
# 使用 Amazon Redshift 数据 API
Amazon Redshift 数据 API 消除了管理数据库驱动程序、连接、网络配置、数据缓冲、凭证等的需求，从而简化了对 Amazon Redshift 数据仓库的访问。您可以通过 AWS SDK，使用数据 API 操作来运行 SQL 语句。有关数据 API 操作的更多信息，请参阅 [Amazon Redshift 数据 API 参考](https://docs.aws.amazon.com/redshift-data/latest/APIReference/)。
数据 API 不需要与数据库的持久连接。相反，它提供了安全 HTTP 端点以及与 AWS 开发工具包的集成。您可以使用终端节点运行 SQL 语句，而无需管理连接。对数据 API 的调用是异步的。数据 API 可以使用存储在 AWS Secrets Manager 中的凭证或临时数据库凭证。您无需使用任何一种授权方法在 API 调用中传递密码。有关 AWS Secrets Manager 的更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[什么是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 您也可以使用 AWS IAM Identity Center 进行授权。
使用数据 API，您可以通过基于 Web 服务的应用程序（包括 AWS Lambda、Amazon SageMaker AI 笔记本和 AWS Cloud9），以编程方式访问 Amazon Redshift 数据。有关这些应用程序的更多信息，请参阅 [AWS Lambda](https://aws.amazon.com/lambda/)、[Amazon SageMaker AI](https://aws.amazon.com/sagemaker/) 和 [AWS Cloud9](https://aws.amazon.com/cloud9/)。
要了解有关数据 API 的更多信息，请参阅 *AWS 大数据博客*中的 [Get started with the Amazon Redshift Data API](https://aws.amazon.com/blogs/big-data/get-started-with-the-amazon-redshift-data-api/)。
## 使用 Amazon Redshift 数据 API
在您使用 Amazon Redshift 数据 API 之前，请查看以下步骤：
1. 确定您作为数据 API 的调用者是否获得授权。有关授权的更多信息，请参阅[授予对 Amazon Redshift 数据 API 的访问权限](data-api-access.md)。
1. 确定是否计划使用来自 Secrets Manager 的身份验证凭证、临时凭证或使用 AWS IAM Identity Center 来调用数据 API。有关更多信息，请参阅 [在调用 Amazon Redshift 数据 API 时选择数据库身份验证凭证](#data-api-calling-considerations-authentication)。
1. 如果您将 Secrets Manager 用于身份验证凭证，请设置密码。有关更多信息，请参阅 [在 AWS Secrets Manager 中存储数据库凭证](data-api-secrets.md)。
1. 查看调用数据 API 时的注意事项和限制。有关更多信息，请参阅 [调用 Amazon Redshift 数据 API 时的注意事项](#data-api-calling-considerations)。
1. 从 AWS Command Line Interface (AWS CLI)、您自己的代码中调用数据 API，或使用 Amazon Redshift 控制台中的查询编辑器。有关从 AWS CLI 进行调用的示例，请参阅[调用 Data API](data-api-calling.md)。
## 调用 Amazon Redshift 数据 API 时的注意事项
调用数据 API 时，请注意以下事项：
+ Amazon Redshift 数据 API 可以访问 Amazon Redshift 预置集群和 Redshift Serverless 工作组中的数据库。有关可以使用数据 API 的 AWS 区域列表，请参阅《Amazon Web Services 一般参考》**中为 [Redshift 数据 API](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html) 列出的端点。
+ 查询的最长持续时间为 24 小时。
+ 每个 Amazon Redshift 集群的最大活动查询（`STARTED` 和 `SUBMITTED` 查询）数量为 500 个。
+ 最大查询结果大小为 500 MB（gzip 压缩后）。如果调用返回的响应数据超过 500 MB，则调用将结束。
+ 查询结果的最长保留时间为 24 小时。
+ 最大查询语句大小为 100 KB。
+ 数据 API 可用于查询以下节点类型的单节点和多节点集群：
+ dc2.large
+ dc2.8xlarge
+ ra3.large
+ ra3.xlplus
+ ra3.4xlarge
+ ra3.16xlarge
+ 集群必须在基于 Amazon VPC 服务的 Virtual Private Cloud (VPC) 中。
+ 默认情况下，具有与 `ExecuteStatement` 或 `BatchExecuteStatement` API 操作运行者相同的 IAM 角色的用户可以使用 `CancelStatement`、`DescribeStatement`、`GetStatementResult`、`GetStatementResultV2` 和 `ListStatements` API 操作对同一个语句进行操作。要从另一个用户对同一 SQL 语句执行操作，该用户必须能够代入运行 SQL 语句的用户的 IAM 角色。有关如何代入角色的更多信息，请参阅[授予对 Amazon Redshift 数据 API 的访问权限](data-api-access.md)。
+ `BatchExecuteStatement` API 操作的 `Sqls` 参数中的 SQL 语句将作为单个事务运行。它们按数组的顺序连续运行。后续的 SQL 语句要等到数组中的前一条语句完成后才会开始。如果任何 SQL 语句失败，由于它们作为一个事务运行，所有工作都将回滚。
+ 在 `ExecuteStatement` 或 `BatchExecuteStatement` API 操作中使用的客户端令牌的最长保留时间为 8 小时。
+ 如果使用客户自主管理型密钥对 Amazon Redshift 预调配集群和 Redshift Serverless 工作组进行加密，则 Redshift 将创建一项授权，允许 Redshift Data API 将该密钥用于其操作。有关更多信息，请参阅 [结合使用 AWS KMS 与 Amazon Redshift Data API](data-api-kms.md)。
+ Redshift 数据 API 中的每个 API 都有每秒事务次数配额，超过该配额会对请求节流。有关配额，请参阅 [Amazon Redshift 数据 API 的配额](amazon-redshift-limits.md#data-api-quotas-account)。如果请求速率超过配额，则会返回 `ThrottlingException` 以及“HTTP 状态代码：400”。要应对节流的情况，请使用重试策略，如《AWS SDK 和工具参考指南》**中的[重试行为](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)所述。在某些 AWS SDK 中，会针对节流错误自动实施这一策略。
**注意**
在 AWS Step Functions 中，默认情况下未启用重试功能。如果您需要在 Step Functions 状态机中调用 Redshift 数据 API，请在 Redshift 数据 API 调用中包括 `ClientToken` 幂等性参数。`ClientToken` 的值需要在重试之间保持不变。在以下 `ExecuteStatement` API 请求的示例片段中，表达式 `States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)` 使用内置函数提取 `$$.Execution.Id` 的 UUID 部分，这一部分在状态机的每次执行中都是唯一的。有关更多信息，请参阅《AWS Step Functions 开发人员指南》**中的[内置函数](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-intrinsic-functions.html)。
```
{
"Database": "dev",
"Sql": "select 1;",
"ClusterIdentifier": "MyCluster",
"ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
}
```
## 在调用 Amazon Redshift 数据 API 时选择数据库身份验证凭证
当您调用数据 API 时，您对某些 API 操作使用以下身份验证方法之一。每种方法都需要不同的参数组合。
**AWS IAM Identity Center**
在 AWS IAM Identity Center 中注册的单点登录用户可以访问数据 API。有关设置 IAM Identity Center 的步骤的信息，请参阅[将数据 API 与可信身份传播结合使用](data-api-trusted-identity-propagation.md)。
**AWS Secrets Manager**
使用此方法，提供存储在 AWS Secrets Manager 中密钥的 `secret-arn`，其中包括了 `username` 和 `password`。指定的密钥包含用于连接到您指定的 `database` 的凭证。在连接到集群时，如果您提供了集群标识符（`dbClusterIdentifier`），则还可以提供数据库名称，该名称必须与密钥中存储的集群标识符相匹配。在连接到无服务器工作组时，也要提供数据库名称。有关更多信息，请参阅 [在 AWS Secrets Manager 中存储数据库凭证](data-api-secrets.md)。
使用此方法，您还可以提供 `region` 值，该值指定您的数据所在的 AWS 区域。
**临时凭证**
使用此方法时，请选择以下选项之一：
+ 在连接到无服务器工作组时，需指定工作组名称和数据库名称。数据库用户名派生自 IAM 身份。例如，`arn:iam::123456789012:user:foo` 具有数据库用户名 `IAM:foo`。此外，需具有调用 `redshift-serverless:GetCredentials` 操作的权限。
+ 以 IAM 身份连接到集群时，需要指定集群标识符和数据库名称。数据库用户名派生自 IAM 身份。例如，`arn:iam::123456789012:user:foo` 具有数据库用户名 `IAM:foo`。此外，需具有调用 `redshift:GetClusterCredentialsWithIAM` 操作的权限。
+ 以数据库用户的身份连接到机群时，需要指定集群标识符、数据库名称和数据库用户名。此外，需具有调用 `redshift:GetClusterCredentials` 操作的权限。有关使用此方法进行连接时如何加入数据库组的信息，请参阅[连接到集群时加入数据库组](data-api-dbgroups.md)。
使用此方法，您还可以提供 `region` 值，该值指定您的数据所在的 AWS 区域。
## 调用 Amazon Redshift 数据 API 时映射 JDBC 数据类型
下表将 Java 数据库连接 (JDBC) 数据类型映射到您在数据 API 调用中指定的数据类型。
****
| JDBC 数据类型 | Data API 数据类型 |
| --- | --- |
| `INTEGER, SMALLINT, BIGINT` | `LONG` |
| `FLOAT, REAL, DOUBLE` | `DOUBLE` |
| `DECIMAL` | `STRING` |
| `BOOLEAN, BIT` | `BOOLEAN` |
| `BLOB, BINARY, LONGVARBINARY` | `BLOB` |
| `VARBINARY` | `STRING` |
| `CLOB` | `STRING` |
| 其他类型（包括与日期和时间有关的类型） | `STRING` |
字符串值将传递到 Amazon Redshift 数据库并隐式转换为数据库数据类型。
**注意**
目前，数据 API 不支持通用唯一标识符 (UUID) 的数组。
## 在调用 Amazon Redshift 数据 API 时运行带有参数的 SQL 语句
您可以通过使用 SQL 语句部分的参数调用数据 API 操作来控制提交到数据库引擎的 SQL 文本。命名参数提供了一种灵活的方式来传入参数，而无需在 SQL 文本中对参数进行硬编码。它们可以帮助您重复使用 SQL 文本并避免 SQL 注入问题。
以下示例显示 `execute-statement` AWS CLI 命令的 `parameters` 字段的命名参数。
```
--parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"
```
使用命名参数时，请注意以下事项：
+ 命名参数只能用于替换 SQL 语句中的值。
+ 您可以替换 INSERT 语句中的值，例如 `INSERT INTO mytable VALUES(:val1)`。
命名参数可以按任意顺序排列，并且参数可以在 SQL 文本中多次使用。前面示例中显示的参数选项，值 `1` 和 `Seattle` 插入到表列 `id` 和 `address` 中。在 SQL 文本中，您可以按如下方式指定命名参数：
```
--sql "insert into mytable values (:id, :address)"
```
+ 您可以替换条件子句中的值，例如 `WHERE attr >= :val1`、`WHERE attr BETWEEN :val1 AND :val2` 和 `HAVING COUNT(attr) > :val`。
+ 您无法替换 SQL 语句中的列名，例如 `SELECT column-name`、`ORDER BY column-name` 或 `GROUP BY column-name`。
例如，以下 SELECT 语句将失败，出现语法无效错误。
```
--sql "SELECT :colname, FROM event" --parameters "[{\"name\": \"colname\", \"value\": \"eventname\"}]"
```
如果您说明（`describe-statement` 操作）语句有语法错误，则返回的 `QueryString` 不会用列名代替参数（`"QueryString": "SELECT :colname, FROM event"`），并且会报告错误（错误：在 \$1"FROM\$1"\$1 处或附近出现语法错误 \$1n 位置：12）。
+ 您无法替换聚合函数中的列名，例如 `COUNT(column-name)`、`AVG(column-name)` 或 `SUM(column-name)`。
+ 您无法替换 JOIN 子句中的列名。
+ SQL 运行时，数据将隐式转换为数据类型。有关数据类型转换的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[数据类型](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html)。
+ 您不能将值设置为 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 语句。
## 在调用 Amazon Redshift 数据 API 时运行带有幂等性令牌的 SQL 语句
当您发出变更 API 请求时，该请求通常会在操作的异步工作流完成之前返回结果。即使请求已经返回结果，操作在完成之前也可能会超时或遇到其他服务器问题。这样就很难确定请求是否成功，并且会导致进行多次重试以确保操作成功完成。但是，如果原始请求和后续重试成功，则会多次完成操作。这意味着您可能会更新比预期更多的资源。
*幂等性*确保 API 请求完成不超过一次。对于幂等性请求，如果原始请求成功完成，则后续重试也会成功完成，而不会执行任何后续操作。数据 API `ExecuteStatement` 和 `BatchExecuteStatement` 操作具有可选的 `ClientToken` 幂等性参数。`ClientToken` 在 8 小时后过期。
**重要**
如果您从 AWS SDK 调用 `ExecuteStatement` 和 `BatchExecuteStatement` 操作，它会自动生成客户端令牌以供重试时使用。在这种情况下，我们不建议将 `client-token` 参数与 `ExecuteStatement` 和 `BatchExecuteStatement` 操作一起使用。查看 CloudTrail 日志以查看 `ClientToken`。有关 CloudTrail 日志示例，请参阅 [Amazon Redshift 数据 API 示例](logging-with-cloudtrail.md#data-api-cloudtrail)。
以下 `execute-statement` AWS CLI 命令说明了幂等性的可选 `client-token` 参数。
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
--client-token b855dced-259b-444c-bc7b-d3e8e33f94g1
```
下表显示了幂等性 API 请求可能获得的一些常见响应，并提供了重试建议。
| 响应 | 建议 | 评论 |
| --- | --- | --- |
| 200（正常） | 不重试 | 原始请求成功完成。成功返回任何后续重试。 |
| 400 系列响应代码 | 不重试 | 请求存在问题，原因如下： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/redshift/latest/mgmt/data-api.html) 如果请求涉及正在改变状态的资源，则重试请求可能会成功。 |
| 500 系列响应代码 | 重试 | 该错误是由 AWS 服务器端问题引起，通常是暂时性的。使用适当的退避策略重复发出请求。 |
有关 Amazon Redshift 响应代码的信息，请参阅《Amazon Redshift API 参考》**中的[常见错误](https://docs.aws.amazon.com/redshift/latest/APIReference/CommonErrors.html)。
## 在调用 Amazon Redshift 数据 API 时运行带有会话重用的 SQL 语句
当您发出 API 请求来运行 SQL 语句时，在其中运行 SQL 的会话通常在 SQL 完成后终止。为了在指定的秒数内使会话保持活动状态，数据 API `ExecuteStatement` 和 `BatchExecuteStatement` 操作具有可选的 `SessionKeepAliveSeconds` 参数。`SessionId` 响应字段包含会话的身份，随后可以在后续 `ExecuteStatement` 和 `BatchExecuteStatement` 操作中使用该身份。在后续调用中，可以指定另一个 `SessionKeepAliveSeconds` 来更改空闲超时时间。如果未更改 `SessionKeepAliveSeconds`，则会保留初始空闲超时设置。使用会话重用时，请考虑以下事项：
+ `SessionKeepAliveSeconds` 的最大值为 24 小时。
+ 会话最多可持续 24 小时。24 小时后，会话将被强制关闭，正在进行的查询将被终止。
+ 每个 Amazon Redshift 集群或 Redshift Serverless 工作组的最大会话数为 500 个。
+ 在会话中，一次只能运行一个查询。您需要等到查询完成后，才能在同一个会话中运行下一个查询。也就是说，不能在提供的会话中并行运行查询。
+ 数据 API 无法对给定会话的查询进行排队。
要检索调用 `ExecuteStatement` 和 `BatchExecuteStatement` 操作时所使用的 `SessionId`，请调用 `DescribeStatement` 和 `ListStatements` 操作。
以下示例演示如何使用 `SessionKeepAliveSeconds` 和 `SessionId` 参数来使会话保持活动状态并重用。首先，在可选 `session-keep-alive-seconds` 参数设置为 `2` 的情况下调用 `execute-statement` AWS CLI 命令。
```
aws redshift-data execute-statement
--session-keep-alive-seconds 2
--sql "select 1"
--database dev
--workgroup-name mywg
```
响应将包含会话标识符。
```
{
"WorkgroupName": "mywg",
"CreatedAt": 1703022996.436,
"Database": "dev",
"DbUser": "awsuser",
"Id": "07c5ffea-76d6-4786-b62c-4fe3ef529680",
"SessionId": "5a254dc6-4fc2-4203-87a8-551155432ee4"
}
```
然后，使用从第一个调用返回的 `SessionId` 来调用 `execute-statement` AWS CLI 命令。或者，指定将 `session-keep-alive-seconds` 参数设置为 `10` 以更改空闲超时值。
```
aws redshift-data execute-statement
--sql "select 1"
--session-id 5a254dc6-4fc2-4203-87a8-551155432ee4
--session-keep-alive-seconds 10
```
## 获取 SQL 语句的结果
根据结果格式，您可以使用不同的数据 API 操作来获取 SQL 结果。在调用 `ExecuteStatement` 和 `BatchExecuteStatement` 操作时，可以指定结果的格式是 JSON 还是 CSV。如果未指定，则默认格式为 JSON。要检索 JSON 结果，请使用 `GetStatementResult` 操作。要检索 CSV 结果，请使用 `GetStatementResultV2` 操作。
以 JSON 格式返回的结果是包含有关每列的元数据的记录。每条记录都是 JSON 格式。例如，来自 `GetStatementResult` 的响应与以下内容相似：
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"longValue": 1
}
]
],
"TotalNumRows":
}
```
以 CSV 格式返回的结果是包含有关每列的元数据的记录。结果以 1 MB 的分块形式返回，其中每个分块能够以 CSV 格式存储任意数量的行。每个请求最多返回 15 MB 的结果。如果结果大于 15 MB，则返回下一页令牌以继续检索结果。例如，来自 `GetStatementResultV2` 的响应与以下内容相似：
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"CSVRecords":"1,2,3\r\n4,5,6\r\n7,8,9\rn, .... 1MB" // First 1MB Chunk
},
{
"CSVRecords":"1025,1026,1027\r\n1028,1029,1030\r\n....2MB" // Second 1MB chunk
}
...
]
],
"ResultFormat" : "CSV",
"TotalNumRows":
}
```
# 授予对 Amazon Redshift 数据 API 的访问权限
用户必须获得授权才能访问数据 API。您可以通过将托管式策略（预定义的 AWS Identity and Access Management (IAM) 策略）添加给用户，授予该用户访问数据 API 的权限。作为最佳实践，我们建议将权限策略附加到 IAM 角色，然后根据需要将其分配给用户和组。有关更多信息，请参阅 [Amazon Redshift 中的 Identity and Access Management](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html)。要查看托管式策略允许和拒绝的权限，请参阅 IAM 控制台 ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/))。
# 配置 IAM 权限
Amazon Redshift 提供 `AmazonRedshiftDataFullAccess` 托管式策略。此策略提供了对 Amazon Redshift 数据 API 操作的完全访问。此策略还允许将访问权限限定为特定 Amazon Redshift、AWS Secrets Manager 以及对 Amazon Redshift 集群或 Redshift Serverless 进行身份验证和访问所需的 IAM API 操作。
此外，您还可以创建自己的 IAM 策略，以允许对特定资源的访问。要创建策略，请使用 `AmazonRedshiftDataFullAccess` 策略作为起始模板。在创建策略后，将该策略添加到需要访问数据 API 的每个用户。
考虑与用户关联的 IAM 策略的以下要求：
+ 如果您使用 AWS Secrets Manager 进行身份验证，请确认策略允许使用 `secretsmanager:GetSecretValue` 操作来检索使用键 `RedshiftDataFullAccess` 标记的密钥。
+ 如果您使用临时凭证对集群进行身份验证，请确认该策略允许将 `redshift:GetClusterCredentials` 操作用于集群中任何数据库的数据库用户名 `redshift_data_api_user`。此用户名必须已在数据库中创建。
+ 如果您使用临时凭证对无服务器工作组进行身份验证，请确认该策略允许使用 `redshift-serverless:GetCredentials` 操作来检索使用键 `RedshiftDataFullAccess` 标记的工作组。数据库用户按 1:1 的比例映射到源 AWS Identity and Access Management (IAM) 身份。例如，用户 sample\$1user 映射到数据库用户 `IAM:sample_user`，而 IAM 角色 sample\$1role 映射到 `IAMR:sample_role`。有关 IAM 身份的更多信息，请参阅《IAM 用户指南》中的 [IAM 身份（用户、组和角色）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html)。
+ IAM 操作 `redshift-data:GetStatementResult` 同时支持访问 `GetStatementResult` 和 `GetStatementResultV2` API 操作。
以下链接提供了《IAM 用户指南》**中有关 AWS Identity and Access Management 的更多信息。
+ 有关创建 IAM 角色的信息，请参阅[创建 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)。
+ 有关创建 IAM 策略的更多信息，请参阅[创建 IAM 策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)。
+ 有关将 IAM 策略添加到用户的信息，请参阅[添加和删除 IAM 身份权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。
## 在其它账户拥有的集群上运行查询
要对其他账户拥有的集群运行查询，拥有账户必须提供一个 IAM 角色，数据 API 可以在调用账户时代入该角色。例如，假设账户 B 拥有账户 A 需要访问的集群。账户 B 可以将 AWS 托管式策略 `AmazonRedshiftDataFullAccess` 附加到账户 B 的 IAM 角色。然后，账户 B 使用信任策略信任账户 A，如下所示：``
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/someRoleA"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
最后，账户 A 的 IAM 角色需要能够代入账户 B 的 IAM 角色。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::111122223333:role/someRoleB"
}
}
```
------
## 指定一个 IAM 角色，该角色将资源限制为 AWS 账户中的 Redshift Serverless 工作组和 Amazon Redshift 集群
可以在基于身份的策略中指定资源 ARN，以便控制对 AWS 账户中 Redshift Serverless 工作组和 Amazon Redshift 集群的访问权限。此示例显示如何创建一个策略，该策略只支持针对指定 AWS 账户中的工作组和集群访问数据 API。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "redshift-data:*",
"Resource": [
"arn:aws:redshift:us-east-1:111122223333:workgroup/*",
"arn:aws:redshift:us-east-1:111122223333:cluster:*"
]
}
]
}
```
------
## 配置 IAM 策略，来限制只有语句所有者才能访问 SQL 语句信息
默认情况下，Amazon Redshift 数据 API 将调用 `ExecuteStatement` 和 `BatchExecuteStatement` 时使用的 IAM 角色视为 SQL 语句的所有者。任何获准代入该角色的人都可以访问有关 SQL 语句的信息，包括其结果。要将 SQL 语句信息访问权限限制为与特定所有者之间的 IAM 角色会话，请添加条件 `redshift-data:statement-owner-iam-userid: "${aws:userid}"`。以下 IAM 策略会限制访问权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:statement-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
可以将条件 `statement-owner-iam-userid` 与 `CancelStatement`、`DescribeStatement`、`GetStatementResult` 和 `ListStatements` 结合使用。有关更多信息，请参阅 [Amazon Redshift Data API 定义的操作](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid)。
## 配置 IAM 策略，来限制只有会话所有者才能访问 SQL 结果
默认情况下，Amazon Redshift 数据 API 将调用 `ExecuteStatement` 和 `BatchExecuteStatement` 时使用的 IAM 角色视为运行 SQL 语句的数据库会话的所有者。任何获准代入该角色的人都可以提交对数据库会话的查询。要将会话访问权限限制为与特定所有者之间的 IAM 角色会话，请添加条件 ` redshift-data:session-owner-iam-userid: "${aws:userid}"`。以下 IAM 策略会限制访问权限。
以下 IAM 策略仅支持会话所有者获取语句结果。条件 `session-owner-iam-userid` 用于将资源访问权限限制为指定的 `userid`。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:ExecuteStatement",
"redshift-data:BatchExecuteStatement"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:session-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
可以将条件 `session-owner-iam-userid` 与 `ExecuteStatement` 和 `BatchExecuteStatement` 结合使用。有关更多信息，请参阅 [Amazon Redshift Data API 定义的操作](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid)。
# 在 AWS Secrets Manager 中存储数据库凭证
在调用数据 API 时，您可以使用 AWS Secrets Manager 中的密钥传递集群或无服务器工作组的凭证。要通过此方式传递凭证，您需要指定密钥的名称或密钥的 Amazon 资源名称（ARN）。
要使用 Secrets Manager 存储凭证，您需要 `SecretManagerReadWrite` 托管式策略权限。有关最低权限的更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[使用 AWS Secrets Manager 创建和管理密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)。
**要将凭证存储在 Amazon Redshift 集群的密钥中**
1. 使用 AWS Secrets Manager 控制台创建包含集群凭证的密钥：
+ 当您选择**存储新密钥**时，选择**Redshift 集群的凭证**。
+ 将**用户名**（数据库用户）、**密码**和 **数据库集群**（集群标识符）的值存储在您的密钥中。
+ 使用键 `RedshiftDataFullAccess` 标记密钥。AWS 托管式策略 `AmazonRedshiftDataFullAccess` 只支持对使用键 `RedshiftDataFullAccess` 进行标记的密钥执行操作 `secretsmanager:GetSecretValue`。
有关说明，请参阅《AWS Secrets Manager 用户指南》**中的[创建基本密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。
1. 使用 AWS Secrets Manager 控制台查看您创建的密钥的详细信息，或运行 `aws secretsmanager describe-secret` AWS CLI 命令。
记下密钥的名称和 ARN。您可以将其用于对数据 API 的调用中。
**将凭证存储在无服务器工作组的密钥中**
1. 使用 AWS Secrets Manager AWS CLI 命令存储包含无服务器工作组凭证的密钥：
+ 在文件中创建密钥，例如名为 `mycreds.json` 的 JSON 文件。在文件中提供**用户名**（数据库用户）和**密码**的值。
```
{
"username": "myusername",
"password": "mypassword"
}
```
+ 将值存储在密钥中，并使用键 `RedshiftDataFullAccess` 标记密钥。
```
aws secretsmanager create-secret --name MyRedshiftSecret --tags Key="RedshiftDataFullAccess",Value="serverless" --secret-string file://mycreds.json
```
下面显示了输出。
```
{
"ARN": "arn:aws:secretsmanager:region:accountId:secret:MyRedshiftSecret-mvLHxf",
"Name": "MyRedshiftSecret",
"VersionId": "a1603925-e8ea-4739-9ae9-e509eEXAMPLE"
}
```
有关更多信息，请参阅《AWS Secrets Manager User Guide》**中的 [Creating a Basic Secret with AWS CLI](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html#proc-create-api)。
1. 使用 AWS Secrets Manager 控制台查看您创建的密钥的详细信息，或运行 `aws secretsmanager describe-secret` AWS CLI 命令。
记下密钥的名称和 ARN。您可以将其用于对数据 API 的调用中。
# 为数据 API 创建 Amazon VPC 终端节点 (AWS PrivateLink)
借助 Amazon Virtual Private Cloud (Amazon VPC)，您可以在 Virtual Private Cloud (VPC) 中启动 AWS 资源（例如 Amazon Redshift 集群和应用程序）。AWS PrivateLink 在亚马逊网络上提供了 Virtual Private Cloud (VPC) 和 AWS 服务之间的私有连接。通过使用 AWS PrivateLink，您可以创建 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 终端节点调用数据 API。使用 Amazon VPC 终端节点可保留 Amazon VPC 中应用程序间的流量与AWS网络中的 Data API，而无需使用公有 IP 地址。Amazon VPC 终端节点可帮助您遵守与管理公共互联网连接有关的合规性和法规要求。例如，如果您使用 Amazon VPC 终端节点，则可保持 Amazon EC2 实例上运行的应用程序和包含终端节点的 VPC 中的 Data API 之间的流量。
创建 Amazon VPC 终端节点后，便能开始使用此终端节点，而无需在应用程序中进行任何代码或配置更改。
**为 Data API 创建 Amazon VPC 终端节点**
1. 登录到AWS 管理控制台并打开 Amazon VPC 控制台，网址：[https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)。
1. 选择**端点**，然后选择**创建端点**。
1. 在**创建终端节点**页面上，为**服务类别**选择 **AWS 服务**。对于**服务名称**，选择 **redshift-data** (`com.amazonaws.region.redshift-data`)。
1. 对于 **VPC**，选择要在其中创建终端节点的 VPC。
选择包含用于进行 Data API 调用的应用程序的 VPC。
1. 对于**子网**，请为运行应用程序的 AWS 服务所使用的每个可用区 (AZ) 选择子网。
要创建 Amazon VPC 终端节点，请指定端点可在其中访问的私有 IP 地址范围。为此，请为每个可用区选择子网。执行此操作会将 VPC 端点限制为特定于每个可用区的私有 IP 地址范围，并且还会在每个可用区中创建一个 Amazon VPC 端点。
1. 对于**启用 DNS 名称**，选择**为此终端节点启用**。
私有 DNS 会将标准 Data API DNS 主机名 (`https://redshift-data.region.amazonaws.com`) 解析为与特定于 Amazon VPC 终端节点的 DNS 主机名关联的私有 IP 地址。因此，您可以使用 AWS CLI 或 AWS 开发工具包访问 Data API VPC 终端节点，而无需进行任何代码或配置更改来更新 Data API 终端节点 URL。
1. 对于**安全组**，选择要与 Amazon VPC 终端节点关联的安全组。
选择允许访问运行应用程序的 AWS 服务的安全组。例如，如果 Amazon EC2 实例正在运行您的应用程序，请选择允许访问 Amazon EC2 实例的安全组。利用安全组，您可以控制从 VPC 中的资源发送到 Amazon VPC 终端节点的流量。
1. 选择**Create endpoint**。
创建终端节点后，选择 AWS 管理控制台中的链接以查看终端节点详细信息。
终端节点**详细信息**选项卡将显示在创建 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 时的注意事项](data-api.md#data-api-calling-considerations)。
# 连接到集群时加入数据库组
数据库组是数据库用户的集合。可以向组授予数据库权限。管理员可以配置 IAM 角色，以便在使用数据 API 运行您的 SQL 时，将这些数据库组考虑在内。有关数据库组的更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的[组](https://docs.aws.amazon.com/redshift/latest/dg/r_Groups.html)。
您可以配置数据 API 调用者的 IAM 角色，以便在数据 API 连接到集群时，在调用中指定的数据库用户加入数据库组。只有在连接到预置集群时才支持此功能。连接到 Redshift Serverless 工作组时不支持此功能。数据 API 调用方的 IAM 角色还必须允许 `redshift:JoinGroup` 操作。
通过向 IAM 角色添加标签来对此进行配置。调用方 IAM 角色的管理员添加以 `RedshiftDbGroups` 为键、以数据库组列表为键值的标签。该值是以冒号 (:) 分隔的数据库组名称的列表，总长度不超过 256 个字符。必须事先在连接的数据库中定义数据库组。如果在数据库中找不到任何指定的组，则将其忽略。例如，对于数据库组 `accounting` 和 `retail`，键/值为 `accounting:retail`。标签键/值对 `{"Key":"RedshiftDbGroups","Value":"accounting:retail"}` 由数据 API 用于确定哪些数据库组与调用数据 API 时提供的数据库用户相关联。
**加入数据库组**
1. 登录AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在控制台的导航窗格中，选择**角色**，然后选择要编辑的角色的名称。
1. 选择**标签**选项卡，然后选择**管理标签**。
1. 选择**添加标签**，然后添加键 **RedshiftDbGroups** 以及一个值，该值是 *database-groups-colon-separated* 的列表。
1. 选择**保存更改**。
现在，当 IAM 主体（附加了此 IAM 角色）调用数据 API 时，指定的数据库用户将加入在 IAM 角色中指定的数据库组。
有关如何将标签附加至主体（包括 IAM 角色和 IAM 用户）的更多信息，请参阅《IAM 用户指南》**中的[标记 IAM 资源](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html)部分。
# 将数据 API 与可信身份传播结合使用
作为 Amazon Redshift 账户管理员，您可以将 Amazon Redshift 集群或工作组与 AWS IAM Identity Center 集成，这有助于管理您的员工通过单点登录访问 Amazon Redshift 的权限。有关更多信息，请参阅 [设置 AWS IAM Identity Center 与 Amazon Redshift 的集成](redshift-iam-access-control-idp-connect-console.md)。Amazon Redshift 数据 API 支持将 IAM Identity Center 用户身份传播到 Amazon Redshift 集群或工作组以及链下游的其它服务，例如 AWS Lake Formation。您可以按照 [Access AWS services programmatically using trusted identity propagation](https://aws.amazon.com/blogs//security/access-aws-services-programmatically-using-trusted-identity-propagation/) 中的步骤操作，使用数据 API 进行设置和查询。
当您在身份增强型 IAM 角色会话中使用 IAM Identity Center 用户身份调用数据 API 时，您只能使用相同的 IAM Identity Center 用户访问生成的语句和语句结果。例如，以下 AWS CLI 命令调用 `execute-statement` 操作，以便使用可信身份传播来运行 SQL 命令。
```
aws redshift-data execute-statement
--sql "select current_user;"
--cluster-id mycluster
--database dev
```
以下 AWS CLI 命令调用 `batch-execute-statement` 操作来运行两个 SQL 命令。
```
aws redshift-data batch-execute-statement
--sqls "select current_user;" "select current_date;"
--cluster-id mycluster
--database dev
```
要访问由身份增强型 IAM 角色会话提交的具有 `cancel-statement`、`describe-statement`、`get-statement-result` 和 `get-statement-result-v2` 的语句，IAM Identity Center 用户和 IAM 角色必须与用于运行 `execute-statment` 或 `batch-execute-statement` 的凭证相匹配。例如，以下 AWS CLI 命令会获取 SQL 语句的结果。
```
aws redshift-data get-statement-result
--id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
```
要列出语句，必须提供 `cluster-identifier` 或 `workgroup-name` 参数，以确保 IAM Identity Center 用户只能访问分配给他们的 Amazon Redshift IAM Identity Center 应用程序。例如，以下 AWS CLI 命令会列出特定集群的语句。
```
aws redshift-data list-statements
--cluster-identifier mycluster
```
您还可以调用数据 API 操作，这些操作使用可信身份传播访问集群或工作组中的数据库对象。这包括 `list-databases`、`list-schemas`、`list-tables` 和 `describe-table` 操作。
可以在 AWS CloudTrail 中跟踪由 IAM Identity Center 用户发出的 API 调用。CloudTrail 事件的 `onBehalfOf` 部分显示了 IAM Identity Center 用户 ID 和身份存储 ARN。以下示例显示了 CloudTrail 事件的一个片段，其中显示了 `onBehalfOf` 部分，IAM Identity Center ID 为 `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111`，身份存储 ARN 为 `arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2`。
```
{
"eventVersion":"1.10",
"userIdentity":{
"type":"AssumedRole",
...
},
"onBehalfOf":{
"userId":"a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"identityStoreArn":"arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2"
}
},
"eventTime":"2025-01-13T04:46:27Z",
"eventSource":"redshift-data.amazonaws.com",
"eventName":"ExecuteStatement",
"awsRegion":"us-east-1"
}
```
您可以运行以下 SQL 命令来检查由 IAM Identity Center 用户提交的查询。在此示例中，在 Identity Center 中注册的电子邮件为 `username@example.com`。
```
SELECT
h.query_id,
h.database_name,
h.status,
h.query_text,
u.usename,
h.start_time,
h.end_time
FROM
sys_query_history h
LEFT JOIN
pg_user u
ON
h.user_id = u.usesysid
where u.usename='awsidc:username@example.com'
ORDER BY
h.start_time DESC;
```
# 调用 Data API
您可以调用数据 API 或 AWS CLI 以在集群或无服务器工作组上运行 SQL 语句。运行 SQL 语句的主要操作是《Amazon Redshift Data API Reference》**中的 [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html) 和 [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html)。数据 API 支持 AWS 开发工具包所支持的编程语言。有关它们的更多信息，请参阅[用于在 AWS 上构建的工具](https://aws.amazon.com/tools/)。
要查看调用 Data API 的代码示例，请参阅 *GitHub* 中的 [Redshift 数据 API入门](https://github.com/aws-samples/getting-started-with-amazon-redshift-data-api#getting-started-with-redshift-data-api)。此存储库包含使用 AWS Lambda，从 Amazon EC2、AWS Glue Data Catalog 和 Amazon SageMaker Runtime 访问 Amazon Redshift 数据的示例。示例编程语言包括 Python、Go、Java 和 Javascript。
您可以使用 AWS CLI 调用 Data API。
以下示例使用 AWS CLI 调用数据 API。要运行示例，请编辑参数值以匹配您的环境。在许多示例中，会提供 `cluster-identifier` 以针对集群运行。在针对无服务器工作组运行时，需改为提供 `workgroup-name`。这些示例演示了一些数据 API 操作。有关更多信息，请参阅 *AWS CLI 命令参考*。
以下示例中的命令已被拆分和格式化以便于阅读。并非所有示例都显示了所有参数和响应。有关完整请求语法、请求参数、响应语法和响应元素的 API 定义，请参阅 [Amazon Redshift Data API Reference](https://docs.aws.amazon.com/redshift-data/latest/APIReference/)。
# 将 SQL 语句传递到 Amazon Redshift 数据仓库
本页中的示例讲述了将 SQL 语句传递到数据仓库的不同方法
## 运行 SQL 语句
要运行 SQL 语句，请使用 `aws redshift-data execute-statement` AWS CLI 命令。
以下 AWS CLI 命令针对集群运行一个 SQL 语句，并返回一个标识符来获取结果。此示例使用 AWS Secrets Manager 身份验证方法。
```
aws redshift-data execute-statement
--secret-arn 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:myuser-secret-hKgPWn"
}
```
以下 AWS CLI 命令针对集群运行一个 SQL 语句，并返回一个标识符来获取结果。此示例使用临时凭证身份验证方法。
```
aws redshift-data execute-statement
--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"
}
```
以下 AWS CLI 命令针对无服务器工作组运行一个 SQL 语句，并返回一个标识符来获取结果。此示例使用临时凭证身份验证方法。
```
aws redshift-data execute-statement
--database dev
--workgroup-name myworkgroup
--sql "select 1;"
```
以下为响应示例。
```
{
"CreatedAt": "2022-02-11T06:25:28.748000+00:00",
"Database": "dev",
"DbUser": "IAMR:RoleName",
"Id": "89dd91f5-2d43-43d3-8461-f33aa093c41e",
"WorkgroupName": "myworkgroup"
}
```
以下 AWS CLI 命令针对集群运行一个 SQL 语句，并返回一个标识符来获取结果。此示例使用 AWS Secrets Manager 身份验证方法和幂等性令牌。
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
--client-token b855dced-259b-444c-bc7b-d3e8e33f94g1
```
以下为响应示例。
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
## 运行带有参数的 SQL 语句
要运行 SQL 语句，请使用 `aws redshift-data execute-statement` AWS CLI 命令。
以下 AWS CLI 命令针对集群运行一个 SQL 语句，并返回一个标识符来获取结果。此示例使用 AWS Secrets Manager 身份验证方法。SQL 文本具有命名参数 `distance`。在这种情况下，在谓词中使用的距离是 `5`。在 SELECT 语句中，列名的命名参数只能在谓词中使用。SQL 语句的命名参数值在 `parameters` 选项中指定。
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "SELECT ratecode FROM demo_table WHERE trip_distance > :distance"
--parameters "[{\"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:myuser-secret-hKgPWn"
}
```
以下示例使用示例数据库中的 `EVENT` 表。有关更多信息，请参阅《Amazon Redshift 数据库开发人员指南》**中的 [EVENT 表](https://docs.aws.amazon.com/redshift/latest/dg/r_eventtable.html)。
如果您的数据库中没有 `EVENT` 表，则可以使用数据 API 创建一个，如下所示：
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--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 mycluster-test
--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` 列是转换为 SMALLINT 数据类型的类型。
+ 表示 DATE 数据类型的字符串将隐式转换为 TIMESTAMP 数据类型。
+ 注释可以在 SQL 文本中使用。
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--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 子句中的命名参数来检索 `eventid` 为 `1` 的行。
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--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` AWS CLI 命令。
以下 AWS CLI 命令针对集群运行三个 SQL 语句，并返回一个标识符来获取结果。此示例使用临时凭证身份验证方法。
```
aws redshift-data batch-execute-statement
--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` AWS CLI 命令。运行此命令的授权基于调用者的 IAM 权限。
以下 AWS CLI 命令列出了运行的 SQL 语句。
```
aws redshift-data list-statements
--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` AWS CLI 命令。运行此命令的授权基于调用者的 IAM 权限。
以下 AWS CLI 命令描述 SQL 语句。
```
aws redshift-data describe-statement
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
以下为响应示例。
```
{
"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` 或 `redshift-data get-statement-result-v2` AWS CLI 命令。来自 `get-statement-result` 的结果采用 JSON 格式。来自 `get-statement-result-v2` 的结果采用 CSV 格式。您可以提供响应 `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 语句的结果，该语句让 `ResultFormat` 默认为 `JSON`。要检索结果，请调用 `get-statement-result` 操作。
```
aws redshift-data get-statement-result
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
以下语句返回 `batch-execute-statement` 运行的第二个 SQL 语句的结果。
```
aws redshift-data get-statement-result
--id b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2
```
以下是调用 `get-statement-result` 的响应示例，其中在响应的 `Records` 键中以 JSON 格式返回 SQL 结果。
```
{
"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
}
```
以下示例显示了 `execute-statement` 运行的一条 SQL 语句，该语句以 JSON 格式返回结果。表 `testingtable` 有三个整数列（col1、col2、col3），还有三行的值分别为（1、2、3）、（4、5、6）和（7、8、9）。
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format JSON
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
以下是调用 `get-statement-result` 的响应示例，其中在响应的 `Records` 键中以 JSON 格式返回 SQL 结果。
```
aws redshift-data get-statement-result
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
[
{
"longValue": 1
},
{
"longValue": 2
},
{
"longValue": 3
}
],
[
{
"longValue": 4
},
{
"longValue": 5
},
{
"longValue": 6
}
],
[
{
"longValue": 7
},
{
"longValue": 8
},
{
"longValue": 9
}
]
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3
}
```
以下示例显示了 `execute-statement` 运行的一条 SQL 语句，该语句以 CSV 格式返回结果。表 `testingtable` 有三个整数列（col1、col2、col3），还有三行的值分别为（1、2、3）、（4、5、6）和（7、8、9）。
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format CSV
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
以下是调用 `get-statement-result-v2` 的响应示例，其中在响应的 `Records` 键中以 CSV 格式返回 SQL 结果。行由回车符和换行符（\$1r\$1n）分隔。`Records` 中返回的第一行是列标题。以 CSV 格式返回的结果以 1 MB 为单位返回，其中每个分块可以存储任意数量的行，最大为 1MB。
```
aws redshift-data get-statement-result-v2
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
{
"CSVRecords": "col1,col2,col3\r\n1,2,3\r\n4,5,6\r\n7,8,9\r\n"
}
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3,
"ResultFormat": "csv"
}
```
# 描述表
要获取描述表的元数据，请使用 `aws redshift-data describe-table` AWS CLI 命令。
以下 AWS CLI 命令针对集群运行一个 SQL 语句，并返回描述表的元数据。此示例使用 AWS Secrets Manager 身份验证方法。
```
aws redshift-data describe-table
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
--secret-arn 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"
}
]
}
```
以下 AWS CLI 命令针对集群运行一个 SQL 语句来描述表。此示例使用临时凭证身份验证方法。
```
aws redshift-data describe-table
--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` AWS CLI 命令。
以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库。此示例使用 AWS Secrets Manager 身份验证方法。
```
aws redshift-data list-databases
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
```
以下为响应示例。
```
{
"Databases": [
"dev"
]
}
```
以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库。此示例使用临时凭证身份验证方法。
```
aws redshift-data list-databases
--db-user myuser
--cluster-identifier mycluster-test
--database dev
```
以下为响应示例。
```
{
"Databases": [
"dev"
]
}
```
# 列出数据库中的架构
要列出数据库中的 schema，请使用 `aws redshift-data list-schemas` AWS CLI 命令。
以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库中的架构。此示例使用 AWS Secrets Manager 身份验证方法。
```
aws redshift-data list-schemas
--secret-arn 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"
]
}
```
以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库中的架构。此示例使用临时凭证身份验证方法。
```
aws redshift-data list-schemas
--db-user mysuser
--cluster-identifier mycluster-test
--database dev
```
以下为响应示例。
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
# 列出数据库中的表
要列出数据库中的表，请使用 `aws redshift-data list-tables` AWS CLI 命令。
以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库中的表。此示例使用 AWS Secrets Manager 身份验证方法。
```
aws redshift-data list-tables
--secret-arn 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"
}
}
```
以下 AWS CLI 命令针对集群运行一个 SQL 语句来列出数据库中的表。此示例使用临时凭证身份验证方法。
```
aws redshift-data list-tables
--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 问题。
**Topics**
+ [用于查询的包太大](#data-api-troubleshooting-packet-too-large)
+ [数据库响应超出大小限制](#data-api-troubleshooting-response-size-too-large)
## 用于查询的包太大
如果您看到一条错误，指示查询的数据包过大，则为行返回的结果集通常过大。数据库返回的结果集中的 Data API 大小限制为每行 64 KB。
要解决此问题，请确保结果集中的每一行都小于或等于 64 KB。
## 数据库响应超出大小限制
如果您看到一条错误，指示数据库响应超出了大小限制，则数据库返回的结果集的大小通常太大。数据库返回的结果集中的数据 API 限制为 500 MB。
要解决此问题，请确保对数据 API 的调用返回 500 MB 或更少的数据。如果需要返回 500 MB 以上的数据，则可以在查询中将多个语句调用与 `LIMIT` 子句结合使用。
# 使用 Amazon EventBridge 计划 Amazon Redshift 数据 API 操作
您可以创建规则来匹配选定的事件，并将它们路由到目标以采取操作。此外，您还可以使用规则对预定的计划采取操作。有关更多信息，请参阅 [Amazon EventBridge 用户指南](https://docs.aws.amazon.com/eventbridge/latest/userguide/)。
要使用 EventBridge 计划数据 API 操作，关联的 IAM 角色必须信任 CloudWatch Events (events.amazonaws.com) 的委托人。此角色应附加相当于托管式策略 `AmazonEventBridgeFullAccess` 的策略。它还应具有 `AmazonRedshiftDataFullAccess` 策略权限，这些权限由数据 API 管理。您可以在 IAM 控制台上创建具有这些权限的 IAM 角色。在 IAM 控制台上创建角色时，为 CloudWatch Events 选择 AWS 服务可信任实体。在 EventBridge 目标的 `RoleArn` JSON 值中指定 IAM 角色。有关创建 IAM 角色的更多信息，请参阅《IAM 用户指南》**中的[为 AWS 服务创建角色（控制台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console)。
您在 Amazon EventBridge 中创建的规则的 `name` 必须与 `RedshiftDataParameters` 中的 `StatementName` 相匹配。
以下示例显示了使用单个或多个 SQL 语句创建 EventBridge 规则的变体，并将 Amazon Redshift 集群或 Amazon Redshift Serverless 工作组作为数据仓库。
## 对集群执行包含单个 SQL 语句的调用
以下示例使用 AWS CLI 创建 EventBridge 规则，用于对 Amazon Redshift 集群运行 SQL 语句。
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
然后创建一个 EventBridge 目标，以按照规则中指定的计划运行。
```
aws events put-targets
--cli-input-json file://data.json
```
输入 data.json 文件如下。`Sql` JSON 键表示只有一个 SQL 语句。`Arn` JSON 值包含集群标识符。`RoleArn` JSON 值包含用于运行 SQL 的 IAM 角色，如前所述。
```
{
"Rule": "test-redshift-cluster-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-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## 使用单个 SQL 语句和工作组进行调用
以下示例使用 AWS CLI 创建 EventBridge 规则，用于对 Amazon Redshift Serverless 工作组运行一个 SQL 语句。
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
然后创建一个 EventBridge 目标，以按照规则中指定的计划运行。
```
aws events put-targets
--cli-input-json file://data.json
```
输入 data.json 文件如下。`Sql` JSON 键表示只有一个 SQL 语句。`Arn` JSON 值包含工作组名称。`RoleArn` JSON 值包含用于运行 SQL 的 IAM 角色，如前所述。
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sql": "select 1;",
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
## 对集群执行包含多个 SQL 语句的调用
以下示例使用 AWS CLI 创建 EventBridge 规则，用于对 Amazon Redshift 集群运行多个 SQL 语句。
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
然后创建一个 EventBridge 目标，以按照规则中指定的计划运行。
```
aws events put-targets
--cli-input-json file://data.json
```
输入 data.json 文件如下。`Sqls` JSON 键表示有多个 SQL 语句。`Arn` JSON 值包含集群标识符。`RoleArn` JSON 值包含用于运行 SQL 的 IAM 角色，如前所述。
```
{
"Rule": "test-redshift-cluster-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",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## 使用多个 SQL 语句和工作组进行调用
以下示例使用 AWS CLI 创建 EventBridge 规则，用于对 Amazon Redshift Serverless 工作组运行多个 SQL 语句。
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
然后创建一个 EventBridge 目标，以按照规则中指定的计划运行。
```
aws events put-targets
--cli-input-json file://data.json
```
输入 data.json 文件如下。`Sqls` JSON 键表示有多个 SQL 语句。`Arn` JSON 值包含工作组名称。`RoleArn` JSON 值包含用于运行 SQL 的 IAM 角色，如前所述。
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
# 监控数据 API
监控是保持数据 API 和您的其他 AWS 解决方案的可靠性、可用性和性能的重要方面。AWS 提供了以下一些监控工具来监控数据 API、在出现错误时进行报告并适时自动采取措施：
+ 您可以使用 Amazon EventBridge 自动执行您的 AWS 服务并自动响应系统事件，例如应用程序可用性问题或资源更改。AWS 服务中的事件将近乎实时地传输到 EventBridge。您可以编写简单的规则来指示您关注的事件，并指示要在事件匹配规则时执行的自动化操作。有关更多信息，请参阅 [Amazon EventBridge 用户指南](https://docs.aws.amazon.com/eventbridge/latest/userguide/)。
+ AWS CloudTrail 捕获由您的 AWS 账户或代表该账户发出的 API 调用和相关事件，并将日志文件传输到您指定的 Amazon S3 桶。您可以标识哪些用户和账户调用了 AWS、发出调用的源 IP 地址以及调用的发生时间。要了解有关 Amazon Redshift 如何与 AWS CloudTrail 集成的更多信息，请参阅[使用 Cloudtrail 进行日志记录](https://docs.aws.amazon.com/redshift/latest/mgmt/logging-with-cloudtrail.html)。有关 CloudTrail 的更多信息，请参阅《AWS CloudTrail 用户指南》[https://docs.aws.amazon.com/awscloudtrail/latest/userguide/](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)。
**Topics**
+ [在 Amazon EventBridge 中监控 Amazon Redshift 数据 API 的事件](data-api-monitoring-events.md)
# 在 Amazon EventBridge 中监控 Amazon Redshift 数据 API 的事件
您可以在 EventBridge 中监控数据 API，这将从您自己的应用程序、软件即服务 (SaaS) 应用程序和 AWS 服务传输实时数据流。EventBridge 将该数据路由到诸如 AWS Lambda 和 Amazon SNS 之类的目标。这些事件与 CloudWatch Events 中出现的事件相同，可提供近乎实时的系统事件流，这些系统事件描述 AWS 资源的变化。事件将发送到包含 Amazon Redshift 数据库的账户。例如，如果您担任另一个账户中的角色，则事件将发送到该账户。有关更多信息，请参阅《Amazon EventBridge 用户指南》**中的 [Amazon EventBridge 事件](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html)。
当 `ExecuteStatement` 或 `BatchExecuteStatement` API 操作将 `WithEvent` 选项设置为 `true` 时，将发送数据 API 事件。事件的 `state` 字段包含以下值之一：
+ 中止 – 用户停止了查询运行。
+ FAILED – 查询运行失败。
+ FINISHED – 查询已完成运行。
事件会确保送达。有关更多信息，请参阅《Amazon EventBridge 用户指南》**中的 [Events from AWS services](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html)。
## 数据 API 完成事件示例
以下示例在 `ExecuteStatement` API 操作完成时显示数据 API 的一个事件。在以下示例中，名为 `test.testtable` 的语句运行完成。
```
{
"version": "0",
"id": "18e7079c-dd4b-dd64-caf9-e2a31640dab0",
"detail-type": "Redshift Data Statement Status Change",
"source": "aws.redshift-data",
"account": "123456789012",
"time": "2020-10-01T21:14:26Z",
"region": "us-east-1",
"resources": [
"arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster-1"
],
"detail": {
"principal": "arn:aws:iam::123456789012:user/myuser",
"statementName": "test.testtable",
"statementId": "dd2e1ec9-2ee3-49a0-819f-905fa7d75a4a",
"redshiftQueryId": -1,
"state": "FINISHED",
"rows": 1,
"expireAt": 1601673265
}
}
```
# 结合使用 AWS KMS 与 Amazon Redshift Data API
在使用客户自主管理型密钥对 Amazon Redshift 集群或 Redshift Serverless 工作组进行加密时，Amazon Redshift Data API 会使用相同的客户自主管理型密钥来存储和加密您的查询与结果。
默认情况下，Data API 会加密您的数据以保护敏感信息，例如查询文本和查询结果。它使用 AWS 拥有的 AWS KMS 加密密钥来实施此保护措施。
静态数据的默认加密可降低保护敏感数据时的运营开销和复杂性。此方法有助于构建符合严格加密合规性和监管要求的安全应用程序。
## 使用 AWS KMS 中的授权
Data API 需要授权才能使用客户自主管理型密钥。
在对已使用客户自主管理型密钥加密的集群调用 `ExecuteStatement` 或 `BatchExecuteStatement` 时，Amazon Redshift 会通过向 AWS KMS 发送 [https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html) 请求来代表您创建授权。AWS KMS 通过授权向数据 API 授予对您账户中的 KMS 密钥的访问权限。
Data API 需要授权，才能将客户自主管理型密钥用于以下操作：
+ 向 AWS KMS 发送 [https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html) 请求，以使用客户自主管理型密钥对查询元数据进行加密。
+ 向 AWS KMS 发送 [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) 请求，以生成由客户自主管理型密钥加密的数据密钥。
+ 向 AWS KMS 发送 [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) 请求，以对已加密的数据密钥进行解密，从而使用这些密钥对您的数据进行加密。
您可以随时撤销对授权的访问权限，或者删除 Amazon Redshift 对客户自主管理型密钥的访问权限。如果您这样做，Data API 将不再能访问由客户自主管理型密钥加密的数据，这会影响依赖于该数据的操作。例如，如果您在撤销授权后尝试检索查询结果或跟踪查询状态，则 Data API 会返回 `AccessDeniedException`。
## 客户自主管理型密钥的密钥策略
密钥政策控制对客户托管密钥的访问。每个客户托管式密钥必须只有一个密钥策略，其中包含确定谁可以使用密钥以及如何使用密钥的声明。创建客户托管式密钥时，可以指定密钥策略。有关更多信息，请参阅《AWS Key Management Service 开发人员指南》**中的[客户托管密钥](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-mgn-key)。
要结合使用您的客户自主管理型密钥与 Data API，您必须先允许访问 Amazon Redshift。密钥策略中必须允许以下 API 操作：
+ `kms:CreateGrant`：向客户托管密钥添加授权。这些授权控制对指定 AWS KMS 密钥的访问权限，从而允许访问 Amazon Redshift 所需的授权操作。有关更多信息，请参阅[在 AWS KMS 中使用授权](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations)。
以下是示例密钥策略：
```
"Statement":[
{
"Sid":"Allow access to principals authorized to use Amazon Redshift",
"Effect":"Allow",
"Principal":{
"AWS":"*"
},
"Action":[
"kms:DescribeKey",
"kms:CreateGrant"
],
"Resource":"*",
"Condition":{
"StringEquals":{
"kms:ViaService":"redshift.amazonaws.com",
"kms:CallerAccount":"111122223333"
}
}
},
{
"Sid":"AllowKeyAdministratorsAccess",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleAdminRole"
},
"Action":"kms:*",
"Resource":"*"
},
{
"Sid":"AllowKeyUseForExampleRole",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleUserRole"
},
"Action":[
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource":"*"
}
]
```
## Data API 加密上下文
加密上下文是一组可选的键值对，包含有关数据的其他上下文信息。AWS KMS 会将加密上下文用作其他已经过验证的数据以支持经过身份验证的加密。在请求中包含加密上下文以加密数据时，AWS KMS 将加密上下文绑定到加密的数据。要解密数据，您必须在请求中包含相同的加密上下文。
Data API 在预调配集群的所有 AWS KMS 加密操作中使用相同的三个加密上下文键值对：
+ `aws:redshift:arn`：集群的 Amazon 资源名称（ARN）
+ `aws:redshift:createtime`：请求创建集群时的时间戳
+ `serviceName` – `RedshiftDataAPI`
```
"EncryptionContextSubset": {
"aws:redshift:arn": "arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster",
"aws:redshift:createtime": "20250815T0000Z",
"serviceName": "RedshiftDataAPI",
}
```
Data API 在无服务器工作组的所有 AWS KMS 加密操作中使用两个加密上下文键值对：
+ `aws:redshift-serverless:arn`：命名空间的 Amazon 资源名称（ARN）
+ `serviceName`：RedshiftDataAPI
```
"EncryptionContextSubset": {
"aws:redshift-serverless:arn": "arn:aws:redshift-serverless:us-east-1:123456789012:namespace:12345678-1234-1234-1234-123456789012",
"serviceName": "RedshiftDataAPI"
}
```
有关加密的更多信息，请参阅 [AWS KMS 的加密详细信息简介](https://docs.aws.amazon.com/kms/latest/cryptographic-details/intro.html)。有关 Amazon Redshift 和 AWS KMS 集成的更多信息，请参阅 [Amazon Redshift 使用 AWS KMS 的方式](https://docs.aws.amazon.com/kms/latest/developerguide/services-redshift.html)。