Amazon Redshift 將不再支援從修補程式 198 開始建立新的 Python UDFs。現有 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 資料倉儲的過程，讓您不需管理資料庫驅動器、連線、網路組態、資料緩衝、憑證等。您可以使用資料 API 操作搭配 AWS SDK 來執行 SQL 陳述式。如需資料 API 操作的詳細資訊，請參閱 [Amazon Redshift 資料 API 參考](https://docs.aws.amazon.com/redshift-data/latest/APIReference/)。
資料 API 不需要與資料庫持續連線。而是提供安全的 HTTP 端點並與 AWS SDKs整合。您可以使用端點來執行 SQL 陳述式，而不需管理連線。對資料 API 的呼叫是非同步的。資料 API 可以使用存放在 中的登入資料 AWS Secrets Manager 或臨時資料庫登入資料。不管是哪一種授權方法，都不需要在 API 呼叫中傳遞密碼。如需 的詳細資訊 AWS Secrets Manager，請參閱[什麼是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) *AWS Secrets Manager 《 使用者指南*》中的 。您也可以使用 AWS IAM Identity Center 進行授權。
使用資料 API，您可以使用 Web 服務型應用程式以程式設計方式存取 Amazon Redshift 資料 AWS Lambda，包括 Amazon SageMaker AI 筆記本和 AWS Cloud9。如需這些應用程式的詳細資訊，請參閱 [AWS Lambda](https://aws.amazon.com/lambda/)、[Amazon SageMaker AI](https://aws.amazon.com/sagemaker/) 和 [AWS Cloud9](https://aws.amazon.com/cloud9/)。
若要進一步了解資料 API，請參閱 *AWS 巨量資料部落格*中的[開始使用 Amazon Redshift 資料 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進行呼叫的範例，請參閱[呼叫資料 API](data-api-calling.md)。
## 呼叫 Amazon Redshift 資料 API 時的考量
在呼叫資料 API 時，請考量下列事項：
+ Amazon Redshift 資料 API 可以存取 Amazon Redshift 所佈建的叢集和 Redshift Serverless 工作群組中的資料庫。如需 Redshift Data API 可用 AWS 區域 位置的清單，請參閱 中針對 [Redshift Data API](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html) 列出的端點*Amazon Web Services 一般參考*。
+ 查詢的持續時間上限為 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 服務為基礎的虛擬私有雲端 (VPC) 中。
+ 根據預設，若使用者的 IAM 角色與 `ExecuteStatement` 或 `BatchExecuteStatement` API 操作的執行者相同，則使用者可以使用 `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 資料 API 使用](data-api-kms.md)。
+ 在限流請求之前，Redshift Data API 中的每個 API 都有每秒交易配額。如需配額的相關資訊，請參閱 [Amazon Redshift Data API 的配額](amazon-redshift-limits.md#data-api-quotas-account)。如果請求的速率超過配額，則傳回附帶 HTTP 狀態碼：400 的 `ThrottlingException`。若要回應限流，請使用重試策略，如 *AWS SDK 和工具參考指南*中的[重試行為](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)中所述。針對某些 AWS SDK 中的限流錯誤，這個策略會自動實作。
**注意**
在 中 AWS Step Functions，預設不會啟用重試。如果您需要在 Step Functions 狀態機器中呼叫 Redshift Data API，請在 Redshift Data 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**
資料 API 可透過 AWS IAM Identity Center中註冊的單一登入使用者存取。如需有關設定 IAM Identity Center 的步驟資訊，請參閱 [使用資料 API 搭配可信身分傳播](data-api-trusted-identity-propagation.md)。
**AWS Secrets Manager**
使用此方法，提供存放在 AWS Secrets Manager 中具有 `username`和 `secret-arn`之秘密的 `password`。指定的機密包含用來連線至所指定 `database` 的憑證。當您連線至叢集時，您也會提供資料庫名稱，如果您提供叢集識別碼 (`dbClusterIdentifier`)，則其必須符合儲存在機密中的叢集識別碼。當您連線至無伺服器工作群組時，您也會提供資料庫名稱。如需詳細資訊，請參閱[在 中存放資料庫登入資料 AWS Secrets Manager](data-api-secrets.md)。
透過此方法，您也可以提供指定資料所在 AWS 區域 位置`region`的值。
**臨時憑證**
使用此方法時，請選擇下列其中一個選項：
+ 在連線至無伺服器工作群組時，請指定工作群組名稱和資料庫名稱。資料庫的使用者名稱會衍生自 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)。
透過此方法，您也可以提供指定資料所在 AWS 區域 位置`region`的值。
## 在呼叫 Amazon Redshift 資料 API 時映射 JDBC 資料類型
下表會將 Java Database Connectivity (JDBC) 資料類型對應至您在資料 API 呼叫中指定的資料類型。
****
| JDBC 資料類型 | 資料 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`或 `batch-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"`)，並且會回報錯誤 (錯誤：在 \\"FROM\\"\\n Position: 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` 和 `batch-execute-statement`操作都支援具有參數的 SQL 陳述式。使用 時`batch-execute-statement`，參數會與批次中的所有 SQL 陳述式共用。每個 SQL 陳述式都可以參考提供的參數子集，但每個參數必須至少由一個 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 (OK) | 請勿重試 | 原始請求已成功完成。任何後續的重試都會成功傳回。 |
| 400 系列的回應碼 | 請勿重試 | 請求有下列方面的問題：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/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 時執行含有 session reuse 的 SQL 陳述式
當您發出 API 請求來執行 SQL 陳述式時，SQL 執行所在的工作階段通常會在 SQL 完成時終止。為了讓工作階段在指定的秒數內保持作用中，資料 API `ExecuteStatement` 和 `BatchExecuteStatement` 操作具有選用的 `SessionKeepAliveSeconds` 參數。`SessionId` 回應欄位包含工作階段的識別，此識別可在後續 `ExecuteStatement` 和 `BatchExecuteStatement` 操作中使用。在後續呼叫中，您可以指定另一個 `SessionKeepAliveSeconds` 來變更閒置逾時時間。如果 `SessionKeepAliveSeconds` 未變更，則會保留初始閒置逾時設定。使用 session reuse 時，請考量下列事項：
+ `SessionKeepAliveSeconds` 的最大值為 24 小時。
+ 工作階段最長可持續 24 小時。24 小時過後，工作階段就會強制關閉，而進行中查詢也會終止。
+ 每個 Amazon Redshift 叢集或 Redshift Serverless 工作群組的工作階段數目上限為 500 個。
+ 您一次只能在一個工作階段中執行一個查詢。您需要等到查詢完成，才能在相同工作階段中執行下一個查詢。也就是說，您無法在提供的工作階段中平行執行查詢。
+ 資料 API 無法將特定工作階段的查詢排入佇列。
若要擷取呼叫 `ExecuteStatement` 和 `BatchExecuteStatement` 操作所使用的 `SessionId`，請呼叫 `DescribeStatement` 和 `ListStatements` 操作。
下列範例示範如何使用 `SessionKeepAliveSeconds` 和 `SessionId` 參數讓工作階段保持作用中並重複使用。首先，呼叫 `execute-statement` AWS CLI 命令，並將選用`session-keep-alive-seconds`參數設定為 `2`。
```
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": {{}}
}
```