使用 Amazon Redshift 資料 API

您可以使用內建的 Amazon Redshift 資料 API 存取 Amazon Redshift 資料庫。使用此 API，您可以使用以網路服務為基礎的應用程式 (包括 AWS Lambda Amazon SageMaker 筆記本和. AWS Cloud9如需這些應用程式的詳細資訊 AWS Lambda，請參閱 Amazon SageMaker 和 AWS Cloud9.

資料 API 不需要與資料庫持續連線。相反，它提供了一個安全的 HTTP 端點，並與 AWS SDK 的集成。您可以使用端點來執行 SQL 陳述式，而不需管理連線。對資料 API 的呼叫是非同步的。

資料 API 使用儲存在資料庫認證 AWS Secrets Manager 或臨時資料庫認證中的認證。不管是哪一種授權方法，都不需要在 API 呼叫中傳遞密碼。如需有關的詳細資訊 AWS Secrets Manager，請參閱什麼是 AWS Secrets Manager？ 在《AWS 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 來取得驗證憑證，請設定機密。如需詳細資訊，請參閱 將資料庫認證儲存於 AWS Secrets Manager。

4. 在呼叫資料 API 時，檢閱考量和限制。如需詳細資訊，請參閱 呼叫 Amazon Redshift 資料 API 時的考量。

5. 從 AWS Command Line Interface (AWS CLI)、您自己的程式碼或使用 Amazon Redshift 主控台中的查詢編輯器呼叫資料 API。如需從呼叫的範例 AWS CLI，請參閱呼叫資料 API。

呼叫 Amazon Redshift 資料 API 時的考量

在呼叫資料 API 時，請考量下列事項：

• Amazon Redshift 資料 API 可以存取 Amazon Redshift 所佈建的叢集和 Redshift Serverless 工作群組中的資料庫。如需可用 Redshift 資料 API 的 AWS 區域 清單，請參閱中針對 Redshift 資料 API 列出的端點。Amazon Web Services 一般參考

• 查詢的持續時間上限為 24 小時。

• 每個 Amazon Redshift 叢集的作用中查詢 (STARTED 和 SUBMITTED 查詢) 數目上限為 200 個。

• 查詢結果大小上限為 100 MB (在 gzip 壓縮之後)。如果呼叫傳回的回應資料超過 100 MB，系統就會結束呼叫。

• 查詢結果的保留時間上限為 24 小時。

• 查詢陳述式的大小上限為 100 KB。

• 資料 API 可用於查詢以下節點類型的單節點和多節點叢集：

  • dc2.large

  • dc2.8xlarge

  • ra3.xlplus

  • ra3.4xlarge

  • ra3.16xlarge

• 叢集必須位於以 Amazon VPC 服務為基礎的虛擬私有雲端 (VPC) 中。

• 根據預設，其 IAM 角色或 IAM 許可與 ExecuteStatement 或 BatchExecuteStatement API 操作的執行者相同的使用者，可以使用 CancelStatement、DescribeStatement、GetStatementResult 和 ListStatements API 操作來處理相同的陳述式。若要處理其他使用者的相同 SQL 陳述式，使用者必須能夠擔任執行了 SQL 陳述式之使用者的 IAM 角色。如需擔任角色的相關資訊，請參閱 授權 Amazon Redshift 資料 API 的存取。

• 在 BatchExecuteStatement API 操作的 Sqls 參數中，SQL 陳述式會以單一交易的形式來執行。其會依陣列順序循序執行。後續的 SQL 陳述式要等到陣列中的前一個陳述式完成後才會啟動。如果有任何 SQL 陳述式失敗，由於其以單一交易的形式執行，因此所有工作都會復原。

• ExecuteStatement 或 BatchExecuteStatement API 操作中所使用的用戶端字符保留時間上限為 8 小時。

• 在限流請求之前，Redshift Data API 中的每個 API 都有每秒交易配額。如需配額的相關資訊，請參閱 Amazon Redshift Data API 的配額。如果請求的速率超過配額，則傳回附帶 HTTP 狀態碼：400 的 ThrottlingException。若要回應限流，請使用重試策略，如 AWS SDK 和工具參考指南中的重試行為中所述。此策略會自動實作，以便在某些 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 開發人員指南中的內部函數。

  {
    "Database": "dev",
    "Sql": "select 1;",
    "ClusterIdentifier": "MyCluster",
    "ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
  }

在呼叫 Amazon Redshift 資料 API 時選擇資料庫身分驗證憑證

當您呼叫資料 API 時，您會對部分 API 操作使用下列其中一種身分驗證方法。每種方法都需要不同的參數組合。

AWS Secrets Manager

使用此方法，提供存儲在 AWS Secrets Manager 其中具有username和secret-arn的秘密password。指定的機密包含用來連線至所指定 database 的憑證。當您連線至叢集時，您也會提供資料庫名稱，如果您提供叢集識別碼 (dbClusterIdentifier)，則其必須符合儲存在機密中的叢集識別碼。當您連線至無伺服器工作群組時，您也會提供資料庫名稱。如需詳細資訊，請參閱 將資料庫認證儲存於 AWS Secrets Manager。

臨時憑證

使用此方法時，請選擇下列其中一個選項：

• 在連線至無伺服器工作群組時，請指定工作群組名稱和資料庫名稱。資料庫的使用者名稱會衍生自 IAM 身分。例如，arn:iam::123456789012:user:foo 的資料庫使用者名稱為 IAM:foo。此外，也需要用來呼叫 redshift-serverless:GetCredentials 操作的許可。

• 以 IAM 身分連線至叢集時，請指定叢集識別碼和資料庫名稱。資料庫的使用者名稱會衍生自 IAM 身分。例如，arn:iam::123456789012:user:foo 的資料庫使用者名稱為 IAM:foo。此外，也需要用來呼叫 redshift:GetClusterCredentialsWithIAM 操作的許可。

• 以資料庫使用者身分連線至叢集時，請指定叢集識別碼、資料庫名稱和資料庫使用者名稱。此外，也需要用來呼叫 redshift:GetClusterCredentials 操作的許可。如需有關在使用此方法進行連線時要如何加入資料庫群組的資訊，請參閱連線到叢集時加入資料庫群組。

使用這些方法，您也可以提供指定資料所 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 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 資料庫開發人員指南》中的資料類型。

• 您無法將值設定為 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 範例。

下面的execute-statement AWS CLI 命令說明了冪等的可選client-token參數。

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 
    --client-token b855dced-259b-444c-bc7b-d3e8e33f94g1                       

下表顯示您可能會從等冪 API 請求得到的一些常見回應，並提供重試建議。

回應	建議	說明
200 (OK)	請勿重試	原始請求已成功完成。任何後續的重試都會成功傳回。
400 系列的回應碼	請勿重試	請求有下列方面的問題： 其包含無效的參數或參數組合。 其使用您沒有許可的動作或資源。 其使用處於變更狀態過程的資源。 如果請求涉及處於變更狀態過程的資源，則重試請求有可能會成功。
500 系列的回應碼	重試	該錯誤是由 AWS 服務器端問題引起的，通常是短暫的。請使用適當的退避策略來重複請求。

如需有關 Amazon Redshift 回應碼的資訊，請參閱《Amazon Redshift API 參考》中的常見錯誤。