使用資料 API 呼叫資料時的考量事項 API 使用意識模糊權杖執行SQL陳述式使用工作階段重複使用執行SQL陳述式

使用 Amazon Redshift Data API

Amazon Redshift Data 可API簡化對 Amazon Redshift 資料倉儲的存取，無需管理資料庫驅動程式、連線、網路組態、資料緩衝、憑證等。您可以使用的資料API操作來執行SQL陳述式 AWS SDK。如需資料API操作的詳細資訊，請參閱 Amazon Redshift 資料API參考。

資料API不需要持續連線至資料庫。相反地，它提供安全的HTTP端點並與整合 AWS SDKs。您可以使用端點來執行SQL陳述式，而不需要管理連線。對資料的呼叫API是非同步的。資料API使用存放在中的憑證 AWS Secrets Manager 或臨時資料庫憑證。您不需要使用任一授權方法在API通話中傳遞密碼。如需的詳細資訊 AWS Secrets Manager，請參閱使用者指南中的什麼是 AWS Secrets Manager？。 AWS Secrets Manager

透過資料 API，您可以使用 Web 服務型應用程式以程式設計方式存取 Amazon Redshift 資料，包括 AWS Lambda、Amazon SageMaker 筆記本和 AWS Cloud9。如需這些應用程式的詳細資訊，請參閱 AWS Lambda、Amazon SageMaker和 AWS Cloud9。

若要進一步了解資料 API，請參閱AWS 大數據部落格 中的 Amazon Redshift Data 入門API。

使用 Amazon Redshift 資料 API

使用 Amazon Redshift Data 之前API，請檢閱下列步驟：

判斷身為資料來電者的您是否API獲得授權。如需授權的相關資訊，請參閱授權存取 Amazon Redshift 資料 API。
決定您打算API使用 Secrets Manager 的身分驗證憑證或暫時憑證呼叫資料。如需詳細資訊，請參閱在呼叫 Amazon Redshift Data 時選擇資料庫身分驗證憑證 API。
如果您使用 Secrets Manager 來取得驗證憑證，請設定機密。如需詳細資訊，請參閱在中存放資料庫憑證 AWS Secrets Manager。
檢閱呼叫資料時的考量和限制API。如需詳細資訊，請參閱呼叫 Amazon Redshift Data 時的考量事項 API。
從 API AWS Command Line Interface （AWS CLI）、從您自己的程式碼或使用 Amazon Redshift 主控台中的查詢編輯器呼叫資料。如需從 AWS CLI進行呼叫的範例，請參閱呼叫資料 API。

呼叫 Amazon Redshift Data 時的考量事項 API

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

Amazon Redshift Data API可以存取 Amazon Redshift 佈建叢集和 Redshift Serverless 工作群組中的資料庫。如需 Redshift Data API 可用 AWS 區域位置的清單，請參閱中為 Redshift Data API 列出的端點Amazon Web Services 一般參考。
查詢的持續時間上限為 24 小時。
每個 Amazon Redshift 叢集的作用中查詢（STARTED 和 SUBMITTED查詢）數目上限為 500。
查詢結果大小上限為 100 MB （gzip 壓縮後）。如果呼叫傳回的回應資料超過 100 MB，系統就會結束呼叫。
查詢結果的保留時間上限為 24 小時。
查詢陳述式的大小上限為 100 KB。
資料API可用於查詢下列節點類型的單節點和多節點叢集：
- dc2.large
- dc2.8xlarge
- ra3.large
- ra3.xlplus
- ra3.4xlarge
- ra3.16xlarge
叢集必須位於以 Amazon VPC服務為基礎的虛擬私有雲端（VPC）中。
根據預設，與或 BatchExecuteStatementAPI操作執行器具有相同IAM角色ExecuteStatement或IAM許可的使用者，可以對具有 CancelStatement、DescribeStatement、 GetStatementResult和 ListStatementsAPI操作的相同陳述式執行動作。若要對來自其他使用者的相同SQL陳述式採取行動，使用者必須能夠擔任執行SQL陳述式的使用者IAM角色。如需擔任角色的相關資訊，請參閱授權存取 Amazon Redshift 資料 API。
BatchExecuteStatement API 操作Sqls參數中的SQL陳述式會以單一交易方式執行。其會依陣列順序循序執行。在陣列中的上一個SQL陳述式完成之前，後續陳述式不會開始。如果任何SQL陳述式失敗，則因為它們以一個交易方式執行，所以所有工作都會復原。
在 ExecuteStatement或 BatchExecuteStatementAPI操作中使用的用戶端權杖最長保留時間為 8 小時。
Redshift Data API中的每個都會在調節請求之前API，有每秒的交易配額。如需配額的相關資訊，請參閱 Amazon Redshift 資料的配額 API。如果請求速率超過配額，則會傳回ThrottlingExceptionHTTP狀態碼為 400 的。若要回應限流，請使用重試策略，如 AWS SDKs和工具參考指南 中的重試行為所述。在某些 AWS 中，此策略會自動實作用於限流錯誤SDKs。
注意
依預設 AWS Step Functions，不會在中啟用重試。如果您需要在 Step Functions 狀態機器API中呼叫 Redshift Data，請在 Redshift Data ClientToken API呼叫中包含意識不清參數。ClientToken 的值需要在重試之間持續存在。在請求的下列範例程式碼片段中ExecuteStatementAPI，表達式States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)會使用內部函數來擷取 UUID的部分$$.Execution.Id，這對於每次執行狀態機器而言都是唯一的。如需詳細資訊，請參閱 AWS Step Functions 開發人員指南中的內部函數。
```
{
  "Database": "dev",
  "Sql": "select 1;",
  "ClusterIdentifier": "MyCluster",
  "ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
}
```

在呼叫 Amazon Redshift Data 時選擇資料庫身分驗證憑證 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 Data 時的映射JDBC資料類型 API

下表將 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不支援通用唯一識別碼陣列（UUIDs）。

呼叫 Amazon Redshift Data 時，使用參數執行SQL陳述式 API

您可以使用 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"）的資料欄名稱，並報告錯誤 ERROR（：位於或接近 \"FROM\"\n 位置：12）。
- 您無法取代彙總函數中的資料欄名稱，例如 COUNT(column-name)、AVG(column-name) 或 SUM(column-name)。
- 您無法取代JOIN子句中的資料欄名稱。
SQL 執行時，資料會隱含地轉換為資料類型。如需資料類型轉換的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》中的資料類型。
您無法將值設定為 NULL。資料會將其API解譯為文字字串 NULL。下列範例會將 id 取代為常值字串 null。不是 SQLNULL值。
```
--parameters "[{\"name\": \"id\", \"value\": \"null\"}]"
```
您無法設定零長度的值。資料APISQL陳述式失敗。下列範例會嘗試使用id零長度值設定，並導致SQL陳述式失敗。
```
--parameters "[{\"name\": \"id\", \"value\": \"\"}]"
```
您無法在具有參數的 SQL陳述式中設定資料表名稱。資料API遵循 JDBC 的規則PreparedStatement。
describe-statement 操作的輸出會傳回SQL陳述式的查詢參數。
只有 execute-statement操作支援具有參數的SQL陳述式。

呼叫 Amazon Redshift Data 時，使用隱含權杖執行SQL陳述式 API

當您發出靜音API請求時，請求通常會在操作的非同步工作流程完成之前傳回結果。即使請求已傳回結果，操作還是可能會在完成前就逾時或發生其他伺服器問題。這可能會讓您難以判斷請求是否成功，而且可能導致系統多次重試以確保操作能成功完成。但是，如果原始請求和後續的重試有成功，則操作會完成多次。這表示您可能會更新比預期數量還多的資源。

不緊急性可確保API請求完成不超過一次。使用等冪請求時，如果原始請求成功完成，則任何後續的重試都會成功完成，而不必執行任何進一步的動作。資料APIExecuteStatement和BatchExecuteStatement操作具有選用ClientToken的無能參數。ClientToken 會在 8 小時後到期。

重要

如果您從呼叫 ExecuteStatement和 BatchExecuteStatement操作 AWS SDK，它會自動產生用戶端權杖，以便在重試時使用。在這種情況下，我們不建議將 client-token 參數與 ExecuteStatement 和 BatchExecuteStatement 操作搭配使用。檢視 CloudTrail 日誌以查看 ClientToken。如需 CloudTrail 日誌範例，請參閱 Amazon Redshift Data 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 伺服器端問題所造成，且通常是暫時性的。請使用適當的退避策略來重複請求。

回應

建議

說明

200 (OK)

請勿重試

原始請求已成功完成。任何後續的重試都會成功傳回。

400 系列的回應碼

請勿重試

請求有下列方面的問題：

其包含無效的參數或參數組合。
其使用您沒有許可的動作或資源。
其使用處於變更狀態過程的資源。

如果請求涉及處於變更狀態過程的資源，則重試請求有可能會成功。

500 系列的回應碼

重試

錯誤是由 AWS 伺服器端問題所造成，且通常是暫時性的。請使用適當的退避策略來重複請求。

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

呼叫 Amazon Redshift Data 時，使用工作階段重複使用執行SQL陳述式 API

當您提出執行SQL陳述式的API請求時，SQL執行的工作階段通常會在 SQL 完成時終止。若要在指定的秒數內保持工作階段作用中，資料APIExecuteStatement和BatchExecuteStatement操作具有選用SessionKeepAliveSeconds參數。SessionId 回應欄位包含工作階段的身分，可用於後續 ExecuteStatement和 BatchExecuteStatement操作。在後續通話中，您可以指定另一個 SessionKeepAliveSeconds來變更閒置逾時時間。如果SessionKeepAliveSeconds未變更，則初始閒置逾時設定會保留。使用工作階段重複使用時，請考慮下列事項：

的最大值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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

針對 Amazon Redshift 中的連線問題進行疑難排解

授權存取