Amazon Redshift 自 2025 年 11 月 1 日起不再支援建立新的 Python UDF。如果您想要使用 Python UDF，請在該日期之前建立 UDF。現有 Python UDF 將繼續正常運作。如需詳細資訊，請參閱部落格文章。

使用 Amazon Redshift 資料 API

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

資料 API 不需要與資料庫持續連線。它反而會提供安全的 HTTP 端點，並與 AWS 開發套件整合。您可以使用端點來執行 SQL 陳述式，而不需管理連線。對資料 API 的呼叫是非同步的。資料 API 可已使用儲存在 AWS Secrets Manager 的憑證，或使用暫時的資料庫憑證。不管是哪一種授權方法，都不需要在 API 呼叫中傳遞密碼。如需 AWS Secrets Manager 的相關資訊，請參閱《AWS Secrets Manager 使用者指南》中的什麼是 AWS Secrets Manager？。您也可以使用 AWS IAM Identity Center 進行授權。

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

若要進一步了解資料 API，請參閱 AWS 巨量資料部落格中的開始使用 Amazon Redshift 資料 API。

使用 Amazon Redshift 資料 API

在使用 Amazon Redshift 資料 API 之前，請先檢閱下列步驟：

呼叫 Amazon Redshift 資料 API 時的考量

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

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

在呼叫 Amazon Redshift 資料 API 時映射 JDBC 資料類型

下表會將 Java Database Connectivity (JDBC) 資料類型對應至您在資料 API 呼叫中指定的資料類型。

字串值會傳遞至 Amazon Redshift 資料庫，並以隱含方式轉換為資料庫的資料類型。

在呼叫 Amazon Redshift 資料 API 時執行含有參數的 SQL 陳述式

您可以透過對 SQL 陳述式的各個部分使用參數來呼叫資料 API 操作，以控制提交給資料庫引擎的 SQL 文字。具名參數可讓您靈活地傳遞參數，而不必以硬式編碼的方式將其寫入 SQL 文字內。其可協助您重複使用 SQL 文字，並避免 SQL 隱碼攻擊問題。

下列範例顯示 execute-statement AWS 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 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 請求得到的一些常見回應，並提供重試建議。

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

在呼叫 Amazon Redshift 資料 API 時執行含有 session reuse 的 SQL 陳述式

當您發出 API 請求來執行 SQL 陳述式時，SQL 執行所在的工作階段通常會在 SQL 完成時終止。為了讓工作階段在指定的秒數內保持作用中，資料 API ExecuteStatement 和 BatchExecuteStatement 操作具有選用的 SessionKeepAliveSeconds 參數。SessionId 回應欄位包含工作階段的識別，此識別可在後續 ExecuteStatement 和 BatchExecuteStatement 操作中使用。在後續呼叫中，您可以指定另一個 SessionKeepAliveSeconds 來變更閒置逾時時間。如果 SessionKeepAliveSeconds 未變更，則會保留初始閒置逾時設定。使用 session reuse 時，請考量下列事項：

若要擷取呼叫 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": "<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>
}