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 叢集所託管的資料庫，您有兩個選項： + 連接至您的叢集，並使用查詢編輯器在 上執行 AWS 管理主控台 查詢。 如果在 Amazon Redshift 主控台中使用查詢編輯器，您即不必下載和設定 SQL 用戶端應用程式。 + 透過 SQL 用戶端工具連接到您的叢集，例如 SQL Workbench/J。 Amazon Redshift 可支援 SQL 用戶端工具透過 Java 資料庫連線 (JDBC) 和開放式資料庫連線 (ODBC) 進行連線。Amazon Redshift 不會提供或安裝任何 SQL 用戶端工具或程式庫，因此您必須在用戶端電腦或 Amazon EC2 執行個體上加以安裝才能使用。您可以使用支援 JDBC 或 ODBC 驅動程式的大多數 SQL 用戶端工具。 **注意** 當您撰寫預存程序時，我們建議您採用保護敏感值的最佳作法： 不要在預存程序邏輯中對任何敏感資訊進行硬式編碼。例如，請勿在預存程序主體的 CREATE USER 陳述式中指派使用者密碼。這會造成安全性風險，因為硬式編碼值可以記錄為目錄資料表中的結構描述資料。應改為透過參數將敏感值 (例如密碼) 當做引數傳遞給預存程序。 如需預存程序的相關資訊，請參閱 [CREATE PROCEDURE](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_PROCEDURE.html) 和[在 Amazon Redshift 中建立預存程序](https://docs.aws.amazon.com/redshift/latest/dg/stored-procedure-overview.html)。如需目錄資料表的相關資訊，請參閱[系統目錄資料表](https://docs.aws.amazon.com/redshift/latest/dg/c_intro_catalog_views.html)。 # 連線至 Amazon Redshift 您可以使用下列語法連線至資料庫。 ``` cluster-name.account-number.aws-region.redshift.amazonaws.com/database-name ``` 語法元素定義如下。 + `cluster-name` 您的叢集名稱。 + `account-number` 與指定 中的 AWS 帳戶號碼相關聯的唯一識別符 AWS 區域。由特定 AWS 區域 中特定帳戶建立的所有叢集會擁有相同的 `account-number`。 + `aws-region` AWS 區域 叢集所在的 程式碼。 + `database-name` 您的資料庫名稱。 例如，下列連線字串會在 us-east-1 中指定`my-cluster`叢集中的`my-db`資料庫 AWS 區域。 ``` my-cluster.123456789012.us-east-1.redshift.amazonaws.com/my-db ``` # 使用查詢編輯器 v2 查詢資料庫 查詢編輯器 v2 是另外一種網頁式 SQL 用戶端應用程式，可用來在 Amazon Redshift 資料倉儲上編寫和執行查詢。查詢編輯器 v2 主要用來編輯和執行查詢、將查詢結果視覺化，以及與團隊共用您的工作。透過查詢編輯器 v2，您可以建立資料庫、結構描述、資料表和使用者定義的函數 (UDF)。在樹狀檢視面板中，您可以針對每個資料庫檢視其結構描述。對於每個結構描述，您可以檢視其資料表、檢視、UDF 和預存程序。查詢編輯器 v2 會取代先前的查詢編輯器。 **注意** 查詢編輯器 v2 提供商業版本 AWS 區域。如需查詢編輯器 v2 可用 AWS 區域 位置的清單，請參閱《》中針對 [Redshift 查詢編輯器 v2](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html) 列出的端點*Amazon Web Services 一般參考*。 如需查詢編輯器 v2 的示範，請觀看下列影片。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/IwZNIroJUnc/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/IwZNIroJUnc) [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/4EIV4XTE9iI/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/4EIV4XTE9iI) [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/7y-f1wlyVhI/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/7y-f1wlyVhI) 查詢編輯器 v2 有一組豐富的功能可供您管理和執行 SQL 陳述式。以下各節中的主題可協助您開始使用其中的許多功能。請自行探索查詢編輯器 v2 以熟悉其功能。 # 設定您的 AWS 帳戶 您可以執行這組任務來設定查詢編輯器 v2 來查詢 Amazon Redshift 資料庫。透過適當的許可，您可以存取 AWS 帳戶 目前 所擁有的 Amazon Redshift 叢集或工作群組中的資料 AWS 區域。 管理員第一次為您的 設定查詢編輯器 v2 時 AWS 帳戶，會選擇用來加密查詢編輯器 v2 資源 AWS KMS key 的 。根據預設， AWS 擁有的金鑰會用來加密資源。另外，管理員也可以在組態頁面中選擇金鑰的 Amazon Resource Name (ARN)，以使用客戶自管金鑰。 設定帳戶之後，就無法變更 AWS KMS 加密設定。如需以查詢編輯器 v2 建立和使用客戶受管金鑰的相關資訊，請參閱[建立 AWS KMS 客戶受管金鑰以搭配查詢編輯器 v2 使用](#query-editor-v2-kms-key)。管理員也可以選擇性地選擇用於某些功能 (例如，從檔案載入資料) 的 S3 儲存貯體和路徑。如需詳細資訊，請參閱[從本機檔案設定和工作流程載入資料](query-editor-v2-loading-data-local.md)。 Amazon Redshift 查詢編輯器 v2 支援身分驗證、加密、隔離和合規功能，以確保靜態資料和傳輸中的資料安全無虞。如需資料安全和查詢編輯器 v2 的相關資訊，請參閱下列內容： + [靜態加密](security-server-side-encryption.md) + [傳輸中加密](security-encryption-in-transit.md) + [Amazon Redshift 中的組態與漏洞分析](security-vulnerability-analysis-and-management.md) AWS CloudTrail 會擷取由 發出或代表發出的 API 呼叫和相關事件， AWS 帳戶 並將日誌檔案交付至您指定的 Amazon S3 儲存貯體。您可以識別呼叫的使用者和帳戶 AWS、進行呼叫的來源 IP 地址，以及呼叫的時間。若要進一步了解查詢編輯器 v2 在 AWS CloudTrail上的執行方式，請參閱[使用 CloudTrail 進行記錄](logging-with-cloudtrail.md)。如需 CloudTrail 的相關資訊，請參閱《[AWS CloudTrail 使用者指南](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html)》。 查詢編輯器 v2 對其某些資源具有可調整的配額。如需詳細資訊，請參閱[Amazon Redshift 物件的配額](amazon-redshift-limits.md#amazon-redshift-limits-quota)。 ## 使用查詢編輯器 v2 所建立的資源 在查詢編輯器 v2 內，您可以建立儲存的查詢和圖表等資源。查詢編輯器 v2 中的所有資源都會與 IAM 角色或使用者相關聯。建議您將政策連接至 IAM 角色，並將該角色指派給使用者。 在查詢編輯器 v2 中，您可以為儲存的查詢和圖表新增及移除標籤。您可以在設定自訂 IAM 政策或搜尋資源時使用這些標籤。您也可以使用標籤編輯器來管理 AWS Resource Groups 標籤。 您可以使用 IAM 政策設定 IAM 角色，在 中與相同 AWS 帳戶 中的其他人共用查詢 AWS 區域。 ## 建立 AWS KMS 客戶受管金鑰以搭配查詢編輯器 v2 使用 **若要建立對稱加密的客戶受管金鑰**： 您可以使用 AWS KMS 主控台或 AWS KMS API 操作，建立對稱加密客戶受管金鑰來加密查詢編輯器 v2 資源。如需建立金鑰的指示，請參閱《 *AWS Key Management Service 開發人員指南*》中的[建立對稱加密 AWS KMS 金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk)。 **金鑰政策** 金鑰政策會控制客戶受管金鑰的存取權限。每個客戶受管金鑰都必須只有一個金鑰政策，其中包含決定誰可以使用金鑰及其使用方式的陳述式。在建立客戶受管金鑰時，可以指定金鑰政策。如需詳細資訊，請參閱《 *AWS Key Management Service 開發人員指南*》中的[管理對 AWS KMS 金鑰的存取](https://docs.aws.amazon.com/kms/latest/developerguide/control-access-overview.html#managing-access)。 若要將客戶受管金鑰與 Amazon Redshift 查詢編輯器 v2 搭配使用，就必須在金鑰政策中允許下列 API 操作： + `kms:GenerateDataKey` — 產生唯一一個用來加密資料的對稱資料金鑰。 + `kms:Decrypt` — 解密使用客戶受管金鑰所加密的資料。 + `kms:DescribeKey` — 提供客戶受管金鑰的詳細資訊，以便服務可以驗證金鑰。 以下是 AWS 帳戶 的範例 AWS KMS 政策`111122223333`。在第一部分中，`kms:ViaService` 會限制金鑰只能用於查詢編輯器 v2 服務 (在政策中名為 `sqlworkbench.region.amazonaws.com`)。 AWS 帳戶 使用 金鑰的 必須是 `111122223333`。在第二個區段中， 的 AWS 帳戶 根使用者和金鑰管理員`111122223333`可以存取金鑰。 當您建立 時 AWS 帳戶，您會從一個名為 AWS 帳戶 *theroot 使用者的*登入身分開始，該身分具有對所有 AWS 服務 和 資源的完整存取權。強烈建議不要使用根使用者來執行日常任務。有關需要根使用者憑證的任務，請參閱《IAM 使用者指南》**中的[需要根使用者憑證的任務](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks)。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "key-consolepolicy", "Statement": [ { "Sid": "Allow access to principals authorized to use Amazon Redshift Query Editor V2", "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": [ "kms:GenerateDataKey", "kms:Decrypt", "kms:DescribeKey" ], "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": "sqlworkbench.us-east-1.amazonaws.com", "kms:CallerAccount": "111122223333" } } }, { "Sid": "Allow access for key administrators", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:root" }, "Action": [ "kms:*" ], "Resource": "arn:aws:kms:us-east-1:111122223333:key/key_ID" } ] } ``` ------ 下列資源提供有關 AWS KMS 金鑰的詳細資訊： + 如需 AWS KMS 政策的詳細資訊，請參閱《 *AWS Key Management Service 開發人員指南*》中的[在政策中指定許可](https://docs.aws.amazon.com/kms/latest/developerguide/control-access-overview.html#overview-policy-elements)。 + 如需對 AWS KMS 政策進行故障診斷的資訊，請參閱《 *AWS Key Management Service 開發人員指南*》中的[對金鑰存取進行故障診斷](https://docs.aws.amazon.com/kms/latest/developerguide/policy-evaluation.html#example-no-iam)。 + 如需金鑰的相關資訊，請參閱《AWS Key Management Service 開發人員指南》**中的 [AWS KMS 金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys)。 ## 存取查詢編輯器 v2 若要存取查詢編輯器 v2，您需要獲得許可。管理員可以將下列其中一個 AWS 受管政策連接至角色，以授予許可。(建議您將政策連接至 IAM 角色，並將該角色指派給使用者。) 這些 AWS 受管政策是以不同的選項撰寫，這些選項可控制標記資源如何允許共用查詢。您可以使用 IAM 主控台 ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) 來連接 IAM 政策。 + **AmazonRedshiftQueryEditorV2FullAccess** – 授予 Amazon Redshift 查詢編輯器 v2 操作和資源的完整存取權。此政策也會授予其他必要服務的存取權。 + **AmazonRedshiftQueryEditorV2NoSharing** – 授予使用 Amazon Redshift 查詢編輯器 v2 的能力，而不共用資源。此政策也會授予其他必要服務的存取權。 + **AmazonRedshiftQueryEditorV2ReadSharing** – 授予使用 Amazon Redshift 查詢編輯器 v2 的能力，並可有限度地共用資源。獲得授予的主體可以讀取與其團隊共用的資源，但無法更新這些資源。此政策也會授予其他必要服務的存取權。 + **AmazonRedshiftQueryEditorV2ReadWriteSharing** – 授予使用 Amazon Redshift 查詢編輯器 v2 的能力，並可共用資源。獲得授予的主體可以讀取和更新與其團隊共用的資源。此政策也會授予其他必要服務的存取權。 您也可以根據所提供受控政策中允許和拒絕的許可來建立自己的政策。如果您使用 IAM 主控台政策編輯器建立自己的政策，請選擇 **SQL Workbench** 作為您在視覺化編輯器中為其建立政策的服務。查詢編輯器 v2 會在視覺化編輯器和 IAM 政策模擬器中使用服務名稱 AWS SQL Workbench。 若要讓主體 (已獲派 IAM 角色的使用者) 能夠連線到 Amazon Redshift 叢集，就需要其中一個查詢編輯器 v2 受管政策中的許可。他們還需要叢集的其中一個 `redshift:GetClusterCredentialsWithIAM`或 `redshift:GetClusterCredentials`許可。若要獲得此許可，具有系統管理許可的人員可以使用臨時憑證，將政策連接至用來連線到叢集的 IAM 角色。您可以將政策的範圍限定在特定叢集或更為普遍的範圍。如需使用臨時登入資料之許可的詳細資訊，請參閱[建立具有呼叫 GetClusterCredentialsWithIAM 或 GetClusterCredentials 許可的 IAM 角色或使用者 GetClusterCredentials](generating-iam-credentials-steps.md#generating-iam-credentials-role-permissions)。 若要讓主體 (一般是已獲派 IAM 角色的使用者) 能夠在**帳戶設定**頁面中為帳戶中的其他使用者開啟**匯出結果集**的功能，他們需要該角色連接的 `sqlworkbench:UpdateAccountExportSettings` 許可。此許可包含在 `AmazonRedshiftQueryEditorV2FullAccess` AWS 受管政策中。 隨著新功能新增至查詢編輯器 v2， AWS 受管政策會視需要更新。如果您根據所提供受管策略中允許和拒絕的許可建立自己的政策，請編輯您的政策，讓政策隨著受管政策的變更進行更新以保持在最新狀態。如需 Amazon Redshift 中受管政策的相關資訊，請參閱 [AWS Amazon Redshift 的 受管政策](redshift-iam-access-control-identity-based.md#redshift-policy-resources.managed-policies)。 若要提供存取權，請新增權限至您的使用者、群組或角色： + 中的使用者和群組 AWS IAM Identity Center： 建立權限合集。請按照《*AWS IAM Identity Center 使用者指南*》中的[建立權限合集](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html)說明進行操作。 + 透過身分提供者在 IAM 中管理的使用者： 建立聯合身分的角色。遵循《*IAM 使用者指南*》的[為第三方身分提供者 (聯合) 建立角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html)中的指示。 + IAM 使用者： + 建立您的使用者可擔任的角色。請按照《*IAM 使用者指南*》的[為 IAM 使用者建立角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html)中的指示。 + (不建議) 將政策直接附加至使用者，或將使用者新增至使用者群組。請遵循《*IAM 使用者指南*》的[新增許可到使用者 (主控台)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) 中的指示。 **注意** 如果 AWS IAM Identity Center 管理員移除整個帳戶中特定許可集的所有許可集關聯，則無法再存取原本與已移除許可集關聯的任何查詢編輯器資源。如果之後重新建立了相同的許可，系統會建立新的內部識別碼。由於內部識別碼已變更，因此使用者無法再存取其先前擁有之查詢編輯器資源的存取權。我們的建議是，在管理員刪除許可集之前，該許可集的使用者先將查詢編輯器資源 (例如筆記本和查詢) 匯出為備份。 ## 設定主體標籤以從查詢編輯器 v2 連接叢集或工作群組 若要使用聯合身分使用者選項連線到叢集或工作群組，請使用主體標籤設定 IAM 角色或使用者。或者，也可以設定身分提供者 (IdP) 以傳入 `RedshiftDbUser` 和 (選擇性) `RedshiftDbGroups`。如需使用 IAM 來管理標籤的相關資訊，請參閱《IAM 使用者指南》**中的[在 AWS Security Token Service中傳遞工作階段標籤](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html)。若要使用 設定存取 AWS Identity and Access Management，管理員可以使用 IAM 主控台 ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)：//) 新增標籤。 **將主體標籤新增至 IAM 角色** 1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。 1. 在導覽窗格中，選擇 **Roles (角色)**。 1. 選擇需要使用聯合身分使用者存取查詢編輯器 v2 的角色。 1. 選擇 **Tags** (標籤) 索引標籤。 1. 選擇**管理標籤**。 1. 選擇**新增標籤**，並以 `RedshiftDbUser` 形式輸入**索引鍵**，然後輸入聯合身分使用者名稱的**值**。 1. 選擇性地選擇**新增標籤**，並以 `RedshiftDbGroups` 形式輸入**索引鍵**，然後輸入要與使用者建立關聯之群組名稱的**值**。 1. 選擇**儲存變更**以檢視與所選擇的 IAM 角色相關聯的標籤清單。傳播變更的過程可能需要幾秒鐘的時間。 1. 若要使用聯合身分使用者，請在變更傳播完成後重新整理查詢編輯器 v2 的頁面。 **設定您的身分提供者 (IdP) 以傳遞主體標籤** 使用身分提供者 (IdP) 設定標籤的程序隨 IdP 而異。如需如何將使用者和群組資訊傳遞至 SAML 屬性的指示，請參閱您的 IdP 文件。正確設定時，下列屬性會出現在您的 SAML 回應中，供 AWS Security Token Service 用來填入 `RedshiftDbUser`和 的主體標籤`RedshiftDbGroups`。 ``` db-user-name db-groups ``` 選擇性的 *db\$1group* 必須是以冒號分隔的清單，例如 `group1:group2:group3`。 此外，您也可以設定 `TransitiveTagKeys` 屬性以在鏈結角色期間保留標籤。 ``` RedshiftDbUser RedshiftDbGroups ``` 如需設定查詢編輯器 v2 的相關資訊，請參閱[要使用查詢編輯器 v2 所需的許可](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor-v2)。 如需有關如何設定 Active Directory Federation Services (AD FS)的資訊，請參閱部落格文章：[將 Amazon Redshift 查詢編輯器 v2 的存取與 Active Directory Federation Services (AD FS) 聯合](https://aws.amazon.com/blogs//big-data/federate-access-to-amazon-redshift-query-editor-v2-with-active-directory-federation-services-ad-fs-part-3/)。 如需有關如何設定 Okta 的資訊，請參閱部落格文章：[將 Amazon Redshift 查詢編輯器 v2 的單一登入存取與 Okta 聯合](https://aws.amazon.com/blogs//big-data/federate-single-sign-on-access-to-amazon-redshift-query-editor-v2-with-okta/)。 **注意** 當您使用查詢編輯器 v2 的**聯合身分使用者**連線選項連線到叢集或工作群組時，身分提供者 (IdP) 可以為 `RedshiftDbUser` 和 `RedshiftDbGroups` 提供自訂主體標籤。目前， AWS IAM Identity Center Dimions 不支援將自訂主體標籤直接傳遞至查詢編輯器 v2。 # 開啟查詢編輯器 v2 您可以透過 Amazon Redshift，於 Amazon Redshift 主控台中使用查詢編輯器 v2 對資料倉儲叢集執行 SQL 查詢。查詢編輯器 v2 是一種 Web 型工具，提供易用的介面來執行臨機查詢、探索資料，以及執行資料分析任務。下列各節將引導您完成在主控台中開啟查詢編輯器 v2 並有效利用其功能的程序。 **開啟查詢編輯器 v2** 1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/redshiftv2/](https://console.aws.amazon.com/redshiftv2/)：// 開啟 Amazon Redshift 主控台。 1. 從導覽器選單中選擇**編輯器**，然後選擇**查詢編輯器 V2**。查詢編輯器 v2 便會在新的瀏覽器標籤中開啟。 查詢編輯器頁面會有一個導覽器選單可供您選擇檢視，如下所示： **編輯器 ![\[Horizontal lines representing redacted or censored text.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-align-left.png)** 您可以管理和查詢組織為資料表並包含在資料庫中的資料。資料庫可以包含儲存的資料，也可以包含儲存在其他地方 (例如 Amazon S3) 之資料的參考。您可以連線到包含在叢集或無伺服器工作群組內的資料庫。 在**編輯器**檢視中工作時，您可以使用下列控制項： + **叢集**或**工作群組**欄位會顯示您目前所連線項目的名稱。**資料庫**欄位會顯示叢集或工作群組內的資料庫。您在**資料庫**檢視中執行的動作預設會對您選取的資料庫採取行動。 + 叢集或工作群組、資料庫和結構描述的樹狀檢視階層式檢視。在結構描述下，您可以處理您的資料表、檢視、函數和預存程序。樹狀檢視中的每個物件都支援可針對物件執行相關動作 (例如**重新整理**或**捨棄**) 的內容選單。 + ![\[The create icon used in the AWS Console.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-add.png) **建立**動作可建立資料庫、結構描述、資料表和函數。 + ![\[The upload icon used in the AWS Console.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-upload.png) **載入資料**動作可將資料從 Amazon S3 或從本機檔案載入到資料庫。 + ![\[The floppy disk icon used in the AWS Console.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-floppy-disk.png) **儲存**圖示可儲存查詢。 + ![\[The shortcut icon used in the AWS Console.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-key-command.png) **捷徑**圖示可顯示編輯器的鍵盤快速鍵。 + ![\[The more actions icon used in the AWS Console.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-more.png) **更多**圖示可在編輯器中顯示更多動作。例如： + **與我的團隊共用**可與團隊共用查詢或筆記本。如需詳細資訊，請參閱[以團隊的形式協作和共用](query-editor-v2-team.md)。 + **捷徑**可顯示編輯器的鍵盤快速鍵。 + **標籤歷史記錄**可在編輯器中顯示標籤的歷史記錄。 + **重新整理自動完成**可在編寫 SQL 時重新整理所顯示的建議。 + ![\[The editor icon in the AWS Console where can enter and run queries.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/add-plus.png) **編輯器**區域，可供您輸入和執行查詢。 執行查詢後會出現**結果**標籤，內有查詢結果。你可以在此開啟**圖表**以將結果視覺化。您也可以**匯出**結果。 + ![\[The icon in the AWS Console where you can add sections to enter and run SQL or add Markdown.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/add-plus.png) **筆記本**區域，可供您新增區段以便輸入和執行 SQL 或新增 Markdown。 執行查詢後會出現**結果**標籤，內有查詢結果。您可以在此**匯出**結果。 **查詢 ![\[A folder icon used in the AWS Console used to query databases.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-folder-close.png)** 查詢包含用來管理和查詢資料庫中所含資料的 SQL 命令。當您使用查詢編輯器 v2 載入範例資料時，其也會為您建立並儲存範例查詢。 當您選擇已儲存的查詢時，您可以使用內容 (右鍵) 選單來將其開啟、重新命名和刪除。您可以選擇**查詢詳細資訊**來檢視已儲存查詢的屬性，例如**查詢 ARN**。您還可以檢視其版本歷史記錄、編輯連接至查詢的標籤，以及將其與您的團隊共用。 **筆記本 ![\[A book icon used in the AWS Console used as SQL notebook.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-manual.png)** SQL 筆記本包含 SQL 和 Markdown 儲存格。使用筆記本可在單一文件中組織、註釋和共用多個 SQL 命令。 當您選擇已儲存的筆記本時，您可以使用內容 (右鍵) 選單來將其開啟、重新命名、複製和刪除。您可以選擇**筆記本詳細資訊**來檢視已儲存筆記本的屬性，例如**筆記本 ARN**。您還可以檢視其版本歷史記錄、編輯連接至筆記本的標籤、匯出筆記本，以及將其與您的團隊共用。如需詳細資訊，請參閱[Amazon Redshift 中的筆記本Notebooks](query-editor-v2-notebooks.md)。 **圖表 ![\[Icon of a chart used in the AWS Console as visual representation of data.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-chart.png)** 圖表會以視覺化方式呈現資料。查詢編輯器 v2 提供了工具供您建立多種類型的圖表並將其儲存起來。 當您選擇已儲存的圖表時，您可以使用內容 (右鍵) 選單來將其開啟、重新命名和刪除。您可以選擇**圖表詳細資訊**來檢視已儲存圖表的屬性，例如**圖表 ARN**。您也可以編輯連接至圖表的標籤，並將其匯出。如需詳細資訊，請參閱[將查詢結果視覺化](query-editor-v2-charts.md)。 **歷史記錄 ![\[Icon of a clock used in the AWS Console for query history.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-clock.png)** 查詢歷史記錄會列出您使用 Amazon Redshift 查詢編輯器 v2 執行的查詢。這些查詢會以個別查詢的形式執行，或是作為 SQL 筆記本的一部分來執行。如需詳細資訊，請參閱[檢視查詢和標籤歷史記錄](query-editor-v2-history.md)。 **已排程的查詢 ![\[Icon of a calendar used in the AWS Console for scheduled queries.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-calendar.png)** 已排程的查詢是設定為在特定時間啟動的查詢。 所有查詢編輯器 v2 檢視都有下列圖示： + ![\[Icon of a quarter moon used in the AWS Console to switch between light and dark modes.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-moon.png) **視覺化模式**圖示可在淺色模式和深色模式之間進行切換。 + ![\[Icon of a gear used in the AWS Console to show settings.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-cog.png) **設定**圖示可顯示不同設定畫面的選單。 + ![\[Icon used in the AWS Console to show editor preferences.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-properties.png) **編輯器偏好設定**圖示可讓您在使用查詢編輯器 v2 時編輯您的偏好設定。您可以在此**編輯工作區設定**，以變更字型大小、標籤大小和其他顯示設定。您也可以開啟 (或關閉) **自動完成**，以在您輸入 SQL 時顯示建議。 + ![\[Icon used in the AWS Console to view connections used in the editor tab.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-connection.png) **連線**圖示可檢視編輯器標籤所使用的連線。 連線可用來擷取資料庫中的資料。連線會針對特定資料庫來建立。使用隔離連線時，在某個編輯器標籤中會變更資料庫的 SQL 命令 (例如建立暫存資料表) 結果，並無法在另一個編輯器標籤中看到。當您在查詢編輯器 v2 中開啟編輯器標籤時，預設會使用隔離連線。當您建立共用連線時 (也就是如果您關閉**隔離工作階段**切換開關的話)，相同資料庫的共用連線彼此能看到其他共用連線的結果。但是，使用資料庫共用連線的編輯器標籤並不會平行執行。使用相同連線的查詢必須等到連線為可用狀態時才能執行。某個資料庫的連線不能與另一個資料庫共用，因此無法在不同的資料庫連線中看見 SQL 結果。 帳戶中的任何使用者可以擁有的作用中連線數目會由查詢編輯器 v2 管理員控制。 + ![\[Icon used in the AWS Console used by administrators to change settings of user accounts.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-settings.png) **帳戶設定**圖示可讓管理員變更帳戶中所有使用者的某些設定。如需詳細資訊，請參閱[帳戶設定](#query-editor-v2-settings)。 ## 使用查詢編輯器 v2 時的考量 在使用查詢編輯器 v2 時，請考量下列事項： + 查詢的持續時間上限為 24 小時。 + 查詢結果大小上限為 100 MB。如果呼叫傳回超過 100 MB 的回應資料，則會傳回前 100 MB 並顯示警告。 + 您可以執行長度最多 300,000 個字元的查詢。 + 您可以儲存長度最多 30,000 個字元的查詢。 + 根據預設，查詢編輯器 v2 會自動遞交每個執行的個別 SQL 命令。在提供了 BEGIN 陳述式時，BEGIN-COMMIT 或 BEGIN-ROLLBACK 區塊內的陳述式會以單一交易的形式來執行。如需交易的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [BEGIN](https://docs.aws.amazon.com/redshift/latest/dg/r_BEGIN.html)。 + 在執行 SQL 陳述式時，查詢編輯器 v2 可顯示的警告數量上限為 `10` 個。例如，在執行預存程序時，不會顯示超過 10 個 RAISE 陳述式。 + 查詢編輯器 v2 不支援包含逗號 (,) 的 IAM `RoleSessionName`。您可能會看到類似以下的錯誤：Error Message : "'AROA123456789EXAMPLE:mytext,yourtext' is not a valid value for TagValue - it contains illegal characters"。當您定義包含逗號的 IAM `RoleSessionName`，然後使用查詢編輯器 v2 搭配該 IAM 角色時，就會發生此問題。 如需 IAM `RoleSessionName` 的詳細資訊，請參閱《IAM 使用者指南》**中的 [RoleSessionName SAML 屬性](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html#saml_role-session-attribute)。 ## 帳戶設定 具有正確 IAM 許可的使用者可以檢視和變更相同 AWS 帳戶中其他使用者的**帳戶設定**。此管理員可以檢視或設定下列項目： + 帳戶中每一使用者的最大並行資料庫連線數。這包括**隔離工作階段**的連線。當您變更此值時，其可能需要 10 分鐘才會生效。 + 允許帳戶中的使用者將 SQL 命令的整個結果集匯出至檔案。 + 載入並顯示包含一些相關聯之已儲存查詢的範例資料庫。 + 指定帳戶使用者用來從本機檔案載入資料的 Amazon S3 路徑。 + 檢視用來加密查詢編輯器 v2 資源的 KMS 金鑰 ARN。 # 連線至 Amazon Redshift 資料庫 若要連線至資料庫，請在樹狀檢視面板中選擇叢集或工作群組的名稱。若出現提示，請輸入連線參數。 在連線至叢集或工作群組及其資料庫時，通常會提供**資料庫**名稱。您也可以提供下列其中一種身分驗證方法所需的參數： **IAM Identity Center** 若使用此方法，您可以使用身分提供者 (IdP) 提供的單一登入憑證連線到 Amazon Redshift 資料倉儲。您的叢集或工作群組必須針對 Amazon Redshift 主控台中的 IAM Identity Center 來啟用。如需協助您設定 IAM Identity Center 連線，請參閱 [將 Redshift 與 AWS IAM Identity Center 連線，以獲得單一登入體驗](redshift-iam-access-control-idp-connect.md)。 **聯合身分使用者** 使用此方法時，IAM 角色或使用者的主體標籤必須提供連線詳細資訊。您可以在 AWS Identity and Access Management 或身分提供者 (IdP) 中設定這些標籤。查詢編輯器 v2 依賴以下標籤。 + `RedshiftDbUser` — 此標籤會定義查詢編輯器 v2 所使用的資料庫使用者。這是必要標籤。 + `RedshiftDbGroups` — 此標籤會定義在連線至查詢編輯器 v2 時所加入的資料庫群組。這是選擇性標籤，其值必須是以冒號分隔的清單，例如 `group1:group2:group3`。系統會忽略空白值，也就是說，會將 `group1::::group2` 解譯為 `group1:group2`。 這些標籤會轉送至 `redshift:GetClusterCredentials` API，以取得叢集的憑證。如需詳細資訊，請參閱[設定主體標籤以從查詢編輯器 v2 連接叢集或工作群組](query-editor-v2-getting-started.md#query-editor-v2-principal-tags-iam)。 **使用資料庫使用者名稱的臨時憑證** 只有在連線至叢集時才能使用此選項。使用此方法時，查詢編輯器 v2 會為資料庫提供**使用者名稱**。查詢編輯器 v2 會產生能以資料庫使用者名稱的身分連線到資料庫的臨時密碼。使用此方法來連線的使用者必須已被允許 `redshift:GetClusterCredentials` 的 IAM 許可。若要防止使用者使用此方法，請修改其 IAM 使用者或角色以拒絕此許可。 **使用 IAM 身分的臨時憑證** 只有在連線至叢集時才能使用此選項。使用此方法時，查詢編輯器 v2 會將使用者名稱對應到您的 IAM 身分，並產生能以 IAM 身分連線到資料庫的臨時密碼。使用此方法來連線的使用者必須已被允許 `redshift:GetClusterCredentialsWithIAM` 的 IAM 許可。若要防止使用者使用此方法，請修改其 IAM 使用者或角色以拒絕此許可。 **資料庫使用者名稱和密碼** 使用此方法時，也會為您要連線的資料庫提供**使用者名稱**和**密碼**。查詢編輯器 v2 會在 AWS Secrets Manager中代表您建立秘密。此秘密包含用來連線至資料庫的憑證。 **AWS Secrets Manager** 使用此方法而不是資料庫名稱時，請提供儲存在 Secrets Manager、包含資料庫和登入憑證的**祕密**。如需有關建立機密的資訊，請參閱 [建立資料庫連線憑證的機密](redshift-secrets-manager-integration-create.md)。 當您使用查詢編輯器 v2 選取叢集或工作群組時，視內容而定，您可以使用內容 (右鍵) 選單來建立、編輯和刪除連線。您可以透過選擇**連線詳細資訊**，檢視連線的**連線 ARN** 等屬性。您也可以編輯連接至連線的標籤。 # 瀏覽 Amazon Redshift 資料庫 在資料庫內，您可於樹狀檢視面板中管理結構描述、資料表、檢視、函數和預存程序。檢視中的每個物件在內容 (右鍵) 選單中都有與其相關聯的動作。 階層式樹狀檢視面板會顯示資料庫物件。若要重新整理樹狀檢視面板，以顯示上次顯示樹狀檢視之後可能已建立的資料庫物件，請選擇 ![\[Circular arrow icon representing a refresh or reload action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-refresh.png) 圖示。開啟物件的內容 (右鍵) 選單即可查看您能夠執行的動作。 ![\[Tree-view icons\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/sqlworkbench-tree-view.png) 在選擇資料表後，您可以執行下列操作： + 若要使用會查詢資料表中所有資料欄的 SELECT 陳述式在編輯器中開始查詢，請使用**選取資料表**。 + 若要查看屬性或資料表，請使用**顯示資料表定義**。使用此選項可查看資料欄名稱、資料欄類型、編碼、分佈索引鍵、排序索引鍵，以及資料欄是否可以包含 Null 值。如需資料表屬性的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [CREATE TABLE](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_TABLE_NEW.html)。 + 若要刪除資料表，請使用**刪除**。您可以使用**截斷資料表**刪除資料表中的所有資料列，或使用**捨棄資料表**從資料庫中移除資料表。如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [TRUNCATE](https://docs.aws.amazon.com/redshift/latest/dg/r_TRUNCATE.html) 和 [DROP TABLE](https://docs.aws.amazon.com/redshift/latest/dg/r_DROP_TABLE.html)。 選擇要**重新整理**的結構描述或**捨棄結構描述**。 選擇要**顯示檢視定義**的檢視或**捨棄檢視**。 選擇要**顯示函數定義**的函數或**捨棄函數**。 選擇要**顯示程序定義**的預存程序或**捨棄程序**。 # 建立資料庫物件 您可以建立資料庫物件，包括資料庫、結構描述、資料表和使用者定義函數 (UDF)。您必須連線至叢集或工作群組和資料庫，才能建立資料庫物件。 ## 建立資料庫 您可以使用查詢編輯器 v2 在叢集或工作群組中建立資料庫。 **若要建立資料庫** 如需有關資料庫的資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [CREATE DATABASE](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_DATABASE.html)。 1. 選擇![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-add.png)**建立**，然後選擇**資料庫**。 1. 輸入**資料庫名稱**。 1. (選擇性) 選取**使用者和群組**，然後選擇**資料庫使用者**。 1. (選擇性) 您可以從資料共用或 AWS Glue Data Catalog建立資料庫。如需詳細資訊 AWS Glue，請參閱《 *AWS Glue 開發人員指南*》中的[什麼是 AWS Glue？](https://docs.aws.amazon.com/glue/latest/dg/what-is-glue.html)。 + (選擇性) 選取**使用資料共用建立**，然後選擇**選取資料共用**。此清單包含可用來在目前的叢集或工作群組中建立取用者資料共用的生產者資料共用。 + （選用） 選取**使用 建立 AWS Glue Data Catalog**，然後選擇**選擇 AWS Glue 資料庫**。在**資料目錄結構描述**中，輸入在參考由三個部分組成的名稱 (database.schema.table) 中的資料時，會用於結構描述的名稱。 1. 選擇**建立資料庫**。 樹狀檢視面板中隨即會顯示新的資料庫。 當您選擇選擇性步驟來查詢從資料共用建立的資料庫時，請連線到叢集或工作群組中的 Amazon Redshift 資料庫 (例如，預設資料庫 `dev`)，並使用由三個部分組成的標記法 (datase.schema.table) (其會參考您選取**使用資料共用建立**時所建立的資料庫名稱)。資料共用資料庫會列在查詢編輯器 v2 的編輯器標籤中，但未啟用直接連線功能。 當您選擇選用步驟來查詢從 建立的資料庫 AWS Glue Data Catalog時，請連線至叢集或工作群組中的 Amazon Redshift 資料庫 （例如，預設資料庫 `dev`)，並使用三部分表示法 (database.schema.table)，以參考您選取**使用 建立 AWS Glue Data Catalog**時建立的資料庫名稱、您在**資料目錄結構描述**中命名的結構描述，以及 中的資料表 AWS Glue Data Catalog。類似於： ``` SELECT * FROM glue-database.glue-schema.glue-table ``` **注意** 確認您已使用 連線方法連線至預設資料庫 **使用 IAM 身分的暫時登入資料**，且您的 IAM 登入資料已獲得 AWS Glue 資料庫的使用權限。 ``` GRANT USAGE ON DATABASE glue-database to "IAM:MyIAMUser" ``` AWS Glue 資料庫會列在查詢編輯器 v2 編輯器索引標籤中，但不會啟用直接連線。 如需查詢 的詳細資訊 AWS Glue Data Catalog，請參閱《*Amazon Redshift 資料庫開發人員指南*》中的以[消費者身分使用 Lake Formation 受管資料共用](https://docs.aws.amazon.com/redshift/latest/dg/lake-formation-getting-started-consumer.html)和[以生產者身分使用 Lake Formation 受管資料共用](https://docs.aws.amazon.com/redshift/latest/dg/lake-formation-getting-started-producer.html)。 **以資料共用取用者身分建立資料庫的範例** 下列範例描述的是所使用的一個特定案例，目的是使用查詢編輯器 v2 從資料共用建立資料庫。請檢閱此案例，以了解如何在環境中從資料共用建立資料庫。此案例使用兩個叢集，分別是 `cluster-base` (生產者叢集) 和 `cluster-view` (取用者叢集)。 1. 使用 Amazon Redshift 主控台在叢集 `cluster-base` 中為資料表 `category2` 建立資料共用。生產者資料共用會命名為 `datashare_base`。 如需有關建立資料共用的資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[在 Amazon Redshift 中跨叢集共用資料](https://docs.aws.amazon.com/redshift/latest/dg/datashare-overview.html)。 1. 使用 Amazon Redshift 主控台接受資料共用 `datashare_base` 作為叢集 `cluster-view` 中資料表 `category2` 的取用者。 1. 檢視查詢編輯器 v2 中的樹狀檢視面板，該面板會將 `cluster-base` 的階層顯示為： + 叢集：`cluster-base` + 資料庫：`dev` + 結構描述︰`public` + 資料表：`category2` 1. 選擇![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-add.png)**建立**，然後選擇**資料庫**。 1. 在**資料庫名稱**中輸入 `see_datashare_base`。 1. 選取**使用資料共用建立**，然後選擇**選取資料共用**。選擇 `datashare_base` 作為您要建立之資料庫的來源。 查詢編輯器 v2 中的樹狀檢視面板會將 `cluster-view` 的階層顯示為： + 叢集：`cluster-view` + 資料庫：`see_datashare_base` + 結構描述︰`public` + 資料表：`category2` 1. 當您查詢資料時，請連線到叢集 `cluster-view` 的預設資料庫 (名稱一般是 `dev`)，但在 SQL 中請參考資料共用資料庫 `see_datashare_base`。 **注意** 在查詢編輯器 v2 的編輯器檢視中，所選取的叢集為 `cluster-view`。所選取的資料庫為 `dev`。資料庫 `see_datashare_base` 會列出，但未啟用直接連線功能。您選擇 `dev` 資料庫，並在執行的 SQL 中參考 `see_datashare_base`。 ``` SELECT * FROM "see_datashare_base"."public"."category2"; ``` 查詢會從叢集 `cluster_base` 中的資料共用 `datashare_base` 擷取資料。 **從 建立資料庫的範例 AWS Glue Data Catalog** 下列範例說明使用 AWS Glue Data Catalog 查詢編輯器 v2 從 建立資料庫的特定案例。檢閱此案例，了解如何從 AWS Glue Data Catalog 環境中的 建立資料庫。這個案例會使用 `cluster-view` 這個叢集來包含您建立的資料庫。 1. 選擇![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-add.png)**建立**，然後選擇**資料庫**。 1. 在**資料庫名稱**中輸入 `data_catalog_database`。 1. 選取**使用 建立 AWS Glue Data Catalog**，然後選擇**選擇 AWS Glue 資料庫**。選擇 `glue_db` 作為您要建立之資料庫的來源。 選擇**資料目錄結構描述**，並輸入 `myschema` 作為要在由三個部分組成的標記法中使用的結構描述名稱。 查詢編輯器 v2 中的樹狀檢視面板會將 `cluster-view` 的階層顯示為： + 叢集：`cluster-view` + 資料庫：`data_catalog_database` + 結構描述︰`myschema` + 資料表：`category3` 1. 當您查詢資料時，請連線到叢集 `cluster-view` 的預設資料庫 (名稱一般是 `dev`)，但在 SQL 中請參考資料庫 `data_catalog_database`。 **注意** 在查詢編輯器 v2 的編輯器檢視中，所選取的叢集為 `cluster-view`。所選取的資料庫為 `dev`。資料庫 `data_catalog_database` 會列出，但未啟用直接連線功能。您選擇 `dev` 資料庫，並在執行的 SQL 中參考 `data_catalog_database`。 ``` SELECT * FROM "data_catalog_database"."myschema"."category3"; ``` 查詢會擷取由 AWS Glue Data Catalog分類的資料。 ## 建立結構描述 您可以使用查詢編輯器 v2 在叢集或工作群組中建立結構描述。 **建立結構描述** 如需有關結構描述的資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[結構描述](https://docs.aws.amazon.com/redshift/latest/dg/r_Schemas_and_tables.html)。 1. 選擇![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-add.png)**建立**，然後選擇**結構描述**。 1. 輸入**結構描述名稱**。 1. 選擇**本機**或**外部**作為**結構描述類型**。 如需本機結構描述的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [CREATE SCHEMA](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_SCHEMA.html)。如需外部結構描述的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [CREATE EXTERNAL SCHEMA](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_EXTERNAL_SCHEMA.html)。 1. 如果您選擇**外部**，則會有下列外部結構描述選項。 + **Glue Data Catalog** — 可在 Amazon Redshift 中建立會參考 AWS Glue中資料表的外部結構描述。除了選擇 AWS Glue 資料庫之外，請選擇與叢集相關聯的 IAM 角色，以及與 Data Catalog 相關聯的 IAM 角色。 + **PostgreSQL** — 可在 Amazon Redshift 中建立會參考 Amazon RDS for PostgreSQL 或 Amazon Aurora PostgreSQL 相容版本資料庫的外部結構描述。也請提供連線資訊給資料庫。如需聯合查詢的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[使用聯合查詢來查詢資料](https://docs.aws.amazon.com/redshift/latest/dg/federated-overview.html)。 + **MySQL** — 可在 Amazon Redshift 中建立會參考 Amazon RDS for MySQL 或 Amazon Aurora MySQL 相容版本資料庫的外部結構描述。也請提供連線資訊給資料庫。如需聯合查詢的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[使用聯合查詢來查詢資料](https://docs.aws.amazon.com/redshift/latest/dg/federated-overview.html)。 1. 選擇**建立結構描述**。 樹狀檢視面板中便會出現新的結構描述。 ## 建立資料表 您可以使用查詢編輯器 v2 在叢集或工作群組中建立資料表。 **若要建立資料表** 您可以根據指定的逗號分隔值 (CSV) 檔案來建立資料表，也可以定義資料表的每個資料欄。如需有關資料表的資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[設計資料表](https://docs.aws.amazon.com/redshift/latest/dg/c_designing-tables-best-practices.html)和 [CREATE TABLE](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_TABLE_NEW.html)。 請選擇**在編輯器中開啟查詢**，先檢視及編輯 CREATE TABLE 陳述式，再執行查詢以建立資料表。 1. 選擇![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-add.png)**建立**，然後選擇**資料表**。 1. 選擇結構描述。 1. 輸入資料表名稱。 1. 選擇 ![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/add-plus.png) **新增欄位**以新增資料欄。 1. 使用 CSV 檔案作為資料表定義的範本： 1. 選擇**從 CSV 載入**。 1. 瀏覽至檔案位置。 如果您使用 CSV 檔案，請確定檔案的第一個資料列包含資料欄標題。 1. 選擇檔案，然後選擇**開啟**。確認資料欄名稱和資料類型符合所需。 1. 針對每一個資料欄，請選擇該資料欄，然後選擇您想要的選項： + 為**編碼**選擇一個值。 + 選擇**預設值**。 + 如果您希望資料欄的值遞增，請開啟**自動遞增**。然後指定**自動遞增種子**和**自動遞增步長**的值。 + 如果資料欄一律應該包含值，請開啟**非 NULL**。 + 輸入資料欄的**大小**值。 + 如果您想讓資料欄成為主索引鍵，請開啟**主索引鍵**。 + 如果您想讓資料欄成為唯一索引鍵，請開啟**唯一索引鍵**。 1. (選擇性) 選擇**資料表詳細資訊**，然後選擇下列任何選項： + 分佈索引鍵資料欄和樣式。 + 排序索引鍵資料欄和排序類型。 + 開啟**備份**，以將資料表包含在快照中。 + 開啟**暫存資料表**以將資料表建立為暫存資料表。 1. 選擇**在編輯器中開啟查詢**以繼續指定用來定義資料表的選項，或選擇**建立資料表**以建立資料表。 ## 建立函數 您可以使用查詢編輯器 v2 在叢集或工作群組中建立函數。 **建立 函數** 1. 選擇![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-add.png)**建立**，然後選擇**函數**。 1. 在**類型**中，選擇 **SQL** 或 **Python**。 1. 選擇**結構描述**的值。 1. 輸入函數**名稱**的值。 1. 輸入函數**波動**的值。 1. 以輸入參數的順序，依資料類型選擇**參數**。 1. 在**傳回**中，選擇資料類型。 1. 輸入函數的 **SQL 程式**或 **Python 程式**的程式碼。 1. 選擇**建立**。 如需使用者定義函數 (UDF) 的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[建立使用者定義函數](https://docs.aws.amazon.com/redshift/latest/dg/user-defined-functions.html)。 # 檢視查詢和標籤歷史記錄 您可以使用查詢編輯器 v2 檢視查詢歷史記錄。只有使用查詢編輯器 v2 執行的查詢才會出現在查詢歷史記錄中。使用**編輯器**標籤或**筆記本**標籤所執行的查詢都會顯示出來。您可以依期間 (例如 `This week`) 篩選所顯示的清單，其中一週會定義為星期一至星期日。查詢清單一次會擷取 25 列符合篩選條件的查詢。選擇**載入更多**便可查看下一組。選擇查詢，然後從**動作**選單中選擇。可用的動作取決於所選擇的查詢是否已儲存。您可以選擇下列操作： + **檢視查詢詳細資訊** — 顯示查詢詳細資訊頁面，其中包含已執行之查詢的詳細資訊。 + **在新標籤中開啟查詢** — 開啟新的編輯器標籤，並使用所選擇的查詢讓其做好準備。如果仍然連線，則系統會自動選取叢集或工作群組和資料庫。若要執行查詢，請先確認是否已選擇正確的叢集或工作群組和資料庫。 + **開啟來源標籤** — 如果仍開啟，請導覽至查詢在執行時所屬的編輯器或筆記本標籤。查詢執行後，編輯器或筆記本的內容可能已有所變更。 + **開啟儲存的查詢** — 導覽至編輯器或筆記本標籤，並開啟查詢。 您也可以檢視在**編輯器**標籤中執行之查詢的歷史記錄，或檢視在**筆記本**標籤中執行之查詢的歷史記錄。若要查看標籤中的查詢歷史記錄，請選擇**標籤歷史記錄**。在標籤歷史記錄內，您可以執行下列操作： + **複製查詢** — 將查詢版本的 SQL 內容複製到剪貼簿。 + **在新標籤中開啟查詢** — 開啟新的編輯器標籤，並使用所選擇的查詢讓其做好準備。若要執行查詢，您必須選擇叢集或工作群組和資料庫。 + **檢視查詢詳細資訊** — 顯示查詢詳細資訊頁面，其中包含已執行之查詢的詳細資訊。 # 與 Amazon Q 生成式 SQL 互動 **注意** Amazon Q 生成式 SQL 支援僅適用於下列項目 AWS 區域： 美國東部 (維吉尼亞北部) 區域 (us-east-1) 美國東部 (俄亥俄) 區域 (us-east-2) 美國西部 (奧勒岡) 區域 (us-west-2) 亞太區域 (孟買) 區域 (ap-south-1) 亞太區域 (首爾) 區域 (ap-northeast-2) 亞太區域 (新加坡) 區域 (ap-southeast-1) 亞太區域 (雪梨) 區域 (ap-southeast-2) 亞太區域 (東京) 區域 (ap-northeast-1) 加拿大 (中部) 區域 (ca-central-1) 歐洲 (法蘭克福) 區域 (eu-central-1) 歐洲 (愛爾蘭) 區域 (eu-west-1) 歐洲 (倫敦) 區域 (eu-west-2) 歐洲 (巴黎) 區域 (eu-west-3) 南美洲 (聖保羅) 區域 (sa-east-1) 如需有關資料在哪裡處理的資訊，請參閱《Amazon Q Developer 使用者指南》**中的 [Amazon Q Developer 中的跨區域推論](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/cross-region-inference.html)。 您可以在 Amazon Redshift 查詢編輯器 v2 中與 Amazon Q 生成式 SQL 功能互動。這是一個編碼助理，可根據您的提示和資料庫模式產生 SQL 陳述式。當您在查詢編輯器 v2 中編寫筆記本時，可以使用此編碼助理。產生的 SQL 適用於筆記本所連線的資料庫。 與 Amazon Q 生成式 SQL 互動時，請提出特定問題，在有複雜的請求時進行迭代，並驗證答案的準確性。 以自然語言提供分析請求時，請盡可能具體地協助編碼助理了解您需要的內容。而不是詢問「尋找售出最多門票的熱門會場」，而是提供更多詳細資訊，例如「尋找 2008 年售出最多門票的前三個會場的名稱/ID」。在資料庫中使用一致且特定的物件名稱 (如果您知道的話)。例如資料庫中定義的結構描述、資料表和欄名稱，而不要以不同的方式參考相同的物件，這樣可能造成助理混淆。 將複雜的請求分解為多個簡單的陳述式，這些陳述式更容易讓助理解譯。反覆提出後續問題，以從助理那裡獲得更詳細的分析。例如，首先要問「哪個州的場地最多？」 然後根據回應，詢問「哪個是這個州最受歡迎的會場？」。 執行產生的 SQL 之前，請先檢閱產生的 SQL 以確保準確性 如果產生的 SQL 查詢有錯誤或不符合您的意圖，請提供指示給助理，說明如何更正，而不是改寫整個請求。例如，如果查詢缺少年份的述詞子句，請詢問「從 2008 年提供會場」。 將您執行生成式 SQL 所收到的錯誤文字作為提示提交至 Amazon Q 生成式 SQL。它會從這些錯誤中學習，以產生更佳的 SQL。 將您的結構描述新增至 SQL 搜尋路徑，以表示應使用結構描述。例如，當資料位於 tickit 結構描述而非公有結構描述中時，新增 tickit 結構描述。 ``` set search_path to '$user', tickit; ``` ## 與 Amazon Q 生成式 SQL 互動時的考量事項 在聊天面板中工作時，請考慮以下幾點。 + 您帳戶的查詢編輯器 v2 管理員必須已在**生成式 SQL 設定**頁面中開啟聊天功能。 + 若要使用 Amazon Q 生成式 SQL，除了查詢編輯器 v2 的 AWS 受管政策中指定的其他許可之外，還需要 IAM 政策`sqlworkbench:GetQSqlRecommendations`中的許可。如需 AWS 受管政策的詳細資訊，請參閱 [存取查詢編輯器 v2](query-editor-v2-getting-started.md#query-editor-v2-configure)。 + 您的問題必須以英文撰寫。 + 您的問題必須參考叢集或工作群組中已連接的資料庫。為了避免空白狀態錯誤，應該有至少一個資料表和資料庫中的一些資料。 + 您的問題必須參照儲存在連線資料庫中的資料。但無法參考外部結構描述。如需受支援之結構描述的詳細資訊，請參閱 *Amazon Redshift 資料庫開發人員指南*中的[建立結構描述](https://docs.aws.amazon.com/redshift/latest/dg/r_CREATE_EXTERNAL_SCHEMA.html)。 + 任何導致 SQL 變更連線資料庫的問題,都可能會產生警告。 + 生成式 AI 技術是一種新穎的技術，在反應中可能會出現錯誤，有時也稱為幻覺。在您的環境或工作負載中使用之前，請先測試並檢閱所有程式碼是否有錯誤和漏洞。 + 您可以透過帳戶中其他使用者執行來分享 SQL 查詢，以改善建議。您的帳戶管理員可以執行下列 SQL 命令，以允許存取帳戶的查詢歷程記錄。 ``` GRANT ROLE SYS:MONITOR to "IAMR:role-name"; GRANT ROLE SYS:MONITOR to "IAM:user-name"; GRANT ROLE SYS:MONITOR to "database-username"; ``` 如需有關 `SYS:MONITOR` 的詳細資訊，請參閱 *Amazon Redshift 資料庫開發人員指南*中的 [Amazon Redshift 系統定義角色](https://docs.aws.amazon.com/redshift/latest/dg/r_roles-default.html)。 + 您的資料是安全和私有的。您的資料不會跨帳戶共用。您的查詢、資料和資料庫結構描述不會用於訓練生成式 AI 基礎模型 (FM)。您的輸入會用作 FM 的上下文提示詞，僅做為對您的查詢的回答。 # 使用生成式 SQL 設定正確的許可權後，在查詢編輯器 v2 中使用筆記本時，您可以選擇圖示來開始對話。 **與 Amazon Q 生成式 SQL 聊天功能進行互動以產生 SQL** 1. 在查詢編輯器 v2 的**編輯器**索引標籤中，開啟筆記本。 1. 選擇 ![\[Generative SQL panel\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-amazon-q.png) 生成式 SQL 圖示，然後按照指令在聊天面板中詢問您對 Amazon Redshift 查詢編輯器 v2 生成式 SQL 的問題。 您在提示欄位中提供問題，Amazon Q 生成式 SQL 就會使用建議的 SQL 來回應。遇到的任何錯誤，都會在聊天面板中傳回給您。 1. 選擇**新增至筆記本**，新增 Markdown 儲存格與您的提示，以及含有建議 SQL 的 SQL 儲存格以加入至您的筆記本。 1. (選用) 藉由選擇 ![\[Helpful feedback\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-thumbs-up.png) 實用意見回饋圖示或 ![\[Not helpful feedback\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-thumbs-down.png) 不實用意見回饋圖示，提供有關所產生 SQL 的意見回饋。您可以將不實用的意見回饋分類為 `Incorrect tables/columns`、`Incorrect predicates/literals/group bys`、`Incorrect SQL structure` 或 `Other`。此外，您可以隨意見回饋提供一些自由格式的文字來敘述 SQL 的準確性。 1. (選用) 選擇**重新產生 SQL**，為相同的提示產生另一個回應。您可以選擇為目前的提示**重新產生 SQL** 一次。 1. (選用) 在生成式 SQL 聊天面板中，選擇 ![\[More\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-vmore.png) **更多**圖示，然後選擇**重新整理資料庫**以重新整理描述已連線之資料庫的中繼資料。此中繼資料包括資料庫中結構描述定義、資料表和欄的定義。 # 以管理員身分更新生成式 SQL 設定 具有正確 IAM 許可的使用者可以檢視和變更相同 AWS 帳戶中其他使用者的**生成式 SQL 設定**。除了查詢編輯器 v2 的 AWS 受管政策中指定的其他許可外，此管理員還必須在其 IAM 政策`sqlworkbench:UpdateAccountQSqlSettings`中擁有許可。如需受管政策的詳細資訊，請參閱 [要使用查詢編輯器 v2 所需的許可](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor-v2)。 **讓系統管理員為帳戶中的所有使用者開啟生成式 SQL 聊天** 1. 選擇 ![\[Settings\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-cog.png) **設定**圖示以顯示不同設定畫面的選單。 1. 然後選擇 ![\[Generative SQL settings\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-amazon-q.png) 生成式 SQL 設定圖示，以顯示 **Q 生成式 SQL 設定**頁面。 1. 選取 **Q 生成式 SQL**，為帳戶中的使用者開啟生成式 SQL 功能。 開啟 Amazon Q 生成式 SQL 之後，您可以檢視配置中剩餘的提示數目。查詢編輯器 v2 管理員可以讓帳戶中的使用者使用 Amazon Q Developer 專業方案。若要使用專業方案，請使用 IAM Identity Center 設定您的使用者，並為每個使用者訂閱 Amazon Q Developer 專業方案。如需設定 IAM Identity Center 搭配 Amazon Redshift 的相關資訊，請參閱 [將 Redshift 與 AWS IAM Identity Center 連線，以獲得單一登入體驗](redshift-iam-access-control-idp-connect.md)。如需有關 Amazon Q Developer 定價的資訊，請參閱 [Amazon Q Developer 定價](https://aws.amazon.com/q/developer/pricing/)。 使用 Amazon Q Developer Free 方案時， 所有使用者的提示總數每月限制 AWS 帳戶 為 1，000 個。使用 Amazon Q Developer 專業方案時，任何個別使用者每月可提交的提示總數限制為 1,000 個。您可以在**設定**頁面上檢視可用的提示數目。如需有關 Amazon Q Developer 定價的資訊，請參閱 [Amazon Q Developer 定價](https://aws.amazon.com/q/developer/pricing/)。 ## 自訂內容 查詢編輯器 v2 管理員可以指定*自訂內容*，以根據您的環境量身打造生成式 SQL。自訂內容提供領域知識和偏好設定，可精細控制 SQL 產生。自訂內容是在 JSON 檔案中定義，查詢編輯器 v2 管理員可將其上傳到 Amazon Q 生成式 SQL。 以下是用來將資料倉儲的生成式 SQL 個人化的 JSON 金鑰。 所有資料表參考都需要遵循三部分標記法 `database.schema.table`。 **Resources** 資源會指定套用自訂內容的資料資產範圍或部分。 **ResourceId** 指定資源的唯一識別碼。對於 Amazon Redshift 叢集，請指定 `cluster id`。對於 Redshift Serverless 工作群組，請指定 `workgroup name`。 **ResourceType** 有效值：`REDSHIFT_WAREHOUSE`。 **TablesToInclude** 指定 SQL 生成時參考的一組資料表。當您想要將 SQL 查詢的範圍限於一組定義的可用資料表子集時，此欄位會非常重要。此欄位可透過減少不必要的資料表參考，協助最佳化生成過程。您可以將此欄位與 `TablesToExclude` 配對，以更精確地控制查詢生成。 **TablesToExclude** 指定要從 SQL 生成中排除的一組資料表。當某些資料表不相關或不應在查詢生成過程中考慮時，可使用此項。 **TableAnnotations** 提供有關使用中資料表的中繼資料或補充資訊。這些註釋可以包括資料表說明、使用須知或任何其他屬性，以協助 Amazon Q 生成式 SQL 進一步了解資料表的內容或結構。這可讓資料表定義更清楚明確，對於提高 SQL 生成的準確性來說非常寶貴。 **ColumnsToInclude** 定義生成 SQL 查詢時要包含指定資料表中的哪些欄。此欄位有助於 Amazon Q 生成式 SQL 聚焦相關欄，並透過縮小資料擷取範圍來改善效能。此欄位可確保 Amazon Q 生成式 SQL 僅提取指定查詢內容所需的資料。 **ColumnsToExclude** 指定 SQL 生成時要省略不予考慮的欄。此項可在某些欄包含不相關或 Amazon Q 生成式 SQL 不應考慮的多餘資料時使用。透過管理包含和排除欄，您就可以精簡結果，並維持對所擷取資料的控制。 **ColumnAnnotations** 與 `TableAnnotations` 類似，此欄位提供個別欄特定的中繼資料或註釋。這些註釋可提供深入了解欄定義或特殊處理指示的資訊。此資訊有助於引導 SQL 生成過程，並確保在查詢中適當地使用欄。 **CuratedQueries** 一組預先定義的問題和答案範例，其中問題是以自然語言 (NLQ) 撰寫，而答案是對應的 SQL 查詢。這些範例可協助 Amazon Q 生成式 SQL 了解預期生成的查詢類型。這些範例可作為參考點來提高 Amazon Q 生成式 SQL 輸出的準確性和關聯性。 **CustomDocuments** 提供給 Amazon Q 生成式 SQL 的額外資訊或提示，例如定義、領域特定知識或解釋。例如，如果您的業務單位使用獨特的方法來計算值，例如「製造部門的總銷售額是價格 \$1 收入」，則可記載於此處。這些文件透過提供額外的內容，增強了 Amazon Q 生成式 SQL 解譯自然語言輸入的能力。 **AdditionalTables** 指定 SQL 生成時應考慮的任何其他資料表，但這些資料表不屬於儲存在資料倉儲中的資料。這可讓 Amazon Q 生成式 SQL 將外部資料來源整合到其 SQL 生成邏輯中，以擴大其處理複雜資料環境的容量。 **AppendToPrompt** 提供給 Amazon Q 生成式 SQL 的額外指示或指南，以引導 SQL 生成程序。這可包括說明如何建構查詢的特定指令、特定 SQL 建構模組的偏好設定，或任何其他提高 Amazon Q 生成式 SQL 輸出品質的高階指示。 下列範例自訂內容會顯示 JSON 檔案的格式，並定義下列項目： + 定義叢集 `mycluster` 的 Amazon Redshift 資料倉儲自訂內容。 + 定義要包含和排除的特定資料表和欄，以協助最佳化 SQL 生成程序。 + 定義要包含之資料表和欄的註釋。 + 定義 Amazon Q 生成式 SQL 要使用的範例策劃查詢。 + 定義生成 SQL 時要使用的自訂文件和防護機制。 + 定義生成 SQL 時要使用的額外資料表的 DDL。 ``` { "resources": [ { "ResourceId": "mycluster", "ResourceType": "REDSHIFT_WAREHOUSE", "TablesToInclude": [ "database.schema.table1", "database.schema.table2" ], "TablesToExclude": [ "database.schema.table3", "database.schema.table4" ], "ColumnsToInclude": { "database.schema.table1": [ "col1", "col2" ], "database.schema.table2": [ "col1", "col2" ] }, "ColumnsToExclude": { "database.schema.table5": [ "col1", "col2" ], "database.schema.table6": [ "col1", "col2" ] }, "TableAnnotations": { "database.schema.table1": "table1 refers to Q3 sales", "database.schema.table2": "table2 refers to Q4 sales" }, "ColumnAnnotations": { "database.schema.table1": { "col1": "col1 refers to Q3 sale total", "col2": "col2 refers to sale location" }, "database.schema.table2": { "col1": "col2 refers to Q4 sale total", "col2": "col2 refers to sale location" } }, "CuratedQueries": [ { "Question": "what is the sales data for Q3", "Answer": "SELECT * FROM table1" }, { "Question": "what is the sales data for Q4", "Answer": "SELECT * FROM table2" } ], "CustomDocuments": [ "in manufacturing division total sales is price * revenue", "in research division total sales is price * revenue" ], "AdditionalTables": { "database.schema.table8": "create table database.schema.table8(col1 int)", "database.schema.table9": "create table database.schema.table9(col1 int)" }, "AppendToPrompt": "Apply these guardrails: Queries should never return the secretId field of a user." } ] } ``` # 教學課程：搭配 TICKIT 資料使用 Amazon Q 生成式 SQL 功能 若要撰寫生成式 SQL 的有效提示詞，您必須了解您的資料庫結構描述和資料。TICKIT 資料包含七個資料表：兩個事實資料表和五個維度資料表。範例資料包含 2008 年發生之娛樂活動服務員銷售的相關記錄。如需 TICKIT 資料結構描述的詳細資訊，請參閱 *Amazon Redshift 資料庫開發人員指南*中的[範例資料庫](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html)。您可以透過 Amazon Redshift 主控台和查詢編輯器 v2 中的各種方法，將 TICKIT 資料載入資料庫。查詢編輯器 v2 提供一種將 TICKIT 資料載入資料庫 `sample_data_dev` 的方法。如需相關資訊，請參閱[將資料載入到資料庫](query-editor-v2-loading.md)。查詢編輯器 v2 也提供 TICKIT 資料的範例提示。下列案例說明與生成式 SQL 的對話，以產生有關 TICKIT 範例資料的 SQL。在這個案例中，TICKIT 範例資料已經建立於 Amazon Redshift 叢集的 `dev` 資料庫中。 **注意** 這個範例是有關對話的圖解。生成式 SQL 的回應可能不符合使用相同提示詞的結果。 **與 Amazon Q 生成式 SQL 的對話範例** 1. 在**編輯**器中，連接至包含 TICKIT 範例資料的叢集或工作群組。 1. 建立空白筆記本，然後選擇 ![\[Generative SQL\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-amazon-q.png) 生成式 SQL 圖示以開啟聊天面板。 1. 輸入以下提示以產生 SQL，以驗證 `VENUE` 資料表中的記錄數： ``` How many venues are there? ``` ``` SELECT COUNT(*) AS num_venues FROM tickit.venue ``` 選擇**新增至筆記本**，新增兩個儲存格至開啟的筆記本。一個 Markdown 儲存格「有多少個會場？」 和一個包含生成式 SQL。 在 SQL 儲存格中，選擇**執行**以接收結果： ``` count ------ 202 ``` 1. 若要請求其他版本的 SQL，請選擇**重新產生 SQL** 並接收下列答案： ``` SELECT venuestate, COUNT(*) AS num_venues FROM tickit.venue GROUP BY venuestate ``` 選擇**新增至筆記本**，多新增兩個儲存格至開啟的筆記本。一個 Markdown 儲存格「有多少個會場？」 和一個包含生成式 SQL。 在 SQL 儲存格中，選擇**執行**以按編號接收列出會場狀態的結果： ``` venuestate num_venues ---------------------- MA 4 OH 8 MI 5 ... ``` 1. 生成式 SQL 助理可以假設您請求的內容。儘管資料庫中沒有小工具，但您仍然可以詢問。在這種情況下，它會提供你一條訊息，表示無法產生 SQL。 ``` How many widgets are there? ``` ``` I was not able to generate any SQL ``` 1. 當您了解更多有關資料庫的資訊時，可以提出更具體的問題來產生 SQL。例如，您知道資料庫包含 2008 年中幾個月份的銷售資料。輸入下列提示詞以產生 SQL，尋找 2008 年 11 月的銷售數量： ``` How many sales were there in November 2008? ``` ``` SELECT COUNT(*) AS num_sales FROM tickit.sales s JOIN tickit.date d ON s.dateid = d.dateid WHERE d.month = 'November' AND d.year = 2008 ``` 選擇**新增至筆記本**，新增兩個儲存格至開啟的筆記本。一個 Markdown 儲存格「2008 年 11 月有多少銷量量？」 和一個包含生成式 SQL。 在 SQL 儲存格中，選擇**執行**以接收結果： ``` num_sales ----- 0 ``` 您了解到這不是你期望的結果。 1. 您注意到述詞 `date.month='November'` 預期 DATE 資料表中的月份會以月份名稱縮寫來表示。您可以將述詞變更為 `d.month='NOV'` 並重新執行 SQL。 ``` SELECT COUNT(*) FROM sales JOIN date ON sales.dateid = date.dateid WHERE date.month = 'NOV' AND date.year = 2008 ``` 在 SQL 儲存格中，選擇**執行**以取得新結果。 ``` count ----- 14261 ``` 1. 如果您問的問題會嘗試變更連線的資料庫，則會傳回警告訊息以及任何建議的 SQL。輸入下列提示詞以產生 SQL，將資料插入資料表： ``` Insert 1 into the venue table. ``` ``` INSERT , UPDATE OR delete data FROM the database AS that could potentially change the data.Please provide a query that ONLY selects data ``` ``` I was not able to generate the correct SQL code. I generated SQL, but you'll have to edit it to work with your database. ``` 如果您選擇**新增至筆記本**，將兩個儲存格新增至開啟的筆記本，並執行 SQL，然後 SQL 會失敗。 ``` ERROR: syntax error at or near "," Position: 132 [ErrorId: 1-6546764a-011df2691778846219ce6ec2] ``` 這個案例只說明了與 Amazon Q 生成式 SQL 互動的一些基本方法。您可以使用這種生成式 AI 技術進行更多實驗，幫助您開始編寫 SQL 來查詢資料庫。 # 將資料載入到資料庫 您可以使用查詢編輯器 v2 將資料載入到 Amazon Redshift 叢集或工作群組中的資料庫。本節說明如何載入範例資料、從 S3 載入資料，以及從本機檔案設定和工作流程載入資料。 ## 範例資料 查詢編輯器 v2 隨附範例資料和筆記本，可供您載入到範例資料庫和對應的結構描述。 若要載入範例資料，請選擇與您要載入的範例資料相關聯的 ![\[External\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/external.png) 圖示。然後，查詢編輯器 v2 便會將資料載入資料庫 `sample_data_dev` 的結構描述中，並建立已儲存筆記本的資料夾。 以下是可用的範例資料集。 **tickit** Amazon Redshift 文件中的多數範例都使用名為 `tickit` 的範本資料。這份資料包含七個資料表：兩個事實資料表和五個維度資料表。在載入這份資料時，系統便會以範例資料更新結構描述 `tickit`。如需 `tickit` 資料的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[範例資料庫](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html)。 **tpch** 這份資料會用於決策支援基準。在載入這份資料時，系統便會以範例資料更新結構描述 `tpch`。如需 `tpch` 資料的相關資訊，請參閱 [TPC-H](http://www.tpc.org/tpch/)。 **tpcds** 這份資料會用於決策支援基準。在載入這份資料時，系統便會以範例資料更新結構描述 `tpcds`。如需 `tpcds` 資料的相關資訊，請參閱 [TPC-DS](http://www.tpc.org/tpcds/)。 # 從 Amazon S3 載入資料 您可以將 Amazon S3 資料載入到現有資料表或新的資料表。 **將資料載入到現有資料表** 查詢編輯器 v2 會使用 COPY 命令從 Amazon S3 載入資料。在查詢編輯器 v2 載入資料精靈中產生和使用的 COPY 命令，支援許多可供 COPY 命令語法從 Amazon S3 進行複製的參數。如需 COPY 命令及其用於從 Amazon S3 載入資料之選項的詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[從 Amazon Simple Storage Service 進行 COPY](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-source-s3.html)。 1. 確認您要將資料載入到其中的資料庫內已建立資料表。 1. 確認您已連線至查詢編輯器 v2 的樹狀檢視面板中的目標資料庫後再繼續。您可以使用內容功能表 (按一下滑鼠右鍵) 對要在其中載入資料的叢集或工作群組建立連線。 選擇 ![\[Load\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-upload.png) **載入資料**。 1. 對於**資料來源**，選擇**從 S3 儲存貯體載入**。 1. 在 **S3 URI** 中選擇**瀏覽 S3**，以尋找要載入的資料所在的 Amazon S3 儲存貯體。 1. 如果指定的 Amazon S3 儲存貯體與目標資料表不 AWS 區域 相同，請為 AWS 區域 資料所在的 選擇 **S3 檔案位置**。 1. 如果 Amazon S3 檔案實際上是包含多個 Amazon S3 儲存貯體 URI 的資訊清單，請選擇**此檔案是資訊清單檔案**。 1. 為要上傳的檔案選擇**檔案格式**。支援的資料格式有 CSV、JSON、DELIMITER、FIXEDWIDTH、SHAPEFILE、AVRO、PARQUET 和 ORC。根據指定的檔案格式，您可以選擇相應的**檔案選項**。如果資料有加密，您也可以選取**資料已加密**，然後輸入用來加密資料之 KMS 金鑰的 Amazon Resource Name (ARN)。 如果您選擇 CSV 或 DELIMITER」，則也可以選擇**分隔符號字元**，以及是否要**忽略標頭資料列** (如果指定的資料列數目實際上是資料欄名稱而非要載入的資料)。 1. 選擇壓縮方法來壓縮檔案。預設為沒有壓縮。 1. (選擇性) **進階設定**支援各種**資料轉換參數**和**載入操作**。視需要為您的檔案輸入此資訊。 如需資料轉換和資料載入參數的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[資料轉換參數](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-conversion.html)和[資料載入操作](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-load.html)。 1. 選擇**下一步**。 1. 選擇**載入現有資料表**。 1. 確認或選擇在其中載入資料的**目標資料表**的位置，包括**叢集或工作群組**、**資料庫**、**結構描述**以及**資料表**名稱。 1. 選擇具有從 Amazon S3 載入資料所需許可的 **IAM 角色**。 1. (選擇性) 選擇資料欄名稱，在**資料欄映射**中輸入以依照輸入資料檔案的順序映射資料欄。 1. 選擇**載入資料**以開始載入資料。 當載入完成時，查詢編輯器會顯示所產生來載入資料的 COPY 命令。系統會顯示 COPY 的**結果**。如果成功，您便可立即使用 SQL 從所載入的資料表中選取資料。如果發生錯誤，請查詢系統檢視 STL\$1LOAD\$1ERRORS 以取得更多詳細資訊。如需有關 COPY 命令錯誤的資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [STL\$1LOAD\$1ERRORS](https://docs.aws.amazon.com/redshift/latest/dg/r_STL_LOAD_ERRORS.html)。 當您將資料載入到新的資料表時，查詢編輯器 v2 會先在資料庫中建立資料表，再於相同工作流程中以個別動作的形式載入資料。 **將資料載入到新的資料表** 查詢編輯器 v2 會使用 COPY 命令從 Amazon S3 載入資料。在查詢編輯器 v2 載入資料精靈中產生和使用的 COPY 命令，支援許多可供 COPY 命令語法從 Amazon S3 進行複製的參數。如需 COPY 命令及其用於從 Amazon S3 載入資料之選項的詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[從 Amazon Simple Storage Service 進行 COPY](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-source-s3.html)。 1. 確認您已連線至查詢編輯器 v2 的樹狀檢視面板中的目標資料庫後再繼續。您可以使用內容功能表 (按一下滑鼠右鍵) 對要在其中載入資料的叢集或工作群組建立連線。 選擇 ![\[Load\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-upload.png) **載入資料**。 1. 對於**資料來源**，選擇**從 S3 儲存貯體載入**。 1. 在 **S3 URI** 中選擇**瀏覽 S3**，以尋找要載入的資料所在的 Amazon S3 儲存貯體。 1. 如果指定的 Amazon S3 儲存貯體與目標資料表不 AWS 區域 相同，請為 AWS 區域 資料所在的 選擇 **S3 檔案位置**。 1. 如果 Amazon S3 檔案實際上是包含多個 Amazon S3 儲存貯體 URI 的資訊清單，請選擇**此檔案是資訊清單檔案**。 1. 為要上傳的檔案選擇**檔案格式**。支援的資料格式有 CSV、JSON、DELIMITER、FIXEDWIDTH、SHAPEFILE、AVRO、PARQUET 和 ORC。根據指定的檔案格式，您可以選擇相應的**檔案選項**。如果資料有加密，您也可以選取**資料已加密**，然後輸入用來加密資料之 KMS 金鑰的 Amazon Resource Name (ARN)。 如果您選擇 CSV 或 DELIMITER」，則也可以選擇**分隔符號字元**，以及是否要**忽略標頭資料列** (如果指定的資料列數目實際上是資料欄名稱而非要載入的資料)。 1. 選擇壓縮方法來壓縮檔案。預設為沒有壓縮。 1. (選擇性) **進階設定**支援各種**資料轉換參數**和**載入操作**。視需要為您的檔案輸入此資訊。 如需資料轉換和資料載入參數的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[資料轉換參數](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-conversion.html)和[資料載入操作](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-load.html)。 1. 選擇**下一步**。 1. 選擇**載入新資料表**。 資料表資料欄會從輸入資料推斷而來。您可以透過新增資料欄和資料表詳細資訊，修改資料表結構描述的定義。若要還原至查詢編輯器 v2 推斷的資料表結構描述，請選擇**還原為預設值**。 1. 確認或選擇在其中載入資料的**目標資料表**的位置，包括**叢集或工作群組**、**資料庫**和**結構描述**。輸入要建立的**資料表**名稱。 1. 選擇具有從 Amazon S3 載入資料所需許可的 **IAM 角色**。 1. 選擇**建立資料表**，使用所顯示的定義建立資料表。 此時會顯示資料表定義的檢閱摘要。資料表會建立到資料庫中。稍後若要刪除資料表，請執行 DROP TABLE SQL 命令。如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [DROP TABLE](https://docs.aws.amazon.com/redshift/latest/dg/r_DROP_TABLE)。 1. 選擇**載入資料**以開始載入資料。 當載入完成時，查詢編輯器會顯示所產生來載入資料的 COPY 命令。系統會顯示 COPY 的**結果**。如果成功，您便可立即使用 SQL 從所載入的資料表中選取資料。如果發生錯誤，請查詢系統檢視 STL\$1LOAD\$1ERRORS 以取得更多詳細資訊。如需有關 COPY 命令錯誤的資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [STL\$1LOAD\$1ERRORS](https://docs.aws.amazon.com/redshift/latest/dg/r_STL_LOAD_ERRORS.html)。 # 從本機檔案設定和工作流程載入資料 您可以將資料從本機檔案載入到現有資料表或新的資料表。 ## 從本機檔案載入資料的管理員設定 您的查詢編輯器 v2 管理員必須在**帳戶設定**視窗中指定常用的 Amazon S3 儲存貯體。您必須已為帳戶使用者設定適當的許可。 + 必要的 IAM 許可 — 從本機檔案載入資料的使用者必須具有 `s3:ListBucket`、`s3:GetBucketLocation`、`s3:putObject`、`s3:getObject` 和 `s3:deleteObject` 許可。您可以指定 *optional-prefix*，以限制只有具有此字首的物件能透過查詢編輯器 v2 使用此儲存貯體。如果您透過查詢編輯器 v2 以外的工具使用這個相同的 Amazon S3 儲存貯體，便可以使用此選項。如需儲存貯體和字首的相關資訊，請參閱《Amazon Simple Storage Service 使用者指南》**中的[管理使用者對特定資料夾的存取](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-folders)。為了確保系統不會允許跨使用者的資料存取，建議查詢編輯器 v2 管理員使用 Amazon S3 儲存貯體政策來根據 `aws:userid` 限制物件的存取。下列範例會向字首為 `aws:userid` 的 Amazon S3 物件允許具有唯讀/唯寫存取權限的 ** Amazon S3 許可。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetBucketLocation" ], "Resource": [ "arn:aws:s3:::" ] }, { "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::[/]/${aws:userid}/*" ] } ] } ``` ------ + 資料分隔 — 建議不要讓使用者擁有存取彼此資料的權限 (即使很短暫也不行)。從本機檔案載入的方式會使用查詢編輯器 v2 管理員所設定的暫存 Amazon S3 儲存貯體。請設定暫存儲存貯體的儲存貯體政策，以在使用者之間提供資料分隔機制。下列範例顯示的儲存貯體政策會在 ** 的使用者之間分隔資料。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ {"Sid": "userIdPolicy", "Effect": "Deny", "Principal": "*", "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"], "NotResource": [ "arn:aws:s3:::[/]/${aws:userid}/*" ] } ] } ``` ------ ## 從本機檔案載入資料 **將本機檔案的資料載入到現有資料表** 查詢編輯器 v2 管理員必須在**帳戶設定**視窗中指定通用的 Amazon S3 儲存貯體。查詢編輯器 v2 會自動將本機檔案上傳到您帳戶使用的通用 Amazon S3 儲存貯體，然後使用 COPY 命令載入資料。查詢編輯器 v2 的載入本機檔案視窗所產生和執行的 COPY 命令，支援許多可供 COPY 命令語法從 Amazon S3 進行複製的參數。如需 COPY 命令及其用於從 Amazon S3 載入資料之選項的詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[從 Amazon S3 進行 COPY](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-source-s3.html)。 1. 確認您要將資料載入到其中的資料庫內已建立資料表。 1. 確認您已連線至查詢編輯器 v2 的樹狀檢視面板中的目標資料庫。您可以使用內容功能表 (按一下滑鼠右鍵) 對要在其中載入資料的叢集或工作群組建立連線。 1. 選擇 ![\[Load\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-upload.png) **載入資料**。 1. 對於**資料來源**，選擇**從本機檔案載入**。 1. 選擇**瀏覽**以尋找包含要**載入檔案**之資料的檔案。依預設，系統會顯示副檔名為 `.csv`、`.avro`、`.parquet` 和 `.orc` 的檔案，但您也可以選擇其他檔案類型。 檔案大小上限為 100 MB。 1. 為要上傳的檔案選擇**檔案格式**。支援的資料格式有 CSV、JSON、DELIMITER、FIXEDWIDTH、SHAPEFILE、AVRO、PARQUET 和 ORC。根據指定的檔案格式，您可以選擇相應的**檔案選項**。如果資料有加密，您也可以選取**資料已加密**，然後輸入用來加密資料之 KMS 金鑰的 Amazon Resource Name (ARN)。 如果您選擇 CSV 或 DELIMITER」，則也可以選擇**分隔符號字元**，以及是否要**忽略標頭資料列** (如果指定的資料列數目實際上是資料欄名稱而非要載入的資料)。 1. (選擇性) **進階設定**支援各種**資料轉換參數**和**載入操作**。視需要為您的檔案輸入此資訊。 如需資料轉換和資料載入參數的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[資料轉換參數](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-conversion.html)和[資料載入操作](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-load.html)。 1. 選擇**下一步**。 1. 選擇**載入現有資料表**。 1. 確認或選擇在其中載入資料的**目標資料表**的位置，包括**叢集或工作群組**、**資料庫**、**結構描述**以及**資料表**名稱。 1. (選擇性) 您可以選擇資料欄名稱，在**資料欄映射**中輸入以依照輸入資料檔案的順序映射資料欄。 1. 選擇**載入資料**以開始載入資料。 載入完成時，無論載入是否成功，系統都會顯示訊息。如果成功，您便可立即使用 SQL 從所載入的資料表中選取資料。如果發生錯誤，請查詢系統檢視 STL\$1LOAD\$1ERRORS 以取得更多詳細資訊。如需有關 COPY 命令錯誤的資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [STL\$1LOAD\$1ERRORS](https://docs.aws.amazon.com/redshift/latest/dg/r_STL_LOAD_ERRORS.html)。 用來載入資料的 COPY 命令範本會出現在您的**查詢歷史記錄**中。此 COPY 命令範本會顯示一些已使用的參數，但其無法直接在編輯器索引標籤中執行。如需查詢歷史記錄的相關資訊，請參閱[檢視查詢和標籤歷史記錄](query-editor-v2-history.md)。 當您將資料載入到新的資料表時，查詢編輯器 v2 會先在資料庫中建立資料表，再於相同工作流程中以個別動作的形式載入資料。 **將本機檔案資料載入到新的資料表** 您的查詢編輯器 v2 管理員必須在**帳戶設定**視窗中指定常用的 Amazon S3 儲存貯體。本機檔案會自動上傳到您帳戶使用的通用 Amazon S3 儲存貯體，然後查詢編輯器 v2 會使用 COPY 命令載入資料。查詢編輯器 v2 的載入本機檔案視窗所產生和執行的 COPY 命令，支援許多可供 COPY 命令語法從 Amazon S3 進行複製的參數。如需 COPY 命令及其用於從 Amazon S3 載入資料之選項的詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[從 Amazon S3 進行 COPY](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-source-s3.html)。 1. 確認您已連線至查詢編輯器 v2 的樹狀檢視面板中的目標資料庫。您可以使用內容功能表 (按一下滑鼠右鍵) 對要在其中載入資料的叢集或工作群組建立連線。 1. 選擇 ![\[Load\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-upload.png) **載入資料**。 1. 對於**資料來源**，選擇**從本機檔案載入**。 1. 選擇**瀏覽**以尋找包含要**載入檔案**之資料的檔案。依預設，系統會顯示副檔名為 `.csv`、`.avro`、`.parquet` 和 `.orc` 的檔案，但您也可以選擇其他檔案類型。 檔案大小上限為 100 MB。 1. 為要上傳的檔案選擇**檔案格式**。支援的資料格式有 CSV、JSON、DELIMITER、FIXEDWIDTH、SHAPEFILE、AVRO、PARQUET 和 ORC。根據指定的檔案格式，您可以選擇相應的**檔案選項**。如果資料有加密，您也可以選取**資料已加密**，然後輸入用來加密資料之 KMS 金鑰的 Amazon Resource Name (ARN)。 如果您選擇 CSV 或 DELIMITER」，則也可以選擇**分隔符號字元**，以及是否要**忽略標頭資料列** (如果指定的資料列數目實際上是資料欄名稱而非要載入的資料)。 1. (選擇性) **進階設定**支援各種**資料轉換參數**和**載入操作**。視需要為您的檔案輸入此資訊。 如需資料轉換和資料載入參數的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[資料轉換參數](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-conversion.html)和[資料載入操作](https://docs.aws.amazon.com/redshift/latest/dg/copy-parameters-data-load.html)。 1. 選擇**下一步**。 1. 選擇**載入新資料表**。 1. 確認或選擇在其中載入資料的**目標資料表**的位置，包括**叢集或工作群組**、**資料庫**和**結構描述**。輸入要建立的**資料表**名稱。 1. 選擇**建立資料表**，使用所顯示的定義建立資料表。 此時會顯示資料表定義的檢閱摘要。資料表會建立到資料庫中。稍後若要刪除資料表，請執行 DROP TABLE SQL 命令。如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [DROP TABLE](https://docs.aws.amazon.com/redshift/latest/dg/r_DROP_TABLE)。 1. 選擇**載入資料**以開始載入資料。 載入完成時，會顯示訊息以指出載入是否成功。如果成功，您便可立即使用 SQL 從所載入的資料表中選取資料。如果發生錯誤，請查詢系統檢視 STL\$1LOAD\$1ERRORS 以取得更多詳細資訊。如需有關 COPY 命令錯誤的資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [STL\$1LOAD\$1ERRORS](https://docs.aws.amazon.com/redshift/latest/dg/r_STL_LOAD_ERRORS.html)。 用來載入資料的 COPY 命令範本會出現在您的**查詢歷史記錄**中。此 COPY 命令範本會顯示一些已使用的參數，但其無法直接在編輯器索引標籤中執行。如需查詢歷史記錄的相關資訊，請參閱[檢視查詢和標籤歷史記錄](query-editor-v2-history.md)。 # 使用 Amazon Redshift 編寫查詢 您可以在編輯器中輸入查詢，或從**查詢**清單中選取已儲存的查詢，然後選擇**執行**。 系統預設會設定**限制 100 個**以將結果限制為 100 個資料列。您可以關閉此選項，以傳回較大的結果集。如果您關閉這個選項，又想要避免結果集太大，則可以在 SQL 陳述式中包含 LIMIT 選項。如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [ORDER BY 子句](https://docs.aws.amazon.com/redshift/latest/dg/r_ORDER_BY_clause.html)。 若要在結果區域中顯示查詢計劃，請開啟**解釋**。開啟**解釋圖形**，讓結果也顯示以圖形表示的解釋計劃。 若要將查詢儲存至**查詢**資料夾，請選擇**儲存**。 如果查詢成功，則會出現成功訊息。如果查詢傳回資訊，結果會顯示在**結果**區段中。如果結果數目超過顯示區域，結果區域的頂端會出現數字。您可以選擇數字以顯示連續的結果頁面。 您可以為每個資料欄篩選和排序**結果**。若要在結果資料欄標頭中輸入篩選條件，請將游標暫留在該資料欄上，以查看可供您輸入資料欄篩選條件的選單 (![\[Filter menu\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/menu.png))。 如果查詢中包含錯誤，查詢編輯器 v2 會在結果區域中顯示錯誤訊息。該訊息會提供有關如何更正查詢的資訊。 您可以在結果區域中使用內容 (右鍵) 選單來匯出或複製查詢結果，如下所示： + 選擇**複製到**和 **JSON** 或 **CSV**，將選取的資料列下載至檔案。 + 選擇**複製資料列**，以將選取的資料列複製到剪貼簿。 + 選擇**複製具有標頭的資料列**，以將具有欄標頭的所選資料列複製到剪貼簿。 您也可以在結果區域中選擇**匯出**，然後選擇 **JSON** 或 **CSV**，以將整組資料列結果下載至檔案。結果集內的資料列數目可能會受限於查詢中的**限制**選項或 SQL `limit` 子句。所下載結果集的大小上限為 5 MB。 您也可以使用 Windows 上的快速鍵 Ctrl\$1C 或 macOS 上的 Cmd\$1C 將資料從目前的結果頁面複製到剪貼板。如果未選取任何資料列，則會將焦點所在的儲存格複製到剪貼簿。如果已選取資料列，則會將選取的資料列複製到剪貼簿。 若要新增查詢標籤，請選擇 ![\[New query tab\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/add-plus.png) 圖示，然後選擇**編輯器**，其會出現在具有查詢標籤的資料列中。查詢標籤不一定會使用 `Isolated session`。使用隔離工作階段時，SQL 命令的結果 (例如，在某個編輯器標籤中建立暫存資料表) 無法在另一個編輯器標籤中看到。當您在查詢編輯器 v2 中開啟編輯器標籤時，預設會使用隔離工作階段。 **若要執行查詢** 1. 在查詢區域中，執行以下其中一項操作： + 輸入查詢。 + 貼上您複製的查詢。 + 選擇**查詢**資料夾、開啟內容選單 (右鍵) 儲存的查詢，然後選擇**開啟查詢**。 1. 確認您已為打算執行的 SQL 選擇了正確的**叢集**或**工作群組**和**資料庫**值。 最初，您可以在樹狀檢視中選擇**叢集**或**工作群組**。也請在樹狀檢視中選擇**資料庫**。 您可以使用每個編輯器索引標籤的**隔離工作階段**標頭附近的下拉式控制項，在每個編輯器索引標籤內變更**叢集**或**工作群組**和**資料庫**。 對於每個編輯器標籤，您要選擇是否要在**隔離工作階段**中執行 SQL。隔離工作階段有自己的資料庫連線。請使用該連線來執行與其他查詢編輯器工作階段隔離的 SQL。如需連線的相關資訊，請參閱[開啟查詢編輯器 v2](query-editor-v2-open.md)。 1. 選擇**執行**。 隨即會開啟**結果**區域，並顯示查詢結果。 **顯示查詢的解釋計劃** 1. 選取查詢。 1. 開啟**解釋**。 預設也會開啟**解釋圖形**。 1. 選擇**執行**。 查詢便會開始執行，解釋計劃則會顯示在查詢的**結果**區域中。 查詢編輯器 v2 支援以下功能： + 您可以在一個查詢標籤中使用多個 SQL 陳述式編寫查詢。系統會依序執行查詢，並針對每個查詢開啟多個結果標籤。 + 您可以使用工作階段變數和暫存資料表編寫查詢。 + 您可以使用以 `${parameter}` 指定的可取代參數來編寫查詢。您可以使用多個可取代參數來編寫 SQL 查詢，並在 SQL 陳述式中的多個位置使用相同的參數。 在執行查詢時，系統會顯示一個視窗供您輸入參數值。每次執行查詢時，系統都會顯示視窗供您輸入參數值。 如需範例，請參閱 [範例：銷售額大於特定參數](#query-editor-v2-example-sales-qtysold-greater-than-parameter)。 + 系統會自動為查詢建立版本。您可以選擇較早的查詢版本來執行。 + 不需要等待查詢完成，就能繼續您的工作流程。即使您關閉查詢編輯器，查詢仍會繼續執行。 + 在編寫查詢時，系統支援自動完成結構描述、資料表和資料欄名稱。 SQL 編輯器支援以下功能： + SQL 中使用的開始和結束括號具有相符的顏色。編輯器中會顯示垂直線以幫助您讓括號相符。 + 您可以收合和展開 SQL 的各個部分。 + 您可以搜尋和取代 SQL 中的文字。 + 您可以使用快速鍵來執行數個常見的編輯任務。 + 編輯器中會反白顯示 SQL 錯誤，以方便您找到問題所在區域。 如需編輯器功能的示範，請觀看下列影片。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/9JAq0yDs0YE/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/9JAq0yDs0YE) ## 查詢範例 您可以在下面找到可以執行的各種查詢類型的描述。 其中許多查詢所使用的資料來自 `tickit` 範例結構描述。如需載入範例 `tickit` 資料的相關資訊，請參閱[將資料載入到資料庫](query-editor-v2-loading.md)。如需 `tickit` 範例資料的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[範例資料庫](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html)。 當您執行這些範例查詢時，請確認您在編輯器中選擇了正確的資料庫，例如 `sample_data_dev`。 **Topics** + [範例：設定工作階段變數](#query-editor-v2-example-set-session-variable) + [範例：按總銷售額排序的最佳活動](#query-editor-v2-example-top-event-sales) + [範例：銷售額大於特定參數](#query-editor-v2-example-sales-qtysold-greater-than-parameter) + [範例：建立暫存資料表](#query-editor-v2-example-create-temporary-table) + [範例：從暫存資料表中選取](#query-editor-v2-example-select-from-temporary-table) ### 範例：設定工作階段變數 下列命令會針對工作階段將 `search_path` 伺服器組態參數設定為「public]**。如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [SET](https://docs.aws.amazon.com/redshift/latest/dg/r_SET.html) 和 [search\$1path](https://docs.aws.amazon.com/redshift/latest/dg/r_search_path.html)。 ``` set search_path to public; ``` ### 範例：按總銷售額排序的最佳活動 下列查詢會尋找銷售額最多的活動。 ``` select eventname, count(salesid) totalorders, sum(pricepaid) totalsales from sales, event where sales.eventid=event.eventid group by eventname order by 3; ``` 以下是結果的部分清單。 ``` eventname totalorders totalsales White Christmas 20 9352 Joshua Radin 38 23469 Beach Boys 58 30383 Linda Ronstadt 56 35043 Rascal Flatts 76 38214 Billy Idol 67 40101 Stephenie Meyer 72 41509 Indigo Girls 57 45399 ... ``` ### 範例：銷售額大於特定參數 下列查詢會尋找銷量大於 `${numberoforders}` 所指定參數的銷售額。當參數值為 `7` 時，結果有 60 列。當您執行查詢時，查詢編輯器 v2 會顯示**執行查詢表單**視窗，以收集 SQL 陳述式中的參數值。 ``` select salesid, qtysold from sales where qtysold > ${numberoforders} order by 2; ``` 以下是結果的部分清單。 ``` salesid qtysold 20005 8 21279 8 130232 8 42737 8 74681 8 67103 8 105533 8 91620 8 121552 8 ... ``` ### 範例：建立暫存資料表 下列陳述式會透過選取「sales」**和「event」**資料表中的資訊來建立暫存資料表「eventsalestemp」**。 ``` create temporary table eventsalestemp as select eventname, count(salesid) totalorders, sum(pricepaid) totalsales from sales, event where sales.eventid=event.eventid group by eventname; ``` ### 範例：從暫存資料表中選取 下列陳述式會從按訂單總量排序的暫存資料表「eventsalestemp」**中選取活動、訂單總量和銷售總額。 ``` select eventname, totalorders, totalsales from eventsalestemp order by 2; ``` 以下是結果的部分清單。 ``` eventname totalorders totalsales White Christmas 20 9352 Joshua Radin 38 23469 Martina McBride 50 52932 Linda Ronstadt 56 35043 Indigo Girls 57 45399 Beach Boys 58 30383 ... ``` # Amazon Redshift 中的筆記本 您可以使用筆記本在單一文件中組織、註釋和共用多個 SQL 查詢。您可以將多個 SQL 查詢和 Markdown 儲存格新增至筆記本。筆記本可讓您透過使用多個查詢和 Markdown 儲存格，將與資料分析相關聯的查詢和說明分組到單一文件中。您可以使用 Markdown 語法新增文字並設定外觀格式，以提供資料分析任務的內容和其他資訊。您可以與團隊成員共用筆記本。 若要使用筆記本，您必須將筆記本的許可新增至 IAM 主體 (IAM 使用者或 IAM 角色)。我們建議的最佳實務是，將許可政策附加到 IAM 角色，然後根據需要將其指派給使用者和群組。如需詳細資訊，請參閱 [Amazon Redshift 中的身分和存取管理](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html)。您可以將許可新增至其中一個查詢編輯器 v2 受管政策。如需詳細資訊，請參閱[存取查詢編輯器 v2](query-editor-v2-getting-started.md#query-editor-v2-configure)。 您可以循序執行筆記本的所有儲存格。筆記本的 SQL 查詢儲存格與查詢編輯器索引標籤的功能大多相同。如需詳細資訊，請參閱[使用 Amazon Redshift 編寫查詢](query-editor-v2-query-run.md)。以下是查詢編輯器索引標籤與筆記本中的 SQL 儲存格之間的差異。 + 沒有控制項可以在筆記本中的 SQL 陳述式上執行 `Explain`。 + 在筆記本中，每個 SQL 儲存格只能建立一個圖表。 您可以將筆記本匯出和匯入至使用查詢編輯器 v2 建立的檔案。檔案的副檔名為 `.ipynb`，檔案大小最多可以為 5 MB。SQL 和 Markdown 儲存格會儲存在檔案中。叢集或工作群組與資料庫不會儲存在匯出的筆記本中。當您開啟匯入的筆記本時，您要選擇叢集或工作群組，以及要在其中執行叢集或工作群組的資料庫。執行 SQL 儲存格之後，您便可以在結果索引標籤中選擇是否要將目前的結果頁面顯示為圖表。查詢的結果集不會儲存在筆記本中。 # 建立筆記本 您可以建立筆記本來整理、標註和共用單一文件中的多個 SQL 查詢。 **若要建立筆記本** 1. 從導覽器功能表中，選擇編輯器圖示 (![\[Horizontal lines representing redacted or censored text.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-align-left.png))。 1. 選擇加號圖示 (![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/add-plus.png))，然後選擇**筆記本**。 根據預設，SQL 查詢儲存格會出現在筆記本中。 1. 在 SQL 查詢儲存格中，執行以下其中一項操作： + 輸入查詢。 + 貼上您複製的查詢。 1. （選用） 選擇加號圖示 (![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/add-plus.png))，然後選擇 **Markdown** 以新增 Markdown 儲存格，您可以在其中使用標準 Markdown 語法提供描述性或說明性文字。 1. （選用） 選擇加號圖示 (![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/add-plus.png))，然後選擇 **SQL** 以插入 SQL 儲存格。 您可以使用鉛筆圖示 () 重新命名筆記本![\[Pencil icon representing an editing or writing function.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-edit.png)。 從功能表圖示 (![\[Three dots arranged horizontally, representing an ellipsis or "more" menu icon.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-more.png))，您也可以在筆記本上執行下列操作： + ![\[Share\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-share.png) **與我的團隊共用** — 依標籤所定義與您的團隊共用筆記本。若要與團隊共用筆記本，請確定您已將主體標籤 `sqlworkbench-team` 設定為與帳戶中其他團隊成員相同的值。例如，管理員可以針對會計部門中的每個人，將值設定為 `accounting-team`。如需範例，請參閱「[要使用查詢編輯器 v2 所需的許可](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor-v2)」。 + ![\[Export\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-export.png) **匯出** — 將筆記本匯出至副檔名為 `.ipynb` 的本機檔案。 + ![\[Import query\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-import.png) **匯入查詢** – 將查詢從本機檔案匯入筆記本中的儲存格。您可以使用 `.sql`和 `.txt`副檔名匯入檔案。 + ![\[Save\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-floppy-disk.png) **儲存版本** — 建立筆記本的版本。若要查看筆記本的版本，請導覽至已儲存的筆記本，然後開啟**版本歷史記錄**。 + ![\[Duplicate\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-duplicate.png) **複製** — 建立筆記本的副本，並在新的筆記本索引標籤中開啟它。 + ![\[Shortcuts\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-key-command.png) **捷徑** — 在編寫筆記本時顯示可用的捷徑。 # 匯入至筆記本 您可以將整個筆記本或個別 SQL 儲存格匯入查詢編輯器 v2 筆記本。 若要將整個筆記本從本機檔案匯入**我的筆記本**，請選擇![\[Import\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-import.png)**匯入**，然後選擇**匯入筆記本**。導覽至包含筆記本`.ipynb`的檔案。筆記本會匯入到目前開啟的筆記本資料夾。您接著可以在筆記本編輯器中開啟筆記本。 若要將查詢從本機檔案匯入筆記本中的 SQL 儲存格，請選擇![\[Import\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-import.png)**匯入**，然後選擇**匯入查詢**。在**匯入查詢**視窗中，依照畫面上的指示，選擇可匯入新筆記本或現有筆記本做為查詢的檔案和資料夾。檔案的副檔名必須為 `.sql`或 `.txt`。每個查詢最多可達 10，000 個字元。將 新增至現有的筆記本時，您可以從**已儲存筆記本清單中的所有筆記本中選擇哪個筆記本**。匯入的查詢會在筆記本結尾新增為 SQL 儲存格。當您選擇新的筆記本時，您可以選擇筆記本的名稱，並在目前開啟的已儲存筆記本資料夾中建立。 **注意** 使用 TextEdit 應用程式在 macOS 上建立`.sql`檔案時，您可能會遇到將其他隱藏副檔名新增至檔案的問題。例如，在 TextEdit 中`Test.sql`建立名為 的檔案最終可能會儲存為 `Test.sql.rtf`。查詢編輯器 v2 不支援副`.rtf`檔名為 的檔案。不過，如果您使用 TextEdit 建立`.sql`檔案，並將其儲存為純文字檔案，則該檔案會有一個額外的隱藏`.txt`副檔名。例如，名為 的檔案`Text.sql`可能會儲存為 `Text.sql.txt`。與 `.rtf` 延伸模組不同，查詢編輯器 v2 支援具有 `.txt`延伸模組的檔案，因此在將查詢匯入筆記本時`Text.sql.txt`支援 。 如需筆記本的示範，請觀看下列影片。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/GNahyu7j98M/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/GNahyu7j98M) # 查詢 AWS Glue Data Catalog 您可以使用查詢編輯器 v2 來查詢 中目錄化的資料 AWS Glue Data Catalog ，方法是使用特定 SQL 命令並授予本節中概述的許可。依預設， AWS Glue Data Catalog 會列為名為 `awsdatacatalog` 的查詢編輯器 v2 資料庫。並非所有 Amazon Redshift AWS 區域都可查詢 AWS Glue Data Catalog 。請使用 SHOW 命令來判斷此功能是否可用。如需 的詳細資訊 AWS Glue，請參閱《 *AWS Glue 開發人員指南*》中的[什麼是 AWS Glue？](https://docs.aws.amazon.com/glue/latest/dg/what-is-glue.html)。 **注意** 只有 Amazon Redshift RA3 節點類型叢集和 Amazon Redshift Serverless AWS Glue Data Catalog 才支援查詢 。 您可以設定資料倉儲，並使用下列 SQL 命令檢視目錄化的 AWS Glue 資料庫物件： + SHOW — 顯示目前連線的資料倉儲是否已掛載 `awsdatacatalog`。例如，若要顯示 `data_catalog_auto_mount` 參數值，請執行： ``` SHOW data_catalog_auto_mount; ``` 如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [SHOW](https://docs.aws.amazon.com/redshift/latest/dg/r_SHOW.html)。 + ALTER SYSTEM — 變更 `data_catalog_auto_mount` 的系統層級組態。例如，若要將 `data_catalog_auto_mount` 參數值變更為 `on`，請執行： ``` ALTER SYSTEM SET data_catalog_auto_mount = on; ``` 當佈建叢集重新啟動或無伺服器工作群組自動暫停並繼續時，變更便會生效。如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [ALTER SYSTEM](https://docs.aws.amazon.com/redshift/latest/dg/r_ALTER_SYSTEM.html)。 + SHOW SCHEMAS — 顯示結構描述的清單。名為 的資料庫中的結構描述`awsdatacatalog`代表 中編目的 AWS Glue 資料庫 AWS Glue Data Catalog。例如，若要顯示這些結構描述，請執行： ``` SHOW SCHEMAS FROM DATABASE awsdatacatalog; ``` 如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [SHOW SCHEMAS](https://docs.aws.amazon.com/redshift/latest/dg/r_SHOW_SCHEMAS.html)。 + SHOW TABLES — 顯示結構描述中的資料表清單。例如，若要在結構描述`myglue`執行中顯示名為 `awsdatacatalog`的 AWS Glue Data Catalog 資料庫中的資料表： ``` SHOW TABLES FROM SCHEMA awsdatacatalog.myschema; ``` 如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [SHOW TABLES](https://docs.aws.amazon.com/redshift/latest/dg/r_SHOW_TABLES.html)。 + SHOW COLUMNS — 顯示資料表中的資料欄清單。例如，若要在結構描述`myglue`和資料表`mytable`執行中顯示名為 `awsdatacatalog`的 AWS Glue Data Catalog 資料庫中的資料欄： ``` SHOW COLUMNS FROM TABLE awsdatacatalog.myglue.mytable; ``` 如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [SHOW COLUMNS](https://docs.aws.amazon.com/redshift/latest/dg/r_SHOW_COLUMNS.html)。 **若要授予 IAM 使用者或角色查詢 的許可 AWS Glue Data Catalog，** 1. 在樹狀檢視窗格中，使用**資料庫使用者名稱和密碼**身分驗證方法，連線至佈建叢集或無伺服器工作群組中的初始資料庫。例如，使用您在建立叢集或工作群組時使用的管理員使用者和密碼連線至 `dev` 資料庫。 1. 在編輯器索引標籤中，執行下列 SQL 陳述式以向 IAM 使用者授予 AWS Glue Data Catalog的存取權。 ``` GRANT USAGE ON DATABASE awsdatacatalog to "IAM:myIAMUser" ``` 其中 *IAM:myIAMUser* 是您想要向其授予 AWS Glue Data Catalog使用權限的 IAM 使用者。或者，您也可以將 *IAMR:myIAMRole* 的使用權限授予 IAM 角色。 1. 在樹狀檢視窗格中，編輯或刪除先前建立的叢集或工作群組連線。使用下列其中一種方式連線至叢集或工作群組： + 若要從叢集存取 `awsdatacatalog` 資料庫，您必須使用身分驗證方法**使用您的 IAM 身分的暫時憑證**。如需此身分驗證方法的相關資訊，請參閱[連線至 Amazon Redshift 資料庫](query-editor-v2-connecting.md)。您的查詢編輯器 v2 管理員可能需要設定帳戶的**帳戶設定**，才能在連線視窗上顯示此身分驗證方法。 + 若要從工作群組存取 `awsdatacatalog` 資料庫，您必須使用身分驗證方法**聯合身分使用者**。如需此身分驗證方法的相關資訊，請參閱[連線至 Amazon Redshift 資料庫](query-editor-v2-connecting.md)。 1. 透過所授予的權限，您可以使用 IAM 身分來針對您的 AWS Glue Data Catalog執行 SQL。 連線後，您可以使用查詢編輯器 v2 來查詢 AWS Glue Data Catalog中所編目的資料。在查詢編輯器 v2 的樹狀檢視窗格上，選擇叢集或工作群組和 `awsdatacatalog` 資料庫。在編輯器或筆記本窗格中，確認您已選擇正確的叢集或工作群組。所選擇的資料庫應該是初始的 Amazon Redshift 資料庫，例如 `dev`。如需有關編寫查詢的資訊，請參閱[使用 Amazon Redshift 編寫查詢](query-editor-v2-query-run.md)和[Amazon Redshift 中的筆記本Notebooks](query-editor-v2-notebooks.md)。系統會保留名為 `awsdatacatalog` 的資料庫，以參考帳戶中的外部 Data Catalog 資料庫。對 `awsdatacatalog` 資料庫所進行的查詢只能是唯讀的。請使用由三個部分組成的標記法來參考 SELECT 陳述式中的資料表。其中第一部分是資料庫名稱，第二部分是 AWS Glue 資料庫名稱，第三部分是 AWS Glue 資料表名稱。 ``` SELECT * FROM awsdatacatalog..; ``` 您可以執行讀取 AWS Glue Data Catalog 資料並填入 Amazon Redshift 資料表的各種案例。 下列範例 SQL 會聯結兩個在其中定義的資料表 AWS Glue。 ``` SELECT pn.emp_id, alias, role, project_name FROM "awsdatacatalog"."empl_db"."project_name_table" pn, "awsdatacatalog"."empl_db"."project_alias_table" pa WHERE pn.emp_id = pa.emp_id; ``` 下列範例 SQL 會建立 Amazon Redshift 資料表，並填入來自兩個 AWS Glue 資料表聯結的資料。 ``` CREATE TABLE dev.public.glue AS SELECT pn.emp_id, alias, role, project_name FROM "awsdatacatalog"."empl_db"."project_name_table" pn, "awsdatacatalog"."empl_db"."project_alias_table" pa WHERE pn.emp_id = pa.emp_id; ``` ## 查詢 Amazon S3 資料表 （預覽） 您可以使用查詢編輯器 v2 來查詢掛載到 的 Amazon S3table 目錄中所保留的資料 AWS Glue Data Catalog。Amazon S3 資料表目錄會在建立 AWS Glue Data Catalog 時掛載到 ，並自動在相同帳戶 AWS 區域 下的相同 中，在所有佈建叢集和無伺服器工作群組上顯示為外部資料庫。如需使用 Amazon Redshift 存取 Amazon S3 資料表的詳細資訊，請參閱[《Amazon Simple Storage Service 使用者指南》中的使用 Amazon Redshift 存取 Amazon S3 資料表](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-integrating-redshift.html)。 # 查詢資料湖 您可以依照本教學課程中的任務集，查詢 Amazon S3 資料湖中的資料。首先，建立外部結構描述以參考 [AWS Glue Data Catalog](https://docs.aws.amazon.com/glue/latest/dg/components-overview.html#data-catalog-intro) 中的外部資料庫。然後，您就可以查詢 Amazon S3 資料湖中的資料。 ## 示範：查詢資料湖 若要了解如何查詢資料湖，請觀看以下影片。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/-pyy0qNmEKo/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/-pyy0qNmEKo) ## 先決條件 在查詢編輯器 v2 中使用資料湖之前，請先確認您已在 Amazon Redshift 環境中設定以下項目： + 使用 編目 Amazon S3 資料， AWS Glue 並啟用 Data Catalog AWS Lake Formation。 + 使用 AWS Glue 已啟用的 Data Catalog 為 Amazon Redshift 建立 IAM 角色 AWS Lake Formation。如需此程序的詳細資訊，請參閱[使用 AWS Glue Data Catalog 啟用的 為 Amazon Redshift 建立 IAM 角色 AWS Lake Formation](https://docs.aws.amazon.com/redshift/latest/dg/c-getting-started-using-spectrum-create-role.html#spectrum-get-stared-create-role-lake-formation)。如需使用 Redshift Spectrum 和 Lake Formation 的詳細資訊，請參閱[搭配使用 Redshift Spectrum。 AWS Lake Formation](https://docs.aws.amazon.com/redshift/latest/dg/spectrum-lake-formation.html) + 授予資料表的 SELECT 許可，以在 Lake Formation 資料庫中進行查詢。如需有關此程序的詳細資訊，請參閱[授予資料表的 SELECT 許可，以在 Lake Formation 資料庫中進行查詢](https://docs.aws.amazon.com/redshift/latest/dg/c-getting-started-using-spectrum-create-role.html#spectrum-get-started-grant-lake-formation-table)。 您可以在 Lake Formation 主控台 (https://console.aws.amazon.com/lakeformation/)、**許可****區段、資料湖許可**頁面中驗證 IAM 角色、 AWS Glue 資料庫和資料表是否具有適當的許可。 + 確認已連線的使用者擁有在 Amazon Redshift 資料庫中建立結構描述和存取資料湖中資料的許可。當您在查詢編輯器 v2 中連線到資料庫時，您要選擇包含憑證 (可以是資料庫使用者或 IAM 使用者) 的驗證方法。已連線的使用者必須具備適當的許可和資料庫權限，例如 `superuser`。建立叢集或工作群組的 Amazon Redshift `admin` 使用者擁有 `superuser` 權限，而且可以建立結構描述和管理 Redshift 資料庫。如需使用查詢編輯器 v2 來連線至資料庫的相關資訊，請參閱[連線至 Amazon Redshift 資料庫](query-editor-v2-connecting.md)。 ## 建立外部結構描述 若要查詢 Amazon S3 資料湖中的資料，請先建立外部結構描述。外部結構描述會參考 [AWS Glue Data Catalog](https://docs.aws.amazon.com/glue/latest/dg/components-overview.html#data-catalog-intro) 中的外部資料庫。 1. 在查詢編輯器 v2 的**編輯器**檢視中，選擇 ![\[Create\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-add.png) **建立**，然後選擇**結構描述**。 1. 輸入**結構描述**名稱。 1. 對於**結構描述類型**，選擇**外部**。 1. 在**資料目錄**詳細資訊中，**區域**預設為 AWS 區域 Redshift 資料庫所在的 。 1. 選擇外部結構描述將對應的**AWS Glue 資料庫**，以及包含 AWS Glue 資料表參考的資料庫。 1. 選擇具有在 Amazon S3 上查詢資料所需許可的 Amazon Redshift **IAM 角色**。 1. 選擇性地選擇具有 Data Catalog 許可的 **IAM 角色**。 1. 選擇**建立結構描述**。 結構描述會出現在樹狀檢視面板中的資料庫下方。 在建立結構描述時，如果您收到資料庫的許可遭拒錯誤，請檢查已連線的使用者是否具有建立結構描述的資料庫權限。 ## 在 Amazon S3 資料湖中查詢資料 請使用您在上一個程序中建立的結構描述。 1. 在樹狀檢視面板中，選擇結構描述。 1. 若要檢視資料表定義，請選擇資料表。隨即會顯示資料表資料欄和資料類型。 1. 若要查詢資料表，請選擇該資料表，然後在內容功能表 (按一下滑鼠右鍵) 中，選擇**選取資料表**以產生查詢。 1. 在**編輯器**中執行查詢。 下列範例 SQL 是由查詢編輯器 v2 產生，用於查詢名為 AWS Glue 資料表中的所有資料列`flightscsv`。為了簡單起見，輸出中顯示的資料欄和資料列已遭到截斷。 ``` SELECT * FROM "dev"."mydatalake_schema"."flightscsv"; year quarter month dom day_of_week fl_date unique_carrier airline_id carrier tail_num fl_num 2016 4 10 19 3 10/19/16 OO 20304 OO N753SK 3086 2016 4 10 19 3 10/19/16 OO 20304 OO N753SK 3086 2016 4 10 19 3 10/19/16 OO 20304 OO N778SK 3087 2016 4 10 19 3 10/19/16 OO 20304 OO N778SK 3087 ... ``` # 資料共用 您可以建立資料共用讓其他叢集上的使用者可以查詢資料。包含您要共用之資料的叢集稱為*生產者*叢集。您必須在生產者叢集上針對要共用的資料庫物件建立資料共用。您可以共用結構描述、資料表、檢視表和 SQL 使用者定義函數 (UDF)。要作為資料共用對象的叢集稱為*取用者*叢集。在取用者叢集上，您必須從資料共用建立資料庫。然後，取用者叢集上的使用者就可以查詢資料。如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[開始使用資料共用](https://docs.aws.amazon.com/redshift/latest/dg/getting-started-datasharing.html)。 # 建立資料共用 您必須在要作為生產者叢集的叢集上建立資料共用。若要進一步了解資料共用的考量，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [Amazon Redshift 中的資料共用考量](https://docs.aws.amazon.com/redshift/latest/dg/datashare-considerations.html)。 1. 選擇您要使用的生產者叢集上的資料庫。 1. 建立資料共用。例如： ``` create datashare mysource; ``` 1. 設定資料共用的許可。例如： ``` grant alter, share on datashare mysource to admin; ``` 1. 設定您要共用之資料庫物件的許可。例如： ``` alter datashare mysource add schema public; ``` ``` alter datashare mysource add table public.event; ``` 1. 在取用者叢集命名空間上設定用來存取資料共用的許可。例如： ``` grant usage on datashare mysource to namespace '2b12345-1234-5678-9012-bb1234567890'; ``` # 顯示資料共用 您可以顯示已在生產者叢集上建立的資料共用。 1. 選擇生產者叢集。 1. 顯示資料共用。例如： ``` show datashares; ``` ``` share_name share_owner source_database consumer_database share_type createdate is_publicaccessible share_acl producer_account producer_namespace test_datashare 100 db_producer NULL OUTBOUND 2/15/2022 FALSE admin 123456789012 p1234567-8765-4321-p10987654321 ``` # 建立取用者資料庫 在取用者叢集上，您必須從資料共用建立資料庫。這些步驟會描述如何在同一帳戶的兩個叢集之間共用資料。如需跨 AWS 帳戶共用資料的資訊，請參閱《*Amazon Redshift 資料庫開發人員指南*》中的[跨 AWS 帳戶共用資料](https://docs.aws.amazon.com/redshift/latest/dg/across-account.html)。 您可以使用 SQL 命令或查詢編輯器 v2 樹狀檢視面板來建立資料庫。 **使用 SQL** 1. 從您帳戶的資料共用和生產者叢集的命名空間建立資料庫。例如： ``` create database share_db from datashare mysource of account '123456789012' namespace 'p1234567-8765-4321-p10987654321'; ``` 1. 設定許可，以便使用者可以存取資料庫和結構描述。例如： ``` grant usage on database share_db to usernames; ``` ``` grant usage on schema public to usernames; ``` **使用查詢編輯器 v2 樹狀檢視面板** 1. 選擇![\[Plus sign icon inside a circle, indicating an add or create action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-add.png)**建立**，然後選擇**資料庫**。 1. 輸入**資料庫名稱**。 1. (選擇性) 選取**使用者和群組**，然後選擇**資料庫使用者**。 1. 選擇**使用資料共用建立**。 1. 選擇資料共用。 1. 選擇**建立資料庫**。 新的 ![\[datashare\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-datashare.png)**資料共用**資料庫便會顯示在查詢編輯器 v2 的樹狀檢視面板中。 1. 設定許可，以便使用者可以存取資料庫和結構描述。例如： ``` grant usage on database share_db to usernames; ``` ``` grant usage on schema public to usernames; ``` # 查詢資料共用物件 在取用者叢集上，您可以使用由三個部分組成的標記法表示的完全合格物件名稱來查詢資料共用物件：資料庫、結構描述和物件名稱。 1. 在查詢編輯器 v2 的樹狀檢視面板中，選擇結構描述。 1. 若要檢視資料表定義，請選擇資料表。 隨即會顯示資料表資料欄和資料類型。 1. 若要查詢資料表，請選擇該資料表，然後使用內容選單 (右鍵) 選擇**選取資料表**。 1. 使用 SELECT 命令查詢資料表。例如： ``` select top 10 * from test_db.public.event; ``` # 使用查詢編輯器 v2 的排程查詢 使用 Amazon Redshift 查詢編輯器 v2 可讓 SQL 查詢按照排程自動執行。排程查詢是依指定時間或間隔自動執行的 SQL 陳述式，可讓您有效率地管理重複的資料操作和分析任務。如果您希望在 Amazon Redshift 環境中簡化批次處理、產生定期報告或維護資料管道，建議您排程查詢。 排程查詢有助於自動化擷取、轉換和載入 (ETL) 工作流程、重新整理儀表板以顯示最新洞察，並且操作各種資料管理常式。以下頁面詳細說明建立、設定和管理排程查詢的程序，以最佳化 Amazon Redshift 工作負載。 # 使用查詢編輯器 v2 建立查詢排程 您可以使用 Amazon Redshift 查詢編輯器 v2 建立排程來執行 SQL 陳述式。您可以建立排程，以符合您業務需求的時間間隔執行 SQL 陳述式。當已排程查詢的執行時間來臨，查詢便會由 Amazon EventBridge 啟動，並使用 Amazon Redshift 資料 API。 **建立排程以執行 SQL 陳述式** 1. 在**編輯器** ![\[Editor\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-align-left.png) 檢視中，選擇 ![\[Schedule\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-calendar.png) **排程**以建立排程來執行 SQL 陳述式。 1. 在定義排程時，您會提供下列資訊。 + 擔任執行查詢所需許可的 IAM 角色。此 IAM 角色也會附加至您的叢集或工作群組。 + AWS Secrets Manager 或臨時登入資料的身分驗證值，以授權存取您的叢集或工作群組。資料 API 支援這些身分驗證方法。如需詳細資訊，請參閱[驗證已排程的查詢](query-editor-v2-schedule-query-authentication.md)。 + 資料庫所在的叢集或工作群組。 + 所要查詢的資料所在資料庫的名稱。 + 已排程查詢的名稱及其描述。查詢編輯器 v2 會在您提供的已排程查詢名稱前面加上「QS2-」。查詢編輯器 v1 會在其已排程查詢的名稱前面加上「QS-」。 + 要依排程執行的 SQL 陳述式。 + 排程頻率和重複選項，或定義排程的 cron 格式值。如需詳細資訊，請參閱《Amazon CloudWatch Events 使用者指南》**中的 [Cron 運算式](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/ScheduledEvents.html#CronExpressions)。 + 您也可以選擇啟用標準 Amazon SNS 通知來監控所排程的查詢。您可能需要確認提供給 Amazon SNS 通知的電子郵件地址。檢查您的電子郵件是否有用來確認 Amazon SNS 通知電子郵件地址的連結。如需詳細資訊，請參閱《Amazon Simple Notification Service 開發人員指南》**中的[電子郵件通知](https://docs.aws.amazon.com/sns/latest/dg/sns-email-notifications.html)。如果您的查詢正在執行中，但在 SNS 主題中看不到發佈的訊息，請參閱《Amazon EventBridge 使用者指南》**中的[我的規則已執行，但我沒看到任何訊息發佈到我的 Amazon SNS 主題](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-troubleshooting.html#eb-no-messages-published-sns)。 1. 選擇**排程查詢**以儲存並啟用排程，並將排程新增至**已排程的查詢**檢視中的查詢清單。 **已排程的查詢** ![\[Scheduled queries\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/qev2-calendar.png) 檢視會列出叢集和工作群組的已排程查詢。使用此檢視時，您可以顯示排程查詢詳細資訊、啟用或停用排程、編輯排程，以及刪除已排程的查詢。當您檢視查詢詳細資訊時，您也可以檢視依排程執行查詢的歷史記錄。 **注意** 排程查詢執行只會在**排程歷史記錄**清單中存在 24 小時。依排程執行的查詢未出現在查詢編輯器 v2 的**查詢歷史記錄**檢視中。 ## 排程查詢的示範 如需排程查詢的示範，請觀看下列影片。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/gTw0XUpO8sw/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/gTw0XUpO8sw) # 設定用來排程查詢的許可 若要排程查詢，定義排程的 AWS Identity and Access Management (IAM) 使用者以及與排程相關聯的 IAM 角色必須設定 IAM 許可，才能使用 Amazon EventBridge 和 Amazon Redshift Data API。若要接收來自已排程查詢的電子郵件，則還必須設定您選擇性指定的 Amazon SNS 通知。 以下說明使用 AWS 受管政策來提供許可的任務，但根據您的環境，您可能想要縮小允許許可的範圍。 若為已登入查詢編輯器 v2 的 IAM 使用者，請使用 IAM 主控台 ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) 編輯 IAM 使用者。 + 除了執行 Amazon Redshift 和查詢編輯器 v2 操作的許可外，請將 `AmazonEventBridgeFullAccess`和 `AmazonRedshiftDataFullAccess` AWS 受管政策連接到 IAM 使用者。 + 或者，請將許可指派給角色，然後將角色指派給使用者。 將允許 `sts:AssumeRole` 許可的政策附加到您在定義已排程查詢時所指定 IAM 角色的資源 ARN。如需有關擔任角色的相關資訊，請參閱《IAM 使用者指南》**中的[向使用者授予切換角色的許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_permissions-to-switch.html)。 下列範例顯示在帳戶 `123456789012` 中擔任 IAM 角色 `myRedshiftRole` 的許可政策。IAM 角色 `myRedshiftRole` 也是附加至已排程查詢執行所在叢集或工作群組的 IAM 角色。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AssumeIAMRole", "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": [ "arn:aws:iam::123456789012:role/myRedshiftRole" ] } ] } ``` ------ 更新用於排程查詢的 IAM 角色信任政策，以允許 IAM 使用者擔任該角色。 ``` { "Sid": "AssumeRole", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/myIAMusername" }, "Action": "sts:AssumeRole" } ] } ``` 針對您指定要允許已排程的查詢執行的 IAM 角色，請使用 IAM 主控台 ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) 編輯 IAM 角色。 + 將 `AmazonRedshiftDataFullAccess`和 `AmazonEventBridgeFullAccess` AWS 受管政策連接至 IAM 角色。`AmazonRedshiftDataFullAccess` 受管政策只會針對標記了索引鍵 `RedshiftDataFullAccess` 的 Redshift Serverless 工作群組允許 `redshift-serverless:GetCredentials` 許可。 # 驗證已排程的查詢 在排程查詢時，您會在 SQL 執行時使用下列其中一種身分驗證方法。每種方法都需要在查詢編輯器 v2 上使用不同的輸入組合。用於執行 SQL 陳述式的資料 API 支援這些身分驗證方法。 用於執行查詢的資料庫使用者或角色必須具備必要的資料庫權限。例如，若要授予資料表 `mytable` 的 `IAMR:MyRedshiftQEv2Scheduler` 權限，請執行下列 SQL 命令。 ``` GRANT all ON TABLE mytable TO "IAMR:MyRedshiftQEv2Scheduler"; ``` 若要檢視叢集或工作群組中的資料庫使用者清單，請查詢系統檢視 `PG_USER_INFO`。 **注意** 您為其排程查詢的任何 Redshift Serverless 工作群組也必須標記索引鍵 `RedshiftDataFullAccess`。如需詳細資訊，請參閱[授權 Amazon Redshift 資料 API 的存取](data-api-access.md)。 若要替代標記工作群組的做法，您也可以將內嵌政策新增至允許 `redshift-serverless:GetCredentials` 的 IAM 角色 (隨排程指定)。例如： **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "UseTemporaryCredentialsForAllServerlessWorkgroups", "Effect": "Allow", "Action": "redshift-serverless:GetCredentials", "Resource": [ "arn:aws:redshift-serverless:*:*:workgroup/*" ] } ] } ``` **AWS Secrets Manager** 使用此方法時，請為儲存在 AWS Secrets Manager中的 **secret-arn** 提供機密值。此秘密包含用來連線至資料庫的憑證。您可能已在建立叢集或工作群組時，建立了具有適當憑證的機密。此機密必須標記了索引鍵 `RedshiftDataFullAccess`。如果標籤索引鍵尚未存在，請使用 AWS Secrets Manager 主控台來新增它。如需有關建立機密的資訊，請參閱 [建立資料庫連線憑證的機密](redshift-secrets-manager-integration-create.md)。 如需最基本許可的相關資訊，請參閱《AWS Secrets Manager 使用者指南》**中的[使用 AWS Secrets Manager建立和管理機密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)。 **臨時憑證** 使用此方法時，請在連線到叢集中的資料庫時提供您的**資料庫名稱**和**資料庫使用者**值。您只需要在連線至工作群組中的資料庫時提供**資料庫名稱**。 在連線至叢集時，`AmazonRedshiftDataFullAccess` 政策會允許名為 `redshift_data_api_user` 的資料庫使用者獲得 `redshift:GetClusterCredentials` 的許可。如果您想要使用不同的資料庫使用者來執行 SQL 陳述式，請在附加至叢集的 IAM 角色中新增政策以允許 `redshift:GetClusterCredentials`。下列範例政策會允許資料庫使用者 `awsuser` 和 `myuser`。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "UseTemporaryCredentialsForAllDbUsers", "Effect": "Allow", "Action": "redshift:GetClusterCredentials", "Resource": [ "arn:aws:redshift:*:*:dbuser:*/awsuser", "arn:aws:redshift:*:*:dbuser:*/myuser" ] } ] } ``` # 設定用來檢視排程查詢歷史記錄的許可 若要允許使用者檢視排程查詢歷史記錄，請編輯 IAM 角色 (隨排程指定) **信任關係**以新增許的。 以下是 IAM 角色中的信任政策範例，該政策允許 IAM 使用者 *myIAMusername* 檢視排程查詢歷史記錄。您不必允許 IAM 使用者獲得 `sts:AssumeRole` 許可，而是可以選擇允許 IAM 角色獲得此許可。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": [ "redshift.amazonaws.com", "redshift-serverless.amazonaws.com" ] }, "Action": "sts:AssumeRole" }, { "Effect": "Allow", "Principal": { "Service": "events.amazonaws.com" }, "Action": "sts:AssumeRole" }, { "Sid": "AssumeRole", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/myIAMusername" }, "Action": "sts:AssumeRole" } ] } ``` ------ # 監控已排程的查詢 對於您指定要傳送電子郵件通知的 Amazon SNS 主題，請透過導覽至 **SNS 通知**區段、**開啟**監控，然後使用**建立 SNS 主題**建立主題，以使用查詢編輯器 v2 建立 Amazon SNS 主題。查詢編輯器 v2 會建立 Amazon SNS 主題，並將服務主體新增至 Amazon EventBridge 的存取政策。以下是在 Amazon SNS 主題中建立的**存取政策**範例。在此範例中，使用 the AWS 區域 *us-west-2*、 AWS 帳戶 *123456789012* 和 Amazon SNS 主題 *select-version-pdx-testunload*。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id": "__default_policy_ID", "Statement": [ { "Sid": "Allow_Publish_Events", "Effect": "Allow", "Principal": { "Service": "events.amazonaws.com" }, "Action": "sns:Publish", "Resource": "arn:aws:sns:us-west-2:123456789012:select-version-pdx-testunload" } ] } ``` ------ 排程查詢執行時，Amazon SNS 會傳送 AWS 通知電子郵件。下列範例顯示針對在 AWS 帳戶 *123456789012* 中的 AWS 區域 *eu-north-1* 上執行的已排程查詢 *QS2-may25a*，使用 Amazon SNS 通知主題 *may25a-SNS* 傳送至 *myemail@example.com* 的電子郵件。 ``` {"version":"0","id":"8e4323ec-5258-7138-181b-91290e30ff9b","detail-type":"Scheduled Event","source":"aws.events","account":"123456789012","time":"2023-05-25T15:22:00Z", "region":"eu-north-1","resources":["arn:aws:events:eu-north-1:123456789012:rule/QS2-may25a"],"detail":{}} -- If you wish to stop receiving notifications from this topic, please click or visit the link below to unsubscribe: https://sns.eu-north-1.amazonaws.com/unsubscribe.html?SubscriptionArn=arn:aws:sns:eu-north-1:123456789012:may25a-SNS:0c1a3d05-39c2-4507-bc3d-47250513d7b0&Endpoint=myemail@example.com Please do not reply directly to this email. If you have any questions or comments regarding this email, please contact us at https://aws.amazon.com/support ``` # 針對排程查詢的設定進行故障診斷 如果您在排程查詢時遇到問題，請考慮下列事項。 **查詢未執行** 檢查排程中使用的 IAM 角色是否有可取得暫時叢集憑證的許可。已佈建叢集的許可為 `redshift:GetClusterCredentialsWithIAM`。Redshift Serverless 工作群組的許可為 `redshift-serverless:GetCredentials`。 **已排程歷史記錄未顯示** 用於登入 AWS 主控台的 IAM 使用者或 IAM 角色並未新增至用於排程查詢之 IAM 角色的信任政策中。 使用 AWS Secrets Manager 進行排程查詢連線時，請確認秘密已加上金鑰 的標籤`RedshiftDataFullAccess`。 如果排程的查詢使用 AWS Secrets Manager 連線，則用於排程查詢的 IAM 角色必須`SecretsManagerReadWrite`具有連接到角色的同等受管政策。 **查詢歷史記錄狀態為 `Failed`** 如需查詢失敗原因的詳細資訊，請檢視 SYS\$1QUERY\$1HISTORY 系統檢視。常見問題是用來執行查詢的資料庫使用者或角色可能沒有要執行 SQL 所需的權限。如需詳細資訊，請參閱[驗證已排程的查詢](query-editor-v2-schedule-query-authentication.md)。 下列 SQL 會查詢 SYS\$1QUERY\$1HISTORY 檢視以傳回失敗的查詢。 ``` SELECT user_id, query_id, transaction_id, session_id, database_name, query_type, status, error_message, query_text FROM sys_query_history WHERE status = 'failed'; ``` 若要了解特定的失敗已排程查詢的詳細資訊，請參閱[使用 檢視排程查詢的結果 AWS CloudShell](query-editor-v2-schedule-query-troubleshooting-cloudshell.md)。 # 使用 檢視排程查詢的結果 AWS CloudShell 您可以使用 AWS CloudShell 來了解排程查詢的詳細資訊。您必須擁有適當的許可，才能執行下列程序中顯示的 AWS CLI 命令。 **檢視已排程查詢的結果** 1. 在 AWS 主控台上，開啟 AWS CloudShell 命令提示字元。如需詳細資訊 AWS CloudShell，請參閱*AWS CloudShell 《 使用者指南*》中的[什麼是 AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) 。 1. 擔任已排程查詢的 IAM 角色。若要擔任該角色，請在查詢編輯器 v2 中尋找與已排程查詢相關聯的 IAM 角色，並在 AWS CloudShell中的 AWS CLI 命令內使用該角色。例如，針對角色 `scheduler`，請輸入 AWS STS 命令來擔任已排程的查詢所使用的角色。 ``` aws sts assume-role --role-arn "arn:aws:iam::123456789012:role/scheduler" --role-session-name "scheduler-test" ``` 傳回的憑證類似以下內容。 ``` "Credentials": { "AccessKeyId": "AKIAIOSFODNN7EXAMPLE", "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", "SessionToken": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY...", "Expiration": "2023-08-18T18:19:44+00:00" }, "AssumedRoleUser": { "AssumedRoleId": "AROA35B2NH6WBTP7ONL4E:scheduler-test", "Arn": "arn:aws:sts::123456789012:assumed-role/scheduler/scheduler-test" } } ``` 1. AWS CLI 使用擔任 IAM 角色中顯示的登入資料，在 中建立環境變數。您必須使用這些字符，直到其到期。例如，您可以在 中輸入下列項目 AWS CloudShell。 ``` export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY export AWS_SESSION_TOKEN=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY... ``` 1. 若要檢視失敗查詢的錯誤，請執行 AWS CLI 命令來描述陳述式。SQL 陳述式的 ID 來自查詢編輯器 v2 中已排程查詢之**排程歷史記錄**區段中顯示的 **ID**。 ``` aws redshift-data describe-statement --id 130d2620-05d2-439c-b7cf-815d9767f513 ``` 在此範例中，已排程的 SQL `select * from users limit 100` 會導致 `users` 資料表不存在的 SQL 錯誤。 ``` { "CreatedAt": "2023-08-18T17:39:15.563000+00:00", "Duration": -1, "Error": "ERROR: relation \"users\" does not exist", "HasResultSet": false, "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "QueryString": "select * from users limit 100\n—RequestID=a1b2c3d4-5678-90ab-cdef-EXAMPLE22222; TraceID=1-633c5642-4039308d03f3a0ba53dbdf6f", "RedshiftPid": 1073766651, "RedshiftQueryId": 0, "ResultRows": -1, "ResultSize": -1, "Status": "FAILED", "UpdatedAt": "2023-08-18T17:39:16.116000+00:00", "WorkgroupName": "default" } ``` # 將查詢結果視覺化 在執行查詢並顯示結果後，您可以開啟**圖表**來顯示透過圖形加以視覺化的目前結果頁面。您可以使用下列控制項來定義圖表的內容、結構和外觀： ![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/add-plus.png) 追蹤 代表圖表中的一組相關圖形標記。您可以在圖表中定義多個追蹤。 Type 您可以定義追蹤類型以將資料表示為下列其中一項： + 散佈圖或氣泡圖。 + 長條圖，以垂直或水平長條表示資料類別。 + 區域圖，以定義填充區域。 + 直方圖，以使用長條表示頻率的分佈。 + 圓餅圖，以圓形表示資料，其中的每個切片各表示在整體中所佔的百分比。 + 漏斗圖或漏斗區域圖，以透過各個程序階段表示資料。 + OHLC (開盤-最高-最低-收盤) 圖，通常用於財務資料，以沿著 x 軸 (通常代表時間間隔) 表示開盤價、最高價、最低價和收盤價。 + 蠟燭圖，在時間線上表示某個類別一系列的值。 + 瀑布圖，透過一系列中間值來表示初始值的增減變化。這些值可以表示時間間隔或類別。 + 折線圖，表示值隨著時間推移的變化情形。 X 軸 您必須指定要沿著 X 軸繪製、含有值的資料表資料欄。包含描述性值的資料欄通常代表維度資料。包含量化值的資料欄通常代表事實資料。 Y 軸 您必須指定要沿著 Y 軸繪製、含有值的資料表資料欄。包含描述性值的資料欄通常代表維度資料。包含量化值的資料欄通常代表事實資料。 子圖 您可以定義圖表資料的其他呈現方式。 轉換 您可以定義轉換以篩選追蹤資料。您必須使用分割轉換以顯示來自單一來源追蹤的多個追蹤。您必須使用彙總轉換以將追蹤顯示為平均值或最小值。您必須使用排序轉換來排序追蹤。 一般外觀 您可以針對下列項目設定預設值：背景顏色、邊界顏色、用來設計色盤的色階、文字樣式和大小、標題樣式和大小，以及模式列。您可以定義拖曳、點按和暫留的互動效果。您可以定義中繼文字。您可以定義追蹤、軸、圖例和註釋的預設外觀。 **建立圖表** 1. 執行查詢並取得結果。 1. 開啟**圖表**。 1. 選擇**追蹤**並開始將資料視覺化。 1. 從下列其中一個選項中選擇圖表樣式： + 散佈圖 + 長條圖 + 區域圖 + 直方圖 + 圓餅圖 + 漏斗圖 + 漏斗區域圖 + OHLC (開盤-最高-最低-收盤) 圖 + 蠟燭圖 + 瀑布圖 + 折線圖 1. 選擇**樣式**以自訂外觀，包括顏色、軸、圖例和註釋。您可以新增文字、形狀和圖像。 1. 選擇**註釋**以新增文字、形狀和圖像。 1. 選擇**重新整理**以更新圖表顯示。選擇**全螢幕**以展開圖表顯示。 ## 範例：建立圓餅圖以將查詢結果視覺化 下列範例會使用範例資料庫的「Sales」**資料表。如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[範例資料庫](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html)。 以下是您為了提供圓餅圖資料所執行的查詢。 ``` select top 5 eventname, count(salesid) totalorders, sum(pricepaid) totalsales from sales, event where sales.eventid=event.eventid group by eventname order by 3; ``` **為按總銷售額排序的最佳活動建立圓餅圖** 1. 執行查詢。 1. 在查詢結果區域中，開啟**圖表**。 1. 選擇**追蹤**。 1. 對於**類型**，選擇**圓餅圖**。 1. 對於**值**，選擇 *totalsales*。 1. 對於**標籤**，選擇 *eventname*。 1. 選擇**樣式**，然後選擇**一般**。 1. 在**色階**底下，選擇**分類**，然後選擇 **Pastel2**。 ![\[圓餅圖\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/pie-chart.png) ## 範例：建立用於比較營收與銷售額的組合圖表 執行此範例中的步驟，以建立由營收資料的長條圖與銷售額資料的折線圖組合而成的圖表。下列範例會使用 tickit 範例資料庫的「Sales」**資料表。如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[範例資料庫](https://docs.aws.amazon.com/redshift/latest/dg/c_sampledb.html)。 以下是您為了提供圖表資料所執行的查詢。 ``` select eventname, total_price, total_qty_sold from (select eventid, total_price, total_qty_sold, ntile(1000) over(order by total_price desc) as percentile from (select eventid, sum(pricepaid) total_price, sum(qtysold) total_qty_sold from tickit.sales group by eventid)) Q, tickit.event E where Q.eventid = E.eventid and percentile = 1 order by total_price desc; ``` **建立用於比較營收與銷售額的組合圖表** 1. 執行查詢。 1. 在查詢結果區域中，開啟**圖表**。 1. 在*追蹤 o* 底下，對於**類型**，選擇**長條圖**。 1. 對於 **X**，選擇 *eventname*。 1. 對於 **Y**，請選擇 *total\$1price*。 長條圖會沿著 X 軸顯示活動名稱。 1. 在**樣式**底下，選擇**追蹤**。 1. 對於**名稱**，輸入*營收*。 1. 在**樣式**底下，選擇**軸**。 1. 對於**標題**，選擇 **Y** 並輸入*營收*。 *營收*標籤隨即會顯示在左側 Y 軸上。 1. 在**結構**底下，選擇**追蹤**。 1. 選擇 ![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/add-plus.png) **追蹤**。 追蹤 1 的選項隨即會顯示出來。 1. 對於**類型**，選擇**折線圖**。 1. 對於 **X**，選擇 *eventname*。 1. 對於 **Y**，選擇 *total\$1qty\$1sold*。 1. 在**要使用的軸**底下，對於 **Y 軸**選擇 ![\[Plus sign icon representing an addition or new item action.\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/add-plus.png)。 **Y 軸**便會顯示 *Y2*。 1. 在**樣式**底下，選擇**軸**。 1. 在**標題**底下，選擇 **Y2**。 1. 對於**名稱**，輸入 *Sales*。 1. 在**折線圖**底下，選擇 *Y:Sales*。 1. 在**軸線**底下，選擇**顯示**，然後對於**位置**，選擇**右**。 ![\[營收和銷售額圖表\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/chart-revenue-sales.png) ## 示範：使用 Amazon Redshift 查詢編輯器 v2 建置視覺效果 如需如何建置視覺效果的示範，請觀看下列影片。 [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/-FYqTIER-6U/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/-FYqTIER-6U) # 以團隊的形式協作和共用 您可以與團隊共用查詢。 您可以為一組會協作和共用查詢編輯器 v2 資源的使用者定義團隊。管理員可以透過將標籤新增至 IAM 角色來建立團隊。如需詳細資訊，請參閱[要使用查詢編輯器 v2 所需的許可](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor-v2)。 # 儲存和瀏覽查詢 在與團隊共用查詢前，請先儲存查詢。您可以檢視和刪除已儲存的查詢。 **儲存查詢** 1. 準備您的查詢並選擇**儲存**。 1. 為查詢輸入標題。 1. 選擇**儲存**。 **瀏覽已儲存的查詢** 1. 從導覽窗格選擇**查詢**。 1. 您可以檢視屬於**我的查詢**、**由我共用**或**共用給我的團隊**的查詢。這些查詢能以個別查詢的形式出現，也能出現在您建立的資料夾內。 # 共用查詢 您可以與團隊共用查詢。您也可以檢視已儲存查詢的歷史記錄並管理查詢版本。 若要與團隊共用查詢，請確定您已將主體標籤 `sqlworkbench-team` 設定為與帳戶中其他團隊成員相同的值。例如，管理員可以針對會計部門中的每個人，將值設定為 `accounting-team`。如需範例，請參閱 [要使用查詢編輯器 v2 所需的許可](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor-v2)。 **與團隊共用查詢** 1. 從導覽窗格選擇**查詢**。 1. 開啟您要共用之查詢的內容 (右鍵) 選單，然後選擇**與我的團隊共用**。 1. 選擇您要與其共用查詢的團隊，然後選擇**儲存共用選項**。 # 管理查詢版本 每次儲存 SQL 查詢時，查詢編輯器 v2 都會將其儲存為新的版本。您可以瀏覽較舊的查詢版本、儲存查詢的複本或還原查詢。 **管理查詢版本** 1. 從導覽窗格選擇**查詢**。 1. 開啟您要使用之查詢的內容 (右鍵) 選單。 1. 選擇**版本歷史記錄**以開啟查詢的版本清單。 1. 在**版本歷史記錄**頁面上，您可以執行下列操作： + **回復為選取項** — 回復為選取的版本，並繼續使用此版本。 + **另存選取項** — 在編輯器中建立新查詢。 # 使用 Amazon Redshift 查詢編輯器 v1 查詢資料庫 若要在 Amazon Redshift 叢集託管的資料庫上執行查詢，簡單的辦法是使用查詢編輯器。建立叢集後，您可以在 Amazon Redshift 主控台中使用查詢編輯器，立即執行查詢。 **注意** 您無法使用這個原始查詢編輯器在 Amazon Redshift Serverless 中查詢資料。請改用 Amazon Redshift 查詢編輯器 v2。 2021 年 2 月，我們部署了更新的查詢編輯器，並變更了可使用查詢編輯器的授權許可。新的查詢編輯器會使用 Amazon Redshift 資料 API 來執行查詢。`AmazonRedshiftQueryEditor` 政策是 AWS 受管 AWS Identity and Access Management (IAM) 政策，已更新為包含必要的許可。如果您有自訂 IAM 政策，請務必加以更新。請使用 `AmazonRedshiftQueryEditor` 作為指南。`AmazonRedshiftQueryEditor` 的變更包括下列內容： + 可管理查詢編輯器陳述式結果的許可需要陳述式擁有者使用者。 + 已新增使用 Secrets Manager 連線至資料庫的許可。 如需詳細資訊，請參閱[要使用 Amazon Redshift 主控台查詢編輯器所需的許可](redshift-iam-access-control-identity-based.md#redshift-policy-resources.required-permissions.query-editor)。 當您從新的查詢編輯器連線到叢集時，您可以使用下列兩種身分驗證方法之一。 您可以使用查詢編輯器執行下列作業： + 執行單一 SQL 陳述式查詢。 + 將最大 100 MB 的結果集下載到逗號分隔值 (CSV) 檔案。 + 儲存查詢供重複使用。您無法在歐洲 (巴黎) 區域、亞太區域 (大阪) 區域、亞太區域 (香港) 區域或中東 (巴林) 區域儲存查詢。 + 檢視使用者定義資料表的查詢執行時間詳細資訊。 + 將查詢排程在未來的時間執行。 + 檢視您在查詢編輯器中所建立查詢的歷史記錄。 + 使用增強的 VPC 路由對叢集執行查詢。 ## 查詢編輯器考量 在使用查詢編輯器時，請考慮下列有關使用查詢的事項： + 查詢的持續時間上限為 24 小時。 + 查詢結果大小上限為 100 MB。如果呼叫傳回的回應資料超過 100 MB，系統會終止呼叫。 + 查詢結果的保留時間上限為 24 小時。 + 查詢陳述式的大小上限為 100 KB。 + 叢集必須位於以 Amazon VPC 服務為基礎的虛擬私有雲端 (VPC) 中。 + 您不能在查詢編輯器中使用交易。如需交易的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [BEGIN](https://docs.aws.amazon.com/redshift/latest/dg/r_BEGIN.html)。 + 您可以儲存長度最多 3,000 個字元的查詢。 # 使用 SQL 用戶端工具連線至 Amazon Redshift 資料倉儲 您可以從 SQL 用戶端工具透過 Java 資料庫連線 (JDBC)、Python 和開放式資料庫連線 (ODBC) 的連線來連線至 Amazon Redshift 資料倉儲。Amazon Redshift 不會提供或安裝任何 SQL 用戶端工具或程式庫。若要使用這些工具或程式庫來處理資料倉儲中的資料，請將其安裝在用戶端電腦或 Amazon EC2 執行個體上。您可以使用支援 JDBC、Python 或 ODBC 驅動程式的大多數 SQL 用戶端工具。 使用本主題結尾的章節清單，可協助您逐步完成將用戶端電腦或 Amazon EC2 執行個體設定為使用 JDBC、Python 或 ODBC 連線的程序。這些主題也會討論用戶端與伺服器連線的相關安全選項。此外，請尋找有關從 SQL 用戶端工具 (例如 [Amazon Redshift RSQL](https://docs.aws.amazon.com/redshift/latest/mgmt/rsql-query-tool.html)) 進行設定和連線的資訊。如果您還沒有商業智慧工具可使用，則可以嘗試這些工具。您也可以利用本節來了解如何連線至叢集。最後，如果您在嘗試連線至資料倉儲時遇到問題，您可以檢閱故障診斷資訊來找出解決方案。 ## 透過用戶端工具連線的建議 如果您使用 IP 位址連線至 Redshift 叢集，當發生中斷或連線中斷，且叢集在新的可用區域 (AZ) 中上線時，可能會導致更長的停機時間。不過，如果您仍希望應用程式使用 IP 位址連線到 Redshift，請使用附加到叢集的虛擬私有雲端 (VPC) 端點的私有 IP 位址。您可以在**屬性**索引標籤下，於**網路和安全**的叢集詳細資訊中找到此資訊。 **注意** 如果您的應用程式使用領導節點的 IP 位址來存取 Redshift 叢集，則建議的最佳實務是改為使用叢集端點 URL。如需詳細資訊，請參閱[在 Amazon Redshift 中設定連線](https://docs.aws.amazon.com/redshift/latest/mgmt/configuring-connections.html)。 **Topics** + [透過用戶端工具連線的建議](#connecting-to-cluster-recommendations) + [在 Amazon Redshift 中設定連線](configuring-connections.md) + [設定連線的安全選項](connecting-ssl-support.md) + [從用戶端工具和程式碼連線](connecting-via-client-tools.md) + [使用身分驗證設定檔連線至 Amazon Redshift](connecting-with-authentication-profiles.md) + [針對 Amazon Redshift 中的連線問題進行疑難排解](troubleshooting-connections.md) # 在 Amazon Redshift 中設定連線 在下一節中，您會了解如何設定 JDBC、Python 和 ODBC 連線，以從 SQL 用戶端工具連線至叢集。本節描述如何設定 JDBC、Python 和 ODBC 連線。也描述如何使用 Secure Sockets Layer (SSL) 和伺服器憑證，以加密用戶端與伺服器之間的通訊。 ## 適用於 Amazon Redshift 的 JDBC、Python 和 ODBC 驅動程式 若要處理叢集中的資料，您必須具有 JDBC、Python 或 ODBC 驅動程式，以便從用戶端電腦或執行個體來連線。將應用程式編寫為使用 JDBC、Python 或 ODBC 資料存取 API 操作，並使用支援 JDBC、Python 或 ODBC 的 SQL 用戶端工具。 Amazon Redshift 提供了 JDBC、Python 和 ODBC 驅動程式供您下載。支援這些驅動程式 支援。PostgreSQL 驅動程式未經過測試，因此未獲得 Amazon Redshift 團隊的支援。在連線至 Amazon Redshift 叢集時，請使用 Amazon Redshift 特定的驅動程式。Amazon Redshift 驅動程式有下列優點： + 支援 IAM、SSO 和聯合身分驗證。 + 支援新的 Amazon Redshift 資料類型。 + 支援身分驗證設定檔。 + 與 Amazon Redshift 增強功能搭配使用而提升了效能。 如需如何下載 JDBC 和 ODBC 驅動程式及設定叢集連線的相關資訊，請參閱 [設定適用於 Amazon Redshift 的 JDBC 驅動器 2.x 版的連線](jdbc20-install.md)、[Amazon Redshift Python 連接器](python-redshift-driver.md) 和 [設定 Amazon Redshift ODBC 驅動程式 2.x 版連線](odbc20-install.md)。 如需如何管理 IAM 身分的相關資訊 (包括 IAM 角色的最佳實務)，請參閱 [Amazon Redshift 中的身分和存取管理](redshift-iam-authentication-access-control.md)。 # 尋找叢集連線字串 若要使用 SQL 用戶端工具來連線至叢集，您必須有叢集連線字串。您可以在 Amazon Redshift 主控台的叢集詳細資訊頁面上找到叢集連線字串。 **尋找叢集的連線字串** 1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/redshiftv2/](https://console.aws.amazon.com/redshiftv2/)：// 開啟 Amazon Redshift 主控台。 1. 在導覽功能表上，選擇**叢集**，然後從清單中選擇叢集名稱以開啟其詳細資訊。 1. **General information** (一般資訊) 區段中提供了 **JDBC URL** 和 **ODBC URL** 連線字串，以及其他詳細資訊。每個字串都以叢集執行 AWS 的區域為基礎。按一下適當連線字串旁邊的圖示以複製連線字串。 若要連線至叢集端點，您可以從 [DescribeClusters API 請求](https://docs.aws.amazon.com/redshift/latest/APIReference/API_DescribeClusters.html)使用叢集端點 URL。以下是叢集端點 URL 的範例。 ``` mycluster.cmeaswqeuae.us-east-2.redshift.amazonaws.com ``` 如果您已經為叢集設定了自訂網域名稱，您也可以使用該名稱來連線至叢集。如需建立自訂網域名稱的相關資訊，請參閱[設定自訂網域名稱](https://docs.aws.amazon.com/redshift/latest/mgmt/connecting-connection-CNAME-connect.html)。 **注意** 連線時，請勿使用叢集節點的 IP 地址或 VPC 端點的 IP 地址。請一律使用 Redshift 端點，以避免發生不必要的中斷。唯一會使用端點 URL 的例外狀況是當您使用自訂網域名稱時。如需詳細資訊，請參閱[使用自訂網域名稱來進行用戶端連線](https://docs.aws.amazon.com/redshift/latest/mgmt/connecting-connection-CNAME.html)。 # 設定適用於 Amazon Redshift 的 JDBC 驅動器 2.x 版的連線 您可以從許多第三方 SQL 用戶端工具使用 JDBC 驅動器 2.x 版連線來連線至 Amazon Redshift 叢集。Amazon Redshift JDBC 連接器會提供開放原始碼的解決方案。您可以瀏覽原始碼、請求增強功能、回報問題並提供貢獻。 如需 JDBC 驅動器變更的最新資訊，請參閱[變更日誌](https://github.com/aws/amazon-redshift-jdbc-driver/blob/master/CHANGELOG.md)。 依預設，Amazon Redshift JDBC 驅動程式會設定為使用 TCP 保持連線，以防止連線逾時。您可以指定驅動程式何時開始傳送保持連線封包，或在連線 URL 中設定相關屬性來關閉此功能。如需連線 URL 語法的相關資訊，請參閱[建置連線 URL](jdbc20-build-connection-url.md)。 | 屬性 | Description | | --- | --- | | `TCPKeepAlive` | 若要關閉 TCP 保持連線，請將此屬性設定為 `FALSE`。 | **Topics** + [下載 Amazon Redshift JDBC 驅動程式 2.1 版](jdbc20-download-driver.md) + [安裝 Amazon Redshift JDBC 驅動程式 2.2 版](jdbc20-install-driver.md) + [取得 JDBC URL](jdbc20-obtain-url.md) + [建置連線 URL](jdbc20-build-connection-url.md) + [使用 Apache Maven 設定 JDBC 連線](configure-jdbc20-connection-with-maven.md) + [設定身分驗證和 SSL](jdbc20-configure-authentication-ssl.md) + [設定 記錄](jdbc20-configuring-logging.md) + [資料類型轉換](jdbc20-data-type-mapping.md) + [使用預備陳述式支援](jdbc20-prepared-statement-support.md) + [JDBC 驅動程式的 2.2 和 1.x 版本之間的差異](jdbc20-jdbc10-driver-differences.md) + [建立 JDBC 驅動器 2.x 版的初始化 (.ini) 檔案](jdbc20-ini-file.md) + [JDBC 驅動器 2.x 版組態的選項](jdbc20-configuration-options.md) + [JDBC 驅動器 2.x 版之前的版本](jdbc20-previous-driver-version-20.md) # 下載 Amazon Redshift JDBC 驅動程式 2.1 版 **注意** Amazon Redshift JDBC 2.x 驅動器並非專為執行緒安全所設計。若有兩個或多個執行緒嘗試以並行方式使用相同連線，可能會導致死結、錯誤、不正確的結果或其他非預期的行為。 如果您擁有多執行緒應用程式，建議您同步驅動器的存取，以避免並行存取。 Amazon Redshift 為與 JDBC 4.2 API 相容的工具提供了驅動程式。此驅動程式的類別名稱為 `com.amazon.redshift.Driver`。 如需如何安裝 JDBC 驅動程式、參考 JDBC 驅動程式庫，以及註冊驅動程式類別的詳細資訊，請參閱下列主題。 對於您使用 Amazon Redshift JDBC 驅動器 2.x 版的每部電腦，請確定其已安裝 Java 執行階段環境 (JRE) 8.0。 如果您使用 Amazon Redshift JDBC 驅動程式進行資料庫身分驗證，請確定您在 Java 類別路徑中具有 適用於 Java 的 AWS SDK 1.11.118 或更新版本。如果您尚未 適用於 Java 的 AWS SDK 安裝 ，請使用 AWS 開發套件的 JDBC 4.2 相容驅動程式和驅動程式相依程式庫下載 ZIP 檔案： + [JDBC 4.2 相容驅動程式 2.x 版和 AWS SDK 驅動程式相依程式庫](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.5/redshift-jdbc42-2.2.5.zip) 此 ZIP 檔案包含 JDBC 4.2 相容驅動器 2.x 版和適用於 Java 的 AWS SDK 1.x 驅動器相依程式庫檔案。將相依 jar 檔案解壓縮到與 JDBC 驅動程式相同的位置。只有 JDBC 驅動程式需要在 CLASSPATH 中。 此 ZIP 檔案不包含適用於 Java 1.x 的完整 AWS SDK。不過，它包含 AWS Identity and Access Management (IAM) 資料庫身分驗證所需的適用於 Java 的 AWS SDK 1.x 驅動程式相依程式庫。 將此 Amazon Redshift JDBC 驅動程式與 IAM 資料庫身分驗證所需的 AWS SDK 搭配使用。 若要安裝適用於 Java 1.x 的完整 AWS 開發套件，請參閱《 *適用於 Java 的 AWS SDK 開發人員指南*》中的[AWS 適用於 Java 1.x 的開發套件](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/welcome.html)。 + 與 [JDBC 4.2 相容的驅動程式 2.x 版 （不含 AWS SDK)](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.5/redshift-jdbc42-2.2.5.jar) 檢閱 JDBC 驅動器 2.x 版軟體授權和變更日誌檔案： + [JDBC 驅動器 2.x 版授權](https://github.com/aws/amazon-redshift-jdbc-driver/blob/master/LICENSE) + [JDBC 驅動器 2.x 版變更日誌](https://github.com/aws/amazon-redshift-jdbc-driver/blob/master/CHANGELOG.md) JDBC 驅動程式 1.2.27.1051 版和更新版本支援 Amazon Redshift 預存程序。如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[在 Amazon Redshift 中建立預存程序](https://docs.aws.amazon.com/redshift/latest/dg/stored-procedure-overview.html)。 # 安裝 Amazon Redshift JDBC 驅動程式 2.2 版 若要安裝適用於 AWS SDK 的 Amazon Redshift JDBC 4.2 相容驅動程式 2.x 版和驅動程式相依程式庫，請將 ZIP 封存檔中的檔案擷取至您選擇的目錄。 若要安裝 Amazon Redshift JDBC 4.2 相容驅動器 2.x 版 (不含 AWS SDK)，請將 JAR 檔案複製到您選擇的目錄。 若要使用 Amazon Redshift JDBC 驅動程式存取 Amazon Redshift 資料存放區，您需要如下所述地執行組態。 **Topics** + [參考 JDBC 驅動程式庫](jdbc20-driver-libraries.md) + [註冊驅動程式類別](jdbc20-register-driver-class.md) # 參考 JDBC 驅動程式庫 您用來連線至資料的 JDBC 應用程式或 Java 程式碼必須存取驅動程式 JAR 檔案。請在應用程式或程式碼中，指定您從 ZIP 封存檔中解壓縮的所有 JAR 檔案。 ## 在 JDBC 應用程式中使用驅動程式 JDBC 應用程式通常會提供一組用於新增驅動程式庫檔案清單的組態選項。請使用所提供的選項，將 ZIP 封存檔中的所有 JAR 檔案納入為應用程式中驅動程式組態的一部分。如需詳細資訊，請參閱 DNS 應用程式的文件。 ## 在 Java 程式碼中使用驅動程式 您必須在類別路徑中包含所有驅動程式庫檔案。Java 執行階段環境會在此路徑中搜尋類別和其他資源檔案。如需詳細資訊，請參閱適當的 Java SE 文件，以便為您的作業系統設定類別路徑。 + Windows：[https://docs.oracle.com/javase/7/docs/technotes/tools/windows/classpath.html](https://docs.oracle.com/javase/7/docs/technotes/tools/windows/classpath.html) + Linux 和 Solaris：[https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/classpath.html](https://docs.oracle.com/javase/7/docs/technotes/tools/solaris/classpath.html) + macOS：預設 macOS 類別路徑是安裝 JDBC 驅動程式的目錄。 # 註冊驅動程式類別 請務必為您的應用程式註冊適當的類別。您可以使用下列類別將 Amazon Redshift JDBC 驅動程式連線到 Amazon Redshift 資料存放區： + `Driver` 類別會擴展 `java.sql.Driver`。 + `DataSource` 類別會擴展 `javax.sql.DataSource` 和 `javax.sql.ConnectionPoolDataSource`。 該驅動程式支援下列完整類別名稱 (與 JDBC 版本無關)： + `com.amazon.redshift.jdbc.Driver` + `com.amazon.redshift.jdbc.DataSource` 下列範例示範如何使用 DriverManager 類別建立 JDBC 4.2 連線。 ``` private static Connection connectViaDM() throws Exception { Connection connection = null; connection = DriverManager.getConnection(CONNECTION_URL); return connection; } ``` 下列範例示範如何使用 `DataSource` 類別建立連線。 ``` private static Connection connectViaDS() throws Exception { Connection connection = null; 11 Amazon Redshift JDBC Driver Installation and Configuration Guide DataSource ds = new com.amazon.redshift.jdbc.DataSource (); ds.setURL(CONNECTION_URL); connection = ds.getConnection(); return connection; } ``` # 取得 JDBC URL 您需要先知道叢集的 JDBC URL，才能從 SQL 用戶端工具連線至 Amazon Redshift 叢集。JDBC URL 採用下列格式：`jdbc:redshift://endpoint:port/database` 前面格式的欄位具有下列值。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/jdbc20-obtain-url.html) 以下是 JDBC URL 範例：`jdbc:redshift://examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com:5439/dev` 如果您的 URL 值包含下列任何 URI 保留字元，則值必須經過 URL 編碼： + ; + \$1 + \$1 + \$1 + [ + ] + & + = + ? + 空格 例如，如果您的 `PWD` 值是 `password:password`，則使用該值的連線 URL 看起來如下： `jdbc:redshift://redshift.company.us-west-1.redshift.amazonaws.com:9000/dev;UID=amazon;PWD=password%3Apassword` 如需如何取得 JDBC 連線的資訊，請參閱[尋找叢集連線字串](connecting-connection-string.md)。 如果用戶端電腦無法連線至資料庫，您可以對可能的問題進行疑難排解。如需詳細資訊，請參閱[針對 Amazon Redshift 中的連線問題進行疑難排解](troubleshooting-connections.md)。 # 建置連線 URL 使用連線 URL 為您要存取的資料存放區提供連線資訊。以下是 Amazon Redshift JDBC 驅動器 2.x 版的連線 URL 格式。在這裡，[Host] 是 Amazon Redshift 伺服器的端點，[Port] 是伺服器用來接聽用戶端請求的傳輸控制通訊協定 (TCP) 連接埠號碼。 ``` jdbc:redshift://[Host]:[Port] ``` 以下是會指定某些選擇性設定的連線 URL 格式。 ``` jdbc:redshift://[Host]:[Port]/[database];[Property1]=[Value]; [Property2]=[Value]; ``` 如果您的 URL 值包含下列任何 URI 保留字元，則值必須經過 URL 編碼： + ; + \$1 + \$1 + \$1 + [ + ] + & + = + ? + 空格 例如，如果您的 `PWD` 值是 `password:password`，則使用該值的連線 URL 看起來如下： `jdbc:redshift://redshift.company.us-west-1.redshift.amazonaws.com:9000/dev;UID=amazon;PWD=password%3Apassword` 例如，假設您想要連線至 AWS上美國西部 (加利佛尼亞北部) 區域中 Amazon Redshift 叢集上的連接埠 9000。您也想要存取名為 `dev` 的資料庫，並使用資料庫使用者名稱和密碼來驗證連線。在此情況下，您會使用下列連線 URL。 ``` jdbc:redshift://redshift.company.us-west-1.redshift.amazonaws.com:9000/dev;UID=amazon;PWD=amazon ``` 您可以使用下列字元將組態選項與 URL 字串的其餘部分隔開： + ; + ? 例如，下面兩個 URL 字串是相等的： ``` jdbc:redshift://my_host:5439/dev;ssl=true;defaultRowFetchSize=100 ``` ``` jdbc:redshift://my_host:5439/dev?ssl=true;defaultRowFetchSize=100 ``` 您可以使用下列字元將 URL 字串中的組態選項彼此隔開： + ; + & 例如，下面兩個 URL 字串是相等的： ``` jdbc:redshift://my_host:5439/dev;ssl=true;defaultRowFetchSize=100 ``` ``` jdbc:redshift://my_host:5439/dev;ssl=true&defaultRowFetchSize=100 ``` 下列 URL 範例會指定日誌層級 6 以及日誌的路徑。 ``` jdbc:redshift://redshift.amazonaws.com:5439/dev;DSILogLevel=6;LogPath=/home/user/logs; ``` 請勿複製連線 URL 中的屬性。 如需可指定之組態選項的完整清單，請參閱 [JDBC 驅動器 2.x 版組態的選項](jdbc20-configuration-options.md)。 **注意** 連線時，請勿使用叢集節點的 IP 地址或 VPC 端點的 IP 地址。請一律使用 Redshift 端點，以避免發生不必要的中斷。唯一會使用端點 URL 的例外狀況是當您使用自訂網域名稱時。如需詳細資訊，請參閱[使用自訂網域名稱來進行用戶端連線](https://docs.aws.amazon.com/redshift/latest/mgmt/connecting-connection-CNAME.html)。 # 使用 Apache Maven 設定 JDBC 連線 Apache Maven 是軟體專案管理和理解工具。 適用於 Java 的 AWS SDK 支援 Apache Maven 專案。如需詳細資訊，請參閱《適用於 Java 的 AWS SDK 開發人員指南》**中的[搭配使用 SDK 與 Apache Maven](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-project-maven.html)。 如果您使用 Apache Maven，您可以將專案設定和建置為使用 Amazon Redshift JDBC 驅動程式來連線至 Amazon Redshift 叢集。若要執行此作業，請在專案的 `pom.xml` 檔案中，將 JDBC 驅動程式新增為相依性。如果您使用 Maven 來建置專案，且想要使用 JDBC 連線，請採取下節中的步驟。 **將 JDBC 驅動程式設定為 Maven 相依性** 1. 將 Amazon 儲存庫或 Maven Central 儲存庫新增到 `pom.xml` 檔案的儲存庫區段。 **注意** 下列程式碼範例中的 URL 在瀏覽器中使用時會傳回錯誤。僅在 Maven 項目的內容中使用此 URL。 若要使用 Secure Sockets Layer (SSL) 來連線，請將下列儲存庫新增至 `pom.xml` 檔案。 ``` redshift https://s3.amazonaws.com/redshift-maven-repository/release ``` 若為 Maven Central 儲存庫，請將以下內容新增到 `pom.xml` 檔案。 ``` redshift https://repo1.maven.org/maven2 ``` 1. 在 `pom.xml` 檔案的相依性區段中，宣告您要使用的驅動程式版本。 Amazon Redshift 為與 JDBC 4.2 API 相容的工具提供了驅動程式。如需這些驅動程式所支援功能的相關資訊，請參閱[下載 Amazon Redshift JDBC 驅動程式 2.1 版](jdbc20-download-driver.md)。 以您的驅動程式版本取代下列範例中的 `driver-version`，例如 `2.1.0.1`。若為 JDBC 4.2 相容驅動程式，請使用以下內容。 ``` com.amazon.redshift redshift-jdbc42 driver-version ``` 此驅動程式的類別名稱為 `com.amazon.redshift.Driver`。 當您使用 IAM 資料庫身分驗證時，Amazon Redshift Maven 驅動程式需要下列選擇性相依性。 ``` com.amazonaws aws-java-sdk-core 1.12.23 runtime true com.amazonaws aws-java-sdk-redshift 1.12.23 runtime true com.amazonaws aws-java-sdk-sts 1.12.23 runtime true ``` 若要將 Amazon Redshift JDBC 驅動程式升級或變更為最新版本，請先將相依性的版本區段修改為驅動程式的最新版本。然後以 Maven Clean Plugin 來清理專案，如下所示。 ``` mvn clean ``` # 設定身分驗證和 SSL 為了防止有人未經授權就存取資料，Amazon Redshift 資料存放區會要求所有連線使用使用者憑證進行身分驗證。某些資料存放區還會要求必須透過 Secure Sockets Layer (SSL) 通訊協定來進行連線 (無論是否使用單向身分驗證)。 Amazon Redshift JDBC 驅動器 2.x 版會針對這些身分驗證通訊協定提供完整支援。 驅動程式支援的 SSL 版本取決於您使用的 JVM 版本。如需每個 Java 版本所支援之 SSL 版本的相關資訊，請參閱 Java Platform Group Product Management 部落格上的[診斷 TLS、SSL 和 HTTPS](https://blogs.oracle.com/java-platform-group/diagnosing-tls,-ssl,-and-https)。 用於連線的 SSL 版本是驅動程式和伺服器支援的最高版本，而這會在連線時確定。 將 Amazon Redshift JDBC 驅動器 2.x 版設定為根據您要連線之 Redshift 伺服器的安全需求驗證您的連線。 您一律必須提供 Redshift 使用者名稱和密碼來驗證連線。根據伺服器上是否啟用且需要 SSL，您可能還需要將驅動程式設定為透過 SSL 連接。或者，您也可以使用單向 SSL 身分驗證，以便用戶端 (驅動程式本身) 驗證伺服器的身分。 您要在連線 URL 中提供組態資訊給驅動程式。如需連線 URL 語法的相關資訊，請參閱[建置連線 URL](jdbc20-build-connection-url.md)。 *SSL* 表示 TLS/SSL，兩者分別是 Transport Layer Security 和 Secure Sockets Layer。此驅動程式支援業界標準的 TLS/SSL 版本。 ## 設定 IAM 身分驗證 如果您要使用 IAM 身分驗證連線至 Amazon Redshift 伺服器，請將以下屬性設定為資料來源連線字串的一部分。 如需 IAM 身分驗證的相關資訊，請參閱 [Amazon Redshift 中的身分和存取管理](redshift-iam-authentication-access-control.md)。 若要使用 IAM 身分驗證，請使用下列其中一種連線字串格式： | 連接字串 | Description | | --- | --- | | `jdbc:redshift:iam:// [host]:[port]/[db]` | 一般連線字串。驅動程式會從主機推斷 ClusterID 和 Region。 | | `jdbc:redshift:iam:// [cluster-id]: [region]/[db]` | 驅動程式會擷取主機資訊 (在給定 ClusterID D 和 Region 的情況下)。 | | `jdbc:redshift:iam:// [host]/[db]` | 驅動程式會預設為連接埠 5439，並從主機推斷 ClusterID 和 Region。根據您在建立、修改或遷移叢集時所選取的連接埠而定，允許存取選取的連接埠。 | ## 指定設定檔 如果您要使用 IAM 身分驗證，則可以在設定檔名稱下指定任何其他必要或選擇性的連線屬性。這樣做可讓您避免將某些資訊直接放在連線字串中。您可以使用 Profile 屬性在連線字串中指定設定檔名稱。 設定檔可以新增至 AWS 登入資料檔案。此檔案的預設位置是：`~/.aws/credentials`。 您可以在下列環境變數中設定路徑來變更預設值：`AWS_CREDENTIAL_PROFILES_FILE` 如需設定檔的相關資訊，請參閱《適用於 Java 的 AWS SDK》**中的[使用 AWS 憑證](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html)。 ## 使用執行個體設定檔憑證 如果您要在與 IAM 角色關聯的 Amazon EC2 執行個體上執行應用程式，您可以使用執行個體設定檔憑證進行連線。 若要這麼做，請使用前述資料表中的其中一種 IAM 連線字串格式，並將 dbuser 連線屬性設定為您要用來連線的 Amazon Redshift 使用者名稱。 如需執行個體設定檔的相關資訊，請參閱《IAM 使用者指南》**中的[存取管理](https://docs.aws.amazon.com/IAM/latest/UserGuide/access.html)。 ## 使用憑證提供者 此驅動程式也支援下列服務的憑證提供者外掛程式： + AWS IAM Identity Center + Active Directory Federation Service (ADFS) + JSON Web 權杖 (JWT) 服務 + Microsoft Azure Active Directory (AD) 服務和瀏覽器 Microsoft Azure Active Directory (AD) 服務 + Okta 服務 + PingFederate 服務 + 適用於 SAML 服務的瀏覽器 SAML，例如 Okta、Ping 或 ADFS 如果您使用這些服務的其中一個，連線 URL 必須指定下列屬性： + **Plugin\$1Name** — 憑證提供者外掛程式類別的完整類別路徑。 + **IDP\$1Host** — 您用來對 Amazon Redshift 進行身分驗證的服務主機。 + **IdP\$1Port** — 用於身分驗證服務的主機監聽的連接埠。Okta 不需要此屬性。 + **User** - idp\$1host 伺服器的使用者名稱。 + **Password** - 與 idp\$1host 使用者名稱相關聯的密碼。 + **DbUser** - 您用來連線的 Amazon Redshift 使用者名稱。 + **SSL\$1Insecure** — 指出是否應驗證 IDP 伺服器憑證。 + **Client\$1ID** - 與 Azure AD 入口網站中的使用者名稱相關聯的用戶端 ID。僅用於 Azure AD。 + **Client\$1Secret** — 與 Azure AD 入口網站中的用戶端 ID 相關聯的用戶端祕密。僅用於 Azure AD。 + **IdP\$1Tenant** — Amazon Redshift 應用程式的 Azure AD 租用戶 ID。僅用於 Azure AD。 + **App\$1ID** — Amazon Redshift 應用程式的 Okta 應用程式 ID。僅用於 Okta。 + **App\$1Name** — Amazon Redshift 應用程式的 Okta 應用程式名稱 (選擇性)。僅用於 Okta。 + **Partner\$1SPID** — 選擇性的合作夥伴 SPID (服務提供者 ID) 值。僅用於 PingFederate。 + **Idc\$1Region** – IAM Identity Center AWS 區域 AWS 執行個體所在的 。僅用於 AWS IAM Identity Center。 + **Issuer\$1Url** – AWS IAM Identity Center 伺服器的執行個體端點。僅用於 AWS IAM Identity Center。 如果您使用這些服務其中之一的瀏覽器外掛程式，連線 URL 也可以包括： + **Login\$1URL** — 透過瀏覽器外掛程式使用安全性聲明標記語言 (SAML) 或 Azure AD 服務時，身分提供者網站上資源的 URL。如果您使用瀏覽器外掛程式，則必須要有此參數。 + **Listen\$1Port** – 透過瀏覽器外掛程式使用 SAML、Azure AD 或 IAM Identity Center AWS 服務時，驅動程式用來從身分提供者取得 SAML 回應的連接埠。 + **IdP\$1Response\$1Timeout** – 透過瀏覽器外掛程式使用 SAML、Azure AD 或 IAM Identity Center AWS 服務時，驅動程式等待來自身分提供者的 SAML 回應的時間，以秒為單位。 如需其他連線字串屬性的資訊，請參閱 [JDBC 驅動器 2.x 版組態的選項](jdbc20-configuration-options.md)。 # 僅使用使用者名稱和密碼 如果您要連線的伺服器未使用 SSL，您只需要提供 Redshift 使用者名稱和密碼即可驗證連線。 **僅使用 Redshift 使用者名稱和密碼來設定身分驗證** 1. 將 `UID` 屬性設定為用於存取 Amazon Redshift 伺服器的 Redshift 使用者名稱。 1. 將 PWD 屬性設定為與 Redshift 使用者名稱對應的密碼。 # 使用 SSL 但不進行身分驗證 如果您要連線的伺服器使用 SSL，但不需要進行身分驗證，則您可以將驅動程式設定為使用非驗證 SSL Factory。 **設定沒有身分驗證的 SSL 連線** 1. 將 `UID` 屬性設定為用於存取 Amazon Redshift 伺服器的 Redshift 使用者名稱。 1. 將 `PWD` 屬性設定為與 Redshift 使用者名稱對應的密碼。 1. 將 `SSLFactory` 屬性設定為 `com.amazon.redshift.ssl.NonValidatingFactory`。 # 使用單向 SSL 身分驗證 如果您要連線的伺服器使用 SSL 且具有憑證，則您可以將驅動程式設定為使用單向身分驗證來驗證伺服器的身分。 單向身分驗證需要已簽署的受信任 SSL 憑證來驗證伺服器的身分。您可以將驅動程式設定為使用特定憑證，或存取包含適當憑證的 TrustStore。如果您未指定憑證或 TrustStore，則驅動程式會使用預設的 Java TrustStore (一般是 `jssecacerts` 或 `cacerts`)。 **設定單向 SSL 身分驗證** 1. 將 UID 屬性設定為用於存取 Amazon Redshift 伺服器的 Redshift 使用者名稱。 1. 將 PWD 屬性設定為與 Redshift 使用者名稱對應的密碼。 1. 將 SSL 屬性設為 true。 1. 將 SSLRootCert 屬性設定為根 CA 憑證的位置。 1. 如果您未使用其中一個預設的 Java TrustStore，請執行以下其中一項操作： + 若要指定伺服器憑證，請將 SSLRootCert 屬性設定為憑證的完整路徑。 + 若要指定 TrustStore，請執行以下操作： 1. 使用 keytool 程式，將伺服器憑證新增至您要使用的 TrustStore。 1. 指定要在使用驅動程式啟動 Java 應用程式時使用的 TrustStore 和密碼。例如： ``` -Djavax.net.ssl.trustStore=[TrustStoreName] -Djavax.net.ssl.trustStorePassword=[TrustStorePassword] -Djavax.net.ssl.trustStoreType=[TrustStoreType] ``` 1. 選擇一項： + 若要驗證憑證，請將 SSLMode 屬性設定為 verify-ca。 + 若要驗證憑證並驗證憑證中的主機名稱，請將 SSLMode 屬性設定為 verify-full。 # 設定 記錄 您可以在驅動程式中開啟日誌記錄功能，以協助診斷問題。 您可以使用下列方法記錄驅動程式資訊： + 若要將記錄的資訊儲存在 .log 檔案中，請參閱[使用日誌檔案](jdbc20-using-log-files.md)。 + 若要將記錄的資訊傳送到 DriverManager 中指定的 LogStream 或 LogWriter，請參閱[使用 LogStream 或 LogWriter](jdbc20-logstream-option.md)。 您要在連線 URL 中提供組態資訊給驅動程式。如需連線 URL 語法的相關資訊，請參閱[建置連線 URL](jdbc20-build-connection-url.md)。 # 使用日誌檔案 日誌記錄功能應該要開啟到足以找到問題的時間長度就好。日誌記錄功能會降低效能，而且還會消耗大量磁碟空間。 在連線 URL 中設定 LogLevel 機碼以開啟日誌記錄功能，並指定日誌檔案中包含的詳細資訊數量。下表列出 Amazon Redshift JDBC 驅動器 2.x 版所提供的日誌記錄層級 (排序方式為最不詳細到最詳細)。 | LogLevel 值 | Description | | --- | --- | | 1 | 記錄會導致驅動程式中止的嚴重錯誤事件。 | | 2 | 記錄可能允許驅動程式繼續執行的錯誤事件。 | | 3 | 未採取動作時可能會導致錯誤的日誌事件。這個層級的日誌記錄和這個層級以上的日誌記錄層級也會記錄使用者的查詢。 | | 4 | 記錄用於描述驅動程式進展的一般資訊。 | | 5 | 記錄有助於偵錯驅動程式的詳細資訊。 | | 6 | 記錄所有驅動程式活動。 | **設定會使用日誌檔案的日誌記錄功能** 1. 將 LogLevel 屬性設定為要包含在日誌檔案中的所需資訊層級。 1. 將 LogPath 屬性設定為用來儲存日誌檔案之資料夾的完整路徑。 例如，下列連線 URL 會啟用日誌記錄層級 3，並將日誌檔案儲存在 C:\$1temp 資料夾：`jdbc:redshift://redshift.company.us-west- 1.redshift.amazonaws.com:9000/Default;DSILogLevel=3;LogPath=C:\temp` 1. 若要確保新設定生效，請重新啟動 JDBC 應用程式並重新連線至伺服器。 Amazon Redshift JDBC 驅動程式會在 LogPath 屬性中指定的位置產生下列日誌檔案： + redshift\$1jdbc.log 檔案，會記錄非連線特定的驅動程式活動。 + redshift\$1jdbc\$1connection\$1[Number].log 檔案，會針對向資料庫建立的每個連線產生此檔案，其中 [Number] 是用來識別每個日誌檔案的編號。此檔案會記錄連線特定的驅動程式活動。 如果 LogPath 值無效，則驅動程式會將日誌記錄資訊傳送至標準輸出串流 (`System.out`) # 使用 LogStream 或 LogWriter 日誌記錄功能應該要開啟到足以找到問題的時間長度就好。日誌記錄功能會降低效能，而且還會消耗大量磁碟空間。 在連線 URL 中設定 LogLevel 機碼以開啟日誌記錄功能，並指定傳送至 DriverManager 中所指定 LogStream 或 LogWriter 的詳細資訊數量。 **若要開啟使用 LogStream 或 LogWriter 的日誌記錄功能：** 1. 若要設定驅動程式以記錄描述驅動程式進度的一般資訊，請將 LogLevel 屬性設定為 1 或 INFO。 1. 若要確保新設定生效，請重新啟動 JDBC 應用程式並重新連線至伺服器。 # 資料類型轉換 Amazon Redshift JDBC 驅動器 2.x 版支援許多常見的資料格式，可在 Amazon Redshift、SQL 和 Java 資料類型之間進行轉換。 下表列出支援的資料類型映射。 | Amazon Redshift 類型 | SQL 類型 | Java 類型 | | --- | --- | --- | | BIGINT | SQL\$1BIGINT | Long | | BOOLEAN | SQL\$1BIT | Boolean | | CHAR | SQL\$1CHAR | String | | DATE | SQL\$1TYPE\$1DATE | java.sql.Date | | DECIMAL | SQL\$1NUMERIC | BigDecimal | | DOUBLE PRECISION | SQL\$1DOUBLE | Double | | GEOMETRY | SQL\$1 LONGVARBINARY | byte[] | | INTEGER | SQL\$1INTEGER | Integer | | OID | SQL\$1BIGINT | Long | | SUPER | SQL\$1LONGVARCHAR | String | | REAL | SQL\$1REAL | Float | | SMALLINT | SQL\$1SMALLINT | Short | | TEXT | SQL\$1VARCHAR | String | | TIME | SQL\$1TYPE\$1TIME | java.sql.Time | | TIMETZ | SQL\$1TYPE\$1TIME | java.sql.Time | | TIMESTAMP | SQL\$1TYPE\$1 TIMESTAMP | java.sql.Timestamp | | TIMESTAMPTZ | SQL\$1TYPE\$1 TIMESTAMP | java.sql.Timestamp | | VARCHAR | SQL\$1VARCHAR | String | # 使用預備陳述式支援 Amazon Redshift JDBC 驅動程式支援預備陳述式。您可以使用預備陳述式來改善需要在相同連線期間執行多次的參數化查詢效能。 預備陳述式**是在伺服器端編譯但不會立即執行的 SQL 陳述式。所編譯的陳述式會以 PreverredStatement 物件的形式儲存在伺服器上，直到您關閉物件或連線為止。當該物件存在時，您可以視需要使用不同的參數值執行預備陳述式多次，而不必重新編譯陳述式。由於額外負荷降低，因此該組查詢的執行速度會變快。 如需預備陳述式的相關資訊，請參閱《Oracle 提供的 JDBC 基本概念教學課程》[https://docs.oracle.com/javase/tutorial/jdbc/basics/prepared.html](https://docs.oracle.com/javase/tutorial/jdbc/basics/prepared.html)中的＜使用預備陳述式＞。 您可以準備包含多個查詢的陳述式。例如，下列預備陳述式包含兩個 INSERT 查詢： ``` PreparedStatement pstmt = conn.prepareStatement("INSERT INTO MyTable VALUES (1, 'abc'); INSERT INTO CompanyTable VALUES (1, 'abc');"); ``` 請注意，這些查詢不會依賴相同預備陳述式中所指定其他查詢的結果。由於準備步驟期間不會執行查詢，因此系統尚未傳回結果，因此沒有結果可供相同預備陳述式中的其他查詢使用。 例如，系統不會允許下列會先建立資料表，然後將值插入該新建資料表的預備陳述式： ``` PreparedStatement pstmt = conn.prepareStatement("CREATE TABLE MyTable(col1 int, col2 varchar); INSERT INTO myTable VALUES (1, 'abc');"); ``` 如果您嘗試準備這個陳述式，伺服器會傳回錯誤，指出目的地資料表 (myTable) 尚不存在。必須先執行 CREATE 查詢，才可以準備 INSERT 查詢。 # JDBC 驅動程式的 2.2 和 1.x 版本之間的差異 本節說明 2.2 和 1.x 版 JDBC 驅動程式傳回的資訊差異。JDBC 驅動程式 1.x 版已停止使用。 下表列出每個 JDBC 驅動程式版本的 getDatabaseProductName() 和 getDatabaseProductVersion() 函數所傳回的 DatabaseMetadata 資訊。JDBC 驅動程式 2.2 版會在建立連線時取得值。JDBC 驅動程式 1.x 版會從查詢結果取得值。 | JDBC 驅動程式版本 | getDatabaseProductName() 結果 | getDatabaseProductVersion() 結果 | | --- | --- | --- | | 2.2 | Redshift | 8.0.2 | | 1.x | PostgreSQL | 08.00.0002 | 下表列出每個 JDBC 驅動程式版本的 getTypeInfo 函數所傳回的 DatabaseMetadata 資訊。 | JDBC 驅動程式版本 | getTypeInfo 結果 | | --- | --- | | 2.2 | 與 Redshift 資料類型一致 | | 1.x | 與 PostgreSQL 資料類型一致 | # 建立 JDBC 驅動器 2.x 版的初始化 (.ini) 檔案 透過使用 Amazon Redshift JDBC 驅動器 2.x 版的初始化 (.ini) 檔案，您可以指定系統層級的組態參數。例如，每個應用程式的聯合 IdP 身分驗證參數可能會有所不同。.ini 檔案會提供通用位置讓 SQL 用戶端取得所需的組態參數。 您可以建立包含 SQL 用戶端組態選項的 JDBC 驅動器 2.x 版初始化 (.ini) 檔案。檔案的預設名稱為 `rsjdbc.ini`。JDBC 驅動器 2.x 版會在下列位置 (依優先順序列出) 檢查 .ini 檔案： + 連線 URL 或 SQL 用戶端的連線屬性對話方塊中的 `IniFile` 參數。請確定 `IniFile` 參數包含 .ini 檔案的完整路徑 (包括檔案名稱)。如需 `IniFile` 參數的詳細資訊，請參閱 [IniFile](jdbc20-configuration-options.md#jdbc20-inifile-option)。如果 `IniFile` 參數未正確指定 .ini 檔案的位置，則會顯示錯誤。 + 具有完整路徑 (包括檔案名稱在內) 的環境變數，例如 AMAZON\$1REDSHIFT\$1JDBC\$1INI\$1FILE。您可以使用 `rsjdbc.ini` 或指定檔案名稱。如果 AMAZON\$1REDSHIFT\$1JDBC\$1INI\$1FILE 環境變數未正確指定 .ini 檔案的位置，則會顯示錯誤。 + 驅動程式 JAR 檔案所在的目錄。 + 使用者主目錄。 + 系統的臨時目錄。 您可以將 .ini 檔案組織為多個驅動，例如 [DRIVER]。每個區段包含指定各種連線參數的鍵值對。您可以使用 `IniSection` 參數來指定 .ini 檔案中的區段。如需 `IniSection` 參數的詳細資訊，請參閱 [IniSection](jdbc20-configuration-options.md#jdbc20-inisection-option)。 以下是 .ini 檔案格式的範例，其中包含 [DRIVER]、[DEV]、[QA] 和 [PROD] 區段。[DRIVER] 區段可套用至任何連線。 ``` [DRIVER] key1=val1 key2=val2 [DEV] key1=val1 key2=val2 [QA] key1=val1 key2=val2 [PROD] key1=val1 key2=val2 ``` JDBC 驅動器 2.x 版會從下列位置 (依優先順序列出) 載入組態參數： + 應用程式程式碼中的預設組態參數。 + .ini 檔案中的 [DRIVER] 區段屬性 (如果包含的話)。 + 自訂區段組態參數 (如果有在連線 URL 或 SQL 用戶端的連線屬性對話方塊中提供 `IniSection` 選項的話)。 + 來自 `getConnection` 呼叫中所指定連線屬性物件的屬性。 + 連線 URL 中所指定的組態參數。 # JDBC 驅動器 2.x 版組態的選項 您可以在下面找到您可以為 Amazon Redshift JDBC 驅動程式 2.2 版指定的選項的說明。組態選項不區分大小寫。 您可以使用連線 URL 設定組態屬性。如需詳細資訊，請參閱[建置連線 URL](jdbc20-build-connection-url.md)。 **Topics** + [AccessKeyID](#jdbc20-accesskeyid-option) + [AllowDBUserOverride](#jdbc20-allowdbuseroverride-option) + [App\$1ID](#jdbc20-app-id-option) + [App\$1Name](#jdbc20-app-name-option) + [ApplicationName](#jdbc20-applicationname-option) + [AuthProfile](#jdbc20-authprofile-option) + [AutoCreate](#jdbc20-autocreate-option) + [Client\$1ID](#jdbc20-client_id-option) + [Client\$1Secret](#jdbc20-client_secret-option) + [ClusterID (ClusterID)](#jdbc20-clusterid-option) + [壓縮](#jdbc20-compression-option) + [connectTimeout](#jdbc20-connecttimeout-option) + [connectionTimezone](#jdbc20-connecttimezone-option) + [databaseMetadataCurrentDbOnly](#jdbc20-databasemetadatacurrentdbonly-option) + [DbUser](#jdbc20-dbuser-option) + [DbGroups](#jdbc20-dbgroups-option) + [DBNAME](#jdbc20-dbname-option) + [defaultRowFetchSize](#jdbc20-defaultrowfetchsize-option) + [DisableIsValidQuery](#jdbc20-disableisvalidquery-option) + [enableFetchRingBuffer](#jdbc20-enablefetchringbuffer-option) + [enableMultiSqlSupport](#jdbc20-enablemultisqlsupport-option) + [fetchRingBufferSize](#jdbc20-fetchringbuffersize-option) + [ForceLowercase](#jdbc20-forcelowercase-option) + [groupFederation](#jdbc20-groupFederation-option) + [HOST](#jdbc20-host-option) + [IAMDisableCache](#jdbc20-iamdisablecache-option) + [IAMDuration](#jdbc20-iamduration-option) + [Idc\$1Client\$1Display\$1Name](#jdbc20-idc_client_display_name) + [Idc\$1Region](#jdbc20-idc_region) + [IdP\$1Host](#jdbc20-idp_host-option) + [IdP\$1Partition](#jdbc20-idp_partition-option) + [IdP\$1Port](#jdbc20-idp_port-option) + [IdP\$1Tenant](#jdbc20-idp_tenant-option) + [IdP\$1Response\$1Timeout](#jdbc20-idp_response_timeout-option) + [IniFile](#jdbc20-inifile-option) + [IniSection](#jdbc20-inisection-option) + [isServerless](#jdbc20-isserverless-option) + [Issuer\$1Url](#jdbc20-issuer-url) + [Listen\$1Port](#jdbc20-listen-port) + [Login\$1URL](#jdbc20-login_url-option) + [loginTimeout](#jdbc20-logintimeout-option) + [loginToRp](#jdbc20-logintorp-option) + [LogLevel](#jdbc20-loglevel-option) + [LogPath](#jdbc20-logpath-option) + [OverrideSchemaPatternType](#jdbc20-override-schema-pattern-type) + [Partner\$1SPID](#jdbc20-partner_spid-option) + [密碼](#jdbc20-password-option) + [Plugin\$1Name](#jdbc20-plugin_name-option) + [PORT](#jdbc20-port-option) + [Preferred\$1Role](#jdbc20-preferred_role-option) + [設定檔](#jdbc20-profile-option) + [PWD](#jdbc20-pwd-option) + [queryGroup](#jdbc20-querygroup-option) + [readOnly](#jdbc20-readonly-option) + [區域](#jdbc20-region-option) + [reWriteBatchedInserts](#jdbc20-rewritebatchedinserts-option) + [reWriteBatchedInsertsSize](#jdbc20-rewritebatchedinsertssize-option) + [roleArn](#jdbc20-rolearn-option) + [roleSessionName](#jdbc20-roleaessionname-option) + [scope](#jdbc20-scope-option) + [SecretAccessKey](#jdbc20-secretaccesskey-option) + [SessionToken](#jdbc20-sessiontoken-option) + [serverlessAcctId](#jdbc20-serverlessacctid-option) + [serverlessWorkGroup](#jdbc20-serverlessworkgroup-option) + [socketFactory](#jdbc20-socketfactory-option) + [socketTimeout](#jdbc20-sockettimeout-option) + [SSL](#jdbc20-ssl-option) + [SSL\$1Insecure](#jdbc20-ssl_insecure-option) + [SSLCert](#jdbc20-sslcert-option) + [SSLFactory](#jdbc20-sslfactory-option) + [SSLKey](#jdbc20-sslkey-option) + [SSLMode](#jdbc20-sslmode-option) + [SSLPassword](#jdbc20-sslpassword-option) + [SSLRootCert](#jdbc20-sslrootcert-option) + [StsEndpointUrl](#jdbc20-stsendpointurl-option) + [tcpKeepAlive](#jdbc20-tcpkeepalive-option) + [token](#jdbc20-token-option) + [token\$1type](#jdbc20-token-type-option) + [UID](#jdbc20-uid-option) + [使用者](#jdbc20-user-option) + [webIdentityToken](#jdbc20-webidentitytoken-option) ## AccessKeyID + **預設值** — 無 + **資料類型** — 字串 您可以指定此參數以輸入使用者或角色的 IAM 存取金鑰。您通常可以透過查看和現有字串或使用者設定檔來找到金鑰。如果您指定此參數，則還必須指定 `SecretAccessKey` 參數。如果在 JDBC URL 中傳遞，則 AccessKeyID 必須經過 URL 編碼。 此為選用參數。 ## AllowDBUserOverride + **預設值** — 0 + **資料類型** — 字串 此選項會指定驅動程式是使用 SAML 聲明中的 `DbUser` 值，還是使用連線 URL 中 `DbUser` 連線屬性所指定的值。 此為選用參數。 **1** 驅動程式會使用 SAML 聲明中的 `DbUser` 值。 如果 SAML 聲明未針對 `DBUser` 指定值，則驅動程式會使用 `DBUser` 連線屬性中指定的值。如果連線屬性也未指定值，則驅動程式會使用連線設定檔中指定的值。 **0** 驅動程式會使用 `DBUser` 連線屬性中指定的 `DBUser` 值。 如果 `DBUser` 連線屬性未指定值，則驅動程式會使用連線設定檔中指定的值。如果連線設定檔也未指定值，則驅動程式會使用 SAML 聲明中的值。 ## App\$1ID + **預設值** — 無 + **資料類型** — 字串 與您的 Amazon Redshift 應用程式相關聯、Okta 所提供的唯一 ID。 如果透過 Okta 服務進行驗證，則需要此參數。 ## App\$1Name + **預設值** — 無 + **資料類型** — 字串 您用來驗證與 Amazon Redshift 之連線的 Okta 應用程式名稱。 此為選用參數。 ## ApplicationName + **預設值** — Null + **資料類型** — 字串 要傳遞給 Amazon Redshift 以進行稽核的應用程式名稱。 此為選用參數。 ## AuthProfile + **預設值** — 無 + **資料類型** — 字串 用於連線至 Amazon Redshift 的身分驗證設定檔名稱。 此為選用參數。 ## AutoCreate + **預設值** — false + **資料類型** — 布林值 此選項會指定當指定的使用者不存在時，驅動程式是否要導致系統建立新的使用者。 此為選用參數。 **true** 如果 `DBUser` 或唯一 ID (UID) 指定的使用者不存在，則系統會建立具有該名稱的新使用者。 **false** 驅動程式不會導致系統建立新的使用者。如果指定的使用者不存在，則身分驗證會失敗。 ## Client\$1ID + **預設值** — 無 + **資料類型** — 字串 使用 Azure AD 服務來驗證連線時要使用的用戶端 ID。 如果透過 Azure AD 服務進行驗證，則需要此參數。 ## Client\$1Secret + **預設值** — 無 + **資料類型** — 字串 使用 Azure AD 服務來驗證連線時要使用的用戶端秘密。 如果透過 Azure AD 服務進行驗證，則需要此參數。 ## ClusterID (ClusterID) + **預設值** — 無 + **資料類型** — 字串 您要連線至的 Amazon Redshift 叢集的名稱。驅動程式會嘗試從給定的主機偵測此參數。如果您使用 Network Load Balancer (NLB) 並透過 IAM 進行連線，則驅動程式無法偵測此參數，因此您可以使用此連線選項設定此參數。 此為選用參數。 ## 壓縮 + **預設值** - off + **資料類型** — 字串 用於 Amazon Redshift 伺服器與用戶端或驅動程式之間的有線通訊協定通訊的壓縮方法。 此為選用參數。 您可以指定下列值： + **lz4** 將用於與 Amazon Redshift 進行有線通訊協定通訊的壓縮方法設定為 lz4。 + **off** 不要對與 Amazon Redshift 進行的有線通訊協定通訊使用壓縮。 ## connectTimeout + **預設值** — 10 + **資料類型** — 整數 用於通訊端連線操作的逾時值。如果建立 Amazon Redshift 連線所需的時間超過此值，系統就會將此連線視為無法使用。逾時會以秒為單位來指定。值為 0 表示未指定逾時。 此為選用參數。 ## connectionTimezone + **預設值** — LOCAL + **資料類型** — 字串 工作階段層級時區。 此為選用參數。 您可以指定下列值： **LOCAL** 將工作階段層級時區設定為 LOCAL JVM 時區。 **SERVER** 將工作階段層級時區設定為在 Amazon Redshift 伺服器上為使用者設定的時區。您可以使用以下命令為使用者設定工作階段層級時區： ``` ALTER USER [...] SET TIMEZONE TO [...]; ``` ## databaseMetadataCurrentDbOnly + **預設值** — true + **資料類型** — 布林值 此選項指定中繼資料 API 會從所有可存取的資料庫擷取資料，還是僅從已連線的資料庫擷取資料。 此為選用參數。 您可以指定下列值： **true** 應用程式會從單一資料庫擷取中繼資料。 **false** 應用程式會從所有可存取的資料庫擷取中繼資料。 ## DbUser + **預設值** — 無 + **資料類型** — 字串 要與您的 Amazon Redshift 帳戶搭配使用的使用者 ID。如果您已啟用 AutoCreate 屬性，則可以使用目前不存在的 ID。 此為選用參數。 ## DbGroups + **預設值** — PUBLIC + **資料類型** — 字串 `DBUser` 針對目前的工作階段所加入之現有資料庫群組名稱的逗號分隔清單。 此為選用參數。 ## DBNAME + **預設值** — Null + **資料類型** — 字串 要連線到之資料庫的名稱。您可以使用此選項在 JDBC 連線 URL 中指定資料庫名稱。 此為必要參數。您必須在連線 URL 或用戶端應用程式的連線屬性中指定資料庫名稱。 ## defaultRowFetchSize + **預設值** — 0 + **資料類型** — 整數 此選項會指定 getFetchSize 的預設值。 此為選用參數。 您可以指定下列值： **0** 在單一操作中擷取所有資料列。 **正整數** 針對 ResultSet 的每次擷取迭代，要從資料庫擷取的資料列數目。 ## DisableIsValidQuery + **預設值** — False + **資料類型** — 布林值 此選項會指定驅動程式在使用 Connection.isValid() 方法判斷資料庫連線是否處於作用中狀態時，是否要提交新的資料庫查詢。 此為選用參數。 **true** 驅動程式在使用 Connection.isValid() 判斷資料庫連線是否處於作用中狀態時，不會提交查詢。如果資料庫伺服器意外關閉，這可能會造成驅動程式錯誤地將資料庫連線識別為作用中狀態。 **false** 驅動程式在使用 Connection.isValid() 判斷資料庫連線是否處於作用中狀態時，會提交查詢。 ## enableFetchRingBuffer + **預設值** — true + **資料類型** — 布林值 此選項指定驅動程式會在個別執行緒上使用環形緩衝器來擷取資料列。fetchRingBufferSize 參數會指定環形緩衝區的大小。 環形緩衝區會在 JDBC 中實作自動記憶體管理，以防止在資料擷取操作期間out-of-memory(OOM) 錯誤。環形緩衝區會即時監控緩衝資料的實際大小，確保驅動程式的總記憶體用量保持在定義的限制內。達到緩衝容量時，驅動程式會暫停資料擷取操作，防止記憶體溢出，而不需要手動介入。此內建防護功能可自動消除 OOM 錯誤，使用者不需要設定。 如果交易偵測到包含多個以分號分隔的 SQL 命令的陳述式，該交易的擷取環形緩衝區會設為 false。enableFetchRingBuffer 的值不會變更。 此為選用參數。 **注意** 當環形緩衝區停用且擷取大小未正確設定時，可能會發生out-of-memory(OOM) 問題。如需設定擷取大小的詳細資訊，請參閱[此處](https://docs.aws.amazon.com/redshift/latest/dg/set-the-JDBC-fetch-size-parameter.html)。 ## enableMultiSqlSupport + **預設值** — true + **資料類型** — 布林值 此選項會指定是否要在陳述式中處理以分號分隔的多個 SQL 命令。 此為選用參數。 您可以指定下列值： **true** 驅動程式會在陳述式物件中處理以分號分隔的多個 SQL 命令。 **false** 驅動程式會在單一陳述式中傳回多個 SQL 命令的錯誤。 ## fetchRingBufferSize + **預設值** — 1G + **資料類型** — 字串 此選項會指定在擷取結果集時使用的環形緩衝區大小。您可以指定以位元組為單位的大小，例如 1K 表示 1 KB、5000 表示 5,000 個位元組、1M 表示 1 MB、1G 表示 1 GB，依此類推。您也可以指定堆積記憶體的百分比。驅動程式會在達到限制時停止擷取資料列。當應用程式讀取資料列並釋放環形緩衝區中的空間時，擷取操作便會繼續。 此為選用參數。 ## ForceLowercase + **預設值** — false + **資料類型** — 布林值 此選項會指定在使用單一登入身分驗證時，驅動程式是否會將從身分提供者傳送至 Amazon Redshift 的所有資料庫群組 (DbGroups) 轉換為小寫。 此為選用參數。 **true** 驅動程式會將從身分提供者傳送的所有資料庫群組轉換為小寫。 **false** 驅動程式不會變更資料庫群組。 ## groupFederation + **預設值** — false + **資料類型** — 布林值 此選項會指定是否使用 Amazon Redshift IDP 群組。這會由 GetClusterCredentialsV2 API 支援。 此為選用參數。 **true** 使用 Amazon Redshift 身分提供者 (IdP) 群組。 **false** 針對使用者聯合使用 STS API 和 GetClusterCredentials，並明確指定連線的 DbGroups。 ## HOST + **預設值** — Null + **資料類型** — 字串 要連線到之 Amazon Redshift 伺服器的主機名稱。您可以使用此選項在 JDBC 連線 URL 中指定主機名稱。 此為必要參數。您必須在連線 URL 或用戶端應用程式的連線屬性中指定主機名稱。 ## IAMDisableCache + **預設值** — false + **資料類型** — 布林值 此選項會指定是否快取 IAM 憑證。 此為選用參數。 **true** 不快取 IAM 憑證。 **false** 快取 IAM 憑證。例如，當對於 API 閘道的請求遭到限流時，這可以提高效能。 ## IAMDuration + **預設值** — 900 + **資料類型** — 整數 臨時 IAM 憑證到期之前的時間長度 (以秒為單位)。 + **最小值** — 900 + **最大值** — 3,600 此為選用參數。 ## Idc\$1Client\$1Display\$1Name + **預設值** - Amazon Redshift JDBC 驅動器 + **資料類型** — 字串 使用 BrowserIdcAuthPlugin 的用戶端要使用的顯示名稱。 此為選用參數。 ## Idc\$1Region + **預設值** — 無 + **資料類型** — 字串 IAM Identity Center 執行個體所在的 AWS 區域。 只有在 plugin\$1name 組態選項中使用 `BrowserIdcAuthPlugin` 進行身分驗證時，才需要此參數。 ## IdP\$1Host + **預設值** — 無 + **資料類型** — 字串 您用來對 Amazon Redshift 進行身分驗證的 IdP (身分提供者) 主機。這可以在連線字串或設定檔中指定。 此為選用參數。 ## IdP\$1Partition + **預設值** — 無 + **資料類型** — 字串 指定設定身分提供者 (IdP) 的雲端分割區。這會決定驅動程式連線到哪個 IdP 身分驗證端點。 如果此參數保留空白，驅動程式會預設為商業分割區。可能值為： + `us-gov`：如果您的 IdP 是在 Azure Government 中設定，請使用此值。例如，Azure AD Government 會使用端點 `login.microsoftonline.us`。 + `cn`：如果您的 IdP 是在中國雲端分割區中設定，請使用此值。例如，Azure AD 中國使用端點 `login.chinacloudapi.cn`。 此為選用參數。 ## IdP\$1Port + **預設值** — 無 + **資料類型** — 字串 IdP (身分提供者) 使用的連接埠。您可以在連線字串或設定檔中指定連接埠。預設連接埠為 5439。根據您在建立、修改或遷移叢集時所選取的連接埠而定，允許存取選取的連接埠。 此為選用參數。 ## IdP\$1Tenant + **預設值** — 無 + **資料類型** — 字串 Amazon Redshift 應用程式的 Azure AD 租用戶 ID。 如果透過 Azure AD 服務進行驗證，則需要此參數。 ## IdP\$1Response\$1Timeout + **預設值** — 120 + **資料類型** — 整數 透過瀏覽器外掛程式使用 SAML 或 Azure AD 服務時，驅動程式等待身分提供者傳回 SAML 回應的時間長度 (以秒為單位)。 此為選用參數。 ## IniFile + **預設值** — 無 + **資料類型** — 字串 .ini 檔案的完整路徑 (包括檔案名稱)。例如： ``` IniFile="C:\tools\rsjdbc.ini" ``` 如需 .ini 檔案的相關資訊，請參閱[建立 JDBC 驅動器 2.x 版的初始化 (.ini) 檔案](jdbc20-ini-file.md)。 此為選用參數。 ## IniSection + **預設值** — 無 + **資料類型** — 字串 .ini 檔案中包含組態選項之區段的名稱。如需 .ini 檔案的相關資訊，請參閱[建立 JDBC 驅動器 2.x 版的初始化 (.ini) 檔案](jdbc20-ini-file.md)。 下列範例會指定 .ini 檔案的 [Prod] 區段： ``` IniSection="Prod" ``` 此為選用參數。 ## isServerless + **預設值** — false + **資料類型** — 布林值 此選項會指定 Amazon Redshift 端點主機是否為無伺服器執行個體。驅動程式會嘗試從給定的主機偵測此參數。如果您使用 Network Load Balancer (NLB)，則驅動程式無法偵測此參數，因此您可以在此設定此參數。 此為選用參數。 **true** Amazon Redshift 端點主機是無伺服器執行個體。 **false** Amazon Redshift 端點主機是已佈建的叢集。 ## Issuer\$1Url + **預設值** — 無 + **資料類型** — 字串 指向 AWS IAM Identity Center 伺服器的執行個體端點。 只有在 plugin\$1name 組態選項中使用 `BrowserIdcAuthPlugin` 進行身分驗證時，才需要此參數。 ## Listen\$1Port + **預設值** — 7890 + **資料類型** — 整數 透過瀏覽器外掛程式使用 SAML、Azure AD 或 AWS Identity Center 服務時，驅動程式用來從身分提供者或授權碼接收 SAML 回應的連接埠。 此為選用參數。 ## Login\$1URL + **預設值** — 無 + **資料類型** — 字串 透過瀏覽器外掛程式使用 SAML 或 Azure AD 服務時，身分提供者網站上資源的 URL。 如果透過瀏覽器外掛程式向 SAML 或 Azure AD 服務進行驗證，則需要此參數。 ## loginTimeout + **預設值** — 0 + **資料類型** — 整數 連線至伺服器並進行驗證時，逾時之前等待的秒數。如果建立連線所花的時間超過此臨界值，連線會中止。 當此屬性設為 0 時，連線不會逾時。 此為選用參數。 ## loginToRp + **預設值** — `urn:amazon:webservices` + **資料類型** — 字串 您要用於 AD FS 身分驗證類型的依賴方信任。 此為選用參數。 ## LogLevel + **預設值** — 0 + **資料類型** — 整數 使用此屬性可在驅動程式中開啟或關閉日誌記錄，以及指定日誌檔案中包含的詳細資訊數量。 日誌記錄功能應該要啟用到足以找到問題的時間長度就好。日誌記錄功能會降低效能，而且還會消耗大量磁碟空間。 此為選用參數。 將此參數設為以下其中一個值： **0** 停用所有日誌記錄功能。 **1** 在 FATAL 層級上啟用日誌記錄功能，這會記錄會導致驅動程式中止的極嚴重錯誤事件。 **2** 在 ERROR 層級上啟用日誌記錄功能，這會記錄可能仍允許驅動程式繼續執行的錯誤事件。 **3** 在 WARNING 層級上啟用日誌記錄功能，這會記錄如果未採取動作可能會導致錯誤的事件。 **4** 在 INFO 層級上啟用日誌記錄功能，這會記錄描述驅動程式進度的一般資訊。 **5** 在 DEBUG 層級上啟用日誌記錄功能，這會記錄有助於偵錯驅動程式的詳細資訊。 **6** 在 TRACE 層級上啟用日誌記錄功能，這會記錄所有驅動程式活動。 在啟用日誌記錄功能時，驅動程式會在 `LogPath` 屬性所指定的位置產生下列日誌檔案： + **`redshift_jdbc.log`** - 記錄非連線特定驅動器活動的檔案。 + **`redshift_jdbc_connection_[Number].log`** — 向資料庫建立的每個連線的檔案，其中 `[Number]` 是用來區別每個日誌檔案的編號。此檔案會記錄連線特定的驅動程式活動。 如果 LogPath 值無效，則驅動程式會將日誌記錄資訊傳送至標準輸出串流 `System.out`。 ## LogPath + **預設值** — 目前的工作目錄。 + **資料類型** — 字串 啟用 DSILogLevel 屬性時，驅動程式用來儲存日誌檔案之資料夾的完整路徑。 為了確定連線 URL 會與所有 JDBC 應用程式相容，建議您輸入另一個反斜線來逸出檔案路徑中的反斜線 (\$1)。 此為選用參數。 ## OverrideSchemaPatternType + **預設值** — Null + **資料類型** — 整數 此選項會指定是否要覆寫 getTables 呼叫中使用的查詢類型。 **0** 無結構描述通用查詢 **1** 本機結構描述查詢 **2** 外部結構描述查詢 此為選用參數。 ## Partner\$1SPID + **預設值** — 無 + **資料類型** — 字串 使用 PingFederate 服務驗證連線時，要使用的合作夥伴 SPID (服務提供者 ID) 值。 此為選用參數。 ## 密碼 + **預設值** — 無 + **資料類型** — 字串 透過 IDP 使用 IAM 身分驗證進行連線時，這是 IDP\$1Host 伺服器的密碼。使用標準身分驗證時，這可以用於 Amazon Redshift 資料庫密碼，而不是 PWD。 此為選用參數。 ## Plugin\$1Name + **預設值** — 無 + **資料類型** — 字串 用來實作特定憑證提供者外掛程式的完整類別名稱。 此為選用參數。 支援的提供者選項如下： + **`AdfsCredentialsProvider`** - Active Directory Federation Service。 + **`AzureCredentialsProvider`** - Microsoft Azure Active Directory (AD) 服務。 + **`BasicJwtCredentialsProvider`** - JSON Web Tokens (JWT) 服務。 + **`BasicSamlCredentialsProvider`** — 可與許多 SAML 服務提供者搭配使用的安全性聲明標記語言 (SAML) 憑證。 + **`BrowserAzureCredentialsProvider`** - 瀏覽器 Microsoft Azure Active Directory (AD) 服務。 + **`BrowserAzureOAuth2CredentialsProvider`** - 適用於原生身分驗證的瀏覽器 Microsoft Azure Active Directory (AD) 服務。 + **`BrowserIdcAuthPlugin` ** – 使用 IAM Identity Center AWS 的授權外掛程式。 + **`BrowserSamlCredentialsProvider`** - 適用於 SAML 服務的瀏覽器 SAML，例如 Okta、Ping 或 ADFS。 + **`IdpTokenAuthPlugin`** – 從連結至 IAM Identity Center AWS 的任何 Web 身分提供者接受 IAM Identity Center 字符或 OpenID Connect (OIDC) JSON 型身分字符 (JWT) AWS 的授權外掛程式。 + **`OktaCredentialsProvider`** - Okta 服務。 + **`PingCredentialsProvider`** - PingFederate 服務。 ## PORT + **預設值** — Null + **資料類型** — 整數 要連線到之 Amazon Redshift 伺服器的連接埠。您可以使用此選項在 JDBC 連線 URL 中指定連接埠。 此為選用參數。 ## Preferred\$1Role + **預設值** — 無 + **資料類型** — 字串 您要在連線到 Amazon Redshift 期間擔任的 IAM 角色。 此為選用參數。 ## 設定檔 + **預設值** — 無 + **資料類型** — 字串 要用於 IAM 身分驗證之設定檔的名稱。此設定檔包含未在連線字串中指定的任何其他連線屬性。 此為選用參數。 ## PWD + **預設值** — 無 + **資料類型** — 字串 與您使用屬性 UID 提供的 Amazon Redshift 使用者名稱對應的密碼。 此為選用參數。 ## queryGroup + **預設值** — Null + **資料類型** — 字串 此選項會在執行期將查詢指派給適當的查詢群組，以便將查詢指派給佇列。系統會針對工作階段設定查詢群組。在連線上執行的所有查詢都屬於此查詢群組。 此為選用參數。 ## readOnly + **預設值** — false + **資料類型** — 布林值 此屬性會指定驅動程式是否處於唯讀模式。 此為選用參數。 **true** 連線處於唯讀模式，且無法寫入到資料存放區。 **false** 連線不處於唯讀模式，可以寫入到資料存放區。 ## 區域 + **預設值** — Null + **資料類型** — 字串 此選項指定叢集所在的 AWS 區域。如果您指定 StsEndPoint 選項，系統會忽略區域選項。Redshift `GetClusterCredentials` API 操作也會使用區域選項。 此為選用參數。 ## reWriteBatchedInserts + **預設值** — false + **資料類型** — 布林值 此選項可實現最佳化，以重寫相容的 INSERT 陳述式並將這些陳述式合併為批次。 此為選用參數。 ## reWriteBatchedInsertsSize + **預設值** — 128 + **資料類型** — 整數 此選項可實現最佳化，以重寫相容的 INSERT 陳述式並將這些陳述式合併為批次。此值必須以 2 的冪呈指數增加。 此為選用參數。 ## roleArn + **預設值** — 無 + **資料類型** — 字串 角色的 Amazon Resource Name (ARN)。當您指定 Plugin\$1Name 選項的 BasicJwtCredentialsProvider 時，請務必指定此參數。請以下列格式指定 ARN： `arn:partition:service:region:account-id:resource-id` 如果您指定 Plugin\$1Name 選項的 BasicJwtCredentialsProvider，則必須有此參數。 ## roleSessionName + **預設值** — jwt\$1redshift\$1session + **資料類型** — 字串 擔任角色工作階段的識別碼。一般來說，您會傳遞與應用程式使用者相關聯的名稱或識別碼。應用程式使用的臨時安全憑證會與該使用者相關聯。當您指定 Plugin\$1Name 選項的 BasicJwtCredentialsProvider 時，您可以指定此參數。 此為選用參數。 ## scope + **預設值** — 無 + **資料類型** — 字串 使用者可以同意的範圍清單 (以空格分隔)。指定這個參數可讓您的 Microsoft Azure 應用程式針對您想要呼叫的 API 取得同意。當您為 Plugin\$1Name 選項指定 BrowserAzureOAuth2CredentialsProvider 時，便可以指定此參數。 BrowserAzureOAuth2CredentialsProvider 外掛程式需要此參數。 ## SecretAccessKey + **預設值** — 無 + **資料類型** — 字串 使用者或角色的 IAM 存取金鑰。如果指定了此參數，則也必須指定 AccessKeyID。如果在 JDBC URL 中傳遞，則 SecretAccessKey 必須經過 URL 編碼。 此為選用參數。 ## SessionToken + **預設值** — 無 + **資料類型** — 字串 與您用來驗證的 IAM 角色相關聯的臨時 IAM 工作階段權杖。如果在 JDBC URL 中傳遞，則臨時 IAM 工作階段權杖必須經過 URL 編碼。 此為選用參數。 ## serverlessAcctId + **預設值** — Null + **資料類型** — 字串 Amazon Redshift Serverless 帳戶 ID。驅動程式會嘗試從給定的主機偵測此參數。如果您使用 Network Load Balancer (NLB)，則驅動程式無法偵測此參數，因此您可以在此設定此參數。 此為選用參數。 ## serverlessWorkGroup + **預設值** — Null + **資料類型** — 字串 Amazon Redshift Serverless 工作群組名稱。驅動程式會嘗試從給定的主機偵測此參數。如果您使用 Network Load Balancer (NLB)，則驅動程式無法偵測此參數，因此您可以在此設定此參數。 此為選用參數。 ## socketFactory + **預設值** — Null + **資料類型** — 字串 此選項會指定用於建立通訊端的通訊端 Factory。 此為選用參數。 ## socketTimeout + **預設值** — 0 + **資料類型** — 整數 在通訊端讀取操作期間，逾時之前等待的秒數。如果操作所花的時間超過此臨界值，連線會關閉。當此屬性設為 0 時，連線不會逾時。 此為選用參數。 ## SSL + **預設值** — TRUE + **資料類型** — 字串 使用此屬性可開啟或關閉連線的 SSL。 此為選用參數。 您可以指定下列值： **TRUE** 驅動程式會透過 SSL 連線到伺服器。 **FALSE** 驅動程式會以不使用 SSL 的方式連線到伺服器。IAM 身分驗證不支援此選項。 或者，您也可以設定 AuthMech 屬性。 ## SSL\$1Insecure + **預設值** — true + **資料類型** — 字串 此屬性會指出是否應驗證 IDP 主機伺服器憑證。 此為選用參數。 您可以指定下列值： **true** 驅動程式不會檢查 IDP 伺服器憑證的真實性。 **false** 驅動程式會檢查 IDP 伺服器憑證的真實性。 ## SSLCert + **預設值** — 無 + **資料類型** — 字串 包含可在使用 SSL 時驗證 Amazon Redshift 伺服器執行個體之其他受信任 CA 憑證的 .pem 或 .crt 檔案的完整路徑。 如果指定 SSLKey，則需要此參數。 ## SSLFactory + **預設值** — 無 + **資料類型** — 字串 在不使用伺服器憑證的情況下，透過 TLS/SSL 連線至伺服器時要使用的 SSL Factory。 ## SSLKey + **預設值** — 無 + **資料類型** — 字串 包含用於驗證 SSLCert 中所指定憑證的 PKCS8 金鑰檔案的 .der 檔案完整路徑。 如果指定 SSLCert，則需要此參數。 ## SSLMode + **預設值** — verify-ca + **資料類型** — 字串 使用此屬性可指定在已啟用 TLS/SSL 時，驅動程式會如何驗證憑證。 此為選用參數。 您可以指定下列值： **verify-ca** 驅動程式會驗證憑證是否來自受信任的憑證授權機構 (CA)。 **verify-full** 驅動程式會驗證憑證是否來自受信任的 CA，以及憑證中的主機名稱是否符合連線 URL 中指定的主機名稱。 ## SSLPassword + **預設值** — 0 + **資料類型** — 字串 SSLKey 中所指定已加密金鑰檔案的密碼。 如果指定了 SSLKey 且金鑰檔案已加密，則需要此參數。 ## SSLRootCert + **預設值** — 無 + **資料類型** — 字串 包含可在使用 SSL 時驗證 Amazon Redshift 伺服器執行個體之根 CA 憑證的 .pem 或 .crt 檔案的完整路徑。 ## StsEndpointUrl + **預設值** — Null + **資料類型** — 字串 您可以指定 AWS Security Token Service (AWS STS) 端點。如果您指定此選項，系統會忽略區域選項。您只能為此端點指定安全的通訊協定 (HTTPS)。 ## tcpKeepAlive + **預設值** — TRUE + **資料類型** — 字串 使用此屬性可開啟或關閉 TCP 保持連線。 此為選用參數。 您可以指定下列值： **TRUE** 驅動程式會使用 TCP 保持連線來防止連線逾時。 **FALSE** 驅動程式不會使用 TCP 保持連線。 ## token + **預設值** — 無 + **資料類型** — 字串 IAM Identity Center AWS 提供存取字符或由與 IAM Identity Center 連結的 Web 身分提供者提供的 OpenID Connect (OIDC) JSON Web Token AWS (JWT)。您的應用程式必須透過使用 IAM Identity Center AWS 或與 IAM Identity Center 連結的身分提供者來驗證應用程式的使用者來產生此字符 AWS 。 此參數適用於 `IdpTokenAuthPlugin`。 ## token\$1type + **預設值** — 無 + **資料類型** — 字串 `IdpTokenAuthPlugin` 中使用的權仗類型。 您可以指定下列值： **ACCESS\$1TOKEN** 如果您使用 AWS IAM Identity Center 提供的存取權杖，請輸入此選項。 **EXT\$1JWT** 如果您使用與 AWS IAM Identity Center 整合的 Web 型身分提供者所提供的 OpenID Connect (OIDC) JSON Web Token (JWT)，請輸入此項。 此參數適用於 `IdpTokenAuthPlugin`。 ## UID + **預設值** — 無 + **資料類型** — 字串 您用來存取資料庫的資料庫使用者名稱。 此為必要參數。 ## 使用者 + **預設值** — 無 + **資料類型** — 字串 透過 IDP 使用 IAM 身分驗證進行連線時，這是 idp\$1host 伺服器的使用者名稱。使用標準身分驗證時，這可以用於 Amazon Redshift 資料庫使用者名稱。 此為選用參數。 ## webIdentityToken + **預設值** — 無 + **資料類型** — 字串 由身分提供者提供的 OAuth 2.1 存取權杖或 OpenID Connect ID 權杖。您的應用程式必須透過使用 Web 身分提供者對應用程式的使用者進行身分驗證來獲取此權杖。當您指定 Plugin\$1Name 選項的 BasicJwtCredentialsProvider 時，請務必指定此參數。 如果您指定 Plugin\$1Name 選項的 BasicJwtCredentialsProvider，則必須有此參數。 # JDBC 驅動器 2.x 版之前的版本 請在您的工具需要特定版本的驅動器時，才下載 Amazon Redshift JDBC 驅動器 2.x 版之前的版本。 下列是之前的 JDBC 4.2 相容 JDBC 驅動器 2.x 版驅動器： + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.4/redshift-jdbc42-2.2.4.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.4/redshift-jdbc42-2.2.4.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.3/redshift-jdbc42-2.2.3.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.3/redshift-jdbc42-2.2.3.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.2/redshift-jdbc42-2.2.2.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.2/redshift-jdbc42-2.2.2.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.1/redshift-jdbc42-2.2.1.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.1/redshift-jdbc42-2.2.1.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.0/redshift-jdbc42-2.2.0.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.2.0/redshift-jdbc42-2.2.0.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.34/redshift-jdbc42-2.1.0.34.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.34/redshift-jdbc42-2.1.0.34.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.33/redshift-jdbc42-2.1.0.33.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.33/redshift-jdbc42-2.1.0.33.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.32/redshift-jdbc42-2.1.0.32.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.32/redshift-jdbc42-2.1.0.32.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.30/redshift-jdbc42-2.1.0.30.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.30/redshift-jdbc42-2.1.0.30.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.29/redshift-jdbc42-2.1.0.29.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.29/redshift-jdbc42-2.1.0.29.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.28/redshift-jdbc42-2.1.0.28.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.28/redshift-jdbc42-2.1.0.28.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.26/redshift-jdbc42-2.1.0.26.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.26/redshift-jdbc42-2.1.0.26.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.25/redshift-jdbc42-2.1.0.25.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.25/redshift-jdbc42-2.1.0.25.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.24/redshift-jdbc42-2.1.0.24.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.24/redshift-jdbc42-2.1.0.24.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.23/redshift-jdbc42-2.1.0.23.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.23/redshift-jdbc42-2.1.0.23.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.22/redshift-jdbc42-2.1.0.22.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.22/redshift-jdbc42-2.1.0.22.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.21/redshift-jdbc42-2.1.0.21.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.21/redshift-jdbc42-2.1.0.21.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.20/redshift-jdbc42-2.1.0.20.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.20/redshift-jdbc42-2.1.0.20.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.19/redshift-jdbc42-2.1.0.19.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.19/redshift-jdbc42-2.1.0.19.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.18/redshift-jdbc42-2.1.0.18.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.18/redshift-jdbc42-2.1.0.18.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.17/redshift-jdbc42-2.1.0.17.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.17/redshift-jdbc42-2.1.0.17.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.16/redshift-jdbc42-2.1.0.16.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.16/redshift-jdbc42-2.1.0.16.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.15/redshift-jdbc42-2.1.0.15.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.15/redshift-jdbc42-2.1.0.15.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.14/redshift-jdbc42-2.1.0.14.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.14/redshift-jdbc42-2.1.0.14.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.13/redshift-jdbc42-2.1.0.13.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.13/redshift-jdbc42-2.1.0.13.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.12/redshift-jdbc42-2.1.0.12.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.12/redshift-jdbc42-2.1.0.12.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.11/redshift-jdbc42-2.1.0.11.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.11/redshift-jdbc42-2.1.0.11.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.10/redshift-jdbc42-2.1.0.10.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.10/redshift-jdbc42-2.1.0.10.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.9/redshift-jdbc42-2.1.0.9.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.9/redshift-jdbc42-2.1.0.9.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.8/redshift-jdbc42-2.1.0.8.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.8/redshift-jdbc42-2.1.0.8.zip) + [https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.7/redshift-jdbc42-2.1.0.7.zip](https://s3.amazonaws.com/redshift-downloads/drivers/jdbc/2.1.0.7/redshift-jdbc42-2.1.0.7.zip) # Amazon Redshift Python 連接器 透過使用適用於 Python 的 Amazon Redshift 連接器，您可以將工作與[適用於 Python (Boto3) 的 AWS SDK](https://github.com/boto/boto3)，以及 pandas 和數值 Python (NumPy) 整合。如需 pandas 的相關資訊，請參閱 [pandas GitHub 儲存庫](https://github.com/pandas-dev/pandas)。如需 NumPy 的相關資訊，請參閱 [NumPy GitHub 儲存庫](https://github.com/numpy/numpy)。 Amazon Redshift Python 連接器提供了開放原始碼的解決方案。您可以瀏覽原始碼、請求增強功能、回報問題並提供貢獻。 若要使用 Amazon Redshift Python 連線器，請確定您的 Python 是 3.6 版或更新版本。如需詳細資訊，請參閱 [Amazon Redshift Python 驅動程式授權合約](https://github.com/aws/amazon-redshift-python-driver/blob/master/LICENSE)。 Amazon Redshift Python 連接器可提供以下功能： + AWS Identity and Access Management (IAM) 身分驗證。如需詳細資訊，請參閱[Amazon Redshift 中的身分和存取管理](redshift-iam-authentication-access-control.md)。 + 使用聯合 API 存取的身分提供者身分驗證。以下企業身分提供者可支援聯合 API 存取： + Azure AD。如需詳細資訊，請參閱 AWS 大數據部落格文章[使用 Microsoft Azure AD 單一登入聯合 Amazon Redshift 存取](https://aws.amazon.com/blogs/big-data/federate-amazon-redshift-access-with-microsoft-azure-ad-single-sign-on/)。 + Active Directory Federation Services。如需詳細資訊，請參閱 AWS 大數據部落格文章[將 Amazon Redshift 叢集的存取與 Active Directory Federation Services (AD FS) 聯合：第 1 部分](https://aws.amazon.com/blogs/big-data/federate-access-to-your-amazon-redshift-cluster-with-active-directory-federation-services-ad-fs-part-1/)。 + Okta。如需詳細資訊，請參閱 AWS 大數據部落格文章[以身分提供者 Okta 聯合 Amazon Redshift 存取](https://aws.amazon.com/blogs/big-data/federate-amazon-redshift-access-with-okta-as-an-identity-provider/)。 + PingFederate。如需詳細資訊，請參閱 [PingFederate 網站](https://www.pingidentity.com/en/software/pingfederate.html)。 + JumpCloud。如需詳細資訊，請參閱 [JumpCloud 網站](https://jumpcloud.com/)。 + Amazon Redshift 資料類型。 Amazon Redshift Python 連接器會實作 Python Database API Specification 2.0。如需詳細資訊，請參閱 Python 網站上的 [PEP 249—Python Database API Specification v2.0](https://www.python.org/dev/peps/pep-0249/)。 **Topics** + [安裝 Amazon Redshift Python 連接器](python-driver-install.md) + [Amazon Redshift Python 連接器的組態選項](python-configuration-options.md) + [匯入 Python 連接器](python-start-import.md) + [將 Python 連接器與 NumPy 進行整合](python-connect-integrate-numpy.md) + [將 Python 連接器與 pandas 進行整合](python-connect-integrate-pandas.md) + [使用身分提供者外掛程式](python-connect-identity-provider-plugins.md) + [使用 Amazon Redshift Python 連接器的範例](python-connect-examples.md) + [Amazon Redshift Python 連接器的 API 參考](python-api-reference.md) # 安裝 Amazon Redshift Python 連接器 您可以使用下列任一方法來安裝 Amazon Redshift Python 連線器： + Python Package Index (PyPI) + Conda + 複製 GitHub 儲存庫 ## 從 PyPI 安裝 Python 連接器 若要從 Python Package Index (PyPI) 安裝 Python 連線器，您可以使用 pip。若要進行這項動作，請執行以下命令。 ``` >>> pip install redshift_connector ``` 您可以在虛擬環境內安裝連接器。若要進行這項動作，請執行以下命令。 ``` >>> pip install redshift_connector ``` 或者，您也可以選擇安裝 pandas 和 NumPy 與連接器。 ``` >>> pip install 'redshift_connector[full]' ``` 如需 pip 的相關資訊，請參閱 [pip 網站](https://pip.pypa.io/en/stable/)。 ## 從 Conda 安裝 Python 連接器 您可以從 Anaconda.org 安裝 Python 連接器。 ``` >>>conda install -c conda-forge redshift_connector ``` ## 從 複製 GitHub 儲存庫來安裝 Python 連接器 AWS 若要從來源安裝 Python 連接器，請從 AWS複製 GitHub 儲存庫。在安裝 Python 和 virtualenv 後，請透過執行以下命令來設定環境並安裝所需的相依性。 ``` $ git clone https://github.com/aws/amazon-redshift-python-driver.git $ cd amazon-redshift-python-driver $ virtualenv venv $ . venv/bin/activate $ python -m pip install -r requirements.txt $ python -m pip install -e . $ python -m pip install redshift_connector ``` # Amazon Redshift Python 連接器的組態選項 接下來，您可以找到可為 Amazon Redshift Python 連接器指定之選項的描述。除非另有指明，否則以下選項適用於最新推出的連接器版本。 ## access\$1key\$1id + **預設值** — 無 + **資料類型** — 字串 針對 IAM 資料庫身分驗證而設定之 IAM 角色或使用者的存取金鑰。 此為選用參數。 ## allow\$1db\$1user\$1override + **預設值** — False + **資料類型** — 布林值 True 指定連接器會使用安全性聲明標記語言 (SAML) 聲明中的 `DbUser` 值。 False 指定使用 `DbUser` 連線參數中的值。 此為選用參數。 ## app\$1name + **預設值** — 無 + **資料類型** — 字串 用於身分驗證之身分提供者 (IdP) 應用程式的名稱。 此為選用參數。 ## application\$1name + **預設值** — 無 + **資料類型** — 字串 要傳遞至 Amazon Redshift 以進行稽核的用戶端應用程式名稱。您提供的應用程式名稱會出現在 [SYS\$1CONNECTION\$1LOG](https://docs.aws.amazon.com/redshift/latest/dg/SYS_CONNECTION_LOG.html) 資料表的 'application\$1name' 欄中。此名稱有助於在偵錯問題時，追蹤連線來源並進行故障診斷。 此為選用參數。 ## auth\$1profile + **預設值** — 無 + **資料類型** — 字串 具有 JSON 形式連線屬性之 Amazon Redshift 身分驗證設定檔的名稱。如需有關命名連線參數的詳細資訊，請參閱 `RedshiftProperty` 類別。`RedshiftProperty` 類別會儲存最終使用者提供的連線參數，以及 (適用的話) 在 IAM 身分驗證程序 (例如臨時 IAM 憑證) 進行期間產生的連線參數。如需詳細資訊，請參閱 [RedshiftProperty 類別](https://github.com/aws/amazon-redshift-python-driver/blob/master/redshift_connector/redshift_property.py#L9)。 此為選用參數。 ## auto\$1create + **預設值** — False + **資料類型** — 布林值 此值會指出是否要在使用者不存在時建立使用者。 此為選用參數。 ## client\$1id + **預設值** — 無 + **資料類型** — 字串 來自 Azure IdP 的用戶端 ID。 此為選用參數。 ## client\$1secret + **預設值** — 無 + **資料類型** — 字串 來自 Azure IdP 的用戶端祕密。 此為選用參數。 ## cluster\$1identifier + **預設值** — 無 + **資料類型** — 字串 Amazon Redshift 叢集的叢集識別碼。 此為選用參數。 ## credentials\$1provider + **預設值** — 無 + **資料類型** — 字串 用於以 Amazon Redshift 進行驗證的 IdP。有效值如下： + `AdfsCredentialsProvider` + `AzureCredentialsProvider` + `BrowserAzureCredentialsProvider` + `BrowserAzureOAuth2CredentialsProvider` + `BrowserIdcAuthPlugin` - 使用 AWS IAM Identity Center 的授權外掛程式。 + `BrowserSamlCredentialsProvider` + `IdpTokenAuthPlugin` – 從任何 AWS 連結至 IAM Identity Center AWS 的 Web 身分提供者接受 IAM Identity Center 字符或 OpenID Connect (OIDC) JSON 型身分字符 (JWT) 的授權外掛程式。 + `PingCredentialsProvider` + `OktaCredentialsProvider` 此為選用參數。 ## 資料庫 + **預設值** — 無 + **資料類型** — 字串 要連線到之資料庫的名稱。 此為必要參數。 ## database\$1metadata\$1current\$1db\$1only + **預設值** — True + **資料類型** — 布林值 此值會指出應用程式是否支援多資料庫資料共用型錄。預設值 True 會指出應用程式不會為了回溯相容性而支援多資料庫資料共用型錄。 此為選用參數。 ## db\$1groups + **預設值** — 無 + **資料類型** — 字串 DbUser 所指出的使用者針對目前的工作階段所加入之現有資料庫群組名稱的逗號分隔清單。 此為選用參數。 ## db\$1user + **預設值** — 無 + **資料類型** — 字串 要與 Amazon Redshift 搭配使用的使用者 ID。 此為選用參數。 ## endpoint\$1url + **預設值** — 無 + **資料類型** — 字串 Amazon Redshift 端點的 URL。此選項僅供 AWS 內部使用。 此為選用參數。 ## group\$1federation + **預設值** — False + **資料類型** — 布林值 此選項會指定是否使用 Amazon Redshift IDP 群組。 此為選用參數。 **true** 使用 Amazon Redshift 身分提供者 (IdP) 群組。 **false** 針對使用者聯合使用 STS API 和 GetClusterCredentials，並指定連線的 **db\$1groups**。 ## 託管 + **預設值** — 無 + **資料類型** — 字串 Amazon Redshift 叢集的主機名稱。 此為選用參數。 ## iam + **預設值** — False + **資料類型** — 布林值 會啟用 IAM 身分驗證。 此為必要參數。 ## iam\$1disable\$1cache + **預設值** — False + **資料類型** — 布林值 此選項會指定是否快取 IAM 憑證。預設會快取 IAM 憑證。當對於 API 閘道的請求遭到限流時，這可以提高效能。 此為選用參數。 ## idc\$1client\$1display\$1name + **預設值** - Amazon Redshift Python 連接器 + **資料類型** — 字串 使用 BrowserIdcAuthPlugin 的用戶端要使用的顯示名稱。 此為選用參數。 ## idc\$1region + **預設值** — 無 + **資料類型** — 字串 IAM Identity Center AWS 執行個體所在的 AWS 區域。 只有在 credentials\$1provider 組態選項中使用 `BrowserIdcAuthPlugin` 進行身分驗證時，才需要此參數。 ## idp\$1partition + **預設值** — 無 + **資料類型** — 字串 指定設定身分提供者 (IdP) 的雲端分割區。這會決定驅動程式連線到哪個 IdP 身分驗證端點。 如果此參數保留空白，驅動程式會預設為商業分割區。可能值為： + `us-gov`：如果您的 IdP 是在 Azure Government 中設定，請使用此值。例如，Azure AD Government 會使用端點 `login.microsoftonline.us`。 + `cn`：如果您的 IdP 是在中國雲端分割區中設定，請使用此值。例如，Azure AD 中國使用端點 `login.chinacloudapi.cn`。 此為選用參數。 ## idpPort + **預設值** — 7890 + **資料類型** — 整數 IdP 會將 SAML 聲明傳送到的接聽連接埠。 此為必要參數。 ## idp\$1response\$1timeout + **預設值** — 120 + **資料類型** — 整數 從 IdP 擷取 SAML 聲明的逾時。 此為必要參數。 ## idp\$1tenant + **預設值** — 無 + **資料類型** — 字串 IdP 租用戶。 此為選用參數。 ## issuer\$1url + **預設值** — 無 + **資料類型** — 字串 指向 AWS IAM Identity Center 伺服器的執行個體端點。 只有在 credentials\$1provider 組態選項中使用 `BrowserIdcAuthPlugin` 進行身分驗證時，才需要此參數。 ## listen\$1port + **預設值** — 7890 + **資料類型** — 整數 透過瀏覽器外掛程式使用 SAML、Azure AD 或 IAM Identity Center AWS 服務時，驅動程式用來從身分提供者或授權碼接收 SAML 回應的連接埠。 此為選用參數。 ## login\$1url + **預設值** — 無 + **資料類型** — 字串 IdP 的單一登入 Url。 此為選用參數。 ## max\$1prepared\$1statements + **預設值** — 1000 + **資料類型** — 整數 每個連線將快取的預備陳述式數量上限。將此參數設為 0 會停用快取機制。針對此參數輸入負數會將其設定為預設值。 此為選用參數。 ## numeric\$1to\$1float + **預設值** — False + **資料類型** — 布林值 此選項指定連接器是否會將數值資料類型值從 decimal.Decimal 轉換為浮點數。依預設，連接器會接收 decimal.Decimal 形式的數值資料類型值，且不會對值進行轉換。 對於需要精確度的使用案例，不建議您啟用 numeric\$1to\$1float，因為得到的結果可能會經過四捨五入。 如需 decimal.Decimal 以及其與浮點數之間權衡的相關資訊，請參閱 Python 網站上的[小數 — 固定小數點和浮點數](https://docs.python.org/3/library/decimal.html)。 此為選用參數。 ## partner\$1sp\$1id + **預設值** — 無 + **資料類型** — 字串 針對以 Ping 進行的身分驗證所使用的合作夥伴 SP ID。 此為選用參數。 ## password + **預設值** — 無 + **資料類型** — 字串 用於身分驗證的密碼。 此為選用參數。 ## port + **預設值** — 5439 + **資料類型** — 整數 Amazon Redshift 叢集的連接埠號碼。 此為必要參數。 ## preferred\$1role + **預設值** — 無 + **資料類型** — 字串 目前連線偏好的 IAM 角色。 此為選用參數。 ## principal\$1arn + **預設值** — 無 + **資料類型** — 字串 要為其產生政策之使用者或 IAM 角色的 Amazon Resource Name (ARN)。建議您將政策連接至角色，然後將角色指派給您的使用者以提供存取權。 此為選用參數。 ## profile + **預設值** — 無 + **資料類型** — 字串 登入 AWS AWS 資料檔案中包含登入資料的設定檔名稱。 此為選用參數。 ## provider\$1name + **預設值** — 無 + **資料類型** — 字串 Redshift 原生身分驗證提供者的名稱。 此為選用參數。 ## region + **預設值** — 無 + **資料類型** — 字串 AWS 區域 叢集所在的 。 此為選用參數。 ## role\$1arn + **預設值** — 無 + **資料類型** — 字串 呼叫者所擔任角色的 Amazon Resource Name (ARN)。`JwtCredentialsProvider` 所指出的提供者會使用此參數。 若為 `JwtCredentialsProvider` 提供者，此為必要參數。否則，此為選擇性參數。 ## role\$1session\$1name + **預設值** — jwt\$1redshift\$1session + **資料類型** — 字串 擔任角色工作階段的識別碼。一般來說，您會傳遞與應用程式使用者相關聯的名稱或識別碼。應用程式使用的臨時安全憑證會與該使用者相關聯。`JwtCredentialsProvider` 所指出的提供者會使用此參數。 此為選用參數。 ## scope + **預設值** — 無 + **資料類型** — 字串 使用者可以同意的範圍清單 (以空格分隔)。指定這個參數可讓您的應用程式針對您想要呼叫的 API 取得同意。當您為 credentials\$1provider 選項指定 BrowserAzureOAuth2CredentialsProvider 時，便可以指定此參數。 BrowserAzureOAuth2CredentialsProvider 外掛程式需要此參數。 ## secret\$1access\$1key\$1id + **預設值** — 無 + **資料類型** — 字串 針對 IAM 資料庫身分驗證而設定之 IAM 角色或使用者的私密存取金鑰。 此為選用參數。 ## session\$1token + **預設值** — 無 + **資料類型** — 字串 針對 IAM 資料庫身分驗證而設定之 IAM 角色或使用者的存取金鑰。如果使用臨時 AWS 登入資料，則需要此參數。 此為選用參數。 ## serverless\$1acct\$1id + **預設值** — 無 + **資料類型** — 字串 Amazon Redshift Serverless 帳戶 ID。 此為選用參數。 ## serverless\$1work\$1group + **預設值** — 無 + **資料類型** — 字串 Amazon Redshift Serverless 工作群組名稱。 此為選用參數。 ## ssl + **預設值** — True + **資料類型** — 布林值 會啟用 Secure Sockets Layer (SSL)。 此為必要參數。 ## ssl\$1insecure + **預設值** — False + **資料類型** — 布林值 此值會指定是否要停用驗證 IdP 主機的伺服器 SSL 憑證。將此參數設定為 True 會停用驗證 IdP 主機的伺服器 SSL 憑證。建議您在生產環境中保留預設值 False。 此為選用參數。 ## sslmode + **預設值** — verify-ca + **資料類型** — 字串 連線至 Amazon Redshift 的安全。您可以指定下列任一項： + verify-ca + verify-full 此為必要參數。 ## tcp\$1keepalive + **預設值** — True + **資料類型** — 布林值 是否使用 TCP 保持連線來防止連線逾時。您可以指定下列值： + True：驅動器將使用 TCP 保持連線來防止連線逾時。 + False：驅動器不會使用 TCP 保持連線。 此為選用參數。 ## tcp\$1keepalive\$1count + **預設值** — 無 + **資料類型** — 整數 在判斷連線為非作用中之前，要傳送的未確認探查數目。例如，將值設定為 3，表示驅動器會先傳送 3 個未回應的保持連線封包，才確定連線非作用中。 如果未指定此參數，Amazon Redshift 會使用系統的預設值。 此為選用參數。 ## tcp\$1keepalive\$1interval + **預設值** — 無 + **資料類型** — 整數 後續保持連線探查之間的間隔 (以秒為單位)，如果驅動器未在此間隔之前收到探查的確認。如果您指定此參數，其必須是正整數。 如果未指定此參數，Amazon Redshift 會使用系統的預設值。 此為選用參數。 ## tcp\$1keepalive\$1idle + **預設值** — 無 + **資料類型** — 整數 無活動的持續時間 (以秒為單位)，經過這段時間後，驅動器會傳送第一個保持連線探查。例如，將值設定為 120，表示驅動器會等待 2 分鐘無活動的時間，才傳送第一個保持連線封包。如果您指定此參數，其必須是正整數。 如果未指定此參數，Amazon Redshift 會使用系統的預設值。 此為選用參數。 ## timeout + **預設值** — 無 + **資料類型** — 整數 對伺服器的連線在逾時前要經過的秒數。 此為選用參數。 ## token + **預設值** — 無 + **資料類型** — 字串 IAM Identity Center AWS 提供存取字符或由與 IAM Identity Center 連結的 Web 身分提供者提供的 OpenID Connect (OIDC) JSON Web Token AWS (JWT)。您的應用程式必須透過使用 IAM Identity Center AWS 或與 IAM Identity Center 連結的身分提供者來驗證應用程式的使用者來產生此字符 AWS 。 此參數適用於 `IdpTokenAuthPlugin`。 ## token\$1type + **預設值** — 無 + **資料類型** — 字串 `IdpTokenAuthPlugin` 中使用的權仗類型。 您可以指定下列值： **ACCESS\$1TOKEN** 如果您使用 AWS IAM Identity Center 提供的存取權杖，請輸入此選項。 **EXT\$1JWT** 如果您使用與 AWS IAM Identity Center 整合的 Web 型身分提供者所提供的 OpenID Connect (OIDC) JSON Web Token (JWT)，請輸入此項。 此參數適用於 `IdpTokenAuthPlugin`。 ## user + **預設值** — 無 + **資料類型** — 字串 用於身分驗證的使用者名稱。 此為選用參數。 ## web\$1identity\$1token + **預設值** — 無 + **資料類型** — 字串 由身分提供者提供的 OAuth 2.0 存取權杖或 OpenID Connect ID 權杖。請確保您的應用程式會透過以 Web 身分提供者對應用程式的使用者進行驗證來取得此權杖。`JwtCredentialsProvider` 所指出的提供者會使用此參數。 若為 `JwtCredentialsProvider` 提供者，此為必要參數。否則，此為選擇性參數。 # 匯入 Python 連接器 若要匯入 Python 連接器，請執行以下命令。 ``` >>> import redshift_connector ``` 若要使用 AWS 登入資料連線至 Amazon Redshift 叢集，請執行下列命令。 ``` conn = redshift_connector.connect( host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com', port=5439, database='dev', user='awsuser', password='my_password' ) ``` # 將 Python 連接器與 NumPy 進行整合 以下是將 Python 連接器與 NumPy 進行整合的範例。 ``` >>> import numpy #Connect to the cluster >>> import redshift_connector >>> conn = redshift_connector.connect( host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com', port=5439, database='dev', user='awsuser', password='my_password' ) # Create a Cursor object >>> cursor = conn.cursor() # Query and receive result set cursor.execute("select * from book") result: numpy.ndarray = cursor.fetch_numpy_array() print(result) ``` 結果如下。 ``` [['One Hundred Years of Solitude' 'Gabriel García Márquez'] ['A Brief History of Time' 'Stephen Hawking']] ``` # 將 Python 連接器與 pandas 進行整合 以下是將 Python 連接器與 pandas 進行整合的範例。 ``` >>> import pandas #Connect to the cluster >>> import redshift_connector >>> conn = redshift_connector.connect( host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com', port=5439, database='dev', user='awsuser', password='my_password' ) # Create a Cursor object >>> cursor = conn.cursor() # Query and receive result set cursor.execute("select * from book") result: pandas.DataFrame = cursor.fetch_dataframe() print(result) ``` # 使用身分提供者外掛程式 如需如何使用身分提供者外掛程式的一般資訊，請參閱[提供 IAM 登入資料的選項](options-for-providing-iam-credentials.md)。如需如何管理 IAM 身分的相關資訊 (包括 IAM 角色的最佳實務)，請參閱 [Amazon Redshift 中的身分和存取管理](redshift-iam-authentication-access-control.md)。 ## 使用 ADFS 身分提供者外掛程式進行身分驗證 以下是使用 Active Directory Federation Service (ADFS) 身分提供者外掛程式來針對連線至 Amazon Redshift 資料庫的使用者進行驗證的範例。 ``` >>> con = redshift_connector.connect( iam=True, database='dev', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', cluster_identifier='my-testing-cluster', credentials_provider='AdfsCredentialsProvider', user='brooke@myadfshostname.com', password='Hunter2', idp_host='myadfshostname.com' ) ``` ## 使用 Azure 身分提供者外掛程式進行身分驗證 以下是使用 Azure 身分提供者外掛程式進行身分驗證的範例。您可以為 Azure 企業應用程式建立 `client_id` 和 `client_secret` 的值，如下所示。 ``` >>> con = redshift_connector.connect( iam=True, database='dev', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', cluster_identifier='my-testing-cluster', credentials_provider='AzureCredentialsProvider', user='brooke@myazure.org', password='Hunter2', idp_tenant='my_idp_tenant', client_id='my_client_id', client_secret='my_client_secret', preferred_role='arn:aws:iam:123:role/DataScientist' ) ``` ## 使用 AWS IAM Identity Center 身分提供者外掛程式進行身分驗證 以下是使用 IAM Identity Center AWS 身分提供者外掛程式進行身分驗證的範例。 ``` with redshift_connector.connect( credentials_provider='BrowserIdcAuthPlugin', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', database='dev', idc_region='us-east-1', issuer_url='https://identitycenter.amazonaws.com/ssoins-790723ebe09c86f9', idp_response_timeout=60, listen_port=8100, idc_client_display_name='Test Display Name', # port value of 5439 is specified by default ) ``` ## 使用 Azure Browser 身分提供者外掛程式進行身分驗證 以下是使用 Azure Browser 身分提供者外掛程式來針對連線至 Amazon Redshift 資料庫的使用者進行驗證的範例。 由使用者提供登入憑據的瀏覽器會進行多重要素驗證。 ``` >>>con = redshift_connector.connect( iam=True, database='dev', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', cluster_identifier='my-testing-cluster', credentials_provider='BrowserAzureCredentialsProvider', idp_tenant='my_idp_tenant', client_id='my_client_id', ) ``` ## 使用 Okta 身分提供者外掛程式進行身分驗證 以下是使用 Okta 身分提供者外掛程式進行身分驗證的範例。您可以透過 Okta 應用程式取得 `idp_host`、`app_id` 和 `app_name` 的值。 ``` >>> con = redshift_connector.connect( iam=True, database='dev', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', cluster_identifier='my-testing-cluster', credentials_provider='OktaCredentialsProvider', user='brooke@myazure.org', password='hunter2', idp_host='my_idp_host', app_id='my_first_appetizer', app_name='dinner_party' ) ``` ## 搭配使用 JumpCloud 與一般 SAML 瀏覽器身分提供者外掛程式來進行身分驗證 以下是搭配使用 JumpCloud 與一般 SAML 瀏覽器身分提供者外掛程式來進行身分驗證的範例。 密碼是必要參數。但是，您不必輸入此參數，因為瀏覽器會進行多重要素驗證。 ``` >>> con = redshift_connector.connect( iam=True, database='dev', host='my-testing-cluster.abc.us-east-2.redshift.amazonaws.com', cluster_identifier='my-testing-cluster', credentials_provider='BrowserSamlCredentialsProvider', user='brooke@myjumpcloud.org', password='', login_url='https://sso.jumpcloud.com/saml2/plustwo_melody' ) ``` # 使用 Amazon Redshift Python 連接器的範例 以下是如何使用 Amazon Redshift Python 連接器的範例。若要執行這些範例，您必須先安裝 Python 連接器。如需安裝 Amazon Redshift Python 連接器的相關資訊，請參閱[安裝 Amazon Redshift Python 連接器](python-driver-install.md)。如需可與 Python 連接器搭配使用之組態選項的相關資訊，請參閱 [Amazon Redshift Python 連接器的組態選項](python-configuration-options.md)。 **Topics** + [使用 AWS 登入資料連線至和查詢 Amazon Redshift 叢集](#python-connect-cluster) + [啟用自動遞交](#python-connect-enable-autocommit) + [設定游標 paramstyle](#python-connect-config-paramstyle) + [使用 COPY 從 Amazon S3 儲存貯體複寫資料，然後使用 UNLOAD 將資料寫入至 Amazon S3 儲存貯體](#python-connect-copy-unload-s3) ## 使用 AWS 登入資料連線至和查詢 Amazon Redshift 叢集 下列範例會引導您使用 AWS 登入資料連線至 Amazon Redshift 叢集，然後查詢資料表並擷取查詢結果。 ``` #Connect to the cluster >>> import redshift_connector >>> conn = redshift_connector.connect( host='examplecluster.abc123xyz789.us-west-1.redshift.amazonaws.com', database='dev', port=5439, user='awsuser', password='my_password' ) # Create a Cursor object >>> cursor = conn.cursor() # Query a table using the Cursor >>> cursor.execute("select * from book") #Retrieve the query result set >>> result: tuple = cursor.fetchall() >>> print(result) >> (['One Hundred Years of Solitude', 'Gabriel García Márquez'], ['A Brief History of Time', 'Stephen Hawking']) ``` ## 啟用自動遞交 自動遞交屬性會預設為關閉，以遵循 Python Database API Specification。執行復原命令後，您可以使用以下命令開啟連線的 autocommit 屬性，以確保沒有進行中的交易。 ``` #Connect to the cluster >>> import redshift_connector >>> conn = redshift_connector.connect(...) # Run a rollback command >>> conn.rollback() # Turn on autocommit >>> conn.autocommit = True >>> conn.run("VACUUM") # Turn off autocommit >>> conn.autocommit = False ``` ## 設定游標 paramstyle 游標的 paramstyle 可透過 cursor.paramstyle 進行修改。所使用的預設 paramstyle 是 `format`。此參數的有效值為 `qmark`、`numeric`、`named`、`format` 和 `pyformat`。 以下是使用各種 paramstyle 將參數傳遞至範例 SQL 陳述式的範例。 ``` # qmark redshift_connector.paramstyle = 'qmark' sql = 'insert into foo(bar, jar) VALUES(?, ?)' cursor.execute(sql, (1, "hello world")) # numeric redshift_connector.paramstyle = 'numeric' sql = 'insert into foo(bar, jar) VALUES(:1, :2)' cursor.execute(sql, (1, "hello world")) # named redshift_connector.paramstyle = 'named' sql = 'insert into foo(bar, jar) VALUES(:p1, :p2)' cursor.execute(sql, {"p1":1, "p2":"hello world"}) # format redshift_connector.paramstyle = 'format' sql = 'insert into foo(bar, jar) VALUES(%s, %s)' cursor.execute(sql, (1, "hello world")) # pyformat redshift_connector.paramstyle = 'pyformat' sql = 'insert into foo(bar, jar) VALUES(%(bar)s, %(jar)s)' cursor.execute(sql, {"bar": 1, "jar": "hello world"}) ``` ## 使用 COPY 從 Amazon S3 儲存貯體複寫資料，然後使用 UNLOAD 將資料寫入至 Amazon S3 儲存貯體 下列範例顯示如何將資料從 Amazon S3 儲存貯體複製到資料表，然後從該資料表卸載回儲存貯體。 名為 `category_csv.txt` 且包含下列資料的文字檔案會上傳至 Amazon S3 儲存貯體：。 ``` 12,Shows,Musicals,Musical theatre 13,Shows,Plays,"All ""non-musical"" theatre" 14,Shows,Opera,"All opera, light, and ""rock"" opera" 15,Concerts,Classical,"All symphony, concerto, and choir concerts" ``` 以下是 Python 程式碼範例，其會先連線至 Amazon Redshift 資料庫。然後，會建立名為 `category` 的資料表，並將 S3 儲存貯體中的 CSV 資料複製到資料表中。 ``` #Connect to the cluster and create a Cursor >>> import redshift_connector >>> with redshift_connector.connect(...) as conn: >>> with conn.cursor() as cursor: #Create an empty table >>> cursor.execute("create table category (catid int, cargroup varchar, catname varchar, catdesc varchar)") #Use COPY to copy the contents of the S3 bucket into the empty table >>> cursor.execute("copy category from 's3://testing/category_csv.txt' iam_role 'arn:aws:iam::123:role/RedshiftCopyUnload' csv;") #Retrieve the contents of the table >>> cursor.execute("select * from category") >>> print(cursor.fetchall()) #Use UNLOAD to copy the contents of the table into the S3 bucket >>> cursor.execute("unload ('select * from category') to 's3://testing/unloaded_category_csv.txt' iam_role 'arn:aws:iam::123:role/RedshiftCopyUnload' csv;") #Retrieve the contents of the bucket >>> print(cursor.fetchall()) >> ([12, 'Shows', 'Musicals', 'Musical theatre'], [13, 'Shows', 'Plays', 'All "non-musical" theatre'], [14, 'Shows', 'Opera', 'All opera, light, and "rock" opera'], [15, 'Concerts', 'Classical', 'All symphony, concerto, and choir concerts']) ``` 如果您未將 `autocommit` 設定為 true，請在執行 `execute()` 陳述式後使用 `conn.commit()` 遞交。 資料會卸載到 S3 儲存貯體中的 `unloaded_category_csv.text0000_part00` 檔案中，其內容如下： ``` 12,Shows,Musicals,Musical theatre 13,Shows,Plays,"All ""non-musical"" theatre" 14,Shows,Opera,"All opera, light, and ""rock"" opera" 15,Concerts,Classical,"All symphony, concerto, and choir concerts" ``` # Amazon Redshift Python 連接器的 API 參考 接下來，您可以找到 Amazon Redshift Python 連線器 API 操作的描述。 ## redshift\$1connector 接下來，您可以找到 `redshift_connector` API 操作的描述。 `connect(user, database, password[, port, …])` 建立對 Amazon Redshift 叢集的連線。此函數會驗證使用者輸入、選擇性地使用身分提供者外掛程式進行驗證，然後建構連線物件。 `apilevel` 支援 DBAPI 層級，目前為「2.0」。 `paramstyle``str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str` 要全域使用的資料庫 API 參數樣式。 ## 連線 接下來，您可以找到 Amazon Redshift Python 連接器的連線 API 操作描述。 `__init__(user, password, database[, host, …])` 將原始連線物件初始化。 `cursor` 建立繫結至此連線的游標物件。 `commit` 遞交目前的資料庫交易。 `rollback` 復原目前的資料庫交易。 `close` 關閉資料庫連線。 `execute(cursor, operation, vals)` 執行指定的 SQL 命令。根據 `redshift_connector.paramstyle` 的值，您可以提供序列或映射形式的參數。 `run(sql[, stream])` 執行指定的 SQL 命令。您可以選擇性提供與 COPY 命令搭配使用的串流。 `xid(format_id, global_transaction_id, …)` 建立交易 ID。只有 `global_transaction_id` 參數會用於 postgres。format\$1id 和 branch\$1qualifier 不會用於 postgres。`global_transaction_id` 可以是由傳回元組 (`format_id`, `global_transaction_id`, `branch_qualifier`) 的 postgres 支援的任何字串識別碼。 `tpc_begin(xid)` 使用由格式 ID、全域交易 ID 和分支限定詞組成的交易 ID `xid` 來開始 TPC 交易。 `tpc_prepare` 執行以 .tpc\$1begin 開始之交易的第一個階段。 `tpc_commit([xid])` 以無引數方式呼叫時，.tpc\$1commit 會遞交先前使用 .tpc\$1prepare() 所準備的 TPC 交易。 `tpc_rollback([xid])` 以無引數方式呼叫時，.tpc\$1rollback 會復原 TPC 交易。 `tpc_recover` 傳回適合與 .tpc\$1commit(xid) 或 .tpc\$1rollback(xid) 搭配使用的待定交易 ID 清單。 ## 游標 接下來，您可以找到游標 API 操作的描述。 `__init__(connection[, paramstyle])` 將原始游標物件初始化。 `insert_data_bulk(filename, table_name, parameter_indices, column_names, delimiter, batch_size)` 執行大量 INSERT 陳述式。 `execute(operation[, args, stream, …])` 執行資料庫操作。 `executemany(operation, param_sets)` 準備資料庫操作，然後針對所提供的所有參數序列或映射執行此操作。 `fetchone` 擷取查詢結果集的下一列。 `fetchmany([num])` 擷取下一組查詢結果資料列。 `fetchall` 擷取查詢結果的所有剩餘資料列。 `close` 立即關閉游標。 `__iter__` 可對游標物件進行迭代以從查詢中擷取資料列。 `fetch_dataframe([num])` 傳回上次查詢結果的資料框。 `write_dataframe(df, table)` 將相同結構資料框寫入到 Amazon Redshift 資料庫。 `fetch_numpy_array([num])` 傳回上次查詢結果的 NumPy 陣列。 `get_catalogs` Amazon Redshift 不支援來自單一連線的多個型錄。Amazon Redshift 只會傳回目前的型錄。 `get_tables([catalog, schema_pattern, …])` 傳回系統內使用者定義的唯一公有資料表。 `get_columns([catalog, schema_pattern, …])` 傳回 Amazon Redshift 資料庫中特定資料表內所有資料欄的清單。 ## AdfsCredentialsProvider 外掛程式 以下是 Amazon Redshift Python 連接器的 AdfsCredentialsProvider 外掛程式 API 操作語法。 ``` redshift_connector.plugin.AdfsCredentialsProvider() ``` ## AzureCredentialsProvider 外掛程式 以下是 Amazon Redshift Python 連接器的 AzureCredentialsProvider 外掛程式 API 操作語法。 ``` redshift_connector.plugin.AzureCredentialsProvider() ``` ## BrowserAzureCredentialsProvider 外掛程式 以下是 Amazon Redshift Python 連接器的 BrowserAzureCredentialsProvider 外掛程式 API 操作語法。 ``` redshift_connector.plugin.BrowserAzureCredentialsProvider() ``` ## BrowserSamlCredentialsProvider 外掛程式 以下是 Amazon Redshift Python 連接器的 BrowserSamlCredentialsProvider 外掛程式 API 操作語法。 ``` redshift_connector.plugin.BrowserSamlCredentialsProvider() ``` ## OktaCredentialsProvider 外掛程式 以下是 Amazon Redshift Python 連接器的 OktaCredentialsProvider 外掛程式 API 操作語法。 ``` redshift_connector.plugin.OktaCredentialsProvider() ``` ## PingCredentialsProvider 外掛程式 以下是 Amazon Redshift Python 連接器的 PingCredentialsProvider 外掛程式 API 操作語法。 ``` redshift_connector.plugin.PingCredentialsProvider() ``` ## SamlCredentialsProvider 外掛程式 以下是 Amazon Redshift Python 連接器的 SamlCredentialsProvider 外掛程式 API 操作語法。 ``` redshift_connector.plugin.SamlCredentialsProvider() ``` # Apache Spark 的 Amazon Redshift 整合 [Apache Spark](https://aws.amazon.com/emr/features/spark/) 是一種分散式處理架構和程式設計模型，可協助您執行機器學習、串流處理或圖形分析。與 Apache Hadoop 類似，Spark 是一種開放原始碼、分散式處理系統，通常用於大數據的工作負載。Spark 具有經過最佳化的有向無環圖 (DAG) 執行引擎，並且會主動快取記憶體中的資料。這可以提高效能，對於某些算法和互動式查詢來說更是如此。 這項整合可為您提供 Spark 連接器，讓您用於建置在 Amazon Redshift 和 Amazon Redshift Serverless 中讀取和寫入資料的 Apache Spark 應用程式。這些應用程式不會影響應用程式效能或資料的交易一致性。這項整合會自動納入到 [Amazon EMR](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/) 和 [AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/)，因此您可以立即執行會在資料擷取和轉換管道中存取資料並將資料載入到 Amazon Redshift 的 Apache Spark 任務。 目前，您可以搭配此整合使用 Spark 的 3.3.x、3.4.x、3.5.x 和 4.0.0 版。 這項整合會提供下列功能： + AWS Identity and Access Management (IAM) 身分驗證。如需詳細資訊，請參閱 [Amazon Redshift 中的身分和存取管理](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html)。 + 述詞和查詢下推，以提升效能。 + Amazon Redshift 資料類型。 + 對 Amazon Redshift 和 Amazon Redshift Serverless 的連線。 ## 使用 Spark 連接器時的考量和限制 + tempdir URI 會指向 Amazon S3 位置。此臨時目錄不會自動清理，因此可能會增加額外的費用。建議您使用《Amazon Simple Storage Service 使用者指南》**中的 [Amazon S3 生命週期政策](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)來定義 Amazon S3 儲存貯體的保留規則。 + 根據預設，如果 Amazon S3和 Redshift 叢集位於不同的 AWS 區域，Amazon S3 和 Redshift 之間的複本將無法運作。若要使用個別 AWS 區域，請將 `tempdir_region` 參數設定為用於 的 S3 儲存貯體區域`tempdir`。 + 如果使用 `tempformat` 參數寫入 Parquet 資料，則會在 S3 和 Redshift 之間進行跨區域寫入。 + 建議您使用 [Amazon S3 伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)來加密所用的 Amazon S3 儲存貯體。 + 建議您[封鎖對 Amazon S3 儲存貯體的公開存取](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html)。 + 建議您不要將 Amazon Redshift 叢集設為可公開存取。 + 建議您開啟 [Amazon Redshift 稽核記錄](https://docs.aws.amazon.com/redshift/latest/mgmt/db-auditing.html)。 + 建議您開啟 [Amazon Redshift 靜態加密](https://docs.aws.amazon.com/redshift/latest/mgmt/security-server-side-encryption.html)。 + 建議您針對從 Amazon EMR 上的 Spark 到 Amazon Redshift 的 JDBC 連線開啟 SSL。 + 建議您使用 Amazon Redshift 身分驗證參數的 `aws_iam_role` 參數傳遞 IAM 角色。 # 使用 Spark 連接器進行身分驗證 下圖描述了 Amazon S3、Amazon Redshift、Spark 驅動程式和 Spark 執行程式之間的身分驗證。 ![\[這是 Spark 連接器的身分驗證圖。\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/images/spark-connector-authentication.png) ## Redshift 和 Spark 之間的身分驗證 您可以使用 Amazon Redshift 提供的 JDBC 驅動器 2.x 版，透過指定登入憑證使用 Spark 連接器連線到 Amazon Redshift。若要使用 IAM，請[設定 JDBC url 以使用 IAM 身分驗證](https://docs.aws.amazon.com/redshift/latest/mgmt/generating-iam-credentials-configure-jdbc-odbc.html)。若要從 Amazon EMR 或 連線至 Redshift 叢集 AWS Glue，請確定您的 IAM 角色具有擷取臨時 IAM 登入資料的必要許可。下列清單描述 IAM 角色要擷取憑證和執行 Amazon S3 操作所需的所有許可。 + [ Redshift:GetClusterCredentials](https://docs.aws.amazon.com/redshift/latest/APIReference/API_GetClusterCredentials.html) (適用於佈建的 Redshift 叢集) + [ Redshift:DescribeClusters](https://docs.aws.amazon.com/redshift/latest/APIReference/API_DescribeClusters.html) (適用於佈建的 Redshift 叢集) + [ Redshift:GetWorkgroup](https://docs.aws.amazon.com/redshift-serverless/latest/APIReference/API_GetWorkgroup.html) (適用於 Amazon Redshift Serverless 工作群組) + [ Redshift:GetCredentials](https://docs.aws.amazon.com/redshift-serverless/latest/APIReference/API_GetCredentials.html) (適用於 Amazon Redshift Serverless 工作群組) + [ s3:ListBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) + [ s3:GetBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_GetBucket.html) + [ s3:GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) + [ s3:PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) + [ s3:GetBucketLifecycleConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLifecycleConfiguration.html) 如需 GetClusterCredentials 的詳細資訊，請參閱 [ GetClusterCredentials 的 IAM 政策](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-access-control-identity-based.html#redshift-policy-resources.getclustercredentials-resources)。 您還必須確保 Amazon Redshift 可以在 `COPY` 和 `UNLOAD` 操作期間擔任 IAM 角色。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "redshift.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ 如果您使用的是最新的 JDBC 驅動程式，該驅動程式會自動管理從 Amazon Redshift 自我簽署憑證到 ACM 憑證的轉換。但是，您必須[指定 JDBC url 的 SSL 選項](https://docs.aws.amazon.com/redshift/latest/mgmt/jdbc20-configuration-options.html#jdbc20-ssl-option)。 以下是如何指定 JDBC 驅動程式 URL 和 `aws_iam_role` 以連線到 Amazon Redshift 的範例。 ``` df.write \ .format("io.github.spark_redshift_community.spark.redshift ") \ .option("url", "jdbc:redshift:iam://") \ .option("dbtable", "") \ .option("tempdir", "s3a:///") \ .option("aws_iam_role", "") \ .mode("error") \ .save() ``` ## Amazon S3 和 Spark 之間的身分驗證 如果您使用 IAM 角色在 Spark 和 Amazon S3 之間進行驗證，請使用下列其中一種方法： + 適用於 Java 的 AWS SDK 會使用 DefaultAWSCredentialsProviderChain 類別實作的預設登入資料提供者鏈結，自動嘗試尋找 AWS 登入資料。如需詳細資訊，請參閱[使用預設憑證提供者鏈結](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default)。 + 您可以透過 [ Hadoop 組態屬性](https://github.com/apache/hadoop/blob/trunk/hadoop-tools/hadoop-aws/src/site/markdown/tools/hadoop-aws/index.md)指定 AWS 金鑰。例如，如果您的 `tempdir` 組態指向 `s3n://` 檔案系統，請在 Hadoop XML 組態檔案中設定 `fs.s3n.awsAccessKeyId` 和 `fs.s3n.awsSecretAccessKey` 屬性，或呼叫 `sc.hadoopConfiguration.set()` 以變更 Spark 的全域 Hadoop 組態。 例如，假設您使用 s3n 檔案系統，請新增： ``` sc.hadoopConfiguration.set("fs.s3n.awsAccessKeyId", "YOUR_KEY_ID") sc.hadoopConfiguration.set("fs.s3n.awsSecretAccessKey", "YOUR_SECRET_ACCESS_KEY") ``` 若為 s3a 檔案系統，請新增： ``` sc.hadoopConfiguration.set("fs.s3a.access.key", "YOUR_KEY_ID") sc.hadoopConfiguration.set("fs.s3a.secret.key", "YOUR_SECRET_ACCESS_KEY") ``` 如果您使用 Python，請使用下列操作： ``` sc._jsc.hadoopConfiguration().set("fs.s3n.awsAccessKeyId", "YOUR_KEY_ID") sc._jsc.hadoopConfiguration().set("fs.s3n.awsSecretAccessKey", "YOUR_SECRET_ACCESS_KEY") ``` + 在 `tempdir` URL 中編碼身分驗證金鑰。例如，URI `s3n://ACCESSKEY:SECRETKEY@bucket/path/to/temp/dir` 會編碼金鑰對 (`ACCESSKEY`,`SECRETKEY`)。 ## Redshift 和 Amazon S3 之間的身分驗證 如果您在查詢中使用 COPY 和 UNLOAD 命令，則也必須向 Amazon S3 授予 Amazon Redshift 的存取權，以代表您執行查詢。若要這麼做，請先[授權 Amazon Redshift 存取其他 AWS 服務](https://docs.aws.amazon.com/redshift/latest/mgmt/authorizing-redshift-service.html)，然後使用 [IAM 角色授權 COPY 和 UNLOAD 操作](https://docs.aws.amazon.com/redshift/latest/mgmt/copy-unload-iam-role.html)。 我們建議的最佳實務是，將許可政策附加到 IAM 角色，然後根據需要將其指派給使用者和群組。如需詳細資訊，請參閱 [Amazon Redshift 中的身分和存取管理](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html)。 ## 與 整合 AWS Secrets Manager 您可以從 AWS Secrets Manager中儲存的機密擷取 Redshift 的使用者名稱和密碼憑證。若要自動提供 Redshift 憑證，請使用 `secret.id` 參數。如需如何建立 Redshift 憑證機密的相關資訊，請參閱[建立 AWS Secrets Manager 資料庫機密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_database_secret.html)。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/redshift-spark-connector-authentication.html) **注意** 確認：本文件包含由 [Apache Software Foundation](http://www.apache.org/) 根據 [Apache 2.0 授權](https://www.apache.org/licenses/LICENSE-2.0)所開發的範例程式碼和語言。 # 透過下推功能改善效能 Spark 連接器會自動套用述詞和查詢下推功能，以針對效能進行最佳化。這項支援表示，如果您在查詢中使用受支援的函數，Spark 連接器便會將該函數轉換為 SQL 查詢，並在 Amazon Redshift 中執行該查詢。此最佳化可減少所擷取的資料，因此 Apache Spark 可以處理較少的資料，獲得較好的效能。依預設，系統會自動啟動下推功能。若要加以停用，請將 `autopushdown` 設定為 false。 ``` import sqlContext.implicits._val sample= sqlContext.read .format("io.github.spark_redshift_community.spark.redshift") .option("url",jdbcURL ) .option("tempdir", tempS3Dir) .option("dbtable", "event") .option("autopushdown", "false") .load() ``` 下推功能支援下列函數。如果您使用的函數不在此清單中，Spark 連接器會在 Spark 中執行此函數，而不是在 Amazon Redshift 中執行，因此無法獲得最佳效能。如需 Spark 中函數的完整清單，請參閱[內建函數](https://spark.apache.org/docs/latest/api/sql/index.html)。 + 彙總函數 + avg + count + max + min + sum + stddev\$1samp + stddev\$1pop + var\$1samp + var\$1pop + 布林值運算子 + in + isnull + isnotnull + contains + endswith + startswith + 邏輯運算子 + 及 + 或 + not (or \$1) + 數學函式 + \$1 + - + \$1 + / + - (unary) + abs + acos + asin + atan + ceil + cos + exp + floor + greatest + least + log10 + pi + pow + round + sin + sqrt + tan + 其他函數 + cast + coalesce + decimal + 如 + in + 關係運算子 + \$1= + = + > + >= + < + <= + 字串函數 + ascii + lpad + rpad + translate + upper + lower + length + trim + ltrim + rtrim + like + substring + concat + 日期和時間函數 + add\$1months + date + date\$1add + date\$1sub + date\$1trunc + timestamp + trunc + 數學運算 + CheckOverflow + PromotePrecision + 關係運算 + Aliases (例如 AS) + CaseWhen + Distinct + InSet + Joins 和 cross joins + 限制 + Unions, union all + ScalarSubquery + Sorts (遞增和遞減) + UnscaledValue # 其他組態選項 在此頁面上，您可以找到可為 Amazon Redshift Spark 連接器指定之選項的說明。 ## 字串欄的大小上限 在建立儲存為 VARCHAR(256) 的資料表時，Redshift 會將字串資料欄建立為文字資料欄。如果你想要支援更大尺寸的資料欄，則可以使用 maxlength 來指定字串資料欄的最大長度。以下範例說明如何指定 `maxlength`。 ``` columnLengthMap.foreach { case (colName, length) => val metadata = new MetadataBuilder().putLong("maxlength", length).build() df = df.withColumn(colName, df(colName).as(colName, metadata)) } ``` ## 資料欄類型 若要設定資料欄類型，請使用 `redshift_type` 欄位。 ``` columnTypeMap.foreach { case (colName, colType) => val metadata = new MetadataBuilder().putString("redshift_type", colType).build() df = df.withColumn(colName, df(colName).as(colName, metadata)) } ``` ## 欄的壓縮編碼 若要在資料欄上使用特定的壓縮編碼，請使用編碼欄位。如需支援壓縮編碼的完整清單，請參閱[壓縮編碼](https://docs.aws.amazon.com/redshift/latest/dg/c_Compression_encodings.html)。 ## 欄的說明 若要設定描述，請使用 `description` 欄位。 ## Redshift 和 Amazon S3 之間的身分驗證 根據預設，結果會以 parquet 格式卸載到 Amazon S3。若要將結果卸載為以豎線分隔的文字檔案，請指定下列選項。 ``` .option("unload_s3_format", "TEXT") ``` ## Pushdown 陳述式 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/spark-redshift-connector-other-config.html) ## 連接器參數 Spark SQL 中的參數映射或 `OPTIONS` 支援以下設定。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/spark-redshift-connector-other-config.html) **注意** 確認：本文件包含由 [Apache Software Foundation](http://www.apache.org/) 根據 [Apache 2.0 授權](https://www.apache.org/licenses/LICENSE-2.0)所開發的範例程式碼和語言。 # 支援的資料類型 Spark 連接器支援 Amazon Redshift 中的下列資料類型。如需 Amazon Redshift 中支援的資料類型完整清單，請參閱[資料類型](https://docs.aws.amazon.com//redshift/latest/dg/c_Supported_data_types.html)。如果資料類型不在下表中，則表示 Spark 連接器不支援該資料類型。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/spark-redshift-connector-data-types.html) ## 複雜資料類型 您可以使用 Spark 連接器在 Redshift SUPER 資料類型資料欄中讀取和寫入 Spark 複雜資料類型 (例如 `ArrayType`、`MapType` 和 `StructType`)。如果您在讀取操作期間提供結構描述，資料欄中的資料會轉換為其在 Spark 中對應的複雜類型，包括任何巢狀類型。此外，如果已啟用 `autopushdown`，則巢狀屬性、映射值和陣列索引的投影會向下推送至 Redshift，在只存取一部分資料時，就不再需要卸載整個巢狀資料結構。 當您從連接器寫入 DataFrames 時，任何類型為 `MapType` (使用`StringType`)、`StructType`、或 `ArrayType` 的資料欄都會寫入到 Redshift SUPER 資料類型資料欄。在撰寫這些巢狀資料結構時，`tempformat` 參數的類型必須是 `CSV`、`CSV GZIP` 或 `PARQUET`。使用 `AVRO` 會導致例外狀況。撰寫具有 `StringType` 以外索引鍵類型的 `MapType` 資料結構也會導致例外狀況。 ### StructType 下列範例會示範如何建立具有 SUPER 資料類型且包含以下結構的資料表 ``` create table contains_super (a super); ``` 然後，您可以使用連接器，在使用如下列範例中的結構描述的資料表中，從 SUPER 資料欄 `a` 查詢 `StringType` 欄位 `hello`。 ``` import org.apache.spark.sql.types._ val sc = // existing SparkContext val sqlContext = new SQLContext(sc) val schema = StructType(StructField("a", StructType(StructField("hello", StringType) ::Nil)) :: Nil) val helloDF = sqlContext.read .format("io.github.spark_redshift_community.spark.redshift") .option("url", jdbcURL ) .option("tempdir", tempS3Dir) .option("dbtable", "contains_super") .schema(schema) .load().selectExpr("a.hello") ``` 下列範例會示範如何將結構寫入到資料欄 `a`。 ``` import org.apache.spark.sql.types._ import org.apache.spark.sql._ val sc = // existing SparkContext val sqlContext = new SQLContext(sc) val schema = StructType(StructField("a", StructType(StructField("hello", StringType) ::Nil)) :: Nil) val data = sc.parallelize(Seq(Row(Row("world")))) val mydf = sqlContext.createDataFrame(data, schema) mydf.write.format("io.github.spark_redshift_community.spark.redshift"). option("url", jdbcUrl). option("dbtable", tableName). option("tempdir", tempS3Dir). option("tempformat", "CSV"). mode(SaveMode.Append).save ``` ### MapType 如果您偏好使用 `MapType` 來表示資料，則可以在結構描述中使用 `MapType` 資料結構，並擷取映射中與索引鍵對應的值。請注意，`MapType` 資料結構中的所有索引鍵都必須是字串類型，並且所有值都必須是相同類型，例如 int。 下列範例會示範如何取得資料欄 `a` 中索引鍵 `hello` 的值。 ``` import org.apache.spark.sql.types._ val sc = // existing SparkContext val sqlContext = new SQLContext(sc) val schema = StructType(StructField("a", MapType(StringType, IntegerType))::Nil) val helloDF = sqlContext.read .format("io.github.spark_redshift_community.spark.redshift") .option("url", jdbcURL ) .option("tempdir", tempS3Dir) .option("dbtable", "contains_super") .schema(schema) .load().selectExpr("a['hello']") ``` ### ArrayType 如果資料欄包含陣列而不是結構，您可以使用連接器來查詢陣列中的第一個元素。 ``` import org.apache.spark.sql.types._ val sc = // existing SparkContext val sqlContext = new SQLContext(sc) val schema = StructType(StructField("a", ArrayType(IntegerType)):: Nil) val helloDF = sqlContext.read .format("io.github.spark_redshift_community.spark.redshift") .option("url", jdbcURL ) .option("tempdir", tempS3Dir) .option("dbtable", "contains_super") .schema(schema) .load().selectExpr("a[0]") ``` ### 限制 搭配 Spark 連接器使用複雜資料類型時有下列限制： + 所有巢狀的結構欄位名稱和映射索引鍵都必須小寫。如果要查詢包含大寫字母的複雜欄位名稱，因應措施是您可以嘗試省略結構描述，並使用 `from_json` Spark 函數在本機轉換傳回的字串。 + 讀取或寫入操作中使用的任何映射欄位都必須只有 `StringType` 索引鍵。 + 只有 `CSV`、`CSV GZIP` 和 `PARQUET ` 才是支援將複雜類型寫入到 Redshift 的 tempformat 值。嘗試使用 `AVRO ` 會擲回例外狀況。 # 設定 Amazon Redshift ODBC 驅動程式 2.x 版連線 您可以從許多第三方 SQL 用戶端工具和應用程式使用 ODBC 連線來連線至 Amazon Redshift 叢集。如果用戶端工具支援 JDBC，您可以選擇使用這種連線，而非 ODBC，因為 JDBC 的設定簡單。不過，如果您的用戶端工具不支援 JDBC，您可以按照本節中的步驟，在用戶端電腦或 Amazon EC2 執行個體上設定 ODBC 連線。 Amazon Redshift 為 Linux、Windows 和 Mac 作業系統提供 64 位元 ODBC 驅動程式；32 位元 ODBC 驅動程式已停用。除了緊急的安全修補程式外，不會再針對 32 位元 ODBC 驅動程式發佈其他更新。 如需 ODBC 驅動程式變更的最新資訊，請參閱[變更日誌](https://github.com/aws/amazon-redshift-odbc-driver/blob/master/CHANGELOG.md)。 **Topics** + [取得 ODBC URL](odbc20-getting-url.md) + [在 Microsoft Windows 上使用 Amazon Redshift ODBC 驅動器](odbc20-install-config-win.md) + [在 Linux 上使用 Amazon Redshift ODBC 驅動器](odbc20-install-config-linux.md) + [在 Apple macOS 上使用 Amazon Redshift ODBC 驅動程式](odbc20-install-config-mac.md) + [身分驗證方法](odbc20-authentication-ssl.md) + [資料類型轉換](odbc20-converting-data-types.md) + [ODBC 驅動器選項](odbc20-configuration-options.md) + [先前的 ODBC 驅動程式版本](odbc20-previous-versions.md) # 取得 ODBC URL Amazon Redshift 會在 Amazon Redshift 主控台中顯示叢集的 ODBC URL。此 URL 包含要在用戶端電腦和資料庫之間設定連線所需的資訊。 ODBC URL 採用下列格式： ``` Driver={driver}; Server=endpoint_host; Database=database_name; UID=user_name; PWD=password; Port=port_number ``` 前面格式的欄位具有下列值： | 欄位 | Value | | --- | --- | | Driver | 要使用的 64 位元 ODBC 驅動程式的名稱：Amazon Redshift ODBC 驅動程式 (x64)。 | | Server | Amazon Redshift 叢集的端點主機。 | | Database | 您為叢集建立的資料庫。 | | UID | 有許可而可連線至資料庫之資料庫使用者帳戶的使用者名稱。雖然這個值是資料庫層級的許可而非叢集層級的許可，但您可以使用您在啟動叢集時所設定的 Redshift 管理員使用者帳戶。 | | PWD | 用來連線至資料庫之資料庫使用者帳戶的密碼。 | | Port | 您啟動叢集時指定的連接埠號碼。如果有防火牆，請確定此連接埠已開放給您使用。 | 以下是 ODBC URL 範例： ``` Driver={Amazon Redshift ODBC Driver (x64)}; Server=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com; Database=dev; UID=adminuser; PWD=insert_your_admin_user_password_here; Port=5439 ``` 如需有關可在何處找到 ODBC URL 的資訊，請參閱[尋找叢集連線字串](https://docs.aws.amazon.com/redshift/latest/mgmt/configuring-connections.html#connecting-connection-string)。 # 在 Microsoft Windows 上使用 Amazon Redshift ODBC 驅動器 您必須在存取 Amazon Redshift 資料倉儲的用戶端電腦上安裝 Amazon Redshift ODBC 驅動程式。針對安裝驅動程式的每一台電腦，有下列最低要求： + 機器上的管理員權限。 + 機器符合下列系統要求： + 下列其中一個操作系統： + Windows 10 或 8.1。 + Windows Server 2019、2016 或 2012。 + 100 MB 的可用磁碟空間。 + 已安裝 Visual C\$1\$1 Redistributable for Visual Studio 2015，適用於 64 位元。您可以在 Microsoft 網站上的[下載適用於 Visual Studio 2022 的 Visual C\$1\$1 可轉散發套件](https://visualstudio.microsoft.com/downloads/#microsoft-visual-c-redistributable-for-visual-studio-2022)下載安裝套件。 # 下載並安裝 Amazon Redshift ODBC 驅動器 使用下列程序來下載並安裝適用於 Windows 作業系統的 Amazon Redshift ODBC 驅動程式。僅在您執行的第三方應用程式經認證可與 Amazon Redshift 搭配使用，且該應用程式需要特定驅動程式時，才使用不同的驅動程式。 若要下載並安裝 ODBC 驅動程式： 1. 下載下列驅動程式：[64 位元 ODBC 驅動程式 2.1.15.0 版](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.15.0/AmazonRedshiftODBC64-2.1.15.0.msi) 此驅動程式的名稱是 **Amazon Redshift ODBC 驅動程式 (x64)**。 1. 檢閱 [Amazon Redshift ODBC 驅動程式 2.x 版授權](https://github.com/aws/amazon-redshift-odbc-driver/blob/master/LICENSE)。 1. 按兩下 .msi 檔案，然後遵循精靈中的步驟來安裝驅動程式。 # 建立 ODBC 連線的系統 DSN 項目 在下載並安裝 ODBC 驅動程式之後，請將資料來源名稱 (DSN) 項目新增至用戶端電腦或 Amazon EC2 執行個體。SQL 用戶端工具可以使用此資料來源以連線至 Amazon Redshift 資料庫。 建議您建立系統 DSN，而不是使用者 DSN。部分應用程式會使用不同資料庫使用者帳戶載入資料，而且可能無法偵測到在其他資料庫使用者帳戶下建立的使用者 DSN。 **注意** 對於使用 AWS Identity and Access Management (IAM) 登入資料或身分提供者 (IdP) 登入資料的身分驗證，需要額外的步驟。如需詳細資訊，請參閱[設定 JDBC 或 ODBC 連線以使用 IAM 憑證](https://docs.aws.amazon.com/redshift/latest/mgmt/generating-iam-credentials-configure-jdbc-odbc.html)。 若要建立 ODBC 連線的系統 DSN 項目： 1. 在**開始**功能表中，輸入「ODBC 資料來源」。選擇 **ODBC 資料來源**。 確定您選擇的 ODBC 資料來源管理員具有與您要用來連線到 Amazon Redshift 的用戶端應用程式相同的位元。 1. 在 **ODBC 資料來源管理員**中，選擇**驅動程式**索引標籤並尋找下列驅動程式資料夾：**Amazon Redshift ODBC 驅動程式 (x64)**。 1. 選擇**系統 DSN**索引標籤，為電腦上的所有使用者設定驅動程式，或選擇**使用者 DSN**索引標籤，只為您的資料庫使用者帳戶設定驅動程式。 1. 選擇**新增**。**Create New Data Source (建立新的資料來源)** 視窗會開啟。 1. 選擇 **Amazon Redshift ODBC 驅動程式 (x64)**，然後選擇**完成**。**Amazon Redshift ODBC 驅動程式 DSN 設定**視窗會開啟。 1. 在**連線設定**區段下，輸入下列資訊： + **資料來源名稱** 輸入資料來源的名稱。例如，如果您遵循了《Amazon Redshift 入門指南》**，則可能會輸入 `exampleclusterdsn`，以便輕鬆記住與此 DSN 建立關聯的叢集。 + **Server** 指定 Amazon Redshift 叢集的端點主機。您可以在 Amazon Redshift 主控台的叢集詳細資訊頁面上找到此資訊。如需詳細資訊，請參閱[在 Amazon Redshift 中設定連線](https://docs.aws.amazon.com/redshift/latest/mgmt/configuring-connections.html)。 + **站點** 輸入資料庫使用的連接埠號碼。根據您在建立、修改或遷移叢集時所選取的連接埠而定，允許存取選取的連接埠。 + **資料庫** 輸入 Amazon Redshift 資料庫的名稱。如果您在未指定資料庫名稱的情況下啟動了叢集，請輸入 `dev`。否則，請使用您在啟動過程選擇的名稱。如果您遵循了《Amazon Redshift 入門指南》**，請輸入 `dev`。 1. 在**身分驗證**區段下，指定要設定標準或 IAM 身分驗證的組態選項。 1. 選擇 **SSL 選項**，並指定下列項目的值： + **身分驗證方式** 選擇用於處理 Secure Sockets Layer (SSL) 的模式。在測試環境中，您可以使用 `prefer`。不過，若為生產環境且需要交換安全資料時，請使用 `verify-ca` 或 `verify-full`。 + **最低 TLS** 或者，選擇驅動器允許資料存放區用於加密連線的最低 TLS/SSL 版本。例如，如果您指定 TLS 1.2，則無法使用 TLS 1.1 來加密連線。預設版本是 TLS 1.2。 1. 在**代理**索引標籤中，指定任何代理連線設定。 1. 在**游標**索引標籤中，指定有關如何將查詢結果傳回給 SQL 用戶端工具或應用程式的選項。 1. 在**進階選項**中，指定 `logLevel`、`logPath`、`compression` 和其他選項的值。 1. 選擇**測試**。如果用戶端電腦可以連線至 Amazon Redshift 資料庫，則會出現下列訊息：**連線成功**。如果用戶端電腦無法連線至資料庫，您可以透過產生日誌檔案並聯絡 AWS 支援來疑難排解可能的問題。如需有關產生日誌的資訊，請參閱 (LINK)。 1. 選擇**確定**。 # 在 Linux 上使用 Amazon Redshift ODBC 驅動器 您必須在存取 Amazon Redshift 資料倉儲的用戶端電腦上安裝 Amazon Redshift ODBC 驅動程式。針對安裝驅動程式的每一台電腦，有下列最低要求： + 機器上的根存取。 + 下列其中一個發行版本： + Red Hat® Enterprise Linux® (RHEL) 8 或更新版本。 + CentOS 8 或更新版本。 + 150 MB 的可用磁碟空間 + unixODBC 2.2.14 或更新版本。 + glibc 2.26 或更新版本。 # 下載並安裝 Amazon Redshift ODBC 驅動器 若要下載並安裝適用於 Linux 的 Amazon Redshift ODBC 驅動程式 2.x 版： 1. 下載下列驅動程式： + [x86 64 位元 RPM 驅動程式版本 2.1.15.0](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.15.0/AmazonRedshiftODBC-64-bit-2.1.15.0.x86_64.rpm) + [ARM 64 位元 RPM 驅動程式版本 2.1.15.0](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.15.0/AmazonRedshiftODBC-64-bit-2.1.15.0.aarch64.rpm) **注意** 32 位元的 ODBC 驅動程式已停用。除了緊急的安全修補程式外，不會再發佈其他更新。 1. 移至您下載套件的位置，然後執行下列其中一個命令。使用與您的 Linux 發行版本相應的指令。 在 RHEL 和 CentOS 作業系統上，執行下列命令： ``` yum --nogpgcheck localinstall RPMFileName ``` 將 `RPMFileName` 取代為 RPM 套件檔案名稱。例如，下列命令示範安裝 64 位元驅動程式： ``` yum --nogpgcheck localinstall AmazonRedshiftODBC-64-bit-2.x.xx.xxxx.x86_64.rpm ``` # 使用 ODBC 驅動器管理員設定 ODBC 驅動器 在 Linux 上，您使用的是 ODBC 驅動程式管理員來設定 ODBC 連線設定。ODBC 驅動程式管理員使用組態檔案來定義及設定 ODBC 資料來源和驅動程式。您使用的 ODBC 驅動程式管理員視您使用的作業系統而定。 ## 使用 unixODBC 驅動程式管理員來設定 ODBC 驅動程式 需要下列檔案才能設定 Amazon Redshift ODBC 驅動程式： + ` amazon.redshiftodbc.ini ` + ` odbc.ini ` + ` odbcinst.ini ` 如果是安裝到預設位置，則 `amazon.redshiftodbc.ini` 組態檔案位於 `/opt/amazon/redshiftodbcx64`。 此外，在 `/opt/amazon/redshiftodbcx64` 下，您可以找到 `odbc.ini` 和 `odbcinst.ini` 範例檔案。您可以使用這些檔案做為設定 Amazon Redshift ODBC 驅動程式和資料來源名稱 (DSN) 的範例。 不建議使用 Amazon Redshift ODBC 驅動程式安裝目錄來存放組態檔案。所安裝目錄中的範例檔案僅供當作範例。如果您後來重新安裝 Amazon Redshift ODBC 驅動程式，或升級為更新版本，安裝目錄會遭到覆寫。您會遺失對安裝目錄中的檔案所做的任何變更。 若要避免這種情況，請將 `amazon.redshiftodbc.ini` 檔案複製到安裝目錄以外的目錄。如果您將此檔案複製到使用者的主目錄，請在檔案名稱開頭加上一點 (.)，將它變成隱藏檔。 對於 `odbc.ini` 和 `odbcinst.ini` 檔案，請使用位於使用者主目錄中的組態檔案，或在另一個目錄中建立新版本。根據預設，您的 Linux 作業系統應該在使用者的主目錄 (`/home/$USER` 或 `~/.`) 中具有 `odbc.ini` 檔案和 `odbcinst.ini` 檔案。這些預設檔案是隱藏檔，每個檔案名稱前面以點表示。僅當使用 `-a` 旗標來列出目錄內容時，才會顯示這些檔案。 無論對 `odbc.ini` 和 `odbcinst.ini` 檔案選擇何種選項，都會修改這些檔案來新增驅動程式和 DSN 組態資訊。如果建立新檔案，則還需要設定環境變數來指定這些組態檔案所在的位置。 根據預設，ODBC 驅動程式管理員會設定為使用隱藏版本的 `odbc.ini` 和 `odbcinst.ini` 組態檔 (命名為 `.odbc.ini` 和 `.odbcinst.ini`)，這些組態檔位於主目錄中。它們也會設定為使用驅動程式安裝目錄中的 `amazon.redshiftodbc.ini` 檔案。如果您將這些組態檔儲存在其他位置，請設定如下所述的環境變數，以便驅動程式管理員可以找到這些檔案。 如果您使用 unixODBC，請執行以下操作： + 將 `ODBCINI` 設定為 `odbc.ini` 檔案的完整路徑和檔案名稱。 + 將 `ODBCSYSINI` 設定為包含 `odbcinst.ini` 檔案之目錄的完整路徑。 + 將 `AMAZONREDSHIFTODBCINI` 設定為 `amazon.redshiftodbc.ini` 檔案的完整路徑和檔案名稱。 以下是設定上述值的範例： ``` export ODBCINI=/usr/local/odbc/odbc.ini export ODBCSYSINI=/usr/local/odbc export AMAZONREDSHIFTODBCINI=/etc/amazon.redshiftodbc.ini ``` ## 在 Linux 上使用資料來源名稱 (DSN) 來設定連線 在使用資料來源名稱 (DSN) 連線至資料存放區時，請設定 `odbc.ini` 檔案來定義資料來源名稱 (DSN)。在 `odbc.ini` 檔案中設定屬性，以建立 DSN 來指定資料倉庫的連線資訊。 在 Linux 作業系統上使用下列格式： ``` [ODBC Data Sources] driver_name=dsn_name [dsn_name] Driver=path/driver_file Host=cluster_endpoint Port=port_number Database=database_name locale=locale ``` 以下範例示範 Linux 作業系統上使用 64 位元 ODBC 驅動程式的 `odbc.ini` 組態。 ``` [ODBC Data Sources] Amazon_Redshift_x64=Amazon Redshift ODBC Driver (x64) [Amazon_Redshift_x64] Driver=/opt/amazon/redshiftodbcx64/librsodbc64.so Host=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com Port=5932Database=dev locale=en-US ``` ## 在 Linux 上設定不使用 DSN 的連線 若要透過沒有 DSN 的連線連接至您的資料存放區，請在 `odbcinst.ini` 檔案中定義驅動程式。然後，在應用程式中提供無 DSN 的連線字串。 在 Linux 作業系統上使用下列格式： ``` [ODBC Drivers] driver_name=Installed ... [driver_name] Description=driver_description Driver=path/driver_file ... ``` 以下範例示範 Linux 作業系統上使用 64 位元 ODBC 驅動程式的 `odbcinst.ini` 組態。 ``` [ODBC Drivers] Amazon Redshift ODBC Driver (x64)=Installed [Amazon Redshift ODBC Driver (x64)] Description=Amazon Redshift ODBC Driver (64-bit) Driver=/opt/amazon/redshiftodbcx64/librsodbc64.so ``` # 在 Apple macOS 上使用 Amazon Redshift ODBC 驅動程式 您必須在存取 Amazon Redshift 資料倉儲的用戶端電腦上安裝 Amazon Redshift ODBC 驅動程式。對於您安裝驅動程式的每個電腦，下列最低需求如下： + 機器上的根存取。 + Apple macOS 系統需求： + 需要 64 位元版本的 Apple macOS 11.7 版或更新版本 （例如 Apple macOS Big Sur、Monterey、Ventura 或更新版本）。Redshift ODBC 驅動程式僅支援 64 位元用戶端應用程式。 + 150 MB 的可用磁碟空間 + 驅動程式支援使用 iODBC 3.52.9\$1 或 unixODBC 2.3.7\$1 建置的應用程式。 # 下載並安裝 Amazon Redshift ODBC 驅動器 使用下列程序，在 Apple macOS 下載並安裝 Amazon Redshift ODBC 驅動程式。僅在您執行的第三方應用程式經認證可與 Amazon Redshift 搭配使用，且該應用程式需要特定驅動程式時，才使用不同的驅動程式。 若要下載並安裝 ODBC 驅動程式： 1. 下載下列驅動程式：[64 位元 ODBC 驅動程式 2.1.15.0 版](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.15.0/AmazonRedshiftODBC-64-bit.2.1.15.0.universal.pkg) x86\$164 和 arm64 架構都支援此驅動程式。此驅動程式的名稱是 **Amazon Redshift ODBC 驅動程式 (x64)**。 1. 檢閱 [Amazon Redshift ODBC 驅動程式 2.x 版授權](https://github.com/aws/amazon-redshift-odbc-driver/blob/master/LICENSE)。 1. 按兩下 .pkg 檔案，然後依照精靈中的步驟安裝驅動程式。或者，執行下列命令： ``` sudo installer -pkg PKGFileName -target / ``` 將 取代`PKGFileName`為 pkg 套件檔案名稱。例如，下列命令示範安裝 64 位元驅動程式： ``` sudo installer -pkg ./AmazonRedshiftODBC-64-bit.X.X.XX.X.universal.pkg -target / ``` # 使用 ODBC 驅動器管理員設定 ODBC 驅動器 在 Mac 上，您可以使用 ODBC 驅動程式管理員來設定 ODBC 連線設定。ODBC 驅動程式管理員使用組態檔案來定義及設定 ODBC 資料來源和驅動程式。您使用的 ODBC 驅動程式管理員視您使用的作業系統而定。 ## 使用 iODBC 或 unixODBC 驅動程式管理員設定 ODBC 驅動程式 需要下列檔案才能設定 Amazon Redshift ODBC 驅動程式： + ` amazon.redshiftodbc.ini ` + ` odbc.ini ` + ` odbcinst.ini ` 如果是安裝到預設位置，則 `amazon.redshiftodbc.ini` 組態檔案位於 `/opt/amazon/redshiftodbcx64`。 此外，在 `/opt/amazon/redshiftodbcx64` 下，您可以找到 `odbc.ini` 和 `odbcinst.ini` 範例檔案。您可以使用這些檔案做為設定 Amazon Redshift ODBC 驅動程式和資料來源名稱 (DSN) 的範例。所安裝目錄中的範例檔案僅供當作範例。 不建議使用 Amazon Redshift ODBC 驅動程式安裝目錄來存放組態檔案。如果您後來重新安裝 Amazon Redshift ODBC 驅動程式，或升級為更新版本，安裝目錄會遭到覆寫。您會遺失對安裝目錄中的檔案所做的任何變更。 若要避免這種情況，請將 `odbc.ini``odbcinst.ini`和 `amazon.redshiftodbc.ini` 檔案複製到安裝目錄以外的目錄。如果您將這些檔案複製到使用者的主目錄，請在這些檔案名稱的開頭新增句點 (.)，使其成為隱藏檔案。 修改檔案以新增 DSN 組態資訊。建立新檔案時，您也需要設定環境變數，以指定這些組態檔案的位置。 以下是設定環境變數的範例： ``` export ODBCINI=/Library/ODBC/odbc.ini export ODBCSYSINI=/Library/ODBC export ODBCINSTINI=${ODBCSYSINI}/odbcinst.ini ``` 對於命令列應用程式：將匯出命令新增至 shell 啟動檔案 （例如 `~/.bash_profile`或 `~/.zshrc`)。 如需驅動程式管理員的支援版本，請參閱[此處](https://docs.aws.amazon.com/redshift/latest/mgmt/odbc20-install-config-mac.html) ### 在 Apple macOS 上使用資料來源名稱 (DSN) 設定連線 在使用資料來源名稱 (DSN) 連線至資料存放區時，請設定 `odbc.ini` 檔案來定義資料來源名稱 (DSN)。設定 `odbc.ini` 檔案中的屬性以建立 DSN，指定 Redshift 資料倉儲的連線資訊。 在 Apple macOS 上，使用下列格式： ``` [ODBC Data Sources] driver_name=dsn_name [dsn_name] Driver=path/driver_file Host=cluster_endpoint Port=port_number Database=database_name locale=locale ``` 下列範例顯示 Apple macOS 上`odbc.ini`具有 64 位元 ODBC 驅動程式的 組態。 ``` [ODBC Data Sources] Amazon_Redshift_x64=Amazon Redshift ODBC Driver (x64) [Amazon_Redshift_x64] Driver=/opt/amazon/redshiftodbcx64/librsodbc64.dylib Host=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com Port=5932 Database=dev locale=en-US ``` ### 在 Apple macOS 上設定沒有 DSN 的連線 若要透過沒有 DSN 的連線連線至 Redshift 資料倉儲，請在 `odbcinst.ini` 檔案中定義驅動程式。然後，在應用程式中提供無 DSN 的連線字串。 在 Apple macOS 上，使用下列格式： ``` [ODBC Drivers] driver_name=Installed ... [driver_name] Description=driver_description Driver=path/driver_file ... ``` 下列範例顯示 Apple macOS 上`odbcinst.ini`具有 64 位元 ODBC 驅動程式的 組態。 ``` [ODBC Drivers] Amazon Redshift ODBC Driver (x64)=Installed [Amazon Redshift ODBC Driver (x64)] Description=Amazon Redshift ODBC Driver (64-bit) Driver=/opt/amazon/redshiftodbcx64/librsodbc64.dylib ``` # 身分驗證方法 為了防止有人未經授權就存取資料，Amazon Redshift 資料存放區會要求所有連線使用使用者憑證進行身分驗證。 下表說明可用來連線至 Amazon Redshift ODBC 驅動程式 2.x 版之每種身分驗證方法的必要和選用連線選項： | 身分驗證方法 | 必要 | 選用 | | --- | --- | --- | | 標準 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | | | IAM 設定檔 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果 **ClusterID** 和 **Region** 未單獨設定，則必須在 **Host** 中加以設定。 | | IAM 登入資料 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果 **ClusterID** 和 **Region** 未單獨設定，則必須在 **Host** 中加以設定。 | | AD FS | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果 **ClusterID** 和 **Region** 未單獨設定，則必須在 **Host** 中加以設定。 | | Azure AD | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果 **ClusterID** 和 **Region** 未單獨設定，則必須在 **Host** 中加以設定。 | | JWT | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | | Okta | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果 **ClusterID** 和 **Region** 未單獨設定，則必須在 **Host** 中加以設定。 | | Ping Federate | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果 **ClusterID** 和 **Region** 未單獨設定，則必須在 **Host** 中加以設定。 | | 瀏覽器 Azure AD | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果 **ClusterID** 和 **Region** 未單獨設定，則必須在 **Host** 中加以設定。 | | 瀏覽器 SAML | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果 **ClusterID** 和 **Region** 未單獨設定，則必須在 **Host** 中加以設定。 | | Auth Profile | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | | | 瀏覽器 Azure AD OAUTH2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) 如果 **ClusterID** 和 **Region** 未單獨設定，則必須在 **Host** 中加以設定。 | | AWS IAM Identity Center | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/odbc20-authentication-ssl.html) | ## 使用外部憑證服務 除了內建支援 AD FS、Azure AD 和 Okta 外，Windows 版本的 Amazon Redshift ODBC 驅動程式也支援其他憑證服務。驅動程式可以使用您選擇的任何 SAML 型憑證提供者外掛程式來驗證連線。 若要在 Windows 上設定外部憑證服務： 1. 建立會指定憑證提供者外掛程式和視需要指定其他身分驗證參數的 IAM 設定檔。設定檔必須採用 ASCII 編碼，且必須包含下列鍵值組，其中 `PluginPath` 是外掛程式應用程式的完整路徑： ``` plugin_name = PluginPath ``` 例如： ``` plugin_name = C:\Users\kjson\myapp\CredServiceApp.exe ``` 如需有關如何建立設定檔的資訊，請參閱《Amazon Redshift 叢集管理指南》中的[使用組態設定檔](https://docs.aws.amazon.com/redshift/latest/mgmt/options-for-providing-iam-credentials.html#using-configuration-profile)。 1. 將驅動程式設定為使用此設定檔。驅動程式會偵測並使用設定檔中指定的驗證設定。 # 資料類型轉換 Amazon Redshift ODBC 驅動程式 2.x 版支援許多常見的資料格式，可在 Amazon Redshift 和 SQL 資料類型之間進行轉換。 下表列出支援的資料類型映射。 | Amazon Redshift 類型 | SQL 類型 | | --- | --- | | BIGINT | SQL\$1BIGINT | | BOOLEAN | SQL\$1BIT | | CHAR | SQL\$1CHAR | | DATE | SQL\$1TYPE\$1DATE | | DECIMAL | SQL\$1NUMERIC | | DOUBLE PRECISION | SQL\$1DOUBLE | | GEOGRAPHY | SQL\$1 LONGVARBINARY | | GEOMETRY | SQL\$1 LONGVARBINARY | | INTEGER | SQL\$1INTEGER | | REAL | SQL\$1REAL | | SMALLINT | SQL\$1SMALLINT | | SUPER | SQL\$1LONGVARCHAR | | TEXT | SQL\$1LONGVARCHAR | | TIME | SQL\$1TYPE\$1TIME | | TIMETZ | SQL\$1TYPE\$1TIME | | TIMESTAMP | SQL\$1TYPE\$1 TIMESTAMP | | TIMESTAMPTZ | SQL\$1TYPE\$1 TIMESTAMP | | VARBYTE | SQL\$1LONGVARBINARY | | VARCHAR | SQL\$1VARCHAR | # ODBC 驅動器選項 您可以使用驅動程式組態選項來控制 Amazon Redshift ODBC 驅動程式的行為。驅動程式選項不區分大小寫。 在 Microsoft Windows 中，您通常於設定資料來源名稱 (DSN) 時設定驅動程式選項。您也可以在連接時以程式設計方式在連線字串中設定驅動程式選項，或在 `HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\your_DSN` 中新增或變更登錄機碼。 在 Linux 中，您可以在 `odbc.ini` 和 `amazon.redshiftodbc.ini` 檔案中設定驅動器組態選項。在 `amazon.redshiftodbc.ini` 檔案中設定的組態選項會套用至所有連線。相反地，`odbc.ini` 檔案中設定的組態選項是針對某個連線。`odbc.ini` 中設定的組態選項優先於 `amazon.redshiftodbc.ini` 中設定的組態選項。 以下是您可以為 Amazon Redshift ODBC 2.x 版驅動程式指定之選項的描述。 ## AccessKeyID + **預設值** — 無 + **資料類型** — 字串 使用者或角色的 IAM 存取金鑰。如果設定此參數，則也必須指定 **SecretAccessKey**。 此為選用參數。 ## app\$1id + **預設值** — 無 + **資料類型** — 字串 與您的 Amazon Redshift 應用程式相關聯、Okta 所提供的唯一 ID。 此為選用參數。 ## ApplicationName + **預設值** — 無 + **資料類型** — 字串 要傳遞至 Amazon Redshift 以進行稽核的用戶端應用程式名稱。您提供的應用程式名稱會出現在 [SYS\$1CONNECTION\$1LOG](https://docs.aws.amazon.com/redshift/latest/dg/SYS_CONNECTION_LOG.html) 資料表的 'application\$1name' 欄中。此名稱有助於在偵錯問題時，追蹤連線來源並進行故障診斷。 此為選用參數。 ## app\$1name + **預設值** — 無 + **資料類型** — 字串 您用來驗證與 Amazon Redshift 之連線的 Okta 應用程式名稱。 此為選用參數。 ## AuthProfile + **預設值** — 無 + **資料類型** — 字串 用來管理連線設定的身分驗證設定檔。如果設定此參數，則也必須指定 **AccessKeyID** 和 **SecretAccessKey**。 此為選用參數。 ## AuthType + **預設值** — 標準 + **資料類型** — 字串 此選項指定當您使用 [Amazon Redshift ODBC 驅動程式 DSN 設定] 對話方塊設定 DSN 時，驅動程式會使用的身分驗證模式： + 標準：使用 Amazon Redshift 使用者名稱和密碼的標準身分驗證。 + AWS 設定檔：使用設定檔進行 IAM 身分驗證。 + AWS IAM 登入資料：使用 IAM 登入資料的 IAM 身分驗證。 + 身分提供者：AD FS：使用 Active Directory Federation Services (AD FS) 進行 IAM 身分驗證。 + Identity Provider：Auth Plugin：從任何連結至 AWS IAM Identity Center 的 Web Identity Provider 接受 IAM Identity Center 權杖或 OpenID Connect (OIDC) JSON 型身分權杖 (JWT) AWS 的授權外掛程式。 + 身分提供者：Azure AD：使用 Azure AD 入口網站進行 IAM 身分驗證。 + 身分提供者：JWT：使用 JSON Web 權杖 (JWT) 進行 IAM 身分驗證。 + 身分提供者：Okta：使用 Okta 進行 IAM 身分驗證。 + 身分提供者：PingFederate：使用 PingFederate 進行 IAM 身分驗證。 只有當您使用 Windows 驅動程式中的 [Amazon Redshift ODBC 驅動程式 DSN 設定] 對話方塊設定 DSN 時，才能使用此選項。當您使用連線字串或非 Windows 機器設定連線時，驅動程式會根據您指定的登入資料，自動判斷要使用標準、 AWS 設定檔或 AWS IAM 登入資料身分驗證。若要使用身分提供者，您必須設定 **plugin\$1name** 屬性。 此為必要參數。 ## AutoCreate + **預設值** — 0 + **資料類型** — 布林值 指定當所指定的使用者不存在時，驅動程式是否會建立新使用者的布林值。 + 1 \$1 TRUE：如果透過 **UID** 指定的使用者不存在，驅動程式會建立新使用者。 + 0 \$1 FALSE：驅動程式不會建立新使用者。如果指定的使用者不存在，則身分驗證會失敗。 此為選用參數。 ## CaFile + **預設值** — 無 + **資料類型** — 字串 用於某些 IAM 身分驗證形式之 CA 憑證檔案的檔案路徑。 這個參數只能在 Linux 上使用。 此為選用參數。 ## client\$1id + **預設值** — 無 + **資料類型** — 字串 與 Azure AD 中 Amazon Redshift 應用程式相關聯的用戶端 ID。 如果透過 Azure AD 服務進行驗證，則需要此參數。 ## client\$1 secret + **預設值** — 無 + **資料類型** — 字串 與 Azure AD 中 Amazon Redshift 應用程式相關聯的私密金鑰。 如果透過 Azure AD 服務進行驗證，則需要此參數。 ## ClusterId + **預設值** — 無 + **資料類型** — 字串 您想要連線到之 Amazon Redshift 叢集的名稱。其會用於 IAM 身分驗證。**伺服器**參數中不會指定叢集 ID。 此為選用參數。 ## 壓縮 + **預設值** - off + **資料類型** — 字串 用於 Amazon Redshift 伺服器與用戶端或驅動程式之間的有線通訊協定通訊的壓縮方法。 您可以指定下列值： + lz4：將用於與 Amazon Redshift 進行有線通訊協定通訊的壓縮方法設定為 `lz4`。 + zstd：將用於與 Amazon Redshift 進行有線通訊協定通訊的壓縮方法設定為 `zstd`。 + off：不要對與 Amazon Redshift 進行的有線通訊協定通訊使用壓縮。 此為選用參數。 ## 資料庫 + **預設值** — 無 + **資料類型** — 字串 您想要存取之 Amazon Redshift 資料庫的名稱。 此為必要參數。 ## DatabaseMetadataCurrentDbOnly + **預設值** — 1 + **資料類型** — 布林值 指定驅動程式是否會從多個資料庫和叢集傳回中繼資料的布林值。 + 1 \$1 TRUE：驅動程式只會從目前的資料庫傳回中繼資料。 + 0 \$1 FALSE。驅動程式會傳回多個 Amazon Redshift 資料庫和叢集的中繼資料。 此為選用參數。 ## dbgroups\$1filter + **預設值** — 無 + **資料類型** — 字串 當您使用 Azure、瀏覽器 Azure 和瀏覽器 SAML 身分驗證類型時，可指定來篩選出從 Amazon Redshift 的 SAML 回應收到之 DbGroups 的規則運算式。 此為選用參數。 ## 驅動程式 + **預設值** — Amazon Redshift ODBC 驅動程式 (x64) + **資料類型** — 字串 驅動程式的名稱。唯一支援的值是 **Amazon Redshift ODBC 驅動程式 (x64)**。 如果您未設定 **DSN**，則需要此參數。 ## DSN + **預設值** — 無 + **資料類型** — 字串 驅動程式資料來源名稱的名稱。應用程式會在 SQLDriverConnect API 中指定 DSN。 如果您未設定**驅動程式**，則需要此參數。 ## EndpointUrl + **預設值** — 無 + **資料類型** — 字串 用來與 Amazon Redshift Coral Service 通訊以進行 IAM 身分驗證的覆寫端點。 此為選用參數。 ## ForceLowercase + **預設值** — 0 + **資料類型** — 布林值 指定在使用單一登入身分驗證時，驅動程式是否會將從身分提供者傳送至 Amazon Redshift 的所有 DbGroups 轉換為小寫的布林值。 + 1 \$1 TRUE：驅動程式會將從身分提供者傳送的所有 DbGroups 轉換為小寫。 + 0 \$1 FALSE：驅動程式不會改變 DbGroups。 此為選用參數。 ## group\$1federation + **預設值** — 0 + **資料類型** — 布林值 此布林值指定是否在佈建叢集中使用 `getClusterCredentialsWithIAM` API 取得臨時叢集憑證。此選項可讓 IAM 使用者與佈建叢集中的 Redshift 資料庫角色整合。請注意，此選項不適用於 Redshift Serverless 命名空間。 + 1 \$1 TRUE：驅動器使用 `getClusterCredentialsWithIAM` API 在佈建叢集中取得臨時叢集憑證。 + 0 \$1 FALSE：驅動器使用預設 `getClusterCredentials` API 在佈建叢集中取得臨時叢集憑證。 此為選用參數。 ## https\$1proxy\$1host + **預設值** — 無 + **資料類型** — 字串 您想要透過其通過 IAM 身分驗證程序之代理伺服器的主機名稱或 IP 地址。 此為選用參數。 ## https\$1proxy\$1password + **預設值** — 無 + **資料類型** — 字串 您用來存取代理伺服器的密碼。其會用於 IAM 身分驗證。 此為選用參數。 ## https\$1proxy\$1port + **預設值** — 無 + **資料類型** — 整數 代理伺服器用來接聽用戶端連線的連接埠號碼。其會用於 IAM 身分驗證。 此為選用參數。 ## https\$1proxy\$1username + **預設值** — 無 + **資料類型** — 字串 您用來存取代理伺服器的使用者名稱。其會用於 IAM 身分驗證。 此為選用參數。 ## IAM + **預設值** — 0 + **資料類型** — 布林值 指定驅動程式是否會使用 IAM 身分驗證方法來驗證連線的布林值。 + 1 \$1 TRUE：驅動程式會使用其中一種 IAM 身分驗證方法 (使用存取金鑰和私密金鑰組、或設定檔或憑證服務)。 + 0 \$1 FALSE。驅動程式會使用標準身分驗證 (使用資料庫使用者名稱和密碼)。 此為選用參數。 ## idc\$1client\$1display\$1name + **預設值** - Amazon Redshift ODBC 驅動器 + **資料類型** — 字串 使用 BrowserIdcAuthPlugin 的用戶端要使用的顯示名稱。 此為選用參數。 ## idc\$1region + **預設值** — 無 + **資料類型** — 字串 IAM Identity Center AWS 執行個體所在的 AWS 區域。 只有在 plugin\$1name 組態選項中使用 `BrowserIdcAuthPlugin` 進行身分驗證時，才需要此參數。 ## idp\$1host + **預設值** — 無 + **資料類型** — 字串 您用來對 Amazon Redshift 進行身分驗證的 IdP (身分提供者) 主機。 此為選用參數。 ## idp\$1port + **預設值** — 無 + **資料類型** — 整數 您用來對 Amazon Redshift 進行身分驗證的 IdP (身分提供者) 連接埠。根據您在建立、修改或遷移叢集時所選取的連接埠而定，允許存取選取的連接埠。 此為選用參數。 ## idp\$1response\$1timeout + **預設值** — 120 + **資料類型** — 整數 透過瀏覽器外掛程式使用 SAML 或 Azure AD 服務時，驅動程式等待身分提供者所傳 SAML 回應的秒數。 此為選用參數。 ## idp\$1tenant + **預設值** — 無 + **資料類型** — 字串 與 Amazon Redshift 應用程式相關聯的 Azure AD 租用戶 ID。 如果透過 Azure AD 服務進行驗證，則需要此參數。 ## idp\$1partition + **預設值** — 無 + **資料類型** — 字串 指定設定身分提供者 (IdP) 的雲端分割區。這會決定驅動程式連線到哪個 IdP 身分驗證端點。 如果此參數保留空白，驅動程式會預設為商業分割區。可能值為： + `us-gov`：如果您的 IdP 是在 Azure Government 中設定，請使用此值。例如，Azure AD Government 會使用端點 `login.microsoftonline.us`。 + `cn`：如果您的 IdP 是在中國雲端分割區中設定，請使用此值。例如，Azure AD 中國使用端點 `login.chinacloudapi.cn`。 此為選用參數。 ## idp\$1use\$1https\$1proxy + **預設值** — 0 + **資料類型** — 布林值 指定驅動程式是否會透過代理伺服器來通過身分提供者 (IdP) 身分驗證程序的布林值。 + 1 \$1 TRUE：驅動程式會透過代理伺服器來通過 IdP 身分驗證程序。 + 0 \$1 FALSE。驅動程式不會透過代理伺服器來通過 IdP 身分驗證程序。 此為選用參數。 ## InstanceProfile + **預設值** — 0 + **資料類型** — 布林值 指定驅動程式在設定為使用設定檔進行身分驗證時，是否會使用 Amazon EC2 執行個體設定檔的布林值。 + 1 \$1 TRUE：驅動程式會使用 Amazon EC2 執行個體設定檔。 + 0 \$1 FALSE。驅動程式會改用 [設定檔名稱] 選項 (**設定檔**) 所指定的鏈結角色設定檔。 此為選用參數。 ## issuer\$1url + **預設值** — 無 + **資料類型** — 字串 指向 AWS IAM Identity Center 伺服器的執行個體端點。 只有在 plugin\$1name 組態選項中使用 `BrowserIdcAuthPlugin` 進行身分驗證時，才需要此參數。 ## KeepAlive + **預設值** — 1 + **資料類型** — 布林值 指定驅動程式是否會使用 TCP 保持連線來防止連線逾時的布林值。 + 1 \$1 TRUE：驅動程式會使用 TCP 保持連線來防止連線逾時。 + 0 \$1 FALSE。驅動程式不會使用 TCP 保持連線。 此為選用參數。 ## KeepAliveCount + **預設值** — 0 + **資料類型** — 整數 在認為連線已中斷之前可遺失的 TCP 保持連線封包數。此參數設為 0 時，驅動程式會使用此設定的系統預設值。 此為選用參數。 ## KeepAliveInterval + **預設值** — 0 + **資料類型** — 整數 每一次 TCP 保持連線重新傳輸之間的秒數。此參數設為 0 時，驅動程式會使用此設定的系統預設值。 此為選用參數。 ## KeepAliveTime + **預設值** — 0 + **資料類型** — 整數 驅動程式傳送 TCP 保持連線封包之前的閒置秒數。此參數設為 0 時，驅動程式會使用此設定的系統預設值。 此為選用參數。 ## listen\$1port + **預設值** — 7890 + **資料類型** — 整數 透過瀏覽器外掛程式使用 SAML、Azure AD 或 IAM Identity Center AWS 服務時，驅動程式用來從身分提供者或授權碼接收 SAML 回應的連接埠。 此為選用參數。 ## login\$1url + **預設值** — 無 + **資料類型** — 字串 使用一般瀏覽器 SAML 外掛程式時，身分提供者網站上資源的 URL。 如果透過瀏覽器外掛程式向 SAML 或 Azure AD 服務進行驗證，則需要此參數。 ## loginToRp + **預設值** — urn:amazon:webservices + **資料類型** — 字串 您要用於 AD FS 身分驗證類型的依賴方信任。 此為選用字串。 ## LogLevel + **預設值** — 0 + **資料類型** — 整數 使用此屬性可在驅動程式中啟用或停用日誌記錄，以及指定日誌檔案中包含的詳細資訊數量。日誌記錄建議只啟用到足以擷取到問題就好，因為日誌記錄會降低效能，而且可能會耗用大量磁碟空間。 將此屬性設為以下其中一個值： + 0：OFF。停用所有日誌記錄功能。 + 1：ERROR。記錄可能允許驅動程式繼續執行但會產生錯誤的錯誤事件。 + 2：API\$1CALL。記錄 ODBC API 函數呼叫與函數引數值。 + 3：INFO。記錄用於描述驅動程式進展的一般資訊。 + 4：MSG\$1PROTOCOL。記錄驅動程式的訊息通訊協定詳細資訊。 + 5：DEBUG。記錄所有驅動程式活動。 + 6：DEBUG\$1APPEND。持續附加所有驅動程式活動的日誌。 在啟用日誌記錄功能時，驅動程式會在您於 **LogPath** 屬性中指定的位置產生下列日誌檔案： + 記錄在連線交握期間發生之驅動程式活動的 `redshift_odbc.log.1` 檔案。 + 在與資料庫建立連線後所有驅動程式活動的 `redshift_odbc.log` 檔案。 此為選用參數。 ## LogPath + **預設值** — 作業系統特定的 TEMP 目錄 + **資料類型** — 字串 **LogLevel** 大於 0 時，驅動程式用來儲存日誌檔案之資料夾的完整路徑。 此為選用參數。 ## Min\$1TLS + **預設值** – 1.2 + **資料類型** — 字串 驅動程式允許資料存放區用於加密連線的 TLS/SSL 最低版本。例如，如果指定 TLS 1.2，則無法使用 TLS 1.1 來加密連線。 Min\$1TLS 接受以下值： + 1.0：連線必須至少使用 TLS 1.0。 + 1.1：連線必須至少使用 TLS 1.1。 + 1.2：連線至少必須使用 TLS 1.2。 此為選用參數。 ## partner\$1spid + **預設值** — 無 + **資料類型** — 字串 使用 PingFederate 服務驗證連線時，要使用的合作夥伴 SPID (服務提供者 ID) 值。 此為選用參數。 ## Password \$1 PWS + **預設值** — 無 + **資料類型** — 字串 與您在 [使用者] 欄位 (**UID** \$1 **User** \$1 **LogonID**) 中所提供資料庫使用者名稱對應的密碼。 此為選用參數。 ## plugin\$1name + **預設值** — 無 + **資料類型** — 字串 您想要用於身分驗證的憑證提供者外掛程式名稱。 支援下列值： + `ADFS`：使用 Active Directory Federation Services 進行身分驗證。 + `AzureAD`：使用 Microsoft Azure Active Directory (AD) Service 進行身分驗證。 + `BrowserAzureAD`：使用 Microsoft Azure Active Directory (AD) Service 的瀏覽器外掛程式進行身分驗證。 + `BrowserIdcAuthPlugin `：使用 AWS IAM Identity Center 的授權外掛程式。 + `BrowserSAML`：使用 SAML 服務 (例如 Okta 或 Ping) 的瀏覽器外掛程式進行身分驗證。 + `IdpTokenAuthPlugin`：從連結至 AWS IAM Identity Center 的任何 Web 身分提供者接受 IAM Identity Center 字符或 OpenID Connect (OIDC) JSON 型身分字符 (JWT) AWS 的授權外掛程式。 + `JWT`：使用 JSON Web 權杖 (JWT) 進行身分驗證。 + `Ping`：使用 PingFederate 服務進行身分驗證。 + `Okta`：使用 Okta 服務進行身分驗證。 此為選用參數。 ## Port \$1 PortNumber + **預設值** — 5439 + **資料類型** — 整數 Amazon Redshift 伺服器用來接聽用戶端連線的 TCP 連接埠號碼。 此為選用參數。 ## preferred\$1role + **預設值** — 無 + **資料類型** — 字串 您要在連線到 Amazon Redshift 期間擔任的角色。其會用於 IAM 身分驗證。 此為選用參數。 ## 設定檔 + **預設值** — 無 + **資料類型** — 字串 用於向 Amazon Redshift 驗證的使用者 AWS 設定檔名稱。 + 如果 Use Instance Profile 參數 (**InstanceProfile** 屬性) 設為 1 \$1 TRUE，則該設定會優先，而且驅動程式會改用 Amazon EC2 執行個體設定檔。 + 包含設定檔之憑證檔案的預設位置為 `~/.aws/Credentials`。可使用 `AWS_SHARED_CREDENTIALS_FILE` 環境變數以指向不同的憑證檔案。 此為選用參數。 ## provider\$1name + **預設值** — 無 + **資料類型** — 字串 使用者使用 CREATE IDENTITY PROVIDER 查詢所建立的身分驗證提供者。其會用於原生 Amazon Redshift 身分驗證。 此為選用參數。 ## ProxyHost + **預設值** — 無 + **資料類型** — 字串 您想要透過其進行連線之代理伺服器的主機名稱或 IP 地址。 此為選用參數。 ## ProxyPort + **預設值** — 無 + **資料類型** — 整數 代理伺服器用來接聽用戶端連線的連接埠號碼。 此為選用參數。 ## ProxyPwd + **預設 ValPrevious ODBC 驅動程式版本ue** – 無 + **資料類型** — 字串 您用來存取代理伺服器的密碼。 此為選用參數。 ## ProxyUid + **預設值** — 無 + **資料類型** — 字串 您用來存取代理伺服器的使用者名稱。 此為選用參數。 ## ReadOnly + **預設值** — 0 + **資料類型** — 布林值 指定驅動程式是否處於唯讀模式的布林值。 + 1 \$1 TRUE：連線處於唯讀模式，無法寫入到資料存放區。 + 0 \$1 FALSE：連接不處於唯讀模式，可以寫入到資料存放區。 此為選用參數。 ## region + **預設值** — 無 + **資料類型** — 字串 叢集所在的 AWS 區域。 此為選用參數。 ## SecretAccessKey + **預設值** — 無 + **資料類型** — 字串 使用者或角色的 IAM 私密金鑰。如果設定此參數，則也必須指定 **AccessKeyID**。 此為選用參數。 ## SessionToken + **預設值** — 無 + **資料類型** — 字串 與您用來驗證的 IAM 角色相關聯的臨時 IAM 工作階段權杖。 此為選用參數。 ## Server \$1 HostName \$1 Host + **預設值** — 無 + **資料類型** — 字串 要連線到的端點伺服器。 此為必要參數。 ## ssl\$1insecure + **預設值** — 0 + **資料類型** — 布林值 指定驅動程式是否會檢查 IdP 伺服器憑證真確性的布林值。 + 1 \$1 TRUE：驅動程式不會檢查 IdP 伺服器憑證的真確性。 + 0 \$1 FALSE：驅動程式會檢查 IdP 伺服器憑證的真確性。 此為選用參數。 ## SSLMode + **預設值** — `verify-ca` + **資料類型** — 字串 連線到 Amazon Redshift 時要使用的 SSL 憑證驗證模式。可能的值如下： + `verify-full`：僅使用 SSL、受信任的憑證授權機構和符合憑證的伺服器名稱進行連線。 + `verify-ca`：僅使用 SSL 和受信任的憑證授權機構進行連線。 + `require`：僅使用 SSL 進行連線。 + `prefer`：使用 SSL (如果可用) 進行連線。否則，以不使用 SSL 的方式進行連線。 + `allow`：預設會以不使用 SSL 的方式進行連線。如果伺服器需要 SSL 連線，則使用 SSL。 + `disable`：以不使用 SSL 的方式進行連線。 此為選用參數。 ## StsConnectionTimeout + **預設值** — 0 + **資料類型** — 整數 IAM 連線的等待時間上限 (以秒為單位)。如果設定為 0 或未指定，驅動程式會等待每次 AWS STS 呼叫 60 秒。 此為選用參數。 ## StsEndpointUrl + **預設值** — 無 + **資料類型** — 字串 此選項會指定用來與 AWS Security Token Service (AWS STS) 進行通訊的覆寫端點。 此為選用參數。 ## token + **預設值** — 無 + **資料類型** — 字串 IAM Identity Center AWS 提供存取字符或由與 IAM Identity Center 連結的 Web 身分提供者提供的 OpenID Connect (OIDC) JSON Web Token AWS (JWT)。您的應用程式必須透過使用 IAM Identity Center AWS 或與 IAM AWS Identity Center 連結的身分提供者驗證應用程式的使用者來產生此字符。 此參數適用於 `IdpTokenAuthPlugin`。 ## token\$1type + **預設值** — 無 + **資料類型** — 字串 `IdpTokenAuthPlugin` 中使用的權仗類型。 您可以指定下列值： **ACCESS\$1TOKEN** 如果您使用 AWS IAM Identity Center 提供的存取權杖，請輸入此選項。 **EXT\$1JWT** 如果您使用與 AWS IAM Identity Center 整合的 Web 型身分提供者所提供的 OpenID Connect (OIDC) JSON Web Token (JWT)，請輸入此項。 此參數適用於 `IdpTokenAuthPlugin`。 ## UID \$1 User \$1 LogonID + **預設值** — 無 + **資料類型** — 字串 您用來存取 Amazon Redshift 伺服器的使用者名稱。 若您使用資料庫身分驗證，則此為必要參數。 ## UseUnicode + **預設值** — 0 + **資料類型** — 布林值 布林值，指定驅動程式是將 Redshift 資料傳回為 Unicode 還是一般 SQL 類型。 + 1 \$1 TRUE：驅動程式會傳回字元資料類型的廣泛 SQL 類型。 + SQL\$1WCHAR 會傳回，而不是 SQL\$1CHAR。 + SQL\$1WVARCHAR 會傳回，而不是 SQL\$1VARCHAR。 + SQL\$1WLONGVARCHAR 會傳回，而不是 SQL\$1LONGVARCHAR。 + 0 \$1 FALSE：驅動程式會傳回字元資料類型的一般 SQL 類型。 + SQL\$1CHAR 會傳回，而不是 SQL\$1WCHAR。 + SQL\$1VARCHAR 會傳回，而不是 SQL\$1WVARCHAR。 + SQL\$1LONGVARCHAR 會傳回，而不是 SQL\$1WLONGVARCHAR。 此為選用參數。它適用於驅動程式 2.1.15 版和更新版本。 ## web\$1identity\$1token + **預設值** — 無 + **資料類型** — 字串 身分提供者所提供的 OAUTH 權杖。其會用於 JWT 外掛程式。 如果您將 **plugin\$1name** 參數設定為 BasicJwtCredentialsProvider，則此為必要參數。 # 先前的 ODBC 驅動程式版本 請在您的工具需要特定版本的驅動程式時，才下載 Amazon Redshift ODBC 驅動程式 2.x 版之前的版本。 ## 使用先前的 ODBC 驅動程式版本 (適用於 Microsoft Windows) 以下是適用於 Microsoft Windows 的舊版 Amazon Redshift ODBC 驅動程式 2.x 版： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC64-2.1.14.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC64-2.1.14.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC64-2.1.13.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC64-2.1.13.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC64-2.1.12.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC64-2.1.12.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC64-2.1.11.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC64-2.1.11.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.10.0/AmazonRedshiftODBC64-2.1.10.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.10.0/AmazonRedshiftODBC64-2.1.10.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC64-2.1.9.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC64-2.1.9.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC64-2.1.9.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC64-2.1.9.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.8.0/AmazonRedshiftODBC64-2.1.8.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.8.0/AmazonRedshiftODBC64-2.1.8.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.7.0/AmazonRedshiftODBC64-2.1.7.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.7.0/AmazonRedshiftODBC64-2.1.7.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.6.0/AmazonRedshiftODBC64-2.1.6.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.6.0/AmazonRedshiftODBC64-2.1.6.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.4.0/AmazonRedshiftODBC64-2.1.4.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.4.0/AmazonRedshiftODBC64-2.1.4.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.3.0/AmazonRedshiftODBC64-2.1.3.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.3.0/AmazonRedshiftODBC64-2.1.3.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.2.0/AmazonRedshiftODBC64-2.1.2.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.2.0/AmazonRedshiftODBC64-2.1.2.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.1.0/AmazonRedshiftODBC64-2.1.1.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.1.0/AmazonRedshiftODBC64-2.1.1.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.0.0/AmazonRedshiftODBC64-2.1.0.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.0.0/AmazonRedshiftODBC64-2.1.0.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.1.0/AmazonRedshiftODBC64-2.0.1.0.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.1.0/AmazonRedshiftODBC64-2.0.1.0.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.11/AmazonRedshiftODBC64-2.0.0.11.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.11/AmazonRedshiftODBC64-2.0.0.11.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.9/AmazonRedshiftODBC64-2.0.0.9.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.9/AmazonRedshiftODBC64-2.0.0.9.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.8/AmazonRedshiftODBC64-2.0.0.8.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.8/AmazonRedshiftODBC64-2.0.0.8.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.7/AmazonRedshiftODBC64-2.0.0.7.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.7/AmazonRedshiftODBC64-2.0.0.7.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.6/AmazonRedshiftODBC64-2.0.0.6.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.6/AmazonRedshiftODBC64-2.0.0.6.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.5/AmazonRedshiftODBC64-2.0.0.5.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.5/AmazonRedshiftODBC64-2.0.0.5.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.3/AmazonRedshiftODBC64-2.0.0.3.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.3/AmazonRedshiftODBC64-2.0.0.3.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.1/AmazonRedshiftODBC64-2.0.0.1.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.1/AmazonRedshiftODBC64-2.0.0.1.msi) ## 使用先前的 ODBC 驅動程式版本 (適用於 Linux) 以下是適用於 Linux 的舊版 Amazon Redshift ODBC 驅動程式 2.x 版： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit-2.1.14.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit-2.1.14.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit-2.1.14.0.aarch64.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit-2.1.14.0.aarch64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit-2.1.13.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit-2.1.13.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit-2.1.13.0.aarch64.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit-2.1.13.0.aarch64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit-2.1.12.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit-2.1.12.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit-2.1.12.0.aarch64.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit-2.1.12.0.aarch64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC-64-bit-2.1.11.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC-64-bit-2.1.11.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC-64-bit-2.1.11.0.aarch64.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.11.0/AmazonRedshiftODBC-64-bit-2.1.11.0.aarch64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.10.0/AmazonRedshiftODBC-64-bit-2.1.10.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.10.0/AmazonRedshiftODBC-64-bit-2.1.10.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC-64-bit-2.1.9.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.9.0/AmazonRedshiftODBC-64-bit-2.1.9.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.8.0/AmazonRedshiftODBC-64-bit-2.1.8.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.8.0/AmazonRedshiftODBC-64-bit-2.1.8.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.7.0/AmazonRedshiftODBC-64-bit-2.1.7.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.7.0/AmazonRedshiftODBC-64-bit-2.1.7.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.6.0/AmazonRedshiftODBC-64-bit-2.1.6.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.6.0/AmazonRedshiftODBC-64-bit-2.1.6.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.4.0/AmazonRedshiftODBC-64-bit-2.1.4.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.4.0/AmazonRedshiftODBC-64-bit-2.1.4.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.3.0/AmazonRedshiftODBC-64-bit-2.1.3.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.3.0/AmazonRedshiftODBC-64-bit-2.1.3.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.2.0/AmazonRedshiftODBC-64-bit-2.1.2.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.2.0/AmazonRedshiftODBC-64-bit-2.1.2.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.1.0/AmazonRedshiftODBC-64-bit-2.1.1.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.1.0/AmazonRedshiftODBC-64-bit-2.1.1.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.0.0/AmazonRedshiftODBC-64-bit-2.1.0.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.0.0/AmazonRedshiftODBC-64-bit-2.1.0.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.1.0/AmazonRedshiftODBC-64-bit-2.0.1.0.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.1.0/AmazonRedshiftODBC-64-bit-2.0.1.0.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.11/AmazonRedshiftODBC-64-bit-2.0.0.11.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.11/AmazonRedshiftODBC-64-bit-2.0.0.11.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.9/AmazonRedshiftODBC-64-bit-2.0.0.9.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.9/AmazonRedshiftODBC-64-bit-2.0.0.9.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.8/AmazonRedshiftODBC-64-bit-2.0.0.8.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.8/AmazonRedshiftODBC-64-bit-2.0.0.8.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.7/AmazonRedshiftODBC-64-bit-2.0.0.7.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.7/AmazonRedshiftODBC-64-bit-2.0.0.7.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.6/AmazonRedshiftODBC-64-bit-2.0.0.6.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.6/AmazonRedshiftODBC-64-bit-2.0.0.6.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.5/AmazonRedshiftODBC-64-bit-2.0.0.5.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.5/AmazonRedshiftODBC-64-bit-2.0.0.5.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.3/AmazonRedshiftODBC-64-bit-2.0.0.3.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.3/AmazonRedshiftODBC-64-bit-2.0.0.3.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.1/AmazonRedshiftODBC-64-bit-2.0.0.1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.0.0.1/AmazonRedshiftODBC-64-bit-2.0.0.1.x86_64.rpm) ## 使用 Apple macOS 的舊版 ODBC 驅動程式 以下是 Amazon Redshift ODBC 驅動程式 2.x for Apple macOS 的先前版本： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit.2.1.14.0.universal.pkg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.14.0/AmazonRedshiftODBC-64-bit.2.1.14.0.universal.pkg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit.2.1.13.0.universal.pkg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.13.0/AmazonRedshiftODBC-64-bit.2.1.13.0.universal.pkg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit.2.1.12.0.universal.pkg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/2.1.12.0/AmazonRedshiftODBC-64-bit.2.1.12.0.universal.pkg) # 設定 ODBC 驅動程式 1.x 版連線 您可以從許多第三方 SQL 用戶端工具和應用程式使用 ODBC 連線來連線至 Amazon Redshift 叢集。若要這麼做，請在用戶端電腦或 Amazon EC2 執行個體上設定連線。如果用戶端工具支援 JDBC，您可能選擇使用這種連線，而非 ODBC，因為 JDBC 的設定簡單。但是，如果用戶端工具不支援 JDBC，請遵循本節的步驟來設定 ODBC 連線。 Amazon Redshift 會提供適用於 Linux、Windows 和 macOS X 作業系統的 64 位元 ODBC 驅動程式。32 位元的 ODBC 驅動程式已停止使用。除了緊急的安全修補程式外，不會再發佈其他更新。 如需 ODBC 驅動程式功能和先決條件的最新資訊，請參閱 [Amazon Redshift ODBC 驅動程式版本備註](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Release+Notes.pdf)。 如需 Amazon Redshift ODBC 驅動程式的安裝與組態資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 **Topics** + [取得 ODBC URL](obtain-odbc-url.md) + [在 Microsoft Windows 上使用 Amazon Redshift ODBC 驅動器](install-odbc-driver-windows.md) + [在 Linux 上使用 Amazon Redshift ODBC 驅動器](install-odbc-driver-linux.md) + [在 macOS X 上使用 Amazon Redshift ODBC 驅動器](install-odbc-driver-mac.md) + [ODBC 驅動器選項](configure-odbc-options.md) + [先前的 ODBC 驅動程式版本](odbc-previous-versions.md) # 取得 ODBC URL Amazon Redshift 會在 Amazon Redshift 主控台中顯示叢集的 ODBC URL。此 URL 包含要在用戶端電腦和資料庫之間設定連線的資訊。 ODBC URL 採用下列格式：`Driver={driver};Server=endpoint;Database=database_name;UID=user_name;PWD=password;Port=port_number` 前面顯示的格式欄位具有下列值。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/obtain-odbc-url.html) 上述資料表中的欄位可包含下列特殊字元： ``` []{}(),;?*=!@ ``` 如果您使用這些特殊字元，則必須用大括號括住值。例如，連線字串中的密碼值 `Your;password123` 會表示為 `PWD={Your;password123};`。 由於 `Field=value` 配對會以分號分隔，因此 `}` 與 `;` 的組合中間若有任意數量的空格，將會被視為是 `Field={value};` 配對的結尾。建議您避免在欄位值中使用連續的 `};`。例如，如果您將密碼值設定為 `PWD={This is a passwor} ;d};`，則密碼會是 `This is a passwor} ;`，因此 URL 會發生錯誤。 以下是 ODBC URL 範例。 ``` Driver={Amazon Redshift (x64)}; Server=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com; Database=dev; UID=adminuser; PWD=insert_your_admin_user_password_here; Port=5439 ``` 如需如何取得 ODBC 連線的資訊，請參閱[尋找叢集連線字串](connecting-connection-string.md)。 # 在 Microsoft Windows 上使用 Amazon Redshift ODBC 驅動器 請在存取 Amazon Redshift 資料倉儲的用戶端電腦上安裝 Amazon Redshift ODBC 驅動程式。您安裝驅動程式的每一台電腦必須符合最低系統需求清單：如需最低系統要求的相關資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 **Topics** + [下載並安裝 Amazon Redshift ODBC 驅動器](odbc-driver-windows-how-to-install.md) + [建立 ODBC 連線的系統 DSN 項目](create-dsn-odbc-windows.md) # 下載並安裝 Amazon Redshift ODBC 驅動器 使用下列程序來下載適用於 Windows 作業系統的 Amazon Redshift ODBC 驅動程式。僅在您執行的第三方應用程式經認證可與 Amazon Redshift 搭配使用，且需要有特定驅動程式時，才使用不同於以下的驅動程式。 **安裝 ODBC 驅動程式** 1. 根據 SQL 用戶端工具或應用程式的系統架構，下載下列其中一個項目： + [64 位元 ODBC 驅動程式 1.6.3 版](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/AmazonRedshiftODBC64-1.6.3.1008.msi) 這個驅動程式的名稱是 Amazon Redshift (x64)。 + [32 位元 ODBC 驅動程式版本 1.4.52](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC32-1.4.52.1000.msi) 這個驅動程式的名稱是 Amazon Redshift (x86)。32 位元的 ODBC 驅動程式已停止使用。除了緊急的安全修補程式外，不會再發佈其他更新。 **注意** 下載對應於 SQL 用戶端工具或應用程式之系統架構的 MSI 套件。例如，假設 SQL 用戶端工具是 64 位元，請安裝 64 位元驅動程式。 然後下載並檢閱 [Amazon Redshift ODBC 和 JDBC 驅動程式授權合約](https://s3.amazonaws.com/redshift-downloads/drivers/Amazon+Redshift+ODBC+and+JDBC+Driver+License+Agreement.pdf)。 1. 按兩下 .msi 檔案，然後遵循精靈中的步驟來安裝驅動程式。 # 建立 ODBC 連線的系統 DSN 項目 在下載並安裝 ODBC 驅動程式之後，請將資料來源名稱 (DSN) 項目新增至用戶端電腦或 Amazon EC2 執行個體。SQL 用戶端工具會使用此資料來源以連線至 Amazon Redshift 資料庫。 建議您建立系統 DSN，而不是使用者 DSN。某些應用程式會使用不同的使用者帳戶載入資料。這些應用程式可能無法偵測在另一個使用者帳戶下建立的使用者 DSN。 **注意** 對於使用 AWS Identity and Access Management (IAM) 登入資料或身分提供者 (IdP) 登入資料的身分驗證，需要額外的步驟。如需詳細資訊，請參閱[步驟 5：設定 JDBC 或 ODBC 連線使用 IAM 登入資料](generating-iam-credentials-steps.md#generating-iam-credentials-configure-jdbc-odbc)。 如需如何建立系統 DSN 項目的相關資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 **在 Windows 上建立 ODBC 連線的系統 DSN 項目** 1. 在 **Start (開啟)** 功能表中，開啟 **ODBC Data Sources (ODBC 資料來源)**。 確定您選擇的 ODBC 資料來源管理員具有與您要用來連線到 Amazon Redshift 的用戶端應用程式相同的位元。 1. 在 **ODBC 資料來源管理員**中，選擇**驅動程式**索引標籤並尋找驅動程式資料夾： + **Amazon Redshift ODBC 驅動程式 (64 位元)** + **Amazon Redshift ODBC 驅動程式 (32 位元)** 1. 選擇 **System DSN (系統 DSN)** 標籤，為電腦上的所有使用者設定驅動程式，或選擇 **User DSN (使用者 DSN)** 標籤，只為您的使用者帳戶設定驅動程式。 1. 選擇**新增**。**Create New Data Source (建立新的資料來源)** 視窗會開啟。 1. 選擇 **Amazon Redshift** ODBC 驅動程式，然後選擇**完成**。**Amazon Redshift ODBC 驅動程式 DSN 設定**視窗會開啟。 1. 在 **Connection Settings (連線設定)** 下，輸入下列資訊： **資料來源名稱** 輸入資料來源的名稱。您可以使用稍後建立叢集連線時要用來識別資料來源的任何名稱。例如，如果您遵循了《Amazon Redshift 入門指南》**，則可能會輸入 `exampleclusterdsn`，以便輕鬆記住與此 DSN 建立關聯的叢集。 **Server** 指定 Amazon Redshift 叢集的端點。您可以在 Amazon Redshift 主控台的叢集詳細資訊頁面上找到此資訊。如需詳細資訊，請參閱[在 Amazon Redshift 中設定連線](configuring-connections.md)。 **站點** 輸入資料庫使用的連接埠號碼。請使用在叢集啟動或修改時設定給叢集使用的連接埠。 **資料庫** 輸入 Amazon Redshift 資料庫的名稱。如果您在未指定資料庫名稱的情況下啟動了叢集，請輸入 `dev`。否則，請使用您在啟動過程選擇的名稱。如果您遵循了《Amazon Redshift 入門指南》**，請輸入 `dev`。 1. 在 **Authentication (身分驗證)** 下，指定要設定標準或 IAM 身分驗證的組態選項。如需不同身分驗證選項的相關資訊，請參閱《Amazon Redshift ODBC 連接器安裝和組態指南》**中的「在 Windows 上設定身分驗證」。 1. 在 **SSL Settings (SSL 設定)** 下，指定下列這一項的值： **SSL authentication (SSL 身分驗證)** 選擇用於處理 Secure Sockets Layer (SSL) 的模式。在測試環境中，您可以使用 `prefer`。不過，若為生產環境且需要交換安全資料時，請使用 `verify-ca` 或 `verify-full`。如需在 Windows 上使用 SSL 的相關資訊，請參閱《Amazon Redshift ODBC 連接器安裝和組態指南》**中的「在 Windows 上設定 SSL 驗證」。 1. 在 **Additional Options (其他選項)** 下，指定如何將查詢結果傳回給 SQL 用戶端工具或應用程式的選項。如需詳細資訊，請參閱《Amazon Redshift ODBC 連接器安裝和組態指南》**中的「在 Windows 上設定其他選項」。 1. 在 **Logging Options (記錄選項)** 中，指定記錄選項的值：如需詳細資訊，請參閱《Amazon Redshift ODBC 連接器安裝和組態指南》**中的「在 Windows 上設定記錄選項」。 然後選擇 **OK (確定)**。 1. 在 **Data Type Options (資料類型選項)** 下，指定資料類型的值。如需詳細資訊，請參閱《Amazon Redshift ODBC 連接器安裝和組態指南》**中的「在 Windows 上設定資料類型選項」。 然後選擇 **OK (確定)**。 1. 選擇**測試**。如果用戶端電腦可以連線至 Amazon Redshift 資料庫，您會看到下列訊息：**連線成功**。 如果用戶端電腦無法連線至資料庫，您可以對可能的問題進行疑難排解。如需詳細資訊，請參閱[針對 Amazon Redshift 中的連線問題進行疑難排解](troubleshooting-connections.md)。 1. 在 Windows 上設定 TCP 保持連線，以防止連線逾時。如需如何在 Windows 上設定 TCP 保持連線的相關資訊，請參閱《Amazon Redshift ODBC 連接器安裝和組態指南》**。 1. 若要協助疑難排解，請設定記錄。如需如何在 Windows 上設定記錄的相關資訊，請參閱《Amazon Redshift ODBC 連接器安裝和組態指南》**。 # 在 Linux 上使用 Amazon Redshift ODBC 驅動器 請在存取 Amazon Redshift 資料倉儲的用戶端電腦上安裝 Amazon Redshift ODBC 驅動程式。您安裝驅動程式的每一台電腦必須符合最低系統需求清單：如需最低系統要求的相關資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 **Topics** + [下載並安裝 Amazon Redshift ODBC 驅動器](odbc-driver-linux-how-to-install.md) + [使用 ODBC 驅動器管理員設定驅動器](odbc-driver-configure-linux.md) # 下載並安裝 Amazon Redshift ODBC 驅動器 使用本節的步驟來下載 Amazon Redshift ODBC 驅動程式並安裝在 Linux 發行版本上。安裝程序會將驅動程式檔案安裝在下列目錄中： + `/opt/amazon/redshiftodbc/lib/64` (適用於 64 位元驅動程式) + `/opt/amazon/redshiftodbc/ErrorMessages` + `/opt/amazon/redshiftodbc/Setup` + `/opt/amazon/redshiftodbc/lib/32` (適用於 32 位元驅動程式) **安裝 Amazon Redshift ODBC 驅動程式** 1. 根據 SQL 用戶端工具或應用程式的系統架構，下載下列其中一個項目： + [64 位元 RPM 驅動程式 1.6.3 版](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/AmazonRedshiftODBC-64-bit-1.6.3.1008-1.x86_64.rpm) + [64 位元 Debian 驅動程式 1.6.3 版](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/AmazonRedshiftODBC-64-bit-1.6.3.1008-1.x86_64.deb) + [32 位元驅動程式版本 1.4.52](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-32-bit-1.4.52.1000-1.i686.rpm) 其中每一個驅動程式的名稱都是 Amazon Redshift ODBC 驅動程式。32 位元的 ODBC 驅動程式已停止使用。除了緊急的安全修補程式外，不會再發佈其他更新。 **注意** 下載對應於 SQL 用戶端工具或應用程式之系統架構的套件。例如，假設用戶端工具是 64 位元，請安裝 64 位元驅動程式。 然後下載並檢閱 [Amazon Redshift ODBC 和 JDBC 驅動程式授權合約](https://s3.amazonaws.com/redshift-downloads/drivers/Amazon+Redshift+ODBC+and+JDBC+Driver+License+Agreement.pdf)。 1. 移至您下載套件的位置，然後執行下列其中一個命令。使用與您的 Linux 發行版本相應的指令。 + 在 RHEL 和 CentOS 作業系統上，執行下列命令。 ``` yum -nogpgcheck localinstall RPMFileName ``` 將 *`RPMFileName`* 取代為 RPM 套件檔案名稱。例如，下列命令示範安裝 64 位元驅動程式。 ``` yum -nogpgcheck localinstall AmazonRedshiftODBC-64-bit-1.x.xx.xxxx-x.x86_64.rpm ``` + 在 SLES 上，執行下列命令。 ``` zypper install RPMFileName ``` 將 *`RPMFileName`* 取代為 RPM 套件檔案名稱。例如，下列命令示範安裝 64 位元驅動程式。 ``` zypper install AmazonRedshiftODBC-1.x.x.xxxx-x.x86_64.rpm ``` + 在 Debian 上，執行下列命令。 ``` sudo apt install ./DEBFileName.deb ``` 將 `DEBFileName.deb` 取代為 Debian 套件檔案名稱。例如，下列命令示範安裝 64 位元驅動程式。 ``` sudo apt install ./AmazonRedshiftODBC-1.x.x.xxxx-x.x86_64.deb ``` **重要** 驅動程式安裝完成時，請設定來用於您的系統。如需驅動程式組態的相關資訊，請參閱[使用 ODBC 驅動器管理員設定驅動器使用 ODBC 驅動器管理員設定驅動器](odbc-driver-configure-linux.md)。 # 使用 ODBC 驅動器管理員設定驅動器 在 Linux 作業系統上，您會使用 ODBC 驅動器管理員來設定 ODBC 連線設定。ODBC 驅動程式管理員使用組態檔案來定義及設定 ODBC 資料來源和驅動程式。您使用的 ODBC 驅動程式管理員視您使用的作業系統而定。對於 Linux，這是 unixODBC 驅動器管理員。 如需支援用來設定 Amazon Redshift ODBC 驅動器的 ODBC 驅動器管理員的詳細資訊，請參閱 Linux 作業系統的 [在 Linux 上使用 Amazon Redshift ODBC 驅動器在 Linux 上使用 ODBC 驅動器](install-odbc-driver-linux.md)。另請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的「在非 Windows 機器上指定 ODBC 驅動程式管理員」。 設定 Amazon Redshift ODBC 驅動程式需要三個檔案：`amazon.redshiftodbc.ini`、`odbc.ini` 和 `odbcinst.ini`。 如果是安裝到預設位置，則 `amazon.redshiftodbc.ini` 組態檔案位於下列其中一個目錄： + `/opt/amazon/redshiftodbc/lib/64` ( 適用於 Linux 作業系統上的 64 位元驅動程式) + `/opt/amazon/redshiftodbc/lib/32` ( 適用於 Linux 作業系統上的 32 位元驅動程式) 此外，在 Linux 的 `/opt/amazon/redshiftodbc/Setup` 下可找到範例 `odbc.ini` 和 `odbcinst.ini` 檔案。您可以使用這些檔案做為設定 Amazon Redshift ODBC 驅動程式和資料來源名稱 (DSN) 的範例。 不建議使用 Amazon Redshift ODBC 驅動程式安裝目錄來存放組態檔案。`Setup` 目錄中的範例檔案僅供當作範例。如果您後來重新安裝 Amazon Redshift ODBC 驅動程式，或升級為更新版本，安裝目錄會遭到覆寫。然後，您對這些檔案可能做的任何變更都會遺失。 若要避免這種情況，請將 `amazon.redshiftodbc.ini` 檔案複製到安裝目錄以外的目錄。如果您將此檔案複製到使用者的主目錄，請在檔案名稱開頭加上一點 (.)，將它變成隱藏檔。 對於 `odbc.ini` 和 `odbcinst.ini` 檔案，請使用位於使用者主目錄中的組態檔案，或在另一個目錄中建立新版本。根據預設，Linux 作業系統的使用者主目錄 (`/home/$USER` 或 `~/`) 中，應該有 `odbc.ini` 檔案和 `odbcinst.ini` 檔案。這些預設檔案是隱藏檔，每個檔案名稱前面以點表示。僅當使用 `-a` 旗標來列出目錄內容時，才會顯示這些檔案。 無論對 `odbc.ini` 和 `odbcinst.ini` 檔案選擇何種選項，都會修改這些檔案來新增驅動程式和 DSN 組態資訊。如果建立新檔案，則還需要設定環境變數來指定這些組態檔案所在的位置。 根據預設，ODBC 驅動程式管理員會設定為使用隱藏版本的 `odbc.ini` 和 `odbcinst.ini` 組態檔 (命名為 .`odbc.ini` 和 .`odbcinst.ini`)，這些組態檔位於主目錄中。它們也會設定為使用驅動程式安裝目錄的 `/lib` 子資料夾中的 `amazon.redshiftodbc.ini` 檔案。如果您將這些組態檔儲存在其他位置，請設定如下所述的環境變數，以便驅動程式管理員可以找到這些檔案。如需詳細資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的「指定驅動程式組態檔案的位置」。 ## 在 Linux 作業系統上建立資料來源名稱 使用資料來源名稱 (DSN) 連接至資料倉庫時，請設定 `odbc.ini` 檔案來定義 DSN。在 `odbc.ini` 檔案中設定屬性，以建立 DSN 來指定資料倉庫的連線資訊。 如需如何設定 `odbc.ini` 檔案的相關資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的「在非 Windows 機器上建立資料來源名稱」 在 Linux 作業系統上使用下列格式。 ``` [ODBC Data Sources] driver_name=dsn_name [dsn_name] Driver=path/driver_file Host=cluster_endpoint Port=port_number Database=database_name locale=locale ``` 以下範例示範 Linux 作業系統上使用 64 位元 ODBC 驅動程式的 odbc.ini 組態。 ``` [ODBC Data Sources] Amazon_Redshift_x64=Amazon Redshift (x64) [Amazon Redshift (x64)] Driver=/opt/amazon/redshiftodbc/lib/64/libamazonredshiftodbc64.so Host=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com Port=5932 Database=dev locale=en-US ``` 以下範例示範 Linux 作業系統上使用 32 位元 ODBC 驅動程式的 odbc.ini 組態。 ``` [ODBC Data Sources] Amazon_Redshift_x32=Amazon Redshift (x86) [Amazon Redshift (x86)] Driver=/opt/amazon/redshiftodbc/lib/32/libamazonredshiftodbc32.so Host=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com Port=5932 Database=dev locale=en-US ``` ## 在 Linux 作業系統上設定沒有 DSN 的連線 若要透過沒有 DSN 的連線連接至您的資料存放區，請在 `odbcinst.ini` 檔案中定義驅動程式。然後，在應用程式中提供無 DSN 的連線字串。 如需如何在此情況下設定 `odbcinst.ini` 檔案的相關資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的「在非 Windows 機器上設定無 DSN 的連線」。 在 Linux 作業系統上使用下列格式。 ``` [ODBC Drivers] driver_name=Installed ... [driver_name] Description=driver_description Driver=path/driver_file ... ``` 以下範例針對 Linux 作業系統上安裝於預設目錄中的 64 位元驅動程式示範 `odbcinst.ini` 組態。 ``` [ODBC Drivers] Amazon Redshift (x64)=Installed [Amazon Redshift (x64)] Description=Amazon Redshift ODBC Driver (64-bit) Driver=/opt/amazon/redshiftodbc/lib/64/libamazonredshiftodbc64.so ``` 以下範例針對 Linux 作業系統上安裝於預設目錄中的 32 位元驅動程式示範 `odbcinst.ini` 組態。 ``` [ODBC Drivers] Amazon Redshift (x86)=Installed [Amazon Redshift (x86)] Description=Amazon Redshift ODBC Driver (32-bit) Driver=/opt/amazon/redshiftodbc/lib/32/libamazonredshiftodbc32.so ``` ## 設定環境變數 使用正確的 ODBC 驅動程式管理員來載入正確的驅動程式。若要這樣做，請設定程式庫路徑環境變數。如需詳細資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的「在非 Windows 機器上指定 ODBC 驅動程式管理員」。 根據預設，ODBC 驅動程式管理員會設定為使用隱藏版本的 `odbc.ini` 和 `odbcinst.ini` 組態檔 (命名為 .`odbc.ini` 和 .`odbcinst.ini`)，這些組態檔位於主目錄中。它們也會設定為使用驅動程式安裝目錄的 `/lib` 子資料夾中的 `amazon.redshiftodbc.ini` 檔案。如果您將這些組態檔儲存在其他位置，請設定環境變數，以便驅動程式管理員可以找到這些檔案。如需詳細資訊，請參閱《Amazon Redshift ODBC 連接器安裝和組態指南》**中的「指定驅動程式組態檔案的位置」。 ## 設定連線功能 您可以將下列連線功能設定給 ODBC 設定： + 設定 ODBC 驅動程式以提供憑證，並驗證 Amazon Redshift 資料庫的連線。 + 設定 ODBC 驅動程式，以連線到啟用 Secure Sockets Layer (SSL) 的通訊端 (如果您連線到已啟用 SSL 的 Amazon Redshift 伺服器)。 + 設定 ODBC 驅動程式，以透過 Proxy 伺服器連線到 Amazon Redshift。 + 將 ODBC 驅動程式設定為使用查詢處理模式，以防止查詢耗用太多記憶體。 + 設定 ODBC 驅動程式，以透過代理伺服器傳遞 IAM 身分驗證程序。 + 設定 ODBC 驅動程式，以使用 TCP 保持連線來防止連線逾時。 如需這些連線功能的相關資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 # 在 macOS X 上使用 Amazon Redshift ODBC 驅動器 請在存取 Amazon Redshift 資料倉儲的用戶端電腦上安裝驅動程式。您安裝驅動程式的每一台電腦必須符合最低系統需求清單：如需最低系統要求的相關資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 **Topics** + [下載並安裝 Amazon Redshift ODBC 驅動器](odbc-driver-mac-how-to-install.md) + [使用 ODBC 驅動器管理員設定驅動器](odbc-driver-configure-mac.md) # 下載並安裝 Amazon Redshift ODBC 驅動器 使用本節的步驟來下載 Amazon Redshift ODBC 驅動程式並安裝在支援的 macOS X 版本上。安裝程序會將驅動程式檔案安裝在下列目錄中： + `/opt/amazon/redshift/lib/universal` + `/opt/amazon/redshift/ErrorMessages` + `/opt/amazon/redshift/Setup` **在 macOS X 上安裝 Amazon Redshift ODBC 驅動程式** 1. 若要在 macOS X 上安裝 Amazon Redshift ODBC 驅動程式，請下載 [macOS 驅動程式 1.6.3 版。](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/AmazonRedshiftODBC-64-bit.1.6.3.1008.universal.pkg) 然後下載並檢閱 [Amazon Redshift ODBC 和 JDBC 驅動程式授權合約](https://s3.amazonaws.com/redshift-downloads/drivers/Amazon+Redshift+ODBC+and+JDBC+Driver+License+Agreement.pdf)。 1. 按兩下 **AmazonRedshiftODBC.pkg** 來執行安裝程式。 1. 依照安裝程式中的步驟完成驅動程式安裝程序。若要執行安裝，請同意授權合約的條款。 **重要** 驅動程式安裝完成時，請設定來用於您的系統。如需驅動程式組態的相關資訊，請參閱[使用 ODBC 驅動器管理員設定驅動器使用 ODBC 驅動器管理員設定驅動器](odbc-driver-configure-mac.md)。 # 使用 ODBC 驅動器管理員設定驅動器 在 macOS X 作業系統上，您會使用 ODBC 驅動器管理員來設定 ODBC 連線設定。ODBC 驅動程式管理員使用組態檔案來定義及設定 ODBC 資料來源和驅動程式。您使用的 ODBC 驅動程式管理員視您使用的作業系統而定。對於 macOS X 作業系統，這是 iODBC 驅動器管理員。 如需支援用來設定 Amazon Redshift ODBC 驅動器的 ODBC 驅動器管理員的詳細資訊，請參閱 macOS X 作業系統的 [在 macOS X 上使用 Amazon Redshift ODBC 驅動器在 macOS X 上使用 ODBC 驅動器](install-odbc-driver-mac.md)。另請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的「在非 Windows 機器上指定 ODBC 驅動程式管理員」。 設定 Amazon Redshift ODBC 驅動程式需要三個檔案：`amazon.redshiftodbc.ini`、`odbc.ini` 和 `odbcinst.ini`。 如果是安裝到預設位置，則 `amazon.redshiftodbc.ini` 組態檔案位於 `/opt/amazon/redshift/lib`。 此外，在 macOS X 的 `/opt/amazon/redshift/Setup` 下可找到範例 `odbc.ini` 和 `odbcinst.ini` 檔案。您可以使用這些檔案做為設定 Amazon Redshift ODBC 驅動程式和資料來源名稱 (DSN) 的範例。 不建議使用 Amazon Redshift ODBC 驅動程式安裝目錄來存放組態檔案。`Setup` 目錄中的範例檔案僅供當作範例。如果您後來重新安裝 Amazon Redshift ODBC 驅動程式，或升級為更新版本，安裝目錄會遭到覆寫。然後，您對這些檔案可能做的任何變更都會遺失。 若要避免這種情況，請將 `amazon.redshiftodbc.ini` 檔案複製到安裝目錄以外的目錄。如果您將此檔案複製到使用者的主目錄，請在檔案名稱開頭加上一點 (.)，將它變成隱藏檔。 對於 `odbc.ini` 和 `odbcinst.ini` 檔案，請使用位於使用者主目錄中的組態檔案，或在另一個目錄中建立新版本。根據預設，macOS X 作業系統的使用者主目錄 (`/home/$USER` 或 `~/`) 中，應該有 `odbc.ini` 檔案和 `odbcinst.ini` 檔案。這些預設檔案是隱藏檔，每個檔案名稱前面以點表示。僅當使用 `-a` 旗標來列出目錄內容時，才會顯示這些檔案。 無論對 `odbc.ini` 和 `odbcinst.ini` 檔案選擇何種選項，都會修改這些檔案來新增驅動程式和 DSN 組態資訊。如果建立新檔案，則還需要設定環境變數來指定這些組態檔案所在的位置。 根據預設，ODBC 驅動程式管理員會設定為使用隱藏版本的 `odbc.ini` 和 `odbcinst.ini` 組態檔 (命名為 .`odbc.ini` 和 .`odbcinst.ini`)，這些組態檔位於主目錄中。它們也會設定為使用驅動程式安裝目錄的 `/lib` 子資料夾中的 `amazon.redshiftodbc.ini` 檔案。如果您將這些組態檔儲存在其他位置，請設定如下所述的環境變數，以便驅動程式管理員可以找到這些檔案。如需詳細資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的「指定驅動程式組態檔案的位置」。 ## 在 macOS X 作業系統上建立資料來源名稱 使用資料來源名稱 (DSN) 連接至資料倉庫時，請設定 `odbc.ini` 檔案來定義 DSN。在 `odbc.ini` 檔案中設定屬性，以建立 DSN 來指定資料倉庫的連線資訊。 如需有關如何設定`odbc.ini`檔案的資訊，請參閱《[Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf) 在 macOS X 作業系統上使用下列格式。 ``` [ODBC Data Sources] driver_name=dsn_name [dsn_name] Driver=path/lib/amazonredshiftodbc.dylib Host=cluster_endpoint Port=port_number Database=database_name locale=locale ``` 以下範例示範 macOS X 作業系統上的 `odbc.ini` 組態。 ``` [ODBC Data Sources] Amazon_Redshift_dylib=Amazon Redshift DSN for macOS X [Amazon Redshift DSN for macOS X] Driver=/opt/amazon/redshift/lib/amazonredshiftodbc.dylib Host=examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com Port=5932 Database=dev locale=en-US ``` ## 在 macOS X 作業系統上設定沒有 DSN 的連線 若要透過沒有 DSN 的連線連接至您的資料存放區，請在 `odbcinst.ini` 檔案中定義驅動程式。然後，在應用程式中提供無 DSN 的連線字串。 如需如何在此情況下設定 `odbcinst.ini` 檔案的相關資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的「在非 Windows 機器上設定無 DSN 的連線」。。 在 macOS X 作業系統上使用下列格式。 ``` [ODBC Drivers] driver_name=Installed ... [driver_name] Description=driver_description Driver=path/lib/amazonredshiftodbc.dylib ... ``` 以下範例針對 macOS X 作業系統上安裝於預設目錄中的驅動程式，示範 `odbcinst.ini` 組態。 ``` [ODBC Drivers] Amazon RedshiftODBC DSN=Installed [Amazon RedshiftODBC DSN] Description=Amazon Redshift ODBC Driver for macOS X Driver=/opt/amazon/redshift/lib/amazonredshiftodbc.dylib ``` ## 設定環境變數 使用正確的 ODBC 驅動程式管理員來載入正確的驅動程式。若要這樣做，請設定程式庫路徑環境變數。如需詳細資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)中的「在非 Windows 機器上指定 ODBC 驅動程式管理員」。 根據預設，ODBC 驅動程式管理員會設定為使用隱藏版本的 `odbc.ini` 和 `odbcinst.ini` 組態檔 (命名為 .`odbc.ini` 和 .`odbcinst.ini`)，這些組態檔位於主目錄中。它們也會設定為使用驅動程式安裝目錄的 `/lib` 子資料夾中的 `amazon.redshiftodbc.ini` 檔案。如果您將這些組態檔儲存在其他位置，請設定環境變數，以便驅動程式管理員可以找到這些檔案。如需詳細資訊，請參閱《Amazon Redshift ODBC 連接器安裝和組態指南》**中的「指定驅動程式組態檔案的位置」。 ## 設定連線功能 您可以將下列連線功能設定給 ODBC 設定： + 設定 ODBC 驅動程式以提供憑證，並驗證 Amazon Redshift 資料庫的連線。 + 設定 ODBC 驅動程式，以連線到啟用 Secure Sockets Layer (SSL) 的通訊端 (如果您連線到已啟用 SSL 的 Amazon Redshift 伺服器)。 + 設定 ODBC 驅動程式，以透過 Proxy 伺服器連線到 Amazon Redshift。 + 將 ODBC 驅動程式設定為使用查詢處理模式，以防止查詢耗用太多記憶體。 + 設定 ODBC 驅動程式，以透過代理伺服器傳遞 IAM 身分驗證程序。 + 設定 ODBC 驅動程式，以使用 TCP 保持連線來防止連線逾時。 如需這些連線功能的相關資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 # ODBC 驅動器選項 您可以使用組態選項來控制 Amazon Redshift ODBC 驅動程式的行為。 在 Microsoft Windows 中，您通常於設定資料來源名稱 (DSN) 時設定驅動程式選項。您也可以在連接時以程式設計方式在連線字串中設定驅動程式選項，或在 `HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\your_DSN` 中新增或變更登錄機碼。如需設定 DSN 的相關資訊，請參閱[在 Microsoft Windows 上使用 Amazon Redshift ODBC 驅動器](install-odbc-driver-windows.md)。 在 macOS X 中，您可以在 `odbc.ini` 和 `amazon.redshiftodbc.ini` 檔案中設定驅動器組態選項，如 [使用 ODBC 驅動器管理員設定驅動器使用 ODBC 驅動器管理員設定驅動器](odbc-driver-configure-mac.md) 中所述。在 `amazon.redshiftodbc.ini` 檔案中設定的組態選項會套用至所有連線。相反地，`odbc.ini` 檔案中設定的組態選項是針對某個連線。`odbc.ini` 中設定的組態選項優先於 `amazon.redshiftodbc.ini` 中設定的組態選項。 如需如何設定 ODBC 驅動程式組態選項的相關資訊，請參閱 [Amazon Redshift ODBC 連接器安裝和組態指南](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1008/Amazon+Redshift+ODBC+Connector+Install+Guide.pdf)。 # 先前的 ODBC 驅動程式版本 只有在您的工具需要特定版本的驅動程式時，才需要下載舊版的 Amazon Redshift ODBC 驅動程式。 ## 先前的 ODBC 驅動器版本 (適用於 Windows) 以下是 64 位元驅動程式： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC64-1.6.3.1006.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC64-1.6.3.1006.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC64-1.6.1.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC64-1.6.1.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC64-1.5.20.1024.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC64-1.5.20.1024.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC64-1.5.16.1019.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC64-1.5.16.1019.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC64-1.5.9.1011.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC64-1.5.9.1011.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC64-1.5.7.1007.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC64-1.5.7.1007.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC64-1.4.65.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC64-1.4.65.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC64-1.4.62.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC64-1.4.62.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC64-1.4.59.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC64-1.4.59.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC64-1.4.56.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC64-1.4.56.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.53.1000/AmazonRedshiftODBC64-1.4.53.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.53.1000/AmazonRedshiftODBC64-1.4.53.1000.msi) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC64-1.4.52.1000.msi](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC64-1.4.52.1000.msi) 32 位元的驅動程式已停止使用，先前的版本已不受支援。 ## 先前的 ODBC 驅動器版本 (適用於 Linux) 以下是 64 位元驅動程式版本： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC-64-bit-1.6.3.1006-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC-64-bit-1.6.3.1006-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC-64-bit-1.6.1.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC-64-bit-1.6.1.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-64-bit-1.5.20.1024-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-64-bit-1.5.20.1024-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC-64-bit-1.5.16.1019-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC-64-bit-1.5.16.1019-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC-64-bit-1.5.9.1011-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC-64-bit-1.5.9.1011-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC-64-bit-1.5.7.1007-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC-64-bit-1.5.7.1007-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC-64-bit-1.4.65.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC-64-bit-1.4.65.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC-64-bit-1.4.62.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC-64-bit-1.4.62.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-64-bit-1.4.59.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-64-bit-1.4.59.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-64-bit-1.4.59.1000-1.x86\$164.deb](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-64-bit-1.4.59.1000-1.x86_64.deb) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-64-bit-1.4.56.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-64-bit-1.4.56.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-64-bit-1.4.56.1000-1.x86\$164.deb](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-64-bit-1.4.56.1000-1.x86_64.deb) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-64-bit-1.4.52.1000-1.x86\$164.rpm](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-64-bit-1.4.52.1000-1.x86_64.rpm) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-64-bit-1.4.52.1000-1.x86\$164.deb](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-64-bit-1.4.52.1000-1.x86_64.deb) 32 位元的驅動程式已停止使用，先前的版本已不受支援。 ## 先前的 ODBC 驅動器版本 (適用於 macOS X) 以下是適用於 macOS X 的 Amazon Redshift ODBC 驅動程式版本： + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC-64-bit.1.6.3.1006.universal.pkg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.3.1006/AmazonRedshiftODBC-64-bit.1.6.3.1006.universal.pkg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC-64-bit.1.6.1.1000.universal.pkg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.6.1.1000/AmazonRedshiftODBC-64-bit.1.6.1.1000.universal.pkg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-1.5.20.1024.arm64.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-1.5.20.1024.arm64.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-1.5.20.1024.x86\$164.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.20.1024/AmazonRedshiftODBC-1.5.20.1024.x86_64.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC-1.5.16.1019.x86\$164.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.16.1019/AmazonRedshiftODBC-1.5.16.1019.x86_64.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC-1.5.9.1011.x86\$164.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.9.1011/AmazonRedshiftODBC-1.5.9.1011.x86_64.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC-1.5.7.1007.x86\$164.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.5.7.1007/AmazonRedshiftODBC-1.5.7.1007.x86_64.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC-1.4.65.1000.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.65.1000/AmazonRedshiftODBC-1.4.65.1000.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC-1.4.62.1000.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.62.1000/AmazonRedshiftODBC-1.4.62.1000.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-1.4.59.1000.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.59.1000/AmazonRedshiftODBC-1.4.59.1000.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-1.4.56.1000.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.56.1000/AmazonRedshiftODBC-1.4.56.1000.dmg) + [https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-1.4.52.1000.dmg](https://s3.amazonaws.com/redshift-downloads/drivers/odbc/1.4.52.1000/AmazonRedshiftODBC-1.4.52.1000.dmg) # 設定連線的安全選項 Amazon Redshift 支援 Secure Sockets Layer (SSL) 連線，可將資料和伺服器憑證加密，以驗證用戶端所連線的伺服器憑證。 ## SSL 為了支援 SSL 連線，Amazon Redshift 會在每一個叢集上建立並安裝 [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/) 發行的 SSL 憑證。ACM 憑證受到大多數作業系統、網頁瀏覽器和用戶端公開信任。如果 SQL 用戶端或應用程式在 `sslmode` 連線選項設為 `require`、`verify-ca` 或 `verify-full` 的情況下，使用 SSL 連線到 Amazon Redshift，您可能需要下載憑證套件。如果用戶端需要憑證，Amazon Redshift 會提供如下的憑證套件： + 從 [https://s3.amazonaws.com/redshift-downloads/amazon-trust-ca-bundle.crt](https://s3.amazonaws.com/redshift-downloads/amazon-trust-ca-bundle.crt) 下載套件。 + 預期的 MD5 檢查總和碼為 418dea9b6d5d5de7a8f1ac42e164cdcf。 + sha256 檢查總和碼為 36dba8e4b8041cd14b9d60158893963301bcbb92e1c456847784de2acb5bd550。 請勿使用位於 `https://s3.amazonaws.com/redshift-downloads/redshift-ca-bundle.crt` 的先前憑證套件。 + 在中國 AWS 區域，請從 https：//[https://s3---cn-north-1.amazonaws.com.rproxy.govskope.ca.cn/redshift-downloads-cn/amazon-trust-ca-bundle.crt](https://s3---cn-north-1.amazonaws.com.rproxy.govskope.ca.cn/redshift-downloads-cn/amazon-trust-ca-bundle.crt) 下載套件。 + 預期的 MD5 檢查總和碼為 418dea9b6d5d5de7a8f1ac42e164cdcf。 + sha256 檢查總和碼為 36dba8e4b8041cd14b9d60158893963301bcbb92e1c456847784de2acb5bd550。 請勿使用位於 `https://s3---cn-north-1.amazonaws.com.rproxy.govskope.ca.cn/redshift-downloads-cn/redshift-ca-bundle.crt` 和 `https://s3---cn-north-1.amazonaws.com.rproxy.govskope.ca.cn/redshift-downloads-cn/redshift-ssl-ca-cert.pem` 的先前憑證套件。 **重要** Amazon Redshift 已變更 SSL 憑證的管理方式。您可能需要更新目前的信任根 CA 憑證，才能繼續使用 SSL 連線到叢集。如需詳細資訊，請參閱[將 SSL 連線轉換為使用 ACM 憑證](connecting-transitioning-to-acm-certs.md)。 根據預設，不論連線是否使用 SSL，叢集資料庫都接受連線。若要將叢集設為需要 SSL 連線，請在與叢集相關聯的參數群組中，將 `require_SSL` 參數設為 `true`。 Amazon Redshift 支援符合美國聯邦資訊處理標準 (FIPS) 140-2 的 SSL 模式。符合 FIPS 的 SSL 模式預設為停用。 **重要** 只在系統需要符合 FIPS 時啟用與 FIPS 相容的 SSL 模式。 若要啟用與 FIPS 相容的 SSL 模式，請在與 Amazon Redshift 叢集或 Redshift Serverless 工作群組相關聯的參數群組中，將 `use_fips_ssl` 參數和 `require_SSL` 參數都設為 `true`。如需修改叢集上參數群組的相關資訊，請參閱 [Amazon Redshift 參數群組](working-with-parameter-groups.md)。如需修改工作群組上參數群組的相關資訊，請參閱 [設定與 FIPS 相容的 Amazon Redshift Serverless SSL 連線](serverless-connecting.md#serverless_secure-fips-ssl)。 Amazon Redshift 支援 Elliptic Curve Diffie—Hellman Ephemeral (ECDHE) 金鑰協議通訊協定。使用 ECDHE 時，用戶端和伺服器各有橢圓曲線公有-私有金鑰對，用於透過不安全通道建立共用秘密。您不需要在 Amazon Redshift 中設定任何項目來啟用 ECDHE。如果您從 SQL 用戶端工具連線，而此工具使用 ECDHE 來加密用戶端和伺服器之間的通訊，Amazon Redshift 會使用提供的密碼清單來建立適當的連線。如需詳細資訊，請參閱 Wikipedia 上的 [Elliptic curve diffie—hellman](https://en.wikipedia.org/wiki/Elliptic_curve_Diffie%E2%80%93Hellman) 和 OpenSSL 網站上的 [Ciphers](https://www.openssl.org/)。 ## ODBC 中的 SSL 和信任 CA 憑證 如果您使用最新的 Amazon Redshift ODBC 驅動程式 (1.3.7.1000 版或更新版本) 來連接，則可略過本節。若要下載最新的驅動程式，請參閱[設定 Amazon Redshift ODBC 驅動程式 2.x 版連線](odbc20-install.md)。 您可能需要更新目前的信任根 CA 憑證，才能繼續使用 SSL 連線到叢集。如需詳細資訊，請參閱[SSL](#connect-using-ssl)。 您可以驗證您下載的憑證是否符合預期的 MD5 檢查總和碼。若要執行此動作，您可以在 Linux 作業系統上使用 Md5sum 程式，或在 Windows 和 macOS X 作業系統上使用其他工具。 ODBC DSN 包含 `sslmode` 設定，可決定如何處理用戶端連線和伺服器憑證驗證的加密。Amazon Redshift 支援來自用戶端連線的下列 `sslmode` 值： + `disable` 停用 SSL，不加密連線。 + `allow` 如果伺服器需要，就使用 SSL。 + `prefer` 如果伺服器支援，就使用 SSL。Amazon Redshift 支援 SSL，因此當您將 `sslmode` 設定為 `prefer` 時，系統會使用 SSL。 + `require` 需要 SSL。 + `verify-ca` 必須使用 SSL 且必須驗證伺服器憑證。 + `verify-full` 必須使用 SSL。必須驗證伺服器憑證，且伺服器主機名稱必須符合憑證上的主機名稱屬性。 您可以判斷用戶端和伺服器之間的連線是否使用 SSL 及是否驗證伺服器憑證。若要執行此作業，您需要在用戶端檢閱 ODBC DSN 的 `sslmode` 設定，並在伺服器上檢閱 Amazon Redshift 叢集的 `require_SSL` 設定。下表描述各種用戶端和伺服器設定組合的加密結果： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/connecting-ssl-support.html) ### 在 Microsoft Windows 上搭配 ODBC 使用伺服器憑證進行連線 如果您想要使用 SSL 和伺服器憑證連線到叢集，請先將憑證下載到用戶端電腦或 Amazon EC2 執行個體。然後，設定 ODBC DSN。 1. 將 Amazon Redshift 憑證授權機構套件下載到用戶端電腦驅動程式安裝目錄中的 `lib` 資料夾，並將檔案儲存為 `root.crt`。如需下載資訊，請參閱 [SSL](#connect-using-ssl)。 1. 開啟 **ODBC 資料來源管理員**，然後新增或編輯 ODBC 連線的系統 DSN 項目。在 **SSL 模式**中，選取 `verify-full` (除非您使用 DNS 別名)。如果您使用 DNS 別名，請選取 `verify-ca`。然後選擇 **Save** (儲存)。 如需設定 ODBC DSN 的相關資訊，請參閱[設定 Amazon Redshift ODBC 驅動程式 2.x 版連線](odbc20-install.md)。 ## Java 中的 SSL 和伺服器憑證 SSL 會將用戶端和伺服器之間移動的資料加密，多一道安全性。使用伺服器憑證可透過驗證叢集是否為 Amazon Redshift 叢集來提供額外一層的安全。在作法上是檢查您佈建的所有叢集上自動安裝的伺服器憑證。如需搭配 JDBC 使用伺服器憑證的相關資訊，請前往 PostgreSQL 文件中的 [Configuring the client](https://jdbc.postgresql.org/documentation/ssl/#configuring-the-client)。 ### 在 Java 中使用信任 CA 憑證進行連線 **重要** Amazon Redshift 已變更 SSL 憑證的管理方式。您可能需要更新目前的信任根 CA 憑證，才能繼續使用 SSL 連線到叢集。如需詳細資訊，請參閱[SSL](#connect-using-ssl)。 **使用信任 CA 憑證來連接** 您可以使用 `redshift-keytool.jar` 檔案，將 Amazon Redshift 憑證授權機構套件中的 CA 憑證匯入至 Java TrustStore 或您的私有信任憑證庫。 1. 如果您使用 Java 命令列 `-Djavax.net.ssl.trustStore` 選項，可能的話，請從命令列中移除。 1. 下載 [redshift-keytool.jar](https://s3.amazonaws.com/redshift-downloads/redshift-keytool.jar)。 1. 執行以下任意一項： + 若要將 Amazon Redshift 憑證授權機構套件匯入 Java TrustStore，請執行下列命令。 ``` java -jar redshift-keytool.jar -s ``` + 若要將 Amazon Redshift 憑證授權機構套件匯入您的私有 TrustStore，請執行下列命令： ``` java -jar redshift-keytool.jar -k -p ``` # 將 SSL 連線轉換為使用 ACM 憑證 Amazon Redshift 將會以 [AWS Certificate Manager (ACM)](https://aws.amazon.com/certificate-manager/) 發行的憑證取代您叢集上的 SSL 憑證。ACM 是大多數現行系統信任的公有憑證授權機構 (CA)。您可能需要更新目前的信任根 CA 憑證，才能繼續使用 SSL 連線到叢集。 只有在下列所有情況都存在時，此變更才會影響您： + SQL 用戶端或應用程式使用 SSL 來連接至 Amazon Redshift 叢集，且 `sslMode` 連線選項設為 `require`、`verify-ca` 或 `verify-full` 組態選項。 + 您不使用 Amazon Redshift ODBC 或 JDBC 驅動程式，或使用的 Amazon Redshift 驅動程式是 ODBC 1.3.7.1000 版或 JDBC 1.2.8.1005 版以前。 如果此變更會在 Amazon Redshift 商業區域影響到您，則您必須在 2017 年 10 月 23 日之前更新目前的信任根 CA 憑證。Amazon Redshift 會從現在開始到 2017 年 10 月 23 日之前，將您的叢集轉換為使用 ACM 憑證。此變更對叢集效能或可用性的影響應該非常小，或完全不影響。 如果此變更影響 AWS GovCloud (US) （美國） 區域，則您必須在 2020 年 4 月 1 日之前更新目前的信任根 CA 憑證，以避免服務中斷。從這個日期起，使用 SSL 加密連線連線至 Amazon Redshift 叢集的用戶端需要額外的受信任憑證授權單位 (CA)。用戶端在連線到 Amazon Redshift 叢集時，會使用受信任的憑證授權單位來確認該叢集的身分。您必須採取動作，才能更新 SQL 用戶端和應用程式，以使用包含新信任 CA 的更新憑證套件。 **重要** 在 2021 年 1 月 5 日的中國區域中，Amazon Redshift 會將叢集上的 SSL 憑證取代為 AWS Certificate Manager (ACM) 發行的憑證。如果此變更會在中國 (北京) 區域或中國 (寧夏) 區域影響到您，則您必須在 2021 年 1 月 5 日之前更新目前的信任根 CA 憑證，以避免服務中斷。從這個日期起，使用 SSL 加密連線連線至 Amazon Redshift 叢集的用戶端需要額外的受信任憑證授權單位 (CA)。用戶端在連線到 Amazon Redshift 叢集時，會使用受信任的憑證授權單位來確認該叢集的身分。您必須採取動作，才能更新 SQL 用戶端和應用程式，以使用包含新信任 CA 的更新憑證套件。 + [使用最新的 Amazon Redshift ODBC 或 JDBC 驅動程式](#connecting-transitioning-to-acm-latest-odbc-jdbc) + [使用較舊的 Amazon Redshift ODBC 或 JDBC 驅動程式](#connecting-transitioning-to-acm-earlier-odbc-jdbc) + [使用其他 SSL 連線類型](#connecting-transitioning-to-acm-other-ssl-types) ## 使用最新的 Amazon Redshift ODBC 或 JDBC 驅動程式 建議使用最新的 Amazon Redshift ODBC 或 JDBC 驅動程式。從 ODBC 1.3.7.1000 版和 JDBC 1.2.8.1005 版開始的 Amazon Redshift 驅動程式，將會自動處理從 Amazon Redshift 自簽憑證轉換到 ACM 憑證。若要下載最新的驅動程式，請參閱[設定適用於 Amazon Redshift 的 JDBC 驅動器 2.x 版的連線](jdbc20-install.md)。 如果您使用最新的 Amazon Redshift JDBC 驅動程式，最好不要在 JVM 選項中使用 `-Djavax.net.ssl.trustStore`。如果您必須使用 `-Djavax.net.ssl.trustStore`，請將 Redshift 憑證授權機構套件匯入其指向的信任憑證庫。如需下載資訊，請參閱 [SSL](connecting-ssl-support.md#connect-using-ssl)。如需詳細資訊，請參閱[將 Amazon Redshift 憑證授權機構套件匯入 TrustStore](#importing-the-acm-bundle-to-truststore)。 ## 使用較舊的 Amazon Redshift ODBC 或 JDBC 驅動程式 + 如果 ODBC DSN 設定為 `SSLCertPath`，請覆寫指定路徑中的憑證檔案。 + 如果未設定 `SSLCertPath`，請覆寫驅動程式 DLL 位置中名為 `root.crt` 的憑證檔案。 如果您必須使用的 1.2.8.1005 版以前的 Amazon Redshift JDBC 驅動程式，請執行下列其中一個動作： + 如果 JDBC 連線字串使用 `sslCert` 選項，請移除 `sslCert` 選項。然後將 Redshift 憑證授權機構套件匯入 Java TrustStore。如需下載資訊，請參閱 [SSL](connecting-ssl-support.md#connect-using-ssl)。如需詳細資訊，請參閱[將 Amazon Redshift 憑證授權機構套件匯入 TrustStore](#importing-the-acm-bundle-to-truststore)。 + 如果您使用 Java 命令列 `-Djavax.net.ssl.trustStore` 選項，可能的話，請從命令列中移除。然後將 Redshift 憑證授權機構套件匯入 Java TrustStore。如需下載資訊，請參閱 [SSL](connecting-ssl-support.md#connect-using-ssl)。如需詳細資訊，請參閱[將 Amazon Redshift 憑證授權機構套件匯入 TrustStore](#importing-the-acm-bundle-to-truststore)。 ### 將 Amazon Redshift 憑證授權機構套件匯入 TrustStore 您可以使用 `redshift-keytool.jar` 將 Amazon Redshift 憑證授權機構套件中的 CA 憑證匯入至 Java TrustStore 或您的私有信任憑證庫。 **將 Amazon Redshift 憑證授權機構套件匯入 TrustStore** 1. 下載 [redshift-keytool.jar](https://s3.amazonaws.com/redshift-downloads/redshift-keytool.jar)。 1. 執行以下任意一項： + 若要將 Amazon Redshift 憑證授權機構套件匯入 Java TrustStore，請執行下列命令。 ``` java -jar redshift-keytool.jar -s ``` + 若要將 Amazon Redshift 憑證授權機構套件匯入您的私有 TrustStore，請執行下列命令： ``` java -jar redshift-keytool.jar -k -p ``` ## 使用其他 SSL 連線類型 如果您使用下列任何一項來連接，請遵循本節的步驟： + 開放原始碼 ODBC 驅動程式 + 開放原始碼 JDBC 驅動程式 + [Amazon Redshift RSQL](https://docs.aws.amazon.com/redshift/latest/mgmt/rsql-query-tool.html) 命令列界面 + 任何以 libpq 為基礎的語言繫結，例如 psycopg2 (Python) 和 ruby-pg (Ruby) **若要對其他 SSL 連線類型使用 ACM 憑證，請執行下列動作：** 1. 下載 Amazon Redshift 憑證授權機構套件。如需下載資訊，請參閱 [SSL](connecting-ssl-support.md#connect-using-ssl)。 1. 將套件中的憑證放入 `root.crt` 檔案中。 + 在 Linux 和 macOS X 作業系統上，此檔案是 `~/.postgresql/root.crt`。 + 在 Microsoft Windows 上，此檔案是 `%APPDATA%\postgresql\root.crt`。 # 從用戶端工具和程式碼連線 Amazon Redshift 提供了 Amazon Redshift 查詢編輯器 v2 供您連線到叢集和工作群組。如需詳細資訊，請參閱[使用查詢編輯器 v2 查詢資料庫使用 Amazon Redshift 查詢編輯器 v2 來查詢資料庫](query-editor-v2.md)。 本節提供一些可供第三方工具進行連線的選項。此外，還描述如何以程式設計方式連接至叢集。 **Topics** + [使用 Amazon Redshift RSQL 進行連線](rsql-query-tool.md) + [使用 Amazon Redshift RSQL 連線至叢集](rsql-query-tool-starting-tool-connection.md) + [Amazon Redshift RSQL 中繼命令](rsql-query-tool-commands.md) + [Amazon Redshift RSQL 變數](rsql-query-tool-variables.md) + [Amazon Redshift RSQL 錯誤代碼](rsql-query-tool-error-codes.md) + [Amazon Redshift RSQL 環境變數](rsql-query-tool-environment-variables.md) # 使用 Amazon Redshift RSQL 進行連線 Amazon Redshift RSQL 是用於與 Amazon Redshift 叢集和資料庫互動的命令列用戶端。您可以連線到 Amazon Redshift 叢集、描述資料庫物件、查詢資料，以及檢視各種輸出格式的查詢結果。 Amazon Redshift RSQL 支援 PostgreSQL psql 命令列工具的功能，以及一組專屬於 Amazon Redshift 的額外功能。這些索引標籤包括以下項目： + 您可以使用 AD FS、PingIdentity、Okta、Azure ADm 或其他 SAML/JWT 型身分提供者，來使用單一登入身分驗證。您也可以使用以瀏覽器為基礎的 SAML 身分供應商來進行多重要素驗證 (MFA)。 + 您可以描述 Amazon Redshift 物件的屬性，例如資料表分佈索引鍵、資料表排序索引鍵、晚期繫結視觀表 (LBV) 和具體化視觀表。您也可以描述 AWS Glue 目錄或 Apache Hive 中繼存放區中外部資料表的屬性或屬性、Amazon RDS for PostgreSQL、Amazon Aurora PostgreSQL 相容版本、RDS for MySQL （預覽） 和 Amazon Aurora MySQL 相容版本 （預覽） 中的外部資料庫，以及使用 Amazon Redshift 資料共用的資料表。 + 您也可以使用增強的控制流程命令，例如 `IF` (`\ELSEIF`、`\ELSE,`、`\ENDIF`)、`\GOTO` 和 `\LABEL`。 透過 Amazon Redshift RSQL 批次模式 (該模式會執行以輸入參數形式傳遞的指令碼)，您可以執行同時包含 SQL 和複雜商業邏輯的指令碼。如果您有現有的自我管理內部部署資料倉儲，則可以使用 Amazon Redshift RSQL 取代現有的擷取、轉換、載入 (ETL) 和自動化指令碼，例如 Teradata BTEQ 指令碼。使用 RSQL 可以幫助您避免在程序語言中手動重新實作指令碼。 Amazon Redshift RSQL 適用於 Linux、Windows 和 macOS X 作業系統。 若要報告 Amazon Redshift RSQL 的問題，請寫信至 redshift-rsql-support@amazon.com。 **Topics** + [開始使用 Amazon Redshift RSQL](rsql-query-tool-getting-started.md) + [Amazon Redshift RSQL 變更日誌](rsql-query-tool-changelog.md) # 開始使用 Amazon Redshift RSQL 在搭載 Linux、macOS 或 Microsoft Windows 作業系統的電腦上安裝 Amazon Redshift RSQL。 ## 下載 RSQL + Linux 64 位元 RPM：[RSQL 1.1.2 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.2/AmazonRedshiftRsql-1.1.2.rhel.x86_64.rpm) + Linux 成品簽章金鑰：[金鑰](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.2/AmazonRedshiftRsql-1.1.2-certificate.pem) + Linux 成品簽署雜湊：[雜湊](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.2/AmazonRedshiftRsql-1.1.2-signature.bin) + Mac OS 64 位元 PKG：[RSQL 1.1.2 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.2/AmazonRedshiftRsql-1.1.2.universal.pkg) + Windows 64 位元 MSI：[RSQL 1.1.2 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.2/AmazonRedshiftRsql-1.1.2.x86_64.msi) 若要查看舊版的變更日誌和下載，請瀏覽 [Amazon Redshift RSQL 變更日誌](rsql-query-tool-changelog.md)。 ## 安裝適用於 Linux 的 RSQL 請遵循下列步驟以安裝適用於 Linux 的 RSQL。 1. 使用以下命令安裝驅動程式管理員： ``` sudo yum install unixODBC ``` 1. 安裝 ODBC 驅動程式：[下載並安裝 Amazon Redshift ODBC 驅動器下載並安裝 ODBC 驅動器](odbc20-install-linux.md)。 1. 將 ini 檔案複製到主目錄： ``` cp /opt/amazon/redshiftodbcx64/odbc.ini ~/.odbc.ini ``` 1. 將環境變數設定為指向檔案的位置： ``` export ODBCINI=~/.odbc.ini export ODBCSYSINI=/opt/amazon/redshiftodbcx64/ export AMAZONREDSHIFTODBCINI=/opt/amazon/redshiftodbcx64/amazon.redshiftodbc.ini ``` 1. 您現在可以執行下列命令來安裝 RSQL。 ``` sudo rpm -i AmazonRedshiftRsql-.rhel.x86_64.rpm ``` ## 安裝適用於 Mac 的 RSQL 請依照下列步驟安裝 RSQL for Mac OSX。 1. 使用以下命令安裝驅動程式管理員： ``` brew install unixodbc --build-from-source ``` 1. 安裝 ODBC 驅動程式：[下載並安裝 Amazon Redshift ODBC 驅動器下載並安裝 ODBC 驅動器](odbc-driver-mac-how-to-install.md)。 1. 將 ini 檔案複製到主目錄： ``` cp /opt/amazon/redshift/Setup/odbc.ini ~/.odbc.ini ``` 1. 將環境變數設定為指向檔案的位置： ``` export ODBCINI=~/.odbc.ini export ODBCSYSINI=/opt/amazon/redshift/Setup export AMAZONREDSHIFTODBCINI=/opt/amazon/redshift/lib/amazon.redshiftodbc.ini ``` 1. 將 `DYLD_LIBRARY_PATH` 設定為 libodbc.dylib 的位置 (如果它不在 `/usr/local/lib` 的話)。 ``` export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/usr/local/lib ``` 1. 按兩下 pkg 檔案來執行安裝程式。 1. 依照安裝程式中的步驟完成安裝。同意授權合約中的條款。 ## 安裝適用於 Windows 的 RSQL 請依照下列步驟安裝 RSQL for Windows。 1. 安裝 ODBC 驅動程式：[下載並安裝 Amazon Redshift ODBC 驅動器下載並安裝 ODBC 驅動器](odbc-driver-windows-how-to-install.md)。 1. 按兩下 RSQL 下載檔案以執行安裝程式，然後遵循提示以完成安裝。 # Amazon Redshift RSQL 變更日誌 *1.1.2 (2025-12-11)* 錯誤修正 + 修正使用 \$1goto 和 \$1label 命令導致失敗的錯誤。 + 修正當變數以引號括住時，導致 RSQL 無法列印變數值的錯誤。 + 修正在啟用 UseDeclareFetch 時，查詢結果超過 ODBC DSN Fetch 參數大小時，導致 RSQL 損毀的錯誤。 + 修正即使開啟分頁器，仍會一次傳回多頁結果的問題。 + 修正在交易區塊內查詢失敗時觸發 RSQL 損毀的錯誤。 *1.1.1 (2025-11-20)* 錯誤修正 + 修正 RSQL 在使用 -c 旗標時錯誤剖析查詢的問題。此修正適用於所有平台。 + 修正 Mac 上導致使用者無法在 RSQL 中使用 \$1s 命令的錯誤。 *1.1.0 (2025-11-11)* 錯誤修正 + 已解決導致 rSQL 中意外當機的記憶體流失問題。 + 從 RSQL 移除 OpenSSL 相依性。 + 修正連結與相同環境中 libpq/psql 安裝的衝突。 + 已改善 Amazon Linux 2023、Windows 和 macOS 的平台相容性。 + 修正輸出在超過目前顯示大小時會遭到截斷的問題。 *1.0.8 (2023-06-19)* 錯誤修正 + 修正了使用 SHOW 命令會截斷輸出的問題。 + 已新增對用於描述外部 Kinesis 串流和 Kafka 主題之 \$1de 的支援。 *1.0.7 (2023-03-22)* 錯誤修正 + 修正了 RSQL 無法描述具體化視觀表的問題。 + 修正了使用 Amazon Redshift Serverless 時，stl\$1connection\$1log 上的許可遭拒錯誤。 + 修正了 RSQL 可能無法正確處理 \$1GOTO 標籤的問題。 + 修正了 SSL 訊息會以靜音模式列印的問題。 + 修正了描述預存程序時會顯示隨機字元的問題。 + 修正了會列印重複 ERROR/INFO 訊息的問題。 新增 + RSQL 現在會直接從 ODBC 驅動程式取得 SSL 資訊。 *1.0.6 (2023-02-21)* 錯誤修正 + 在 Redshift 修補程式 1.0.46086 (P173) 上修正了 \$1d 會擲出錯誤 (整數的輸入語法無效: "xid") 的問題。 新增 + 已重新命名安裝檔案以反映支援的架構。 *1.0.5 (2022-06-27)* 錯誤修正 + 將 SQL 錯誤訊息傳送到標準錯誤 (stderr)。 + 修正了使用 ON\$1ERROR\$1STOP 時結束代碼所發生的問題。指令碼現在會在遇到錯誤後結束，並返回正確的結束代碼。 + Maxerror 現在不區分大小寫。 新增 + 已新增對 ODBC 2.x 驅動程式的支援。 *1.0.4 (2022-03-19)* + 新增對 RSPASSWORD 環境變數的支援。設定密碼以連線到 Amazon Redshift。例如 `export RSPASSWORD=TestPassw0rd`。 *1.0.3 (2021-12-08)* 錯誤修正 + 修正了在 Windows 作業系統中使用 `\c` 或 `\logon` 在資料庫之間進行切換時的快顯對話方塊。 + 修正了檢查 ssl 資訊時的損毀問題。 ## Amazon Redshift RSQL 的先前版本 請根據您的作業系統選擇其中一個連結，以下載您需要的 Amazon Redshift RSQL 版本。 **Linux 64 位元 RPM** + [RSQL 1.1.1 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.1/AmazonRedshiftRsql-1.1.1.rhel.x86_64.rpm) + [RSQL 1.1.0 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.0/AmazonRedshiftRsql-1.1.0.rhel.x86_64.rpm) + [RSQL 1.0.8 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.8/AmazonRedshiftRsql-1.0.8.x86_64.rpm) + [RSQL 1.0.7 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.7/AmazonRedshiftRsql-1.0.7.x86_64.rpm) + [RSQL 1.0.6 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.6/AmazonRedshiftRsql-1.0.6.x86_64.rpm) + [RSQL 1.0.5 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.5/AmazonRedshiftRsql-1.0.5-1.x86_64.rpm) + [RSQL 1.0.4 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.4/AmazonRedshiftRsql-1.0.4-1.x86_64.rpm) + [RSQL 1.0.3 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.3/AmazonRedshiftRsql-1.0.3-1.x86_64.rpm) + [RSQL 1.0.1 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.1/AmazonRedshiftRsql-1.0.1-1.x86_64.rpm) **Mac OS 64 位元 DMG/PKG** + [RSQL 1.1.1 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.1/AmazonRedshiftRsql-1.1.1.universal.pkg) + [RSQL 1.1.0 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.0/AmazonRedshiftRsql-1.1.0.universal.pkg) + [RSQL 1.0.8 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.8/AmazonRedshiftRsql-1.0.8.x86_64.dmg) + [RSQL 1.0.7 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.7/AmazonRedshiftRsql-1.0.7.x86_64.dmg) + [RSQL 1.0.6 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.6/AmazonRedshiftRsql-1.0.6.x86_64.dmg) + [RSQL 1.0.5 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.5/AmazonRedshiftRsql-1.0.5.dmg) + [RSQL 1.0.4 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.4/AmazonRedshiftRsql-1.0.4.dmg) + [RSQL 1.0.3 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.3/AmazonRedshiftRsql-1.0.3.dmg) + [RSQL 1.0.1 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.1/AmazonRedshiftRsql-1.0.1.dmg) **Windows 64 位元 MSI** + [RSQL 1.1.1 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.1/AmazonRedshiftRsql-1.1.1.x86_64.msi) + [RSQL 1.1.0 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.1.0/AmazonRedshiftRsql-1.1.0.x86_64.msi) + [RSQL 1.0.8 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.8/AmazonRedshiftRsql-1.0.8.x86_64.msi) + [RSQL 1.0.7 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.7/AmazonRedshiftRsql-1.0.7.x86_64.msi) + [RSQL 1.0.6 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.6/AmazonRedshiftRsql-1.0.6.x86_64.msi) + [RSQL 1.0.5 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.5/AmazonRedshiftRsql-1.0.5.msi) + [RSQL 1.0.4 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.4/AmazonRedshiftRsql-1.0.4.msi) + [RSQL 1.0.3 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.3/AmazonRedshiftRsql-1.0.3.msi) + [RSQL 1.0.1 版](https://s3.amazonaws.com/redshift-downloads/amazon-redshift-rsql/1.0.1/AmazonRedshiftRsql-1.0.1.msi) # 使用 Amazon Redshift RSQL 連線至叢集 透過 Amazon Redshift，您可以使用 RSQL 連線到叢集並與其互動。這是一種命令列工具，提供了安全的方法來查詢資料、建立資料庫物件及管理 Amazon Redshift 叢集。下列各節將引導您完成在使用和不使用資料來源名稱 (DSN) 搭配 RSQL 的情況下，建立與叢集的連線的步驟。 ## 在不使用 DSN 的情況下進行連線 1. 在 Amazon Redshift 主控台上，選擇要連線到的叢集，並記下端點、資料庫和連接埠。 1. 在命令提示字元中，使用命令列參數指定連線資訊。 ``` rsql -h -U -d -p ``` 這裡會套用下列項目： + ** 是您在前一步驟中記錄的 **Endpoint (端點)**。 + ** 是有許可而可以連線至叢集的使用者名稱。 + ** 是您在前一步驟中記錄的 **Database Name (資料庫名稱)**。 + ** 是您在上一個步驟中記錄的**連接埠**。** 是選用參數。 範例如下。 ``` rsql -h testcluster.example.amazonaws.com -U user1 -d dev -p 5439 ``` 1. 在密碼提示中，輸入 ** 使用者的密碼。 成功連線的回應看起來如下。 ``` % rsql -h testcluster.example.com -d dev -U user1 -p 5349 Password for user user1: DSN-less Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) user1@dev=# ``` 用來連線的命令在 Linux、Mac OS 和 Windows 上具有相同的參數。 ## 在使用 DSN 的情況下進行連線 您可以使用 DSN 將 RSQL 連線至 Amazon Redshift，以簡化連線屬性的組織。本主題包含 ODBC 驅動器安裝的指示，以及 DSN 屬性的說明。 ### 使用具有密碼的 DSN 連線 以下示範使用密碼的 DSN 連線組態範例。Mac OSX 的預設 `` 是 `/opt/amazon/redshift/lib/libamazonredshiftodbc.dylib`，Linux 的則是 `/opt/amazon/redshiftodbc/lib/64/libamazonredshiftodbc64.so`。 ``` [testuser] Driver=/opt/amazon/redshiftodbc/lib/64/libamazonredshiftodbc64.so SSLMode=verify-ca Min_TLS=1.2 boolsaschar=0 Host= Port= Database= UID= PWD= sslmode=prefer ``` 以下輸出來自成功的連線。 ``` % rsql -D testuser DSN Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) user1@dev=# ``` ### 使用單一登入 DSN 您可以設定 DSN 以進行單一登入身分驗證。以下示範使用 Okta 單一登入的 DSN 連線組態範例。 ``` [testokta] Driver= SSLMode=verify-ca Min_TLS=1.2 boolsaschar=0 Host= clusterid= region= Database= locale=en-US iam=1 plugin_name= uid= pwd= idp_host= app_id= app_name= preferred_role= ``` 成功連線的範例輸出。 ``` % rsql -D testokta DSN Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) user1@dev=# ``` 以下範例示範使用 Azure 單一登入的 DSN 連線組態範例。 ``` [testazure] Driver= SSLMode=verify-ca Min_TLS=1.2 boolsaschar=0 Host= Port= clusterid= region= Database= locale=en-us iam=1 plugin_name= uid= pwd= idp_tenant= client_id= client_secret= ``` ### 搭配 IAM 設定檔使用 DSN 連線 您可以使用所設定的 IAM 設定檔連線到 Amazon Redshift。IAM 設定檔必須具有呼叫 `GetClusterCredentials` 的權限。以下範例示範要使用的 DSN 屬性。只有在 `Host` 不是 Amazon 提供的端點 (例如 `examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com`) 時，才需要 `ClusterID` 和 `Region` 參數。 ``` [testiam] Driver=Default Host=testcluster.example.com Database=dev DbUser=testuser ClusterID=rsqltestcluster Region=us-east-1 IAM=1 Profile=default ``` `Profile` 金鑰的值是您從 CLI AWS 登入資料中選擇的具名設定檔。本範例示範名為 `default` 之設定檔的憑證。 ``` $ cat .aws/credentials [default] aws_access_key_id = ASIAIOSFODNN7EXAMPLE aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ``` 以下示範連線回應。 ``` $ rsql -D testiam DSN Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) testuser@dev=> ``` ### 搭配執行個體設定檔使用 DSN 連線 您可以使用 Amazon EC2 執行個體設定檔連線到 Amazon Redshift。執行個體設定檔必須具有呼叫 `GetClusterCredentials` 的權限。如需要使用的 DSN 屬性，請參閱以下範例。只有在 `Host` 不是 Amazon 提供的端點 (例如 `examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com`) 時，才需要 `ClusterID` 和 `Region` 參數。 ``` [testinstanceprofile] Driver=Default Host=testcluster.example.com Database=dev DbUser=testuser ClusterID=rsqltestcluster Region=us-east-1 IAM=1 Instanceprofile=1 ``` 以下示範連線回應。 ``` $ rsql -D testinstanceprofile DSN Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) testuser@dev=> ``` ### 搭配使用 DSN 連線與預設憑證提供者鏈結 若要使用預設登入資料提供者鏈結進行連線，請僅指定 IAM 屬性，Amazon Redshift RSQL 將嘗試按照適用於 Java 的 AWS SDK 中的[使用登入資料中所述的順序取得 AWS 登入](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html)資料。鏈結中至少要有一個提供者必須具有 `GetClusterCredentials` 許可。這對於從 ECS 容器進行連線 (舉例來說) 非常有用。 ``` [iamcredentials] Driver=Default Host=testcluster.example.com Database=dev DbUser=testuser ClusterID=rsqltestcluster Region=us-east-1 IAM=1 ``` # Amazon Redshift RSQL 中繼命令 Amazon Redshift RSQL 中繼命令會傳回有關資料庫或特定資料庫物件的資訊記錄。結果中可以包含各種資料行和中繼資料。其他命令會執行特定動作。這些命令的前面會加上反斜線。 ## \$1d[S\$1] 列出本機使用者建立的資料表、一般視觀表、晚期繫結視觀表及具體化視觀表。`\dS ` 也會列出資料表和視觀表 (例如 `\d`)，但系統物件包含在傳回的記錄中。`+` 會導致所有列出的物件產生額外的中繼資料資料行 `description`。以下示範執行命令所傳回的範例記錄。 ``` List of relations schema | name | type | owner --------+-----------+-------+--------- public | category | table | awsuser public | date | table | awsuser public | event | table | awsuser public | listing | table | awsuser public | sales | table | awsuser public | users | table | awsuser public | venue | table | awsuser (7 rows) ``` ## \$1d[S\$1] NAME 描述資料表、視觀表或索引。包括資料行名稱和類型。其還會提供 diststyle、備份組態、建立日期 (2018 年 10 月之後建立的資料表) 和限制。例如，`\dS+ sample` 會傳回物件屬性。附加 `S+` 會導致所傳回的記錄中包含額外資料行。 ``` Table "public.sample" Column | Type | Collation | Nullable | Default Value | Encoding | DistKey | SortKey --------+-----------------------------+----------------+----------+---------------+-----------+---------+--------- col1 | smallint | | NO | | none | t | 1 col2 | character(100) | case_sensitive | YES | | none | f | 2 col3 | character varying(100) | case_sensitive | YES | | text32k | f | 3 col4 | timestamp without time zone | | YES | | runlength | f | 0 col5 | super | | YES | | zstd | f | 0 col6 | bigint | | YES | | az64 | f | 0 Diststyle: KEY Backup: YES Created: 2021-07-20 19:47:27.997045 Unique Constraints: "sample_pkey" PRIMARY KEY (col1) "sample_col2_key" UNIQUE (col2) Foreign-key constraints: "sample_col2_fkey" FOREIGN KEY (col2) REFERENCES lineitem(l_orderkey) ``` 資料表的分佈樣式 (簡稱 *Diststyle*) 可以是 KEY、AUTO、EVEN 或 ALL。 *Backup* 會指出在擷取快照時是否有備份資料表。有效值為 `YES` 或 `NO`。 *Created* 是建立資料表時的時間戳記。建立日期不適用於 2018 年 11 月之前建立的 Amazon Redshift 資料表。在此日期之前建立的資料表會顯示 n/a (不適用)。 *Unique Constraints* 會列出資料表上唯一的和主索引鍵的限制。 *Foreign-key constraints* 會列出資料表上的外部索引鍵限制。 ## \$1dC[\$1] [PATTERN] 列出轉換。包括來源類型、目標類型，以及轉換是否為隱含。 以下示範 `\dC+` 的結果子集。 ``` List of casts source type | target type | function | implicit? | description -----------------------------+-----------------------------+---------------------+---------------+------------- "char" | character | bpchar | in assignment | "char" | character varying | text | in assignment | "char" | integer | int4 | no | "char" | text | text | yes | "path" | point | point | no | "path" | polygon | polygon | in assignment | abstime | date | date | in assignment | abstime | integer | (binary coercible) | no | abstime | time without time zone | time | in assignment | abstime | timestamp with time zone | timestamptz | yes | abstime | timestamp without time zone | timestamp | yes | bigint | bit | bit | no | bigint | boolean | bool | yes | bigint | character | bpchar | in assignment | bigint | character varying | text | in assignment | bigint | double precision | float8 | yes | bigint | integer | int4 | in assignment | bigint | numeric | numeric | yes | bigint | oid | oid | yes | bigint | real | float4 | yes | bigint | regclass | oid | yes | bigint | regoper | oid | yes | bigint | regoperator | oid | yes | bigint | regproc | oid | yes | bigint | regprocedure | oid | yes | bigint | regtype | oid | yes | bigint | smallint | int2 | in assignment | bigint | super | int8_partiql | in assignment | ``` ## \$1dd[S] [PATTERN] 顯示其他地方未顯示的物件描述。 ## \$1de 列出外部資料表。這包括 中的資料表 AWS Glue Data Catalog、Hive 中繼存放區和來自 Amazon RDS/Aurora MySQL、Amazon RDS/Aurora PostgreSQL 和 Amazon Redshift 資料共用資料表的聯合資料表。 ## \$1de NAME 描述外部資料表。 下列範例顯示 AWS Glue 外部資料表。 ``` # \de spectrum.lineitem Glue External table "spectrum.lineitem" Column | External Type | Redshift Type | Position | Partition Key | Nullable -----------------+---------------+---------------+----------+---------------+---------- l_orderkey | bigint | bigint | 1 | 0 | l_partkey | bigint | bigint | 2 | 0 | l_suppkey | int | int | 3 | 0 | l_linenumber | int | int | 4 | 0 | l_quantity | decimal(12,2) | decimal(12,2) | 5 | 0 | l_extendedprice | decimal(12,2) | decimal(12,2) | 6 | 0 | l_discount | decimal(12,2) | decimal(12,2) | 7 | 0 | l_tax | decimal(12,2) | decimal(12,2) | 8 | 0 | l_returnflag | char(1) | char(1) | 9 | 0 | l_linestatus | char(1) | char(1) | 10 | 0 | l_shipdate | date | date | 11 | 0 | l_commitdate | date | date | 12 | 0 | l_receiptdate | date | date | 13 | 0 | l_shipinstruct | char(25) | char(25) | 14 | 0 | l_shipmode | char(10) | char(10) | 15 | 0 | l_comment | varchar(44) | varchar(44) | 16 | 0 | Location: s3://redshiftbucket/kfhose2019/12/31 Input_format: org.apache.hadoop.mapred.TextInputFormat Output_format: org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat Serialization_lib: org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe Serde_parameters: {"field.delim":"|","serialization.format":"|"} Parameters: {"EXTERNAL":"TRUE","numRows":"178196721475","transient_lastDdlTime":"1577771873"} ``` Hive Metastore 資料表。 ``` # \de emr.lineitem Hive Metastore External Table "emr.lineitem" Column | External Type | Redshift Type | Position | Partition Key | Nullable -----------------+---------------+---------------+----------+---------------+---------- l_orderkey | bigint | bigint | 1 | 0 | l_partkey | bigint | bigint | 2 | 0 | l_suppkey | int | int | 3 | 0 | l_linenumber | int | int | 4 | 0 | l_quantity | decimal(12,2) | decimal(12,2) | 5 | 0 | l_extendedprice | decimal(12,2) | decimal(12,2) | 6 | 0 | l_discount | decimal(12,2) | decimal(12,2) | 7 | 0 | l_tax | decimal(12,2) | decimal(12,2) | 8 | 0 | l_returnflag | char(1) | char(1) | 9 | 0 | l_linestatus | char(1) | char(1) | 10 | 0 | l_commitdate | date | date | 11 | 0 | l_receiptdate | date | date | 12 | 0 | l_shipinstruct | char(25) | char(25) | 13 | 0 | l_shipmode | char(10) | char(10) | 14 | 0 | l_comment | varchar(44) | varchar(44) | 15 | 0 | l_shipdate | date | date | 16 | 1 | Location: s3://redshiftbucket/cetas Input_format: org.apache.hadoop.hive.ql.io.parquet.MapredParquetInputFormat Output_format: org.apache.hadoop.hive.ql.io.parquet.MapredParquetOutputFormat Serialization_lib: org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe Serde_parameters: {"serialization.format":"1"} Parameters: {"EXTERNAL":"TRUE", "numRows":"4307207", "transient_lastDdlTime":"1626990007"} ``` PostgreSQL 外部資料表。 ``` # \de pgrsql.alltypes Postgres Federated Table "pgrsql.alltypes" Column | External Type | Redshift Type | Position | Partition Key | Nullable --------+-----------------------------+-----------------------------+----------+---------------+---------- col1 | bigint | bigint | 1 | 0 | col2 | bigint | bigint | 2 | 0 | col5 | boolean | boolean | 3 | 0 | col6 | box | varchar(65535) | 4 | 0 | col7 | bytea | varchar(65535) | 5 | 0 | col8 | character(10) | character(10) | 6 | 0 | col9 | character varying(10) | character varying(10) | 7 | 0 | col10 | cidr | varchar(65535) | 8 | 0 | col11 | circle | varchar(65535) | 9 | 0 | col12 | date | date | 10 | 0 | col13 | double precision | double precision | 11 | 0 | col14 | inet | varchar(65535) | 12 | 0 | col15 | integer | integer | 13 | 0 | col16 | interval | varchar(65535) | 14 | 0 | col17 | json | varchar(65535) | 15 | 0 | col18 | jsonb | varchar(65535) | 16 | 0 | col19 | line | varchar(65535) | 17 | 0 | col20 | lseg | varchar(65535) | 18 | 0 | col21 | macaddr | varchar(65535) | 19 | 0 | col22 | macaddr8 | varchar(65535) | 20 | 0 | col23 | money | varchar(65535) | 21 | 0 | col24 | numeric | numeric(38,20) | 22 | 0 | col25 | path | varchar(65535) | 23 | 0 | col26 | pg_lsn | varchar(65535) | 24 | 0 | col28 | point | varchar(65535) | 25 | 0 | col29 | polygon | varchar(65535) | 26 | 0 | col30 | real | real | 27 | 0 | col31 | smallint | smallint | 28 | 0 | col32 | smallint | smallint | 29 | 0 | col33 | integer | integer | 30 | 0 | col34 | text | varchar(65535) | 31 | 0 | col35 | time without time zone | varchar(65535) | 32 | 0 | col36 | time with time zone | varchar(65535) | 33 | 0 | col37 | timestamp without time zone | timestamp without time zone | 34 | 0 | col38 | timestamp with time zone | timestamp with time zone | 35 | 0 | col39 | tsquery | varchar(65535) | 36 | 0 | col40 | tsvector | varchar(65535) | 37 | 0 | col41 | txid_snapshot | varchar(65535) | 38 | 0 | col42 | uuid | varchar(65535) | 39 | 0 | col43 | xml | varchar(65535) | 40 | 0 | ``` ## \$1df[anptw][S\$1] [PATTERN] 列出各種類型的函數。例如，命令 `\df` 會傳回函數清單。結果包括名稱、傳回的資料類型、存取權限和其他中繼資料等屬性。函數類型可以包括觸發條件、預存程序、視窗函數和其他類型。當您附加 `S+` 至命令時 (例如 `\dfantS+`)，其中會包括其他中繼資料資料行，例如 `owner`、`security` 和 `access privileges`。 ## \$1dL[S\$1] [PATTERN] 列出與資料庫相關聯之程序語言的相關資料。資訊中會包括名稱 (例如 plpgsql) 和其他中繼資料，其中包括其是否受信任、存取權限和描述。例如，範例呼叫是會列出語言及其屬性的 `\dLS+`。當您附加 `S+` 至命令時，其中會包括其他中繼資料資料行，例如 `call handler` 和 `access privileges`。 範例結果： ``` List of languages name | trusted | internal language | call handler | validator | access privileges | description -----------+---------+-------------------+-------------------------+------------------------------------------------------------+-------------------+-------------------------------- c | f | t | - | fmgr_c_validator(oid) | | Dynamically-loaded C functions exfunc | f | f | exfunc_call_handler() | - | rdsdb=U/rdsdb | internal | f | t | - | fmgr_internal_validator(oid) | | Built-in functions mlfunc | f | f | mlfunc_call_handler() | - | rdsdb=U/rdsdb | plpgsql | t | f | plpgsql_call_handler() | plpgsql_validator(oid) | | plpythonu | f | f | plpython_call_handler() | plpython_compiler(cstring,cstring,cstring,cstring,cstring) | rdsdb=U/rdsdb | sql | t | t | - | fmgr_sql_validator(oid) | =U/rdsdb | SQL-language functions ``` ## \$1dm[S\$1] [PATTERN] 列出具體化視觀表。例如，`\dmS+` 會列出具體化視觀表及其屬性。當您附加 `S+` 至命令時，其中會包括其他中繼資料資料行。 ## \$1dn[S\$1] [PATTERN] 列出結構描述。當您附加 `S+` 至命令時 (例如 `\dnS+`)，其中會包括其他中繼資料資料行，例如 `description` 和 `access privileges`。 ## \$1dp [PATTERN] 列出資料表、視觀表和序列存取權限。 ## \$1dt[S\$1] [PATTERN] 列出資料表。當您附加 `S+` 至命令時 (例如 `\dtS+`)，其中會包括其他中繼資料資料行，例如本案例中的 `description`。 ## \$1du 列出資料庫的使用者。包括其名稱及其角色 (例如超級使用者) 和屬性。 ## \$1dv[S\$1] [PATTERN] 列出視觀表。包括結構描述、類型和擁有者資料。當您附加 `S+` 至命令時 (例如 `\dvS+`)，其中會包括其他中繼資料資料行。 ## \$1H 開啟 HTML 輸出。這對於快速傳回格式化結果非常有用。例如，`select * from sales; \H` 會以 HTML 格式傳回銷售資料表的結果。若要切換回表格式結果，請使用 `\q` 或靜音。 ## \$1i 從檔案執行命令。例如，假設工作目錄中有 rsql\$1steps.sql，以下內容會執行檔案中的命令：`\i rsql_steps.sql`。 ## \$1l[\$1] [PATTERN] 列出資料庫。包括擁有者、編碼和其他資訊。 ## \$1q 結束或 `\q` 命令會登出資料庫工作階段並結束 RSQL。 ## \$1sv[\$1] VIEWNAME 顯示視觀表的定義。 ## \$1timing 例如，顯示查詢的執行時間。 ## \$1z [PATTERN] 與 \$1dp 相同的輸出。 ## \$1? 顯示說明資訊。選用參數會指定要解釋的項目。 ## \$1EXIT 登出所有資料庫工作階段並結束 Amazon Redshift RSQL。此外，您也可以指定選用的結束代碼。例如，`\EXIT 15` 會結束 Amazon Redshift RSQL 終端並傳回結束代碼 15。 以下範例示範從連線輸出以及從 RSQL 結束。 ``` % rsql -D testuser DSN Connected DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.34.1000 Rsql Version: 1.0.1 Redshift Version: 1.0.29306 Type "help" for help. (testcluster) user1@dev=# \exit 15 % echo $? 15 ``` ## \$1EXPORT 指定 RSQL 用來儲存後續 SQL SELECT 陳述式所傳回之資料庫資訊的匯出檔案名稱。 export\$101.sql ``` \export report file='E:\\accounts.out' \rset rformat off \rset width 1500 \rset heading "General Title" \rset titledashes on select * from td_dwh.accounts; \export reset ``` 主控台輸出 ``` Rformat is off. Target width is 1500. Heading is set to: General Title Titledashes is on. (exported 40 rows) ``` ## \$1LOGON 連線至資料庫。您可以使用位置語法或連線字串形式指定連線參數。 命令語法如下：`\logon {[DBNAME|- USERNAME|- HOST|- PORT|- [PASSWORD]] | conninfo}` `DBNAME` 是所連線的資料庫名稱。`USERNAME` 是連線時所用身分的使用者名稱。預設的 `HOST` 是 `localhost`。預設的 `PORT` 是 `5439`。 在 `\LOGON` 命令中指定主機名稱時，其會變成其他 `\LOGON` 命令的預設主機名稱。若要變更預設主機名稱，請在另外的 `\LOGON` 命令中指定新的 `HOST`。 來自 `user1` 之 `\LOGON` 命令的範例輸出如下。 ``` (testcluster) user1@redshiftdb=# \logon dev DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 You are now connected to database "dev" as user "user1". (testcluster) user1@dev=# ``` *user2* 的範例輸出。 ``` (testcluster) user1@dev=# \logon dev user2 testcluster2.example.com Password for user user2: DBMS Name: Amazon Redshift Driver Name: Amazon Redshift ODBC Driver Driver Version: 1.4.27.1000 Rsql Version: 1.0.1 You are now connected to database "dev" as user "user2" on host "testcluster2.example.com" at port "5439". (testcluster2) user2@dev=# ``` ## \$1REMARK `\echo` 命令的延伸。`\REMARK` 會將指定字串列印至輸出串流。`\REMARK ` 會透過新增將輸出換行到不同行的能力來延伸 `\echo`。 以下範例示範命令的輸出。 ``` (testcluster) user1@dev=# \remark 'hello//world' hello world ``` ## \$1RSET 命令 `\rset` 會設定命令參數和變數。`\rset` 同時具有互動式模式和批次模式。其不支援將選項作為 bash 選項，如 *-x* 或引數，例如 *--*。 其會設定變數，如下所示： + ERRORLEVEL + HEADING 和 RTITLE + RFORMAT + MAXERROR + TITLEDASHES + WIDTH 以下範例會指定標題。 ``` \rset heading "Winter Sales Report" ``` 如需更多如何使用 `\rset` 的範例，您可以在 [Amazon Redshift RSQL 變數](rsql-query-tool-variables.md) 主題中找到幾個。 ## \$1RUN 執行指定檔案中包含的 Amazon Redshift RSQL 指令碼。`\RUN` 會透過新增選項來擴展 `\i` 命令，以略過檔案中的標題行。 如果檔案名稱包含逗號、分號或空格，請以單引號將其括住。此外，如果檔案名稱後面有文字，請以引號將其括住。在 UNIX 中，檔案名稱會區分大小寫。在 Windows 中，檔案名稱不區分大小寫。 以下範例示範命令的輸出。 ``` (testcluster) user1@dev=# \! cat test.sql select count(*) as lineitem_cnt from lineitem; select count(*) as customer_cnt from customer; select count(*) as orders_cnt from orders; (testcluster) user1@dev=# \run file=test.sql lineitem_cnt -------------- 4307207 (1 row) customer_cnt -------------- 37796166 (1 row) orders_cnt ------------ 0 (1 row) (testcluster) user1@dev=# \run file=test.sql skip=2 2 records skipped in RUN file. orders_cnt ------------ 0 (1 row) ``` ## \$1OS `\!` 命令的別名。`\OS` 會執行以參數的形式傳遞的作業系統命令。執行命令後，控制項會回到 Amazon Redshift RSQL。例如，您可以執行以下命令來列印目前的系統日期時間，並返回 RSQL 終端：`\os date`。 ``` (testcluster) user1@dev=# \os date Tue Sep 7 20:47:54 UTC 2021 ``` ## \$1GOTO Amazon Redshift RSQL 的新命令。`\GOTO` 會略過所有中間命令，並在指定的 `\LABEL` 繼續處理。`\LABEL` 必須是前向參照。你不能跳到詞法上在 `\GOTO` 之前的 `\LABEL`。 下面顯示了範例輸出。 ``` (testcluster) user1@dev=# \! cat test.sql select count(*) as cnt from lineitem \gset select :cnt as cnt; \if :cnt > 100 \goto LABELB \endif \label LABELA \remark 'this is label LABELA' \label LABELB \remark 'this is label LABELB' (testcluster) user1@dev=# \i test.sql cnt --------- 4307207 (1 row) \label LABELA ignored \label LABELB processed this is label LABELB ``` ## \$1LABEL Amazon Redshift RSQL 的新命令。`\LABEL` 會建立用於執行程式的進入點，以作為 `\GOTO` 命令的目標。 以下示範命令的範例輸出。 ``` (testcluster) user1@dev=# \! cat test.sql select count(*) from lineitem limit 5; \goto LABELB \remark "this step was skipped by goto label"; \label LABELA \remark 'this is label LABELA' \label LABELB \remark 'this is label LABELB' (testcluster) user1@dev=# \i testgoto.sql count 4307193 (1 row) \label LABELA ignored \label LABELB processed this is label LABELB ``` ## \$1IF (\$1ELSEIF, \$1ELSE, \$1ENDIF) `\IF` 和相關命令會有條件地執行輸入指令碼的某些部分。PSQL `\if` (`\elif`、`\else`、`\endif`) 命令的延伸。`\IF` 和 `\ELSEIF` 支援布林運算式，包括 `AND`、`OR` 和 `NOT` 條件。 以下示範命令的範例輸出。 ``` (testcluster) user1@dev=# \! cat test.sql SELECT query FROM stv_inflight LIMIT 1 \gset select :query as query; \if :query > 1000000 \remark 'Query id is greater than 1000000' \elseif :query = 1000000 \remark 'Query id is equal than 1000000' \else \remark 'Query id is less than 1000000' \endif (testcluster) user1@dev=# \i test.sql query -------- 994803 (1 row) Query id is less than 1000000 ``` 在您的分支邏輯中使用 `ERRORCODE`。 ``` \if :'ERRORCODE' = '00000' \remark 'The statement was executed without error' \else \remark :LAST_ERROR_MESSAGE \endif ``` 在 `\IF` 區塊內使用 `\GOTO` 來控制程式碼的執行方式。 # Amazon Redshift RSQL 變數 某些關鍵字會作為 RSQL 中的變數。您可以將每個關鍵字設定為特定值，或重設該值。大多數關鍵字會使用具有互動式模式和批次模式的 `\rset` 來進行設定。命令可以用小寫或大寫來定義。 ## ACTIVITYCOUNT 指出上次提交的請求所影響的資料列數目。若為資料傳回請求，這是從資料庫傳回到 RSQL 的資料列數目。此值是 0 或正整數。最大值是 18,446,744,073,709,551,615。 特殊對待的變數 `ACTIVITYCOUNT` 類似於變數 `ROW_COUNT`。不過，`ROW_COUNT` 不會在 `SELECT`、`COPY` 或 `UNLOAD` 的命令完成時，向用戶端應用程式報告受影響的資料列計數。但 `ACTIVITYCOUNT` 會。 activitycount\$101.sql： ``` select viewname, schemaname from pg_views where schemaname = 'not_existing_schema'; \if :ACTIVITYCOUNT = 0 \remark 'views do not exist' \endif ``` 主控台輸出： ``` viewname | schemaname ----------+------------ (0 rows) views do not exist ``` ## ERRORLEVEL 指定錯誤的嚴重性等級。使用嚴重性等級可決定行動方式。如果尚未使用 `ERRORLEVEL` 命令，則其值預設會是 `ON`。 errorlevel\$101.sql： ``` \rset errorlevel 42P01 severity 0 select * from tbl; select 1 as col; \echo exit \quit ``` 主控台輸出： ``` Errorlevel is on. rsql: ERROR: relation "tbl" does not exist (1 row) col 1 exit ``` ## HEADING 和 RTITLE 可讓使用者指定顯示在報告頂端的標頭。`RSET RTITLE` 命令指定的標頭會自動包含用戶端電腦的目前系統日期。 rset\$1heading\$1rtitle\$102.rsql content： ``` \remark Starting... \rset rtitle "Marketing Department||Confidential//Third Quarter//Chicago" \rset width 70 \rset rformat on select * from rsql_test.tbl_currency order by id limit 2; \exit \remark Finishing... ``` 主控台輸出： ``` Starting... Rtitle is set to: &DATE||Marketing Department||Confidential//Third Quarter//Chicago (Changes will take effect after RFORMAT is switched ON) Target width is 70. Rformat is on. 09/11/20 Marketing Department Confidential Third Quarter Chicago id | bankid | name | start_date 100 | 1 | USD | 2020-09-11 10:51:39.106905 110 | 1 | EUR | 2020-09-11 10:51:39.106905 (2 rows) Press any key to continue . . . ``` ## MAXERROR 指定 RSQL 會終止任務處理的最大錯誤嚴重性等級。傳回代碼是 RSQL 在完成每項任務之後傳回給用戶端作業系統的整數值。傳回代碼的值會指出任務的完成狀態。如果指令碼包含的陳述式所產生的錯誤嚴重性等級大於指定的 `maxerror` 值，則 RSQL 會立即結束。因此，若要讓 RSQL 在錯誤嚴重性等級為 8 時結束，請使用 `RSET MAXERROR 7`。 maxerror\$101.sql content： ``` \rset maxerror 0 select 1 as col; \quit ``` 主控台輸出： ``` Maxerror is default. (1 row) col 1 ``` ## RFORMAT 可讓使用者指定是否要套用格式化命令的設定。 rset\$1rformat.rsql content： ``` \remark Starting... \pset border 2 \pset format wrapped \pset expanded on \pset title 'Great Title' select * from rsql_test.tbl_long where id = 500; \rset rformat select * from rsql_test.tbl_long where id = 500; \rset rformat off select * from rsql_test.tbl_long where id = 500; \rset rformat on select * from rsql_test.tbl_long where id = 500; \exit \remark Finishing... ``` 主控台輸出： ``` Starting... Border style is 2. (Changes will take effect after RFORMAT is switched ON) Output format is wrapped. (Changes will take effect after RFORMAT is switched ON) Expanded display is on. (Changes will take effect after RFORMAT is switched ON) Title is "Great Title". (Changes will take effect after RFORMAT is switched ON) id | long_string 500 | In general, the higher the number the more borders and lines the tables will have, but details depend on the particular format. (1 row) Rformat is on. Great Title +-[ RECORD 1 ]+---------------------------------------------------------------------------------------------------------------------- -----------+ | id | 500 | | long_string | In general, the higher the number the more borders and lines the tables will have, but details depend on the particular format. | +-------------+---------------------------------------------------------------------------------------------------------------------- -----------+ Rformat is off. id | long_string 500 | In general, the higher the number the more borders and lines the tables will have, but details depend on the particular format. (1 row) Rformat is on. Great Title +-[ RECORD 1 ]+---------------------------------------------------------------------------------------------------------------------- -----------+ | id | 500 | | long_string | In general, the higher the number the more borders and lines the tables will have, but details depend on the particular format. | +-------------+---------------------------------------------------------------------------------------------------------------------- -----------+ Press any key to continue . . . ``` ## ROW\$1COUNT 取得受先前查詢影響的記錄數目。其通常用來檢查結果，如下面的程式碼片段： ``` SET result = ROW_COUNT; IF result = 0 ... ``` ## TITLEDASHES 此控制項可讓使用者指定是否要在針對 SQL 陳述式所傳回的資料行資料上方列印一行破折號字元。 範例： ``` \rset titledashes on select dept_no, emp_no, salary from rsql_test.EMPLOYEE where dept_no = 100; \rset titledashes off select dept_no, emp_no, salary from rsql_test.EMPLOYEE where dept_no = 100; ``` 主控台輸出： ``` dept_no emp_no salary ----------- ----------- -------------------- 100 1000346 1300.00 100 1000245 5000.00 100 1000262 2450.00 dept_no emp_no salary 100 1000346 1300.00 100 1000245 5000.00 100 1000262 2450.00 ``` ## WIDTH 將輸出格式設定為換行，並指定報告中每一行的目標寬度。如果沒有參數，則會傳回格式和目標寬度的目前設定。 rset\$1width\$101.rsql content： ``` \echo Starting... \rset width \rset width 50 \rset width \quit \echo Finishing... ``` 主控台輸出： ``` Starting... Target width is 75. Target width is 50. Target width is 50. Press any key to continue . . . ``` 有參數的範例： ``` \echo Starting... \rset rformat on \pset format wrapped select * from rsql_test.tbl_long where id = 500; \rset width 50 select * from rsql_test.tbl_long where id = 500; \quit \echo Finishing... ``` 主控台輸出： ``` Starting... Rformat is on. Output format is wrapped. id | long_string 500 | In general, the higher the number the more borders and lines the ta. |.bles will have, but details depend on the particular format. (1 row) Target width is 50. id | long_string 500 | In general, the higher the number the more. |. borders and lines the tables will have, b. |.ut details depend on the particular format. |.. (1 row) Press any key to continue . . . ``` # Amazon Redshift RSQL 錯誤代碼 成功訊息、警告和例外狀況： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/rsql-query-tool-error-codes.html) 資料例外狀況： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/rsql-query-tool-error-codes.html) 完整性限制違規： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/redshift/latest/mgmt/rsql-query-tool-error-codes.html) # Amazon Redshift RSQL 環境變數 Amazon Redshift RSQL 可以使用環境變數來選取預設的參數值。 ## RSPASSWORD **重要** 基於安全考量，不建議您使用此環境變數，因為某些作業系統會允許非系統管理使用者查看處理序環境變數。 設定 Amazon Redshift RSQL 在連線至 Amazon Redshift 時要使用的密碼。此環境變數需要 Amazon Redshift RSQL 1.0.4 及以上版本。 如果設定了 RSPASSWORD，RSQL 會優先使用 RSPASSWORD。如果未設定 RSPASSWORD，而且您使用 DSN 進行連線，則 RSQL 會從 DSN 檔案的參數中取得密碼。最後，如果未設定 RSPASSWORD，而且您沒有使用 DSN，則 RSQL 會在嘗試連線後提供密碼提示。 以下是設定 RSPASSWORD 的範例： ``` export RSPASSWORD=TestPassw0rd ``` # 使用身分驗證設定檔連線至 Amazon Redshift 如果您有許多 Amazon Redshift 連線，則可能難以管理所有連線的設定。每個 JDBC 或 ODBC 連線通常會使用特定的組態選項。透過使用身分驗證設定檔，您可以將連線選項儲存在一起。如此一來，使用者就可以選擇要用來連線的設定檔，而不必管理個別選項的設定。設定檔可以套用至各種案例和使用者類型。 在您建立身分驗證設定檔後，使用者便可以將已可使用的設定檔新增至連線字串。如此一來，其便可以使用每個角色和使用案例的正確設定來連線至 Amazon Redshift。 如需 Amazon Redshift API 資訊，請參閱 [CreateAuthenticationProfile](https://docs.aws.amazon.com/redshift/latest/APIReference/redshift-api.pdf#API_CreateAuthenticationProfile)。 # 建立身分驗證設定檔 使用 AWS CLI，您可以使用 `create-authentication-profile`命令建立身分驗證設定檔。這會假設您有現有的 Amazon Redshift 叢集和現有的資料庫。您的憑證必須具有可連線至 Amazon Redshift 資料庫的許可，以及可擷取身分驗證設定檔的權限。您可以透過 JSON 字串的形式提供組態選項，也可以參考包含 JSON 字串的檔案。 ``` create-authentication-profile --authentication-profile-name --authentication-profile-content ``` 以下範例會建立名為 `ExampleProfileName` 的設定檔。在這裡，您可以將定義叢集名稱和其他選項設定的金鑰和值新增為 JSON 字串。 ``` create-authentication-profile --authentication-profile-name "ExampleProfileName" --authentication-profile-content "{\"AllowDBUserOverride\":\"1\",\"Client_ID\":\"ExampleClientID\",\"App_ID\":\"ExampleAppID\",\"AutoCreate\":false,\"enableFetchRingBuffer\":true,\"databaseMetadataCurrentDbOnly\":true}" } ``` 此命令會使用指定的 JSON 設定建立設定檔。系統會傳回以下內容，以指出您已建立設定檔。 `{"AuthenticationProfileName": "ExampleProfileName", "AuthenticationProfileContent": "{\"AllowDBUserOverride\":\"1\",\"Client_ID\":\"ExampleClientID\",\"App_ID\":\"ExampleAppID\",\"AutoCreate\":false,\"enableFetchRingBuffer\":true,\"databaseMetadataCurrentDbOnly\":true}" } ` ## 建立身分驗證設定檔的限制和配額 每位客戶的配額為十 (10) 個身分驗證設定檔。 身分驗證設定檔可能會發生某些錯誤。例如，如果您使用現有名稱建立新的設定檔，或是您超過設定檔配額的話。如需詳細資訊，請參閱 [CreateAuthenticationProfile](https://docs.aws.amazon.com/redshift/latest/APIReference/redshift-api.pdf#API_CreateAuthenticationProfile)。 您無法在身分驗證設定檔存放區中儲存 JDBC、ODBC 和 Python 連線字串的某些選項金鑰和值： + `AccessKeyID` + `access_key_id` + `SecretAccessKey` + `secret_access_key_id` + `PWD` + `Password` + `password` 您無法在設定檔存放區中儲存 JDBC 或 ODBC 連線字串的金鑰或值 `AuthProfile`。若為 Python 連線，您無法儲存 `auth_profile`。 身分驗證設定檔存放在 Amazon DynamoDB 中並由 管理 AWS。 # 使用身分驗證設定檔連線 在建立身分驗證設定檔後，便可以在 JDBC 2.0 版 `AuthProfile` 中將設定檔名稱納入為連線選項。使用此連線選項會擷取已儲存的設定。 ``` jdbc:redshift:iam://endpoint:port/database?AuthProfile=&AccessKeyID=&SecretAccessKey= ``` 以下是 JDBC URL 字串範例。 ``` jdbc:redshift:iam://examplecluster:us-west-2/dev?AuthProfile="ExampleProfile"&AccessKeyID="AKIAIOSFODNN7EXAMPLE"&SecretAccessKey="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" ``` 在 JDBC URL 中指定 `AccessKeyID` 和 `SecretAccessKey`，以及身分驗證設定檔名稱。 您也可以使用分號分隔符號來分隔組態選項，例如以下範例 (其包含記錄的選項)。 ``` jdbc:redshift:iam://my_redshift_end_point:5439/dev?LogLevel=6;LogPath=/tmp;AuthProfile=my_profile;AccessKeyID="AKIAIOSFODNN7EXAMPLE";SecretAccessKey="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" ``` **注意** 請勿將機密資訊新增至身分驗證設定檔。例如，請勿在身分驗證設定檔中儲存 `AccessKeyID` 或 `SecretAccessKey` 值。身分驗證設定檔存放區具有禁止儲存秘密金鑰的規則。如果您嘗試儲存與敏感資訊相關聯的金鑰和值，就會收到錯誤。 # 取得身分驗證設定檔 若要列出現有的身分驗證設定檔，請呼叫以下命令。 ``` describe-authentication-profiles --authentication-profile-name ``` 以下範例示範所擷取的兩個設定檔。如果未指定設定檔名稱，則會傳回所有設定檔。 `{ "AuthenticationProfiles": [ { "AuthenticationProfileName": "testProfile1", "AuthenticationProfileContent": "{\"AllowDBUserOverride\":\"1\",\"Client_ID\":\"ExampleClientID\",\"App_ID\":\"ExampleAppID\",\"AutoCreate\":false,\"enableFetchRingBuffer\":true,\"databaseMetadataCurrentDbOnly\":true}" }, { "AuthenticationProfileName": "testProfile2", "AuthenticationProfileContent": "{\"AllowDBUserOverride\":\"1\",\"Client_ID\":\"ExampleClientID\",\"App_ID\":\"ExampleAppID\",\"AutoCreate\":false,\"enableFetchRingBuffer\":true,\"databaseMetadataCurrentDbOnly\":true}" } ] } ` # 針對 Amazon Redshift 中的連線問題進行疑難排解 如果從 SQL 用戶端工具連接至叢集時有問題，您可以檢查幾個項目來縮小問題的範圍。如果您使用 SSL 或伺服器憑證，對連線問題進行故障排除時，請先移除此複雜度。然後在找到解決方案之後加回來。如需詳細資訊，請參閱[設定連線的安全選項](connecting-ssl-support.md)。 如需 Amazon Redshift 功能中可能影響應用程式的行為變更相關資訊，請參閱 [Amazon Redshift 中的行為變更](behavior-changes.md)。 **重要** Amazon Redshift 已變更 SSL 憑證的管理方式。如果您無法使用 SSL 來連接，您可能需要更新目前的信任根 CA 憑證。如需詳細資訊，請參閱[將 SSL 連線轉換為使用 ACM 憑證](connecting-transitioning-to-acm-certs.md)。 下一節提供連線問題的一些範例錯誤訊息及可能的解決方案。因為不同的 SQL 用戶端工具會提供不同的錯誤訊息，所以這不是完整的清單，但很適合作為問題疑難排解時的起點。 ## 從 Amazon EC2 外部進行連線並發生防火牆逾時問題 執行長時間查詢 (例如 COPY 命令) 時，對資料庫的用戶端連線似乎懸置或逾時。在此情況下，您可能會發現 Amazon Redshift 主控台顯示查詢已完成，但用戶端工具本身仍似乎在執行查詢。取決於連線停止的時間，查詢的結果可能遺漏或不完整。 ### 可能的解決方案 從 Amazon EC2 執行個體以外的機器連線到 Amazon Redshift 時，便會發生此問題。在此情況下，閒置連線會在閒置一段時間後，遭到中繼網路元件 (例如防火牆) 終止。當您從虛擬私有網路 (VPN) 或本機網路登入時，這是很典型的行為。 為了避免這些逾時，建議採取下列變更： + 提高與 TCP/IP 逾時有關的用戶端系統值。請在您用來連接至叢集的電腦上進行這些變更。應該依您的用戶端和網路來調整逾時期間。如需詳細資訊，請參閱[變更 TCP/IP 逾時設定](#connecting-firewall-guidance.change-tcpip-settings)。 + (選用) 在 DSN 層級上設定保持連線行為。如需詳細資訊，請參閱[變更 DSN 逾時設定](#connecting-firewall-guidance.change-dsn-settings)。 ### 變更 TCP/IP 逾時設定 若要變更 TCP/IP 逾時設定，請根據您用於連接至叢集的作業系統來設定逾時設定。 + Linux — 如果用戶端在 Linux 上執行，請以根使用者身分執行下列命令，以變更目前工作階段的逾時設定： ``` /sbin/sysctl -w net.ipv4.tcp_keepalive_time=200 net.ipv4.tcp_keepalive_intvl=200 net.ipv4.tcp_keepalive_probes=5 ``` 若要保留設定，請使用下列值建立或修改 `/etc/sysctl.conf` 檔案，然後重新啟動系統。 ``` net.ipv4.tcp_keepalive_time=200 net.ipv4.tcp_keepalive_intvl=200 net.ipv4.tcp_keepalive_probes=5 ``` + Windows — 如果用戶端在 Windows 上執行，請在 HKEY\$1LOCAL\$1MACHINE\$1SYSTEM\$1CurrentControlSet\$1Services\$1Tcpip\$1Parameters\$1 下編輯下列登錄設定的值： + KeepAliveTime：30000 + KeepAliveInterval：1000 + TcpMaxDataRetransmissions：10 這些設定使用 DWORD 資料類型。如果這些設定不存在於登錄路徑下，您可以建立設定並指定這些建議值。如需編輯 Windows 登錄的相關資訊，請參閱 Windows 文件。 設定這些值之後，請重新啟動電腦以讓變更生效。 + Mac — 如果用戶端在 Mac 上執行，請執行下列命令，以變更目前工作階段的逾時設定： ``` sudo sysctl net.inet.tcp.keepintvl=200000 sudo sysctl net.inet.tcp.keepidle=200000 sudo sysctl net.inet.tcp.keepinit=200000 sudo sysctl net.inet.tcp.always_keepalive=1 ``` 若要保留設定，請使用下列值建立或修改 `/etc/sysctl.conf` 檔案： ``` net.inet.tcp.keepidle=200000 net.inet.tcp.keepintvl=200000 net.inet.tcp.keepinit=200000 net.inet.tcp.always_keepalive=1 ``` 重新啟動電腦，然後執行下列命令，以驗證是否已設定這些值。 ``` sysctl net.inet.tcp.keepidle sysctl net.inet.tcp.keepintvl sysctl net.inet.tcp.keepinit sysctl net.inet.tcp.always_keepalive ``` ### 變更 DSN 逾時設定 您可以在 DSN 層級上設定保持連線行為 (若選擇這麼做)。在作法上是在 odbc.ini 檔案中新增或修改下列參數： **KeepAlivesCount** 在認為連線已中斷之前可遺失的 TCP 保持連線封包數。 **KeepAlivesIdle** 驅動程式傳送 TCP 保持連線封包之前的閒置秒數。 **KeepAlivesInterval** 每一次 TCP 保持連線重新傳輸之間的秒數。 如果這些參數不存在，或值為 0，系統會使用指定給 TCP/IP 的保持連線參數，以決定 DSN 保持連線行為。在 Windows 上，您可以在 `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\` 的登錄中找到 TCP/IP 參數。在 Linux 和 macOS 上，您可以在 sysctl.conf 檔案中找到 TCP/IP 參數。 ## 連線遭拒或失敗 如果您的連線遭拒或失敗，您可能會收到類似下列其中一項的錯誤。 + 「無法對 ** 建立連線。」 + 「無法連接至伺服器：連線逾時。伺服器在主機 *''* 上執行且在連接埠 *''* 上接受 TCP/IP 連線嗎？」 + 「連線遭拒。請檢查主機名稱和連接埠正確，且 postmaster 接受 TCP/IP 連線。」 ### 可能的解決方案 一般來說，收到錯誤訊息指出無法建立連線時，表示存取叢集的許可有問題，或到達叢集的網路流量有問題。 若要從叢集所在網路外部的用戶端工具連線至叢集，請在叢集的安全群組中新增傳入規則。規則組態取決於 Amazon Redshift 叢集是否建立於虛擬私有雲端 (VPC)： + 如果您在以 Amazon VPC 為基礎的虛擬私有雲端 (VPC) 中建立了 Amazon Redshift 叢集，請在 Amazon VPC 中於 VPC 安全群組內新增會指定用戶端 CIDR/IP 地址的傳入規則。如需為叢集設定 VPC 安全群組以及可公開存取選項的相關資訊，請參閱 [VPC 中的 Redshift 資源](managing-clusters-vpc.md)。 + 如果在 VPC 外部建立了 Amazon Redshift 叢集，請在 Amazon Redshift 中將用戶端 CIDR/IP 地址新增至叢集安全群組。如需設定叢集安全群組的相關資訊，請參閱 [Amazon Redshift 安全群組](security-network-isolation.md#working-with-security-groups)。 如果您嘗試從在 Amazon EC2 執行個體上執行的用戶端工具連線至叢集，您也會新增傳入規則。在此情況下，請在叢集安全群組中新增規則。此規則必須指定與用戶端工具的 Amazon EC2 執行個體相關聯的 Amazon EC2 安全群組。 在某些情況下，您的用戶端與伺服器之間可能有一層，例如防火牆。在這些情況下，請確定防火牆透過您為叢集設定的連接埠接受傳入連線。 ## 用戶端和驅動程式不相容 如果您的用戶端和驅動器不相容，您可能會收到錯誤，指出「指定的 DSN 包含驅動器與應用程式之間的架構不符」。 ### 可能的解決方案 當您嘗試連接並得到有關架構不符的錯誤時，這表示用戶端工具和驅動程式不相容。原因是它們的系統架構不相符。例如，假設您有 32 位元用戶端工具，但卻安裝 64 位元版本的驅動程式，就可能發生此錯誤。有時，64 位元用戶端工具可以使用 32 位元驅動程式，但 32 位元應用程式不能搭配 64 位元驅動程式一起使用。請確定驅動程式和用戶端工具使用相同版本的系統架構。 ## 查詢似乎沒有回應且有時無法觸達叢集 您遇到查詢完成方面的問題，查詢似乎正在執行，但在 SQL 用戶端工具中無回應。有時，查詢無法出現在叢集，例如系統資料表或 Amazon Redshift 主控台。 ### 可能的解決方案 由於封包捨棄，可能發生此問題。在兩個網際網路通訊協定 (IP) 主機之間的網路路徑中，最大傳輸單位 (MTU) 出現差異。MTU 大小決定網路連線上的一個乙太網路訊框中可傳輸的封包大小上限 (位元組)。在 中 AWS，某些 Amazon EC2 執行個體類型支援 1500 的 MTU （乙太網路 v2 訊框），而其他執行個體類型則支援 9001 的 MTU (TCP/IP 巨型訊框）。 為了避免因為 MTU 大小不同而發生問題，建議採取下列其中一個動作： + 如果叢集使用 EC2-VPC 平台，請以傳回 `Destination Unreachable` 的傳入自訂「網際網路控制訊息通訊協定 (ICMP)」規則來設定 Amazon VPC 安全群組。此規則會藉以指示原始主機沿著網路路徑使用最低的 MTU 大小。如需此方法的詳細資訊，請參閱[將安全群組設為允許 ICMP「無法觸達目標」](#configure-custom-icmp)。 + 如果叢集使用 EC2-Classic 平台，或您無法允許 ICMP 傳入規則，請停用 TCP/IP 巨型訊框，以便使用乙太網路 v2 訊框。如需此方法的詳細資訊，請參閱[設定執行個體的 MTU](#set-mtu)。 ### 將安全群組設為允許 ICMP「無法觸達目標」 在兩個主機之間的網路中，當 MTU 大小出現差異時，首先請確定網路設定並未禁止路徑 MTU 探索 (PMTUD)。PMTUD 可讓接收端主機向原始主機回應下列 ICMP 訊息：`Destination Unreachable: fragmentation needed and DF set (ICMP Type 3, Code 4)`。此訊息指示原始主機沿著網路路徑，使用最低的 MTU 大小來重新傳送請求。如果不這樣協議，可能會因為請求太大，使得接收端主機無法接受，而發生封包捨棄。如需此 ICMP 訊息的相關資訊，請前往*網際網路工程任務組 (IETF)* 網站上的 [RFC792](http://tools.ietf.org/html/rfc792)。 如果您沒有明確為 Amazon VPC 安全群組設定此 ICMP 傳入規則，則會封鎖 PMTUD。在 中 AWS，安全群組是虛擬防火牆，可指定執行個體傳入和傳出流量的規則。如需 Amazon Redshift 叢集安全群組的相關資訊，請參閱 [Amazon Redshift 安全群組](security-network-isolation.md#working-with-security-groups)。對於使用 EC2-VPC 平台的叢集，Amazon Redshift 會使用 VPC 安全群組來允許或拒絕流量進入叢集。根據預設，安全群組會鎖定並拒絕所有傳入流量。如需如何為 EC2-Classic 或 EC2-VPC 執行個體設定傳入和傳出規則的相關資訊，請參閱《Amazon EC2 使用者指南》**中的 [EC2-Classic 與 VPC 中的執行個體差異](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-classic-platform.html#ec2_classic_platform)。 如需如何將規則新增至 VPC 安全群組的相關資訊，請參閱[VPC security groups (VPC 安全群組)](managing-vpc-security-groups.md)。如需此規則中所需特定 PMTUD 設定的相關資訊，請參閱《Amazon EC2 使用者指南》**中的[路徑 MTU 探索](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/network_mtu.html#path_mtu_discovery)。 ### 設定執行個體的 MTU 在某些情況下，您的叢集可能會使用 EC2-Classic 平台，或您無法允許傳入流量的自訂 ICMP 規則。在這些情況下，我們建議您將連線到 Amazon Redshift 叢集之 EC2 執行個體的網路界面 (NIC) 上的 MTU 調整為 1500。此調整會停用 TCP/IP 巨型訊框，以確保連線始終使用相同的封包大小。不過，此選項會完全地降低執行個體的最大網路輸送量，而不只是 Amazon Redshift 的連線而已。如需詳細資訊，請參閱下列程序。 **在 Microsoft Windows 作業系統上設定 MTU** 如果用戶端在 Microsoft Windows 作業系統中執行，您可以使用 `netsh` 命令來檢閱並設定乙太網路卡的 MTU 值。 1. 執行下列命令來判斷目前的 MTU 值： ``` netsh interface ipv4 show subinterfaces ``` 1. 在輸出中檢閱 `MTU` 界面卡的 `Ethernet` 值。 1. 如果值不是 `1500`，請執行下列命令來設定此值： ``` netsh interface ipv4 set subinterface "Ethernet" mtu=1500 store=persistent ``` 設定此值之後，請重新啟動電腦以讓變更生效。 **在 Linux 作業系統上設定 MTU** 如果用戶端在 Linux 作業系統中執行，您可以使用 `ip` 命令來檢閱並設定 MTU 值。 1. 執行下列命令來判斷目前的 MTU 值： ``` $ ip link show eth0 ``` 1. 在輸出中檢閱 `mtu` 後面的值。 1. 如果值不是 `1500`，請執行下列命令來設定此值： ``` $ sudo ip link set dev eth0 mtu 1500 ``` **在 Mac 作業系統上設定 MTU** + 請遵循 macOS 支援網站上有關 的指示`How to change the MTU for troubleshooting purposes`。如需詳細資訊，請搜尋[支援網站](https://support.apple.com)。 ## 設定 JDBC 擷取大小參數 根據預設，Redshift JDBC 驅動程式會使用環形緩衝區來有效管理記憶體，並防止out-of-memory錯誤。擷取大小參數僅適用於明確停用環緩衝區的情況。如需詳細資訊，請檢閱[連結](https://docs.aws.amazon.com/redshift/latest/mgmt/jdbc20-configuration-options.html#jdbc20-enablefetchringbuffer-option)。在此組態中，您應該設定擷取大小，以控制每個批次中要擷取的資料列數量。 在下列情況下使用擷取大小參數： + 您需要精細控制以資料列為基礎的批次 + 使用需要傳統擷取大小行為的舊版應用程式 當環緩衝區停用時，JDBC 驅動程式預設會一次收集查詢的所有結果。傳回大型結果集的查詢可能會耗用過多記憶體。若要以批次而非一次全部擷取結果集，請在應用程式中設定 JDBC 擷取大小參數。 **注意** ODBC 不支援擷取大小。 為求最佳效能，請將擷取大小設定為不會導致記憶體不足錯誤的最高值。較低的擷取大小值會造成更多伺服器來回行程，進而延長執行時間。伺服器會預留資源，包括 WLM 查詢位置和關聯的記憶體，直到用戶端擷取整個結果集或查詢取消為止。適當地調校擷取大小時，那些資源會更快速釋出，使得它們可供其他查詢使用。 **注意** 如果您必須擷取大型資料集，建議使用 [UNLOAD](https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD.html) 陳述式來將資料傳輸至 Amazon S3。使用 UNLOAD 時，運算節點會平行運作，以加速資料的傳輸。 如需設定 JDBC 擷取大小參數的相關資訊，請前往 PostgreSQL 文件中的[根據游標取得結果](https://jdbc.postgresql.org/documentation/query/#getting-results-based-on-a-cursor)。 # 使用 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 《 使用者指南*》中的[什麼是 AWS Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。您也可以使用 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` 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"`)，並且會回報錯誤 (錯誤：在 \$1"FROM\$1"\$1n 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` 操作會支援含有參數的 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": } ``` # 授權 Amazon Redshift 資料 API 的存取 若要存取資料 API，使用者必須獲得授權。您可以透過將受管政策 (即預先定義的 AWS Identity and Access Management (IAM) 政策) 新增至該使用者，來授權其存取資料 API。我們建議的最佳實務是，將許可政策附加到 IAM 角色，然後根據需要將其指派給使用者和群組。如需詳細資訊，請參閱 [Amazon Redshift 中的身分和存取管理](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html)。若要查看受管政策允許和拒絕的許可，請參閱 IAM 主控台 ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/))。 # 設定 IAM 許可權限 Amazon Redshift 會提供 `AmazonRedshiftDataFullAccess` 受管政策。此政策可提供 Amazon Redshift 資料 API 操作的完整存取權。此政策也允許對特定 Amazon Redshift 的存取範圍 AWS Secrets Manager，以及驗證和存取 Amazon Redshift 叢集或 Redshift Serverless 工作群組所需的 IAM API 操作。 您也可以建立自己的 IAM 政策，以允許存取特定資源。若要建立您的政策，請使用 `AmazonRedshiftDataFullAccess` 政策作為起始範本。建立政策後，將它新增給每一位需要資料 API 存取的使用者。 請考量與使用者相關聯之 IAM 政策的下列要求： + 如果您使用 AWS Secrets Manager 進行身分驗證，請確認政策允許使用 `secretsmanager:GetSecretValue`動作來擷取以金鑰 標記的秘密`RedshiftDataFullAccess`。 + 如果您使用暫時憑證對叢集進行身分驗證，請確認政策允許對叢集中任何資料庫的資料庫使用者名稱 `redshift_data_api_user` 使用 `redshift:GetClusterCredentials` 動作。此使用者名稱必須已建立在資料庫中。 + 如果您使用暫時憑證向無伺服器工作群組進行身分驗證，請確認政策允許使用 `redshift-serverless:GetCredentials` 動作來擷取以索引鍵 `RedshiftDataFullAccess` 標記的工作群組。資料庫使用者會以 1：1 映射至 source AWS Identity and Access Management (IAM) 身分。例如，使用者 sample\$1user 會映射至資料庫使用者 `IAM:sample_user`，而 IAM 角色 sample\$1role 會映射至 `IAMR:sample_role`。如需 IAM 身分的相關資訊，請參閱《IAM 使用者指南》中的 [IAM 身分 (使用者、使用者群組和角色)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html)。 + IAM 動作 `redshift-data:GetStatementResult` 允許存取 `GetStatementResult` 和 `GetStatementResultV2` API 操作。 下列連結提供 *IAM 使用者指南* AWS Identity and Access Management 中有關 的詳細資訊。 + 如需有關建立 IAM 角色的資訊，請參閱[建立 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)。 + 如需有關建立 IAM 政策的資訊，請參閱[建立 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)。 + 如需有關將 IAM 政策新增給使用者的資訊，請參閱[新增和移除 IAM 身分許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。 ## 在另一個帳戶擁有的叢集上執行查詢 若要在另一個帳戶擁有的叢集上執行查詢，擁有端帳戶必須提供資料 API 可在呼叫端帳戶中擔任的 IAM 角色。例如，假設帳戶 B 擁有帳戶 A 需要存取的叢集。帳戶 B 可將 AWS 受管政策連接至`AmazonRedshiftDataFullAccess`帳戶 B 的 IAM 角色。然後，帳戶 B 會使用信任政策來信任帳戶 A，如下所示：`` ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:role/someRoleA" ] }, "Action": "sts:AssumeRole" } ] } ``` ------ 最後，帳戶 A 的 IAM 角色必須能夠擔任帳戶 B 的 IAM 角色。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::111122223333:role/someRoleB" } } ``` ------ ## 指定 IAM 角色，將資源限制在 中的 Redshift Serverless 工作群組和 Amazon Redshift 叢集 AWS 帳戶 您可以在身分型政策中指定資源 ARN，以控制對 AWS 帳戶中 Redshift Serverless 工作群組和 Amazon Redshift 叢集的存取。此範例示範如何建立政策，以便僅允許所指定 AWS 帳戶中的工作群組和叢集存取資料 API。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "redshift-data:CancelStatement", "redshift-data:DescribeStatement", "redshift-data:GetStatementResult", "redshift-data:ListStatements" ], "Resource": "*" }, { "Effect": "Allow", "Action": "redshift-data:*", "Resource": [ "arn:aws:redshift:us-east-1:111122223333:workgroup/*", "arn:aws:redshift:us-east-1:111122223333:cluster:*" ] } ] } ``` ------ ## 設定 IAM 政策，以限制只有陳述式擁有者能夠存取 SQL 陳述式資訊 根據預設，Amazon Redshift 資料 API 會將呼叫 `ExecuteStatement` 和 `BatchExecuteStatement` 時使用的 IAM 角色視為 SQL 陳述式的擁有者。允許擔任該角色的任何人都可以存取 SQL 陳述式的相關資訊，包括其結果。若要限制只有特定擁有者的 IAM 角色工作階段才能存取 SQL 陳述式資訊，請新增條件 `redshift-data:statement-owner-iam-userid: "${aws:userid}"`。下列 IAM 政策會限制存取權。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "redshift-data:CancelStatement", "redshift-data:DescribeStatement", "redshift-data:GetStatementResult", "redshift-data:ListStatements" ], "Resource": "*", "Condition": { "StringEquals": { "redshift-data:statement-owner-iam-userid": "${aws:userid}" } } } ] } ``` ------ 您可以使用條件 `statement-owner-iam-userid` 搭配 `CancelStatement`、`DescribeStatement`、`GetStatementResult` 和 `ListStatements`。如需詳細資訊，請參閱 [Amazon Redshift 資料 API 定義的動作](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid)。 ## 設定 IAM 政策以限制只有工作階段擁有者才能存取 SQL 結果 根據預設，Amazon Redshift 資料 API 會將呼叫 `ExecuteStatement` 和 `BatchExecuteStatement` 時使用的 IAM 角色，視為執行 SQL 陳述式的資料庫工作階段的擁有者。允許擔任該角色的任何人都可以將查詢提交至資料庫工作階段。若要限制只有特定擁有者的 IAM 角色工作階段才能存取，請新增條件 ` redshift-data:session-owner-iam-userid: "${aws:userid}"`。下列 IAM 政策會限制存取權。 下列 IAM 政策僅允許工作階段擁有者取得陳述式結果。條件 `session-owner-iam-userid` 可用來限制只有指定的 `userid` 可存取資源。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "redshift-data:ExecuteStatement", "redshift-data:BatchExecuteStatement" ], "Resource": "*", "Condition": { "StringEquals": { "redshift-data:session-owner-iam-userid": "${aws:userid}" } } } ] } ``` ------ 您可以使用條件 `session-owner-iam-userid` 搭配 `ExecuteStatement` 和 `BatchExecuteStatement`。如需詳細資訊，請參閱 [Amazon Redshift 資料 API 定義的動作](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid)。 # 在 中存放資料庫登入資料 AWS Secrets Manager 當您呼叫資料 API 時，您可以透過在 AWS Secrets Manager中使用機密來傳遞叢集或無伺服器工作群組的憑證。若要這樣傳遞登入資料，請指定秘密的名稱或秘密的 Amazon Resource Name (ARN)。 若要使用 Secrets Manager 來儲存憑證，您需要 `SecretManagerReadWrite` 受管政策許可。如需最低許可的詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[使用 Secrets Manager 建立和管理 AWS 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)。 **將憑證儲存在 Amazon Redshift 叢集的機密中** 1. 使用 AWS Secrets Manager 主控台建立包含叢集登入資料的秘密： + 當您選擇**儲存新的機密**時，請選擇 **Redshift 叢集的憑證**。 + 將**使用者名稱** (資料庫使用者)、**密碼**和**資料庫叢集** (叢集識別碼) 的值儲存在機密中。 + 使用索引鍵 `RedshiftDataFullAccess` 標記機密。 AWS 受管政策`AmazonRedshiftDataFullAccess`僅允許`secretsmanager:GetSecretValue`以金鑰 標記的秘密執行 動作`RedshiftDataFullAccess`。 如需說明，請參閱《AWS Secrets Manager 使用者指南》**中的[建立基本秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html)。 1. 使用 AWS Secrets Manager 主控台來檢視您建立之秘密的詳細資訊，或執行 `aws secretsmanager describe-secret` AWS CLI 命令。 記下秘密的名稱和 ARN。您可以在呼叫資料 API 時使用這些資料。 **將憑證儲存在無伺服器工作群組的機密中** 1. 使用 AWS Secrets Manager AWS CLI 命令來存放包含無伺服器工作群組登入資料的秘密： + 在檔案中建立您的秘密，例如名為 `mycreds.json` 的 JSON 檔案。在檔案中提供**使用者名稱** (資料庫使用者) 和**密碼**的值。 ``` { "username": "myusername", "password": "mypassword" } ``` + 將值儲存在機密中，並使用索引鍵 `RedshiftDataFullAccess` 標記機密。 ``` aws secretsmanager create-secret --name MyRedshiftSecret --tags Key="RedshiftDataFullAccess",Value="serverless" --secret-string file://mycreds.json ``` 以下將顯示輸出。 ``` { "ARN": "arn:aws:secretsmanager:region:accountId:secret:MyRedshiftSecret-mvLHxf", "Name": "MyRedshiftSecret", "VersionId": "a1603925-e8ea-4739-9ae9-e509eEXAMPLE" } ``` 如需詳細資訊，請參閱《AWS Secrets Manager 使用者指南》**中的[使用 AWS CLI建立基本機密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html#proc-create-api)。 1. 使用 AWS Secrets Manager 主控台來檢視您建立之秘密的詳細資訊，或執行 `aws secretsmanager describe-secret` AWS CLI 命令。 記下秘密的名稱和 ARN。您可以在呼叫資料 API 時使用這些資料。 # 建立資料 API 的 Amazon VPC 端點 (AWS PrivateLink) Amazon Virtual Private Cloud (Amazon VPC) 可讓您在虛擬私有雲端 (VPC) 中安全地啟動 AWS 資源，例如 AWS Amazon Redshift 叢集和應用程式。 在虛擬私有雲端 (VPCs) 和服務之間 AWS PrivateLink 提供私有連線。您可以使用 AWS PrivateLink建立 VPC 端點，以根據 Amazon VPC 連接到不同帳戶和 VPCs 的服務。如需詳細資訊 AWS PrivateLink，請參閱《*Amazon Virtual Private Cloud 使用者指南*》中的 [VPC 端點服務 (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html)。 您可以使用 Amazon VPC 端點呼叫資料 API。使用 Amazon VPC 端點可使 Amazon VPC 中的應用程式與資料 API 中的流量保持在 AWS 網路，而不使用公有 IP 地址。Amazon VPC 端點能協助您符合與限制公有網際網路連線相關的合規和法律需求。舉例來說，若使用 Amazon VPC 端點，就能讓在 Amazon EC2 執行個體上執行之應用程式和資料 API 的流量，只在包含兩者的 VPC 中傳送。 建立 Amazon VPC 端點之後就能開始使用，而不需要在應用程式中進行任何程式碼或組態變更。 **建立資料 API 的 Amazon VPC 端點** 1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)：// 開啟 Amazon VPC 主控台。 1. 選擇 **Endpoints (端點)**，然後選擇 **Create Endpoint (建立端點)**。 1. 在 **Create Endpoint** (建立端點) 頁面上，針對 **Service category** (服務類別) 選擇 **AWS services** ( 服務)。針對**服務名稱**，選擇 **redshift-data** (`com.amazonaws.region.redshift-data`)。 1. 針對 **VPC**，選擇要在其中建立端點的 VPC。 選擇包含進行資料 API 呼叫之應用程式的 VPC。 1. 針對**子網路**，選擇執行您應用程式之 AWS 服務所使用的每個可用區域 (AZ) 的子網路。 若要建立 Amazon VPC 端點，請指定可存取端點的私有 IP 地址範圍。若要執行此作業，請選擇每個可用區域的子網路。這麼做會將 VPC 端點限制為每個可用區域專屬的私有 IP 地址範圍，並且也會在每個可用區域中建立 Amazon VPC 端點。 1. 針對 **Enable DNS name (啟用 DNS 名稱)**，選取 **Enable for this endpoint (為此端點啟用)**。 私有 DNS 會將標準資料 API DNS 主機名稱 (`https://redshift-data.region.amazonaws.com`) 解析為與您 Amazon VPC 端點專用 DNS 主機名稱相關的私有 IP 地址。因此，您可以使用 AWS CLI AWS SDKs存取資料 API VPC 端點，而不需要進行任何程式碼或組態變更來更新資料 API 端點 URL。 1. 針對 **Security group (安全群組)**，選擇要與 Amazon VPC 端點建立關聯的安全群組。 選擇允許存取執行您應用程式之 AWS 服務的安全群組。舉例來說，若有 Amazon EC2 執行個體在執行您的應用程式，請選擇要允許存取 Amazon EC2 執行個體的安全群組。安全群組能讓您控制 VPC 中，資源流向 Amazon VPC 端點的流量。 1. 選擇**建立端點**。 建立端點之後，請選擇 中的連結 AWS 管理主控台 以檢視端點詳細資訊。 端點 **Details (詳細資訊)** 標籤會顯示建立 Amazon VPC 端點時產生的 DNS 主機名稱。 您可以使用標準端點 (`redshift-data.region.amazonaws.com`) 或其中一個 VPC 專用端點，來在 Amazon VPC 中呼叫資料 API。標準資料 API 端點會自動路由至 Amazon VPC 端點。因為私有 DNS 主機名稱在 Amazon VPC 端點建立時已啟用，所以會發生此路由。 當您在資料 API 呼叫中使用 Amazon VPC 端點時，應用程式與資料 API 間的所有流量都會維持在包含兩者的 Amazon VPC 中。您可以使用 Amazon VPC 端點進行任何類型的資料 API 呼叫。如需呼叫資料 API 的詳細資訊，請參閱[呼叫 Amazon Redshift 資料 API 時的考量](data-api.md#data-api-calling-considerations)。 # 連線到叢集時加入資料庫群組 資料庫群組是資料庫使用者的集合。您可以向群組授予資料庫權限。管理員可以設定 IAM 角色，以便在使用資料 API 執行 SQL 時將這些資料庫群組納入考量。如需資料庫群組的相關資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的[群組](https://docs.aws.amazon.com/redshift/latest/dg/r_Groups.html)。 您可以設定資料 API 呼叫者的 IAM 角色，以便在資料 API 連線到叢集時，呼叫中指定的資料庫使用者會加入資料庫群組。只有在連線至已佈建的叢集時才支援此功能。連線至 Redshift Serverless 工作群組時則不支援。資料 API 呼叫者的 IAM 角色也必須允許 `redshift:JoinGroup` 動作。 請透過向 IAM 角色新增標籤來進行此設定。呼叫者 IAM 角色的管理員會新增標籤，標籤中包含資料庫群組清單的索引鍵 `RedshiftDbGroups` 和索引鍵值。此值是以冒號 (:) 分隔的資料庫群組名稱清單，總長度最多可有 256 個字元。您必須之前就已在連線的資料庫中定義好資料庫群組。如果在資料庫中找不到任何指定的群組，則會忽略該群組。例如，對於資料庫群組 `accounting` 和 `retail`，索引鍵-值為 `accounting:retail`。資料 API 會使用標籤索引鍵-值組 `{"Key":"RedshiftDbGroups","Value":"accounting:retail"}` 來判斷在呼叫資料 API 時，哪些資料庫群組會與所提供的資料庫使用者相關聯。 **聯結資料庫群組** 1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 IAM 主控台。 1. 在主控台導覽窗格中，選擇 **Roles** (角色)，然後選擇您要編輯的角色名稱。 1. 選擇**標籤**索引標籤，然後選擇**管理標籤**。 1. 選擇**新增標籤**，然後新增 **RedshiftDbGroups** 索引鍵和值 (此為 *database-groups-colon-separated* 清單)。 1. 選擇**儲存變更**。 現在，當 IAM 主體 (附加了此 IAM 角色) 呼叫資料 API 時，指定的資料庫使用者便會加入 IAM 角色中指定的資料庫群組。 如需如何將標籤附加到主體 (包括 IAM 角色和 IAM 使用者) 的相關資訊，請參閱《IAM 使用者指南》**中的[標記 IAM 資源](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html)。 # 使用資料 API 搭配可信身分傳播 身為 Amazon Redshift 帳戶管理員，您可以將 Amazon Redshift 叢集或工作群組與 整合 AWS IAM Identity Center，這有助於透過單一登入來管理對 Amazon Redshift 的人力資源存取。如需詳細資訊，請參閱[設定與 AWS Amazon Redshift 的 IAM Identity Center 整合](redshift-iam-access-control-idp-connect-console.md)。Amazon Redshift Data API 支援將 IAM Identity Center 使用者身分傳播到 Amazon Redshift 叢集或工作群組，以及其他服務 AWS Lake Formation，例如鏈結下。您可以依照[使用受信任身分傳播以程式設計方式存取 AWS 服務](https://aws.amazon.com/blogs//security/access-aws-services-programmatically-using-trusted-identity-propagation/)中的步驟，使用資料 API 來設定和查詢。 當您使用來自身分增強型 IAM 角色工作階段的 IAM Identity Center 使用者身分呼叫資料 API 時，您只能存取使用相同 IAM Identity Center 使用者產生的陳述式和陳述式結果。例如，下列 AWS CLI 命令會呼叫 `execute-statement`操作，以執行具有信任身分傳播的 SQL 命令。 ``` aws redshift-data execute-statement --sql "select current_user;" --cluster-id mycluster --database dev ``` 下列 AWS CLI 命令會呼叫 `batch-execute-statement`操作來執行兩個 SQL 命令。 ``` aws redshift-data batch-execute-statement --sqls "select current_user;" "select current_date;" --cluster-id mycluster --database dev ``` 若要存取由身分增強型 IAM 角色工作階段所提交具有 `cancel-statement`、`describe-statement`、`get-statement-result` 和 `get-statement-result-v2` 的陳述式，IAM Identity Center 使用者和 IAM 角色必須符合用於執行 `execute-statment` 或 `batch-execute-statement` 的憑證。例如，下列 AWS CLI 命令會取得 SQL 陳述式的結果。 ``` aws redshift-data get-statement-result --id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 ``` 若要列出陳述式，則必須提供 `cluster-identifier` 或 `workgroup-name` 參數，以確保 IAM Identity Center 使用者只能存取指派給他們的 Amazon Redshift IAM Identity Center 應用程式。例如，下列 AWS CLI 命令會列出特定叢集的陳述式。 ``` aws redshift-data list-statements --cluster-identifier mycluster ``` 您也可以調用資料 API 操作，以使用可信身分傳播來存取叢集或工作群組中的資料庫物件。這包括 `list-databases`、`list-schemas`、`list-tables` 和 `describe-table` 操作。 IAM Identity Center 使用者發出的 API 呼叫可以在 AWS CloudTrail中追蹤。CloudTrail 事件的 `onBehalfOf` 區段會顯示 IAM Identity Center 使用者 ID 和身分存放區 ARN。下列範例示範 CloudTrail 事件的程式碼片段，顯示 `onBehalfOf` 區段中包含 IAM Identity Center 使用者 ID `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111` 和身分存放區 ARN `arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2`。 ``` { "eventVersion":"1.10", "userIdentity":{ "type":"AssumedRole", ... }, "onBehalfOf":{ "userId":"a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "identityStoreArn":"arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2" } }, "eventTime":"2025-01-13T04:46:27Z", "eventSource":"redshift-data.amazonaws.com", "eventName":"ExecuteStatement", "awsRegion":"us-east-1" } ``` 您可以執行下列 SQL 命令來檢查 IAM Identity Center 使用者提交的查詢。在此範例中，Identity Center 中註冊的電子郵件為 `username@example.com`。 ``` SELECT h.query_id, h.database_name, h.status, h.query_text, u.usename, h.start_time, h.end_time FROM sys_query_history h LEFT JOIN pg_user u ON h.user_id = u.usesysid where u.usename='awsidc:username@example.com' ORDER BY h.start_time DESC; ``` # 呼叫資料 API 您可以呼叫資料 API 或 AWS CLI ，在您的叢集或無伺服器工作群組上執行 SQL 陳述式。在《Amazon Redshift 資料 API 參考》**中，用來執行 SQL 陳述式的主要操作是 [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html) 和 [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html)。資料 API 支援 AWS SDK 支援的程式設計語言。如需這些語言的相關資訊，請參閱[用來在 AWS上進行建置的工具](https://aws.amazon.com/tools/)。 若要查看呼叫資料 API 的程式碼範例，請參閱 *GitHub* 中的[開始使用 Redshift 資料 API](https://github.com/aws-samples/getting-started-with-amazon-redshift-data-api#getting-started-with-redshift-data-api)。此儲存庫具有使用 從 Amazon EC2 AWS Glue Data Catalog和 Amazon SageMaker 執行期 AWS Lambda 存取 Amazon Redshift 資料的範例。範例程式設計語言包括 Python、Go、Java 和 Javascript。 您可以使用 AWS CLI呼叫資料 API。 下列範例使用 AWS CLI 呼叫資料 API。若要執行範例，請編輯參數值以符合您的環境。許多範例會提供 `cluster-identifier` 來針對叢集執行。當您針對無伺服器工作群組執行時，請改為提供 `workgroup-name`。這些範例會示範一些資料 API 操作。如需詳細資訊，請參閱 *AWS CLI 命令參考*。 下列範例中的命令已經過分割和格式化，以方便您閱讀。並非所有參數和回應都會在所有範例中顯示。如需完整請求語法、請求參數、回應語法和回應元素的 API 定義，請參閱 [Amazon Redshift 資料 API 參考](https://docs.aws.amazon.com/redshift-data/latest/APIReference/)。 # 將 SQL 陳述式傳遞至 Amazon Redshift 資料倉儲 本頁中的範例涵蓋將 SQL 陳述式傳遞至資料倉儲的不同方式 ## 執行 SQL 陳述式 若要執行 SQL 陳述式，請使用 `aws redshift-data execute-statement` AWS CLI 命令。 下列 AWS CLI 命令會對叢集執行 SQL 陳述式，並傳回識別符以擷取結果。此範例會使用 AWS Secrets Manager 身分驗證方法。 ``` 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 ``` 以下是回應的範例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598323175.823, "Database": "dev", "Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814", "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn" } ``` 下列 AWS CLI 命令會對叢集執行 SQL 陳述式，並傳回識別符以擷取結果。此範例使用暫時憑證身分驗證方法。 ``` aws redshift-data execute-statement --db-user myuser --cluster-identifier mycluster-test --database dev --sql "select * from stl_query limit 1" ``` 以下是回應的範例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598306924.632, "Database": "dev", "DbUser": "myuser", "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766" } ``` 下列 AWS CLI 命令會對無伺服器工作群組執行 SQL 陳述式，並傳回識別符以擷取結果。此範例使用暫時憑證身分驗證方法。 ``` aws redshift-data execute-statement --database dev --workgroup-name myworkgroup --sql "select 1;" ``` 以下是回應的範例。 ``` { "CreatedAt": "2022-02-11T06:25:28.748000+00:00", "Database": "dev", "DbUser": "IAMR:RoleName", "Id": "89dd91f5-2d43-43d3-8461-f33aa093c41e", "WorkgroupName": "myworkgroup" } ``` 下列 AWS CLI 命令會對叢集執行 SQL 陳述式，並傳回識別符以擷取結果。此範例會使用 AWS Secrets Manager 身分驗證方法和等冪性字符。 ``` 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 ``` 以下是回應的範例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598323175.823, "Database": "dev", "Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814", "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn" } ``` ## 執行含有參數的 SQL 陳述式 若要執行 SQL 陳述式，請使用 `aws redshift-data execute-statement` AWS CLI 命令。 下列 AWS CLI 命令會對叢集執行 SQL 陳述式，並傳回識別符以擷取結果。此範例會使用 AWS Secrets Manager 身分驗證方法。SQL 文字有具名參數 `distance`。在此案例中，述詞中使用的距離是 `5`。在 SELECT 陳述式中，資料欄名稱的具名參數只能在述詞中使用。SQL 陳述式的具名參數值會於 `parameters` 選項中指定。 ``` aws redshift-data execute-statement --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --sql "SELECT ratecode FROM demo_table WHERE trip_distance > :distance" --parameters "[{\"name\": \"distance\", \"value\": \"5\"}]" --database dev ``` 以下是回應的範例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598323175.823, "Database": "dev", "Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814", "SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn" } ``` 下列範例會使用來自範例資料庫的 `EVENT` 資料表。如需詳細資訊，請參閱《Amazon Redshift 資料庫開發人員指南》**中的 [EVENT 資料表](https://docs.aws.amazon.com/redshift/latest/dg/r_eventtable.html)。 如果資料庫中還沒有 `EVENT` 資料表，您可以使用資料 API 加以建立，如下所示： ``` aws redshift-data execute-statement --database dev --cluster-id mycluster-test --db-user awsuser --sql "create table event( eventid integer not null distkey, venueid smallint not null, catid smallint not null, dateid smallint not null sortkey, eventname varchar(200), starttime timestamp)" ``` 下列命令會在 `EVENT` 資料表中插入一個資料列。 ``` aws redshift-data execute-statement --database dev --cluster-id mycluster-test --db-user awsuser --sql "insert into event values(:eventid, :venueid::smallint, :catid, :dateid, :eventname, :starttime)" --parameters "[{\"name\": \"eventid\", \"value\": \"1\"}, {\"name\": \"venueid\", \"value\": \"1\"}, {\"name\": \"catid\", \"value\": \"1\"}, {\"name\": \"dateid\", \"value\": \"1\"}, {\"name\": \"eventname\", \"value\": \"event 1\"}, {\"name\": \"starttime\", \"value\": \"2022-02-22\"}]" ``` 下列命令會在 `EVENT` 資料表中插入第二個資料列。此範例示範下列操作： + 名為 `id` 的參數會在 SQL 文字中使用四次。 + 在插入參數 `starttime` 時會自動套用隱含類型轉換。 + `venueid` 資料欄是轉換為 SMALLINT 資料類型的類型。 + 代表 DATE 資料類型的字元字串會隱含地轉換成 TIMESTAMP 資料類型。 + 您可以在 SQL 文字中使用註解。 ``` aws redshift-data execute-statement --database dev --cluster-id mycluster-test --db-user awsuser --sql "insert into event values(:id, :id::smallint, :id, :id, :eventname, :starttime) /*this is comment, and it won't apply parameterization for :id, :eventname or :starttime here*/" --parameters "[{\"name\": \"eventname\", \"value\": \"event 2\"}, {\"name\": \"starttime\", \"value\": \"2022-02-22\"}, {\"name\": \"id\", \"value\": \"2\"}]" ``` 下列範例顯示所插入的兩個資料列： ``` eventid | venueid | catid | dateid | eventname | starttime ---------+---------+-------+--------+-----------+--------------------- 1 | 1 | 1 | 1 | event 1 | 2022-02-22 00:00:00 2 | 2 | 2 | 2 | event 2 | 2022-02-22 00:00:00 ``` 下列命令會在 WHERE 子句中使用具名參數來擷取 `eventid` 是 `1` 的資料列。 ``` aws redshift-data execute-statement --database dev --cluster-id mycluster-test --db-user awsuser --sql "select * from event where eventid=:id" --parameters "[{\"name\": \"id\", \"value\": \"1\"}]" ``` 執行下列命令以取得上一個 SQL 陳述式的 SQL 結果： ``` aws redshift-data get-statement-result --id 7529ad05-b905-4d71-9ec6-8b333836eb5a ``` 提供下列結果： ``` { "Records": [ [ { "longValue": 1 }, { "longValue": 1 }, { "longValue": 1 }, { "longValue": 1 }, { "stringValue": "event 1" }, { "stringValue": "2022-02-22 00:00:00.0" } ] ], "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "eventid", "length": 0, "name": "eventid", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "venueid", "length": 0, "name": "venueid", "nullable": 0, "precision": 5, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int2" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "catid", "length": 0, "name": "catid", "nullable": 0, "precision": 5, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int2" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "dateid", "length": 0, "name": "dateid", "nullable": 0, "precision": 5, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "int2" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "eventname", "length": 0, "name": "eventname", "nullable": 1, "precision": 200, "scale": 0, "schemaName": "public", "tableName": "event", "typeName": "varchar" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "label": "starttime", "length": 0, "name": "starttime", "nullable": 1, "precision": 29, "scale": 6, "schemaName": "public", "tableName": "event", "typeName": "timestamp" } ], "TotalNumRows": 1 } ``` ## 執行多個 SQL 陳述式 若要使用一個命令執行多個 SQL 陳述式，請使用 `aws redshift-data batch-execute-statement` AWS CLI 命令。 下列 AWS CLI 命令會對叢集執行三個 SQL 陳述式，並傳回識別符來擷取結果。此範例使用暫時憑證身分驗證方法。 ``` aws redshift-data batch-execute-statement --db-user myuser --cluster-identifier mycluster-test --database dev --sqls "set timezone to BST" "select * from mytable" "select * from another_table" ``` 以下是回應的範例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598306924.632, "Database": "dev", "DbUser": "myuser", "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766" } ``` # 列出有關 SQL 陳述式的中繼資料 若要列出 SQL 陳述式的中繼資料，請使用 `aws redshift-data list-statements` AWS CLI 命令。執行此命令的授權取決於呼叫者的 IAM 許可。 下列 AWS CLI 命令會列出執行的 SQL 陳述式。 ``` aws redshift-data list-statements --status ALL ``` 以下是回應的範例。 ``` { "Statements": [ { "CreatedAt": 1598306924.632, "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766", "QueryString": "select * from stl_query limit 1", "Status": "FINISHED", "UpdatedAt": 1598306926.667 }, { "CreatedAt": 1598311717.437, "Id": "e0ebd578-58b3-46cc-8e52-8163fd7e01aa", "QueryString": "select * from stl_query limit 1", "Status": "FAILED", "UpdatedAt": 1598311719.008 }, { "CreatedAt": 1598313683.65, "Id": "c361d4f7-8c53-4343-8c45-6b2b1166330c", "QueryString": "select * from stl_query limit 1", "Status": "ABORTED", "UpdatedAt": 1598313685.495 }, { "CreatedAt": 1598306653.333, "Id": "a512b7bd-98c7-45d5-985b-a715f3cfde7f", "QueryString": "select 1", "Status": "FINISHED", "UpdatedAt": 1598306653.992 } ] } ``` # 描述有關 SQL 陳述式的中繼資料 若要取得 SQL 陳述式中繼資料的說明，請使用 `aws redshift-data describe-statement` AWS CLI 命令。執行此命令的授權取決於呼叫者的 IAM 許可。 下列 AWS CLI 命令說明 SQL 陳述式。 ``` aws redshift-data describe-statement --id d9b6c0c9-0747-4bf4-b142-e8883122f766 ``` 以下是回應的範例。 ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": 1598306924.632, "Duration": 1095981511, "Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766", "QueryString": "select * from stl_query limit 1", "RedshiftPid": 20859, "RedshiftQueryId": 48879, "ResultRows": 1, "ResultSize": 4489, "Status": "FINISHED", "UpdatedAt": 1598306926.667 } ``` 以下是在執行含有多個 SQL 陳述式的 `batch-execute-statement` 命令後的 `describe-statement` 回應範例。 ``` { "ClusterIdentifier": "mayo", "CreatedAt": 1623979777.126, "Duration": 6591877, "HasResultSet": true, "Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652", "RedshiftPid": 31459, "RedshiftQueryId": 0, "ResultRows": 2, "ResultSize": 22, "Status": "FINISHED", "SubStatements": [ { "CreatedAt": 1623979777.274, "Duration": 3396637, "HasResultSet": true, "Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:1", "QueryString": "select 1;", "RedshiftQueryId": -1, "ResultRows": 1, "ResultSize": 11, "Status": "FINISHED", "UpdatedAt": 1623979777.903 }, { "CreatedAt": 1623979777.274, "Duration": 3195240, "HasResultSet": true, "Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2", "QueryString": "select 2;", "RedshiftQueryId": -1, "ResultRows": 1, "ResultSize": 11, "Status": "FINISHED", "UpdatedAt": 1623979778.076 } ], "UpdatedAt": 1623979778.183 } ``` # 擷取 SQL 陳述式的結果 若要從執行的 SQL 陳述式擷取結果，請使用 `redshift-data get-statement-result`或 `redshift-data get-statement-result-v2` AWS CLI 命令。來自 `get-statement-result` 的結果為 JSON 格式。來自 `get-statement-result-v2` 的結果為 CSV 格式。您可以提供所收到的 `Id` 以回應 `execute-statement` 或 `batch-execute-statement`。由 `batch-execute-statement` 執行的 SQL 陳述式的 `Id` 值可以在 `describe-statement` 的結果中擷取，並且會加上由冒號和序號組成的字尾 (例如 `b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2`)。如果您使用 `batch-execute-statement` 執行多個 SQL 陳述式，則每個 SQL 陳述式都會有一個 `Id` 值，如 `describe-statement` 中所示。執行此命令的授權取決於呼叫者的 IAM 許可。 下列陳述式會傳回由 `ResultFormat` 預設為 `JSON` 的 `execute-statement` 所執行 SQL 陳述式的結果。若要擷取結果，請呼叫 `get-statement-result` 操作。 ``` aws redshift-data get-statement-result --id d9b6c0c9-0747-4bf4-b142-e8883122f766 ``` 下列陳述式會傳回由 `batch-execute-statement` 執行的第二個 SQL 陳述式的結果。 ``` aws redshift-data get-statement-result --id b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2 ``` 以下是呼叫 `get-statement-result` 的回應範例，其中 SQL 結果會在回應的 `Records` 索引鍵中以 JSON 格式傳回。 ``` { "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "userid", "length": 0, "name": "userid", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "query", "length": 0, "name": "query", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "label", "length": 0, "name": "label", "nullable": 0, "precision": 320, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "bpchar" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "xid", "length": 0, "name": "xid", "nullable": 0, "precision": 19, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int8" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "pid", "length": 0, "name": "pid", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "database", "length": 0, "name": "database", "nullable": 0, "precision": 32, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "bpchar" }, { "isCaseSensitive": true, "isCurrency": false, "isSigned": false, "label": "querytxt", "length": 0, "name": "querytxt", "nullable": 0, "precision": 4000, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "bpchar" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "label": "starttime", "length": 0, "name": "starttime", "nullable": 0, "precision": 29, "scale": 6, "schemaName": "", "tableName": "stll_query", "typeName": "timestamp" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "label": "endtime", "length": 0, "name": "endtime", "nullable": 0, "precision": 29, "scale": 6, "schemaName": "", "tableName": "stll_query", "type": 93, "typeName": "timestamp" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "aborted", "length": 0, "name": "aborted", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "insert_pristine", "length": 0, "name": "insert_pristine", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "concurrency_scaling_status", "length": 0, "name": "concurrency_scaling_status", "nullable": 0, "precision": 10, "scale": 0, "schemaName": "", "tableName": "stll_query", "typeName": "int4" } ], "Records": [ [ { "longValue": 1 }, { "longValue": 3 }, { "stringValue": "health" }, { "longValue": 1023 }, { "longValue": 15279 }, { "stringValue": "dev" }, { "stringValue": "select system_status from stv_gui_status;" }, { "stringValue": "2020-08-21 17:33:51.88712" }, { "stringValue": "2020-08-21 17:33:52.974306" }, { "longValue": 0 }, { "longValue": 0 }, { "longValue": 6 } ] ], "TotalNumRows": 1 } ``` 下列範例顯示 `execute-statement` 執行的 SQL 陳述式，且傳回的結果為 JSON 格式。資料表 `testingtable` 有三個整數欄 (col1、col2、col3)，而且有三列的值 (1、2、3)、(4、5、6) 和 (7、8、9)。 ``` aws redshift-data execute-statement --database dev --sql "SELECT col1, col2, col3 FROM testingtable" --cluster-id mycluster-test --result-format JSON ``` ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": "2024-04-02T16:45:25.144000+00:00", "Database": "dev", "DbUser": "IAMR:Administrator", "Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3" } ``` 以下是呼叫 `get-statement-result` 的回應範例，其中 SQL 結果會在回應的 `Records` 索引鍵中以 JSON 格式傳回。 ``` aws redshift-data get-statement-result --id d468d942-6df9-4f85-8ae3-bac01a61aec3 ``` ``` { "Records": [ [ { "longValue": 1 }, { "longValue": 2 }, { "longValue": 3 } ], [ { "longValue": 4 }, { "longValue": 5 }, { "longValue": 6 } ], [ { "longValue": 7 }, { "longValue": 8 }, { "longValue": 9 } ] ], "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col1", "name": "col1", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col2", "name": "col2", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col3", "name": "col3", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 } ], "TotalNumRows": 3 } ``` 下列範例顯示 `execute-statement` 執行的 SQL 陳述式，且傳回的結果為 CSV 格式。資料表 `testingtable` 有三個整數欄 (col1、col2、col3)，而且有三列的值 (1、2、3)、(4、5、6) 和 (7、8、9)。 ``` aws redshift-data execute-statement --database dev --sql "SELECT col1, col2, col3 FROM testingtable" --cluster-id mycluster-test --result-format CSV ``` ``` { "ClusterIdentifier": "mycluster-test", "CreatedAt": "2024-04-02T16:45:25.144000+00:00", "Database": "dev", "DbUser": "IAMR:Administrator", "Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3" } ``` 以下是呼叫 `get-statement-result-v2` 的回應範例，其中 SQL 結果會在回應的 `Records` 索引鍵中以 CSV 格式傳回。資料列會以換行和新行 (\$1r\$1n) 符號分隔。`Records` 中傳回的第一列為欄標頭。以 CSV 格式傳回的結果會以 1 MB 為單位傳回，且每個區塊可以儲存最大 1MB 的任意列數。 ``` aws redshift-data get-statement-result-v2 --id d468d942-6df9-4f85-8ae3-bac01a61aec3 ``` ``` { "Records": [ { "CSVRecords": "col1,col2,col3\r\n1,2,3\r\n4,5,6\r\n7,8,9\r\n" } ], "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col1", "name": "col1", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col2", "name": "col2", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "col3", "name": "col3", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "public", "tableName": "testingtable", "typeName": "int4", "length": 0 } ], "TotalNumRows": 3, "ResultFormat": "csv" } ``` # 描述資料表 若要取得描述資料表的中繼資料，請使用 `aws redshift-data describe-table` AWS CLI 命令。 下列 AWS CLI 命令會對叢集執行 SQL 陳述式，並傳回描述資料表的中繼資料。此範例使用 AWS Secrets Manager 身分驗證方法。 ``` aws redshift-data describe-table --cluster-identifier mycluster-test --database dev --schema information_schema --table sql_features --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn ``` 以下是回應的範例。 ``` { "ColumnList": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_id", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_name", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" } ] } ``` 下列 AWS CLI 命令會對描述資料表的叢集執行 SQL 陳述式。此範例使用暫時憑證身分驗證方法。 ``` aws redshift-data describe-table --db-user myuser --cluster-identifier mycluster-test --database dev --schema information_schema --table sql_features ``` 以下是回應的範例。 ``` { "ColumnList": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_id", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "feature_name", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "sub_feature_id", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "sub_feature_name", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "is_supported", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "is_verified_by", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": false, "length": 2147483647, "name": "comments", "nullable": 1, "precision": 2147483647, "scale": 0, "schemaName": "information_schema", "tableName": "sql_features", "typeName": "character_data" } ] } ``` # 列出叢集中的資料庫 若要列出叢集中的資料庫，請使用 `aws redshift-data list-databases` AWS CLI 命令。 下列 AWS CLI 命令會對叢集執行 SQL 陳述式，以列出資料庫。此範例使用 AWS Secrets Manager 身分驗證方法。 ``` aws redshift-data list-databases --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --database dev ``` 以下是回應的範例。 ``` { "Databases": [ "dev" ] } ``` 下列 AWS CLI 命令會對叢集執行 SQL 陳述式，以列出資料庫。此範例使用暫時憑證身分驗證方法。 ``` aws redshift-data list-databases --db-user myuser --cluster-identifier mycluster-test --database dev ``` 以下是回應的範例。 ``` { "Databases": [ "dev" ] } ``` # 列出資料庫中的結構描述 若要列出資料庫中的結構描述，請使用 `aws redshift-data list-schemas` AWS CLI 命令。 下列 AWS CLI 命令會對叢集執行 SQL 陳述式，以列出資料庫中的結構描述。此範例使用 AWS Secrets Manager 身分驗證方法。 ``` aws redshift-data list-schemas --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --database dev ``` 以下是回應的範例。 ``` { "Schemas": [ "information_schema", "pg_catalog", "pg_internal", "public" ] } ``` 下列 AWS CLI 命令會對叢集執行 SQL 陳述式，以列出資料庫中的結構描述。此範例使用暫時憑證身分驗證方法。 ``` aws redshift-data list-schemas --db-user mysuser --cluster-identifier mycluster-test --database dev ``` 以下是回應的範例。 ``` { "Schemas": [ "information_schema", "pg_catalog", "pg_internal", "public" ] } ``` # 列出資料庫中的資料表 若要列出資料庫中的資料表，請使用 `aws redshift-data list-tables` AWS CLI 命令。 下列 AWS CLI 命令會對叢集執行 SQL 陳述式，以列出資料庫中的資料表。此範例使用 AWS Secrets Manager 身分驗證方法。 ``` aws redshift-data list-tables --secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn --cluster-identifier mycluster-test --database dev --schema information_schema ``` 以下是回應的範例。 ``` { "Tables": [ { "name": "sql_features", "schema": "information_schema", "type": "SYSTEM TABLE" }, { "name": "sql_implementation_info", "schema": "information_schema", "type": "SYSTEM TABLE" } } ``` 下列 AWS CLI 命令會對叢集執行 SQL 陳述式，以列出資料庫中的資料表。此範例使用暫時憑證身分驗證方法。 ``` aws redshift-data list-tables --db-user myuser --cluster-identifier mycluster-test --database dev --schema information_schema ``` 以下是回應的範例。 ``` { "Tables": [ { "name": "sql_features", "schema": "information_schema", "type": "SYSTEM TABLE" }, { "name": "sql_implementation_info", "schema": "information_schema", "type": "SYSTEM TABLE" } ] } ``` # 針對 Amazon Redshift 資料 API 的問題進行故障診斷 請使用下列標題包含常見錯誤訊息的章節，協助針對您在使用資料 API 時所發生的問題進行故障診斷。 **Topics** + [查詢封包過大](#data-api-troubleshooting-packet-too-large) + [資料庫回應超過大小上限](#data-api-troubleshooting-response-size-too-large) ## 查詢封包過大 如果您看到錯誤，內容指出查詢的封包太大，這一般是因為針對資料列傳回的結果集太大。針對資料庫傳回結果集中的每個資料列，資料 API 的大小上限為每個資料列 64 KB。 若要解決此問題，請確定結果集的每個資料列都是 64 KB 或更小。 ## 資料庫回應超過大小上限 如果您看到錯誤，內容指出資料庫回應超過大小限制，這一般是因為資料庫傳回的結果集大小太大。資料庫傳回的結果集中的資料 API 限制為 500 MB。 若要解決此問題，請確保對資料 API 的呼叫傳回 500 MB 或更少的資料。如果您需要傳回超過 500 MB，您可以使用查詢中的 `LIMIT`子句執行多個陳述式呼叫。 # 使用 Amazon EventBridge 來排程 Amazon Redshift 資料 API 操作 您可以建立會比對所選事件並將其路由到目標以採取行動的規則。您也可以使用規則對預定的排程採取行動。如需詳細資訊，請參閱[「Amazon EventBridge 使用者指南」](https://docs.aws.amazon.com/eventbridge/latest/userguide/)。 若要使用 EventBridge 來排程資料 API 操作，相關聯的 IAM 角色必須信任 CloudWatch Events 的主體 (events.amazonaws.com)。此角色應該要有已附加之受管政策 `AmazonEventBridgeFullAccess` 的對等項目。其也應該要有由資料 API 管理的 `AmazonRedshiftDataFullAccess` 政策許可。您可以在 IAM 主控台上使用這些許可建立 IAM 角色。在 IAM 主控台上建立角色時，請選擇 CloudWatch Events AWS 的服務信任實體。在 EventBridge 目標的 `RoleArn` JSON 值中指定 IAM 角色。如需建立 IAM 角色的詳細資訊，請參閱《*IAM 使用者指南*》中的[為 AWS 服務建立角色 （主控台）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console)。 您在 Amazon EventBridge 中所建立規則的 `name` 必須符合 `RedshiftDataParameters` 中的 `StatementName`。 下列範例顯示使用單一或多個 SQL 陳述式，以及使用 Amazon Redshift 叢集或 Amazon Redshift Serverless 工作群組作為資料倉儲來建立 EventBridge 規則的各種變化。 ## 使用單一 SQL 陳述式和叢集來進行呼叫 下列範例使用 AWS CLI 建立 EventBridge 規則，用於對 Amazon Redshift 叢集執行 SQL 陳述式。 ``` aws events put-rule --name test-redshift-cluster-data --schedule-expression "rate(1 minute)" ``` 然後，會建立 EventBridge 目標以便依照規則中指定的排程來執行。 ``` aws events put-targets --cli-input-json file://data.json ``` data.json 輸入檔案如下。`Sql` JSON 索引鍵表示有單一 SQL 陳述式。`Arn` JSON 值包含叢集識別碼。`RoleArn` JSON 值包含用來執行 SQL 的 IAM 角色，如先前所述。 ``` { "Rule": "test-redshift-cluster-data", "EventBusName": "default", "Targets": [ { "Id": "2", "Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster", "RoleArn": "arn:aws:iam::123456789012:role/Administrator", "RedshiftDataParameters": { "Database": "dev", "DbUser": "root", "Sql": "select 1;", "StatementName": "test-redshift-cluster-data", "WithEvent": true } } ] } ``` ## 使用單一 SQL 陳述式和工作群組來進行呼叫 下列範例使用 AWS CLI 建立 EventBridge 規則，用於對 Amazon Redshift Serverless 工作群組執行 SQL 陳述式。 ``` aws events put-rule --name test-redshift-serverless-workgroup-data --schedule-expression "rate(1 minute)" ``` 然後，會建立 EventBridge 目標以便依照規則中指定的排程來執行。 ``` aws events put-targets --cli-input-json file://data.json ``` data.json 輸入檔案如下。`Sql` JSON 索引鍵表示有單一 SQL 陳述式。`Arn` JSON 值包含工作群組名稱。`RoleArn` JSON 值包含用來執行 SQL 的 IAM 角色，如先前所述。 ``` { "Rule": "test-redshift-serverless-workgroup-data", "EventBusName": "default", "Targets": [ { "Id": "2", "Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "RoleArn": "arn:aws:iam::123456789012:role/Administrator", "RedshiftDataParameters": { "Database": "dev", "Sql": "select 1;", "StatementName": "test-redshift-serverless-workgroup-data", "WithEvent": true } } ] } ``` ## 使用多個 SQL 陳述式和叢集進行呼叫 下列範例使用 AWS CLI 建立 EventBridge 規則，用於對 Amazon Redshift 叢集執行多個 SQL 陳述式。 ``` aws events put-rule --name test-redshift-cluster-data --schedule-expression "rate(1 minute)" ``` 然後，會建立 EventBridge 目標以便依照規則中指定的排程來執行。 ``` aws events put-targets --cli-input-json file://data.json ``` data.json 輸入檔案如下。`Sqls` JSON 索引鍵表示有多個 SQL 陳述式。`Arn` JSON 值包含叢集識別碼。`RoleArn` JSON 值包含用來執行 SQL 的 IAM 角色，如先前所述。 ``` { "Rule": "test-redshift-cluster-data", "EventBusName": "default", "Targets": [ { "Id": "2", "Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster", "RoleArn": "arn:aws:iam::123456789012:role/Administrator", "RedshiftDataParameters": { "Database": "dev", "Sqls": ["select 1;", "select 2;", "select 3;"], "StatementName": "test-redshift-cluster-data", "WithEvent": true } } ] } ``` ## 使用多個 SQL 陳述式和工作群組進行呼叫 下列範例使用 AWS CLI 建立 EventBridge 規則，用於對 Amazon Redshift Serverless 工作群組執行多個 SQL 陳述式。 ``` aws events put-rule --name test-redshift-serverless-workgroup-data --schedule-expression "rate(1 minute)" ``` 然後，會建立 EventBridge 目標以便依照規則中指定的排程來執行。 ``` aws events put-targets --cli-input-json file://data.json ``` data.json 輸入檔案如下。`Sqls` JSON 索引鍵表示有多個 SQL 陳述式。`Arn` JSON 值包含工作群組名稱。`RoleArn` JSON 值包含用來執行 SQL 的 IAM 角色，如先前所述。 ``` { "Rule": "test-redshift-serverless-workgroup-data", "EventBusName": "default", "Targets": [ { "Id": "2", "Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "RoleArn": "arn:aws:iam::123456789012:role/Administrator", "RedshiftDataParameters": { "Database": "dev", "Sqls": ["select 1;", "select 2;", "select 3;"], "StatementName": "test-redshift-serverless-workgroup-data", "WithEvent": true } } ] } ``` # 監控資料 API 監控是維護資料 API 和其他 AWS 解決方案的可靠性、可用性和效能的重要部分。 AWS 提供下列監控工具來監看資料 API、在發生錯誤時回報，以及適時採取自動動作： + Amazon EventBridge 可用來自動化您的 AWS 服務，並自動回應系統事件，例如應用程式可用性問題或資源變更。來自 AWS 服務的事件會以近乎即時的方式交付至 EventBridge。您可編寫簡單的規則，來指示您在意的事件，以及當事件符合規則時所要自動執行的動作。如需詳細資訊，請參閱[「Amazon EventBridge 使用者指南」](https://docs.aws.amazon.com/eventbridge/latest/userguide/)。 + AWS CloudTrail 會擷取由您的帳戶或代表 AWS 您的帳戶發出的 API 呼叫和相關事件，並將日誌檔案交付至您指定的 Amazon S3 儲存貯體。您可以識別呼叫的使用者和帳戶 AWS、進行呼叫的來源 IP 地址，以及呼叫的時間。若要進一步了解 Amazon Redshift 如何與 整合 AWS CloudTrail，請參閱[使用 CloudTrail 記錄](https://docs.aws.amazon.com/redshift/latest/mgmt/logging-with-cloudtrail.html)。如需 CloudTrail 的相關資訊，請參閱《[AWS CloudTrail 使用者指南](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)》。 **Topics** + [在 Amazon EventBridge 中監控 Amazon Redshift 資料 API 的事件](data-api-monitoring-events.md) # 在 Amazon EventBridge 中監控 Amazon Redshift 資料 API 的事件 EventBridge 會從您自己的應用程式、軟體即服務 (SaaS) 應用程式和 AWS 服務提供即時資料串流，因此您可以在 EventBridge 中監控資料 API 事件。EventBridge 會將該資料路由到目標，例如 AWS Lambda 和 Amazon SNS。這些事件與 CloudWatch Events 中出現的事件相同，可提供近乎即時的系統事件串流，說明 AWS 資源的變更。事件會傳送至包含 Amazon Redshift 資料庫的帳戶。例如，如果您在另一個帳戶中擔任某個角色，事件便會傳送至該帳戶。如需詳細資訊，請參閱《Amazon EventBridge 使用者指南》**中的 [Amazon EventBridge 事件](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html)。 當 `ExecuteStatement` 或 `BatchExecuteStatement` API 操作將 `WithEvent` 選項設定為 `true` 時，系統就會傳送資料 API 事件。事件的 `state` 欄位會包含下列其中一個值： + 已中止 — 使用者已停止執行查詢。 + 失敗 — 查詢執行失敗。 + 已完成 — 查詢已執行完成。 系統保證會提供事件。如需詳細資訊，請參閱《*Amazon EventBridge 使用者指南*》中的[來自 AWS 服務的事件](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html)。 ## 資料 API 的已完成事件範例 下列範例顯示當 `ExecuteStatement` API 操作完成時的資料 API 事件。在此範例中，名為 `test.testtable` 的陳述式已執行完成。 ``` { "version": "0", "id": "18e7079c-dd4b-dd64-caf9-e2a31640dab0", "detail-type": "Redshift Data Statement Status Change", "source": "aws.redshift-data", "account": "123456789012", "time": "2020-10-01T21:14:26Z", "region": "us-east-1", "resources": [ "arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster-1" ], "detail": { "principal": "arn:aws:iam::123456789012:user/myuser", "statementName": "test.testtable", "statementId": "dd2e1ec9-2ee3-49a0-819f-905fa7d75a4a", "redshiftQueryId": -1, "state": "FINISHED", "rows": 1, "expireAt": 1601673265 } } ``` # AWS KMS 搭配 Amazon Redshift 資料 API 使用 當您使用客戶受管金鑰加密 Amazon Redshift 叢集或 Redshift Serverless 工作群組時，Amazon Redshift Data API 會使用相同的客戶受管金鑰來存放和加密您的查詢和結果。 資料 API 預設會加密您的資料，以保護敏感資訊，例如查詢文字和查詢結果。它會針對此保護使用 擁有 AWS 的 AWS KMS 加密金鑰。 當您保護敏感資料時，靜態資料的預設加密可減少操作開銷和複雜性。此方法可協助您建置符合嚴格加密合規和法規要求的安全應用程式。 ## 在 中使用授予 AWS KMS 資料 API 需要授予才能使用客戶受管金鑰。 當您`BatchExecuteStatement`針對使用客戶受管金鑰加密的叢集呼叫 `ExecuteStatement`或 時，Amazon Redshift 會透過傳送[https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)請求至 來代表您建立授予 AWS KMS。 AWS KMS 使用授予來授予資料 API 存取您帳戶中的 KMS 金鑰。 資料 API 需要授予 ，才能將客戶受管金鑰用於下列操作： + 傳送[https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html)請求至 AWS KMS ，以使用客戶受管金鑰加密查詢中繼資料。 + 傳送[https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)請求至 AWS KMS ，以產生由客戶受管金鑰加密的資料金鑰。 + 將[https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)請求傳送至 AWS KMS 以解密加密的資料金鑰，以便他們可以加密您的資料。 您可以隨時撤銷授予的存取權，或移除客戶受管金鑰的 Amazon Redshift 存取權。如果您這麼做，資料 API 就無法再存取客戶受管金鑰加密的資料，這會影響依賴該資料的操作。例如，如果您在撤銷授予後嘗試擷取查詢結果或追蹤查詢狀態，資料 API 會傳回 `AccessDeniedException`。 ## 客戶受管金鑰的金鑰政策 金鑰政策會控制客戶受管金鑰的存取權限。每個客戶受管金鑰都必須只有一個金鑰政策，其中包含決定誰可以使用金鑰及其使用方式的陳述式。在建立客戶受管金鑰時，可以指定金鑰政策。如需更多資訊，請參閱 *AWS Key Management Service 開發人員指南*中的[客戶受管金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-mgn-key)。 若要搭配資料 API 使用客戶受管金鑰，您必須先允許存取 Amazon Redshift。金鑰政策中必須允許下列 API 操作： + `kms:CreateGrant`：新增客戶受管金鑰的授權。授予控制對指定 AWS KMS 金鑰的存取，允許存取 Amazon Redshift 所需的授予操作。如需詳細資訊，請參閱[在 中使用授予 AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations)。 以下是金鑰政策範例： ``` "Statement":[ { "Sid":"Allow access to principals authorized to use Amazon Redshift", "Effect":"Allow", "Principal":{ "AWS":"*" }, "Action":[ "kms:DescribeKey", "kms:CreateGrant" ], "Resource":"*", "Condition":{ "StringEquals":{ "kms:ViaService":"redshift.amazonaws.com", "kms:CallerAccount":"111122223333" } } }, { "Sid":"AllowKeyAdministratorsAccess", "Effect":"Allow", "Principal":{ "AWS":"arn:aws:iam::111122223333:role/ExampleAdminRole" }, "Action":"kms:*", "Resource":"*" }, { "Sid":"AllowKeyUseForExampleRole", "Effect":"Allow", "Principal":{ "AWS":"arn:aws:iam::111122223333:role/ExampleUserRole" }, "Action":[ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource":"*" } ] ``` ## 資料 API 加密內容 加密內容是選用的一組金鑰/值對，其中包含有關資料的其他內容資訊。 AWS KMS 會使用加密內容作為額外的已驗證資料，以支援已驗證的加密。當您在加密資料的請求中包含加密內容時， 會將加密內容 AWS KMS 繫結至加密的資料。若要解密資料，您必須在請求中包含相同的加密內容。 資料 API 在所有已佈建叢集 AWS KMS 的密碼編譯操作中使用相同的三個加密內容金鑰/值對： + `aws:redshift:arn` – 叢集的 Amazon Resource Name (ARN) + `aws:redshift:createtime` – 您請求建立叢集時的時間戳記 + `serviceName` – `RedshiftDataAPI` ``` "EncryptionContextSubset": { "aws:redshift:arn": "arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster", "aws:redshift:createtime": "20250815T0000Z", "serviceName": "RedshiftDataAPI", } ``` 資料 API 在所有 AWS KMS 無伺服器工作群組的密碼編譯操作中使用兩個加密內容金鑰/值對： + `aws:redshift-serverless:arn` – 命名空間的 Amazon Resource Name (ARN) + `serviceName` – RedshiftDataAPI ``` "EncryptionContextSubset": { "aws:redshift-serverless:arn": "arn:aws:redshift-serverless:us-east-1:123456789012:namespace:12345678-1234-1234-1234-123456789012", "serviceName": "RedshiftDataAPI" } ``` 如需加密的詳細資訊，請參閱 [的密碼編譯詳細資訊簡介 AWS KMS](https://docs.aws.amazon.com/kms/latest/cryptographic-details/intro.html)。如需 Amazon Redshift 和 AWS KMS 整合的詳細資訊，請參閱 [Amazon Redshift 如何使用 AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/services-redshift.html)。 # 使用 Amazon Sagemaker Unified Studio 在 Amazon Redshift 和 SageMaker Lakehouse 中查詢資料庫 Amazon SageMaker Unified Studio 提供主控台外開發環境，並支援對 SageMaker Lakehouse、Amazon Redshift 和適用於 SQL 分析的 Amazon Athena 中的資料進行 SQL 分析。使用管理員的 URL 導覽至 Amazon SageMaker Unified Studio，並使用 SSO 或 AWS 登入資料登入。如需設定第一個專案的詳細資訊，請參閱《Amazon SageMaker Unified Studio 使用者指南》**中的[入門](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/getting-started.html)。 在 Amazon SageMaker Unified Studio 中，您可以使用[查詢編輯器](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/query-editor-navigate.html)執行 Amazon Redshift 和 Amazon Athena 來進行 [SQL 分析](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/sql-query.html)。使用查詢編輯器編寫和執行查詢、檢視結果，並與您的團隊共用您的工作。針對您 中的 Redshift 資料倉儲執行查詢 AWS 帳戶 （在相同 帳戶內和跨其他 AWS 帳戶)、使用相同界面為 Redshift 和 Athena 建置 SQL 查詢，並使用 Amazon Managed Workflows for Apache Airflow 排程 SQL 查詢。您也可以使用 Amazon Q 生成式 SQL 從自然語言生成 SQL。