Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

使用 Amazon Redshift 数据 API

Amazon Redshift 数据 API 消除了管理数据库驱动程序、连接、网络配置、数据缓冲、凭证等的需求，从而简化了对 Amazon Redshift 数据仓库的访问。您可以通过 Amazon SDK，使用数据 API 操作来运行 SQL 语句。有关数据 API 操作的更多信息，请参阅 Amazon Redshift 数据 API 参考。

数据 API 不需要与数据库的持久连接。相反，它提供了安全 HTTP 终端节点以及与 Amazon 开发工具包的集成。您可以使用终端节点运行 SQL 语句，而无需管理连接。对数据 API 的调用是异步的。数据 API 使用存储在 Amazon Secrets Manager 中的凭证或临时数据库凭证。您无需使用任何一种授权方法在 API 调用中传递密码。有关 Amazon Secrets Manager 的更多信息，请参阅《Amazon Secrets Manager 用户指南》中的什么是 Amazon Secrets Manager？

使用数据 API，您可以通过基于 Web 服务的应用程序（包括 Amazon Lambda、Amazon SageMaker AI 笔记本和 Amazon Cloud9），以编程方式访问 Amazon Redshift 数据。有关这些应用程序的更多信息，请参阅 Amazon Lambda、Amazon SageMaker AI 和 Amazon Cloud9。

要了解有关数据 API 的更多信息，请参阅 Amazon 大数据博客中的 Get started with the Amazon Redshift Data API。

使用 Amazon Redshift 数据 API

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

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

调用数据 API 时，请注意以下事项：

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

使用这些方法，您还可以提供 region 值，该值指定您的数据所在的 Amazon Web Services 区域。

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

下表将 Java 数据库连接 (JDBC) 数据类型映射到您在数据 API 调用中指定的数据类型。

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

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

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

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

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

使用命名参数时，请注意以下事项：

在调用 Amazon Redshift 数据 API 时运行带有幂等性令牌的 SQL 语句

当您发出变更 API 请求时，该请求通常会在操作的异步工作流完成之前返回结果。即使请求已经返回结果，操作在完成之前也可能会超时或遇到其他服务器问题。这样就很难确定请求是否成功，并且会导致进行多次重试以确保操作成功完成。但是，如果原始请求和后续重试成功，则会多次完成操作。这意味着您可能会更新比预期更多的资源。

幂等性确保 API 请求完成不超过一次。对于幂等性请求，如果原始请求成功完成，则后续重试也会成功完成，而不会执行任何后续操作。数据 API ExecuteStatement 和 BatchExecuteStatement 操作具有可选的 ClientToken 幂等性参数。ClientToken 在 8 小时后过期。

以下 execute-statement Amazon CLI 命令说明了幂等性的可选 client-token 参数。

aws redshift-data execute-statement 
    --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 
    --client-token b855dced-259b-444c-bc7b-d3e8e33f94g1                       

下表显示了幂等性 API 请求可能获得的一些常见响应，并提供了重试建议。

有关 Amazon Redshift 响应代码的信息，请参阅《Amazon Redshift API 参考》中的常见错误。

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

当您发出 API 请求来运行 SQL 语句时，在其中运行 SQL 的会话通常在 SQL 完成后终止。为了在指定的秒数内使会话保持活动状态，数据 API ExecuteStatement 和 BatchExecuteStatement 操作具有可选的 SessionKeepAliveSeconds 参数。SessionId 响应字段包含会话的身份，随后可以在后续 ExecuteStatement 和 BatchExecuteStatement 操作中使用该身份。在后续调用中，可以指定另一个 SessionKeepAliveSeconds 来更改空闲超时时间。如果未更改 SessionKeepAliveSeconds，则会保留初始空闲超时设置。使用会话重用时，请考虑以下事项：

要检索调用 ExecuteStatement 和 BatchExecuteStatement 操作时所使用的 SessionId，请调用 DescribeStatement 和 ListStatements 操作。

以下示例演示如何使用 SessionKeepAliveSeconds 和 SessionId 参数来使会话保持活动状态并重用。首先，在可选 session-keep-alive-seconds 参数设置为 2 的情况下调用 execute-statement Amazon 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 Amazon 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": "<token>",
   "Records": [
        [
            {
                "longValue": 1
            }
        ]
    ],
   "TotalNumRows": <number>
}

以 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": "<token>",
    "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": <number>
}