本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 ODBC 和 JDBC 驅動器連接至 Amazon Athena
為了使用商業智慧工具探索您的資料並加以和視覺化，請下載、安裝並設定 ODBC (開放資料庫連線) 或 JDBC (Java 資料庫連線) 驅動程式。
**Topics**
+ [使用 JDBC 連接到 Athena](connect-with-jdbc.md)
+ [使用 ODBC 連接到 Athena](connect-with-odbc.md)
+ [搭配使用可信身分傳播與驅動器](using-trusted-identity-propagation.md)
另請參閱下列 AWS 知識中心和 AWS 大數據部落格主題：
+ [使用 JDBC 驅動程式連接至 Athena 時，如何使用 IAM 角色憑證或切換至其他 IAM 角色？](https://aws.amazon.com/premiumsupport/knowledge-center/athena-iam-jdbc-driver/)
+ [設定 ADFS 與 之間的信任 AWS ，以及使用 Active Directory 登入資料透過 ODBC 驅動程式連線至 Amazon Athena ](https://aws.amazon.com/blogs/big-data/setting-up-trust-between-adfs-and-aws-and-using-active-directory-credentials-to-connect-to-amazon-athena-with-odbc-driver/)
# 使用 JDBC 連接到 Amazon Athena
Amazon Athena 提供兩個 JDBC 驅動程式：版本 2.x 和 3.x。Athena JDBC 3.x 驅動器是新一代的驅動器，可提供更好的效能和相容性。JDBC 3.x 驅動器支援直接從 Amazon S3 讀取查詢結果，從而可提升應用程式的效能，其中這些應用程式會耗用大量查詢結果。新的驅動器降低了第三方相依性，因此可以更輕鬆地整合 BI 工具與自訂應用程式。在大多數情況下，您可以使用新的驅動器，無需變更現有組態或只需進行最少的變更。
+ 若要下載 JDBC 3.x 驅動程式，請參閱 [Athena JDBC 3.x 驅動程式](jdbc-v3-driver.md)。
+ 若要下載 JDBC 2.x 驅動程式，請參閱 [Athena JDBC 2.x 驅動程式](jdbc-v2.md)。
**Topics**
+ [Athena JDBC 3.x 驅動程式](jdbc-v3-driver.md)
+ [Athena JDBC 2.x 驅動程式](jdbc-v2.md)
# Athena JDBC 3.x 驅動程式
您可以從許多第三方 SQL 用戶端工具和自訂應用程式使用 Athena ODBC 驅動程式連接至 Amazon Athena。
## 系統要求
+ Java 8 (或更高版本) 執行期環境
+ 至少 20 MB 的可用磁碟空間
## 考量和限制
以下是 Athena JDBC 3.x 驅動程式的一些考量與限制。
+ **記錄日誌** – 3.x 驅動程式使用 [SLF4J](https://www.slf4j.org/manual.html)，這是可在執行期啟用數個記錄日誌系統其中之一的抽象層。
+ **加密** – 搭配使用 Amazon S3 擷取程式與 `CSE_KMS` 加密選項時，Amazon S3 用戶端無法解密存放於 Amazon S3 儲存貯體中的結果。如果您需要 `CSE_KMS` 加密，則可以繼續使用串流擷取程式。已計劃支援搭配使用 `CSE_KMS` 加密與 Amazon S3 擷取程式。
## JDBC 3.x 驅動程式下載
本節包含 JDBC 3.x 驅動程式的下載和授權資訊。
**重要**
當您使用 JDBC 3.x 驅動程式時，務必注意以下要求：
**打開連接埠 444** – 將 Athena 用來串流查詢結果的連接埠 444 保持開放給輸出流量。當您使用 PrivateLink 端點連接到 Athena 時，請確定連接至 PrivateLink 端點的安全群組已在連接埠 444 上開放給輸入流量。
**athena:GetQueryResultsStream 政策** – 新增針對使用 JDBC 驅動程式的 IAM 主體的 `athena:GetQueryResultsStream` 政策動作。此政策動作不會直接透過 API 公開。它僅與 ODBC 和 JDBC 驅動程式搭配使用，做為串流結果支援的一部分。如需政策範例，請參閱 [AWS 受管政策：AWSQuicksightAthenaAccess](security-iam-awsmanpol.md#awsquicksightathenaaccess-managed-policy)。
若要下載 Amazon Athena 3.x JDBC 驅動程式，請造訪以下連結。
### JDBC 驅動程式 uber jar
下面的下載將驅動程式及其所有相依性包在同一個 `.jar` 檔案中。此下載通常用於第三方 SQL 用戶端。
[3.7.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.7.0/athena-jdbc-3.7.0-with-dependencies.jar)
### JDBC 驅動程式 lean jar
下面的下載是一個 `.zip` 檔案，其中包含驅動程式的 lean `.jar` 和驅動程式相依性的單獨 `.jar` 檔案。此下載通常用於可能具有相依性與驅動程式使用的相依性衝突的自訂應用程式。如果您想選擇要包含在 lean jar 中的驅動程式相依性，以及要排除的驅動程式相依性 (如果您的自訂應用程式已包含一或多個驅動程式相依性)，則此下載非常有用。
[3.7.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.7.0/athena-jdbc-3.7.0-lean-jar-and-separate-dependencies-jars.zip)
### 授權
下列連結包含 JDBC 3.x 驅動程式的授權合約。
[授權](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.7.0/LICENSE.txt)
## 可信身分傳播與 JDBC
您現在可以透過 AWS Identity and Access Management Identity Center 使用具有單一登入功能的 JDBC 驅動程式連線至 Amazon Athena。當您從 PowerBI、Tableau 或 DBeaver 等工具存取 Athena 時，您的身分和許可會透過 IAM Identity Center 自動傳播到 Athena。如需詳細資訊，請參閱[搭配使用可信身分傳播與 Amazon Athena 驅動器](using-trusted-identity-propagation.md)。
**Topics**
+ [系統要求](#jdbc-v3-driver-system-requirements)
+ [考量和限制](#jdbc-v3-driver-considerations-and-limitations)
+ [JDBC 3.x 驅動程式下載](#jdbc-v3-driver-download)
+ [可信身分傳播與 JDBC](#jdbc-v3-driver-trusted-identity)
+ [JDBC 3.x 驅動器入門](jdbc-v3-driver-getting-started.md)
+ [Amazon Athena JDBC 3.x 連線參數](jdbc-v3-driver-connection-parameters.md)
+ [其他 JDBC 3.x 組態](jdbc-v3-driver-other-configuration.md)
+ [Amazon Athena JDBC 3.x 版本備註](jdbc-v3-driver-release-notes.md)
+ [舊版 Athena JDBC 3.x 驅動器](jdbc-v3-driver-previous-versions.md)
# JDBC 3.x 驅動器入門
使用本節中的資訊，開始使用 Amazon Athena JDBC 3.x 驅動程式。
**Topics**
+ [安裝說明](#jdbc-v3-driver-installation-instructions)
+ [執行驅動程式](#jdbc-v3-driver-running-the-driver)
+ [設定驅動程式](#jdbc-v3-driver-configuring-the-driver)
+ [從 Athena JDBC v2 驅動程式升級](#jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3)
## 安裝說明
您可以在自訂應用程式或第三方 SQL 用戶端中，使用 JDBC 3.x 驅動程式。
### 在自訂應用程式中
下載包含驅動程式 jar 及其相依性的 `.zip` 檔案。每個相依性都有自己的 `.jar` 檔案。在自訂應用程式中新增驅動程式 jar 作為相依性。根據您是否已經從另一個來源新增這些相依性至應用程式中，選擇性地新增驅動程式 jar 的相依性。
### 在第三方 SQL 用戶端中
下載驅動程式 uber jar 檔案，並依照該用戶端的指示將其新增至第三方 SQL 用戶端。
## 執行驅動程式
若要執行驅動程式，您可以使用自訂應用程式或第三方 SQL 用戶端。
### 在自訂應用程式中
使用 JDBC 介面與程式的 JDBC 驅動程式進行互動。下列程式碼顯示了一個自訂 Java 應用程式範例。
```
public static void main(String args[]) throws SQLException {
Properties connectionParameters = new Properties();
connectionParameters.setProperty("Workgroup", "primary");
connectionParameters.setProperty("Region", "us-east-2");
connectionParameters.setProperty("Catalog", "AwsDataCatalog");
connectionParameters.setProperty("Database","sampledatabase");
connectionParameters.setProperty("OutputLocation","s3://amzn-s3-demo-bucket");
connectionParameters.setProperty("CredentialsProvider","DefaultChain");
String url = "jdbc:athena://";
AthenaDriver driver = new AthenaDriver();
Connection connection = driver.connect(url, connectionParameters);
Statement statement = connection.createStatement();
String query = "SELECT * from sample_table LIMIT 10";
ResultSet resultSet = statement.executeQuery(query);
printResults(resultSet); // A custom-defined method for iterating over a
// result set and printing its contents
}
```
### 在第三方 SQL 用戶端中
遵循您所使用之 SQL 用戶端的文件。一般而言，您可以使用 SQL 用戶端的圖形化使用者介面來輸入及提交查詢，而查詢結果會顯示在相同的介面中。
## 設定驅動程式
您可以使用連線參數來設定 Amazon Athena JDBC 驅動程式。如需支援的連線參數，請參閱 [Amazon Athena JDBC 3.x 連線參數](jdbc-v3-driver-connection-parameters.md)。
### 在自訂應用程式中
若要在自訂應用程式中設定 JDBC 驅動程式的連線參數，請執行下列其中一個動作：
+ 將參數名稱及其值新增至 `Properties` 物件。當您呼叫 `Connection#connect` 時，將該物件與 URL 一起傳遞。如需範例，請參閱 [執行驅動程式](#jdbc-v3-driver-running-the-driver) 中的 Java 範例應用程式。
+ 在連線字串 (URL) 中，使用下列格式將參數名稱及其值直接新增至通訊協定字首之後。
```
=;
```
在每個參數名稱/參數值配對的末尾使用分號，分號後不留空格，如下列範例所示。
```
String url = "jdbc:athena://WorkGroup=primary;Region=us-east-1;...;";AthenaDriver driver = new AthenaDriver();Connection connection = driver.connect(url, null);
```
**注意**
如果在連線字串和 `Properties` 物件中同時指定參數，則連線字串中的值優先。不建議在兩個位置指定相同的參數。
+ 將參數值作為引數新增至 `AthenaDataSource` 的方法，如下列範例所示。
```
AthenaDataSource dataSource = new AthenaDataSource();
dataSource.setWorkGroup("primary");
dataSource.setRegion("us-east-2");
...
Connection connection = dataSource.getConnection();
...
```
### 在第三方 SQL 用戶端中
依照您所使用之 SQL 用戶端的指示進行。通常，用戶端會提供圖形化使用者介面來輸入參數名稱及其值。
## 從 Athena JDBC v2 驅動程式升級
大多數 JDBC 第 3 版驅動器連線參數都與 JDBC 驅動器第 2 版 (Simba) 回溯相容。這意味著第 2 版連線字串可以與第 3 版驅動程式重複使用。但是，某些連線參數已更改。此處會有這些變更的相關說明。如有必要，當您升級至 JDBC 驅動器第 3 版時，請更新現有的組態。
### 驅動程式類別
有些 BI 工具會要求您從 JDBC 驅動程式 `.jar` 檔案提供驅動程式類別。大多數工具都會自動尋找這個類別。第 3 版驅動程式中完全合格的類別名稱為 `com.amazon.athena.jdbc.AthenaDriver`。在第 2 版驅動程式中，該類別為 `com.simba.athena.jdbc.Driver`。
### 連接字串
第 3 版驅動器將 `jdbc:athena://` 用於 JDBC 連線字串 URL 開頭的通訊協定。第 3 版驅動器還支援第 2 版通訊協定 `jdbc:awsathena://`，但第 2 版通訊協定已廢除。為了避免出現未定義的行為，如果第 2 版 (或接受以 `jdbc:awsathena://` 為開頭的連線字串的任何其他驅動器) 已向 [DriverManager](https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html) 類別註冊，則第 3 版不接受以 `jdbc:awsathena://` 為開頭的連線字串。
### 憑證提供者
第 2 版驅動程式會使用完全合格的名稱來辨識不同的憑證提供者 (例如 `com.simba.athena.amazonaws.auth.DefaultAWSCredentialsProviderChain`)。第 3 版驅動程式則使用較短的名稱 (例如 `DefaultChain`)。新名稱會在每個憑證提供者的對應章節中說明。
為第 2 版驅動程式編寫的自訂憑證提供者需要修改第 3 版驅動程式，才能從新的 實作 [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) 介面， 適用於 Java 的 AWS SDK 而不是從先前的 [AWSCredentialsProvider](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html) 介面 適用於 Java 的 AWS SDK。
JDBC 3.x 驅動器不支援 `PropertiesFileCredentialsProvider`。提供者已在 JDBC 2.x 驅動程式中使用，但屬於舊版的適用於 Java 的 AWS SDK，即將終止支援。若要在 JDBC 3.x 驅動器中實現相同的功能，請改用 [AWS 組態設定檔登入資料](jdbc-v3-driver-aws-configuration-profile-credentials.md) 提供者。
### 日誌層級
下表顯示 JDBC 第 2 版和第 3 版驅動程式中的 `LogLevel` 參數差異。
****
| JDBC 驅動程式版本 | 參數名稱 | 參數類型 | 預設值 | 可能的值 | 連線字串範例 |
| --- | --- | --- | --- | --- | --- |
| v2 | LogLevel | 選用 | 0 | 0-6 | LogLevel=6; |
| v3 | LogLevel | 選用 | TRACE | OFF、ERROR、WARN、INFO、DEBUG、TRACE | LogLevel=INFO; |
### 查詢 ID 擷取
在第 2 版驅動程式中，您可以將 `Statement` 執行個體取消包裝至 `com.interfaces.core.IStatementQueryInfoProvider`，一個具有兩種方法 `#getPReparedQueryId` 和 `#getQueryId` 的介面。您可以使用這些方法來取得已執行之查詢的查詢執行 ID。
在第 3 版驅動程式中，您可以將 `Statement`、`PreparedStatement` 和 `ResultSet` 執行個體取消包裝至 `com.amazon.athena.jdbc.AthenaResultSet` 介面。該介面有一種方法：`#getQueryExecutionId`。
# Amazon Athena JDBC 3.x 連線參數
支援的連線參數在此分為三個區段：[基本連線參數](jdbc-v3-driver-basic-connection-parameters.md)、[進階連線參數](jdbc-v3-driver-advanced-connection-parameters.md) 和 [身分驗證連線參數](jdbc-v3-driver-authentication-connection-parameters.md)。「進階」連線參數和「身分驗證」連線參數區段都有將相關參數群組在一起的子區段。
**Topics**
+ [基本連線參數](jdbc-v3-driver-basic-connection-parameters.md)
+ [進階連線參數](jdbc-v3-driver-advanced-connection-parameters.md)
+ [身分驗證連線參數](jdbc-v3-driver-authentication-connection-parameters.md)
# 基本連線參數
下列各節說明 JDBC 3.x 驅動程式的基本連線參數。
## 區域
將執行查詢 AWS 區域 的 。如需區域清單，請參閱 [Amazon Athena 端點和配額](https://docs.aws.amazon.com/general/latest/gr/athena.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 區域 | AwsRegion (已廢除) | 強制性 (但如果未提供，將使用 [DefaultAwsRegionProviderChain](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/regions/providers/DefaultAwsRegionProviderChain.html) 進行搜尋) | 無 |
## 目錄
包含將透過驅動程式存取的資料庫和資料表的目錄。如需有關目錄的資訊，請參閱 [DataCatalog](https://docs.aws.amazon.com/athena/latest/APIReference/API_DataCatalog.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 目錄 | 無 | 選用 | AwsDataCatalog |
## 資料庫
將在其中執行查詢的資料庫。未明確限定資料庫名稱的資料表將解析至此資料庫。如需有關資料庫的資訊，請參閱[資料庫](https://docs.aws.amazon.com/athena/latest/APIReference/API_Database.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 資料庫 | 結構描述 | 選用 | 預設 |
## 工作群組
將在其中執行查詢的工作群組。如需有關工作群組的資訊，請參閱[工作群組](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| WorkGroup | 無 | 選用 | 主要 |
## 輸出位置
Amazon S3 中儲存查詢結果的位置。如需有關輸出位置的資訊，請參閱 [ResultConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| OutputLocation | S3OutputLocation (已廢除) | 強制性 (除非工作群組指定了輸出位置) | 無 |
# 進階連線參數
下列各節說明 JDBC 3.x 驅動程式的進階連線參數。
**Topics**
+ [結果加密參數](#jdbc-v3-driver-result-encryption-parameters)
+ [結果擷取參數](#jdbc-v3-driver-result-fetching-parameters)
+ [結果組態參數](#jdbc-v3-driver-result-config)
+ [查詢結果重複使用參數](#jdbc-v3-driver-query-result-reuse-parameters)
+ [查詢執行輪詢參數](#jdbc-v3-driver-query-execution-polling-parameters)
+ [端點覆寫參數](#jdbc-v3-driver-endpoint-override-parameters)
+ [代理組態參數](#jdbc-v3-driver-proxy-configuration-parameters)
+ [記錄日誌參數](#jdbc-v3-driver-logging-parameters)
+ [Application name (應用程式名稱)](#jdbc-v3-driver-application-name)
+ [連線測試](#jdbc-v3-driver-connection-test)
+ [重試次數](#jdbc-v3-driver-number-of-retries)
+ [網路逾時](#jdbc-v3-driver-networktimeoutmillis)
## 結果加密參數
請注意以下重點：
+ 金鑰 AWS KMS 必須在 `EncryptionOption`為 `SSE_KMS`或 時指定`CSE_KMS`。
+ `EncryptionOption` 若未指定 或 `EncryptionOption`為 ，則無法指定 AWS KMS 金鑰`SSE_S3`。
### 加密選項
查詢結果存放在 Amazon S3 時所使用的加密類型。如需有關查詢結果加密的資訊，請參閱《Amazon Athena API 參考》**中的 [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 可能的值 |
| --- | --- | --- | --- | --- |
| EncryptionOption | S3OutputEncOption (已廢除) | 選用 | 無 | SSE\$1S3、SSE\$1KMS、CSE\$1KMS |
### KMS 金鑰
如果選擇 `SSE_KMS` 或 `CSE_KMS` 做為加密選項，則為 KMS 金鑰 ARN 或 ID。如需詳細資訊，請參閱《Amazon Athena API 參考》**中的 [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| KmsKey | S3OutputEncKMSKey (已廢除) | 選用 | 無 |
## 結果擷取參數
### 結果擷取程式
將用於下載查詢結果的擷取程式。
預設的結果擷取程式 `auto` 會直接從 Amazon S3 下載查詢結果，而無需使用 Athena API。當無法直接下載 S3 時，例如使用 `CSE_KMS` 選項加密查詢結果時，其會自動回退至使用 `GetQueryResultsStream` API。
在大多數情況下，建議使用 `auto` 擷取程式。如果您的 IAM 政策或 S3 儲存貯體政策使用 [s3:CalledVia](security-iam-athena-calledvia.md) 條件來限制存取來自 Athena 的 S3 物件請求，則 `auto` 擷取程式會先嘗試從 S3 下載結果，然後回退至使用 `GetQueryResultsStream` API。在這種情況下，您可以將 ResultFetcher 設定為 `GetQueryResultsStream`，以避免額外的 API 呼叫。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 可能的值 |
| --- | --- | --- | --- | --- |
| ResultFetcher | 無 | 選用 | auto | auto、S3、GetQueryResults、GetQueryResultsStream |
### 擷取大小
這個參數的值用做內部緩衝區的最小值，以及擷取結果時的目標頁面大小。值 0 (零) 表示驅動程式應使用其預設值，如下所述。最大值為 1,000,000。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| FetchSize | RowsToFetchPerBlock (已廢除) | 選用 | 0 |
+ `GetQueryResults` 擷取程式一律會使用 1,000 的頁面大小，這是 API 呼叫所支援的最大值。當擷取大小大於 1,000 時，會進行多次連續的 API 呼叫，以填滿高於最小值的緩衝區。
+ `GetQueryResultsStream` 擷取程式會使用設定的擷取大小做為頁面大小，或依預設使用 10,000。
+ `S3` 擷取程式會使用設定的擷取大小做為頁面大小，或依預設使用 10,000。
## 結果組態參數
### Expected bucket owner (預期的儲存貯體擁有者)
預期的 S3 儲存貯體擁有者的帳戶 ID。如果您提供的帳戶 ID 與儲存貯體的實際擁有者不相符，則請求會失敗。如需有關驗證 s3 儲存貯體擁有者的詳細資訊，請參閱[驗證儲存貯體擁有權](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-owner-condition.html#bucket-owner-condition-use)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ExpectedBucketOwner | 無 | 選用 | 無 |
### Acl 選項
指出 Amazon S3 標準 ACL 應設定為控制儲存查詢結果的擁有權。如需有關 `AclOption` 的詳細資訊，請參閱 [AclConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_AclConfiguration.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 可能的值 |
| --- | --- | --- | --- | --- |
| AclOption | 無 | 選用 | 無 | BUCKET\$1OWNER\$1FULL\$1CONTROL |
## 查詢結果重複使用參數
### 啟用結果重複使用
指定執行查詢時是否可以重複使用同一查詢之前的結果。如需有關查詢結果重複使用的資訊，請參閱 [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| EnableResultReuseByAge | 無 | 選用 | FALSE |
### 結果重複使用最長期限
Athena 應考慮重複使用的之前查詢結果的最長期限 (以分鐘為單位)。如需有關結果重複使用最長期限的資訊，請參閱 [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| MaxResultReuseAgeInMinutes | 無 | 選用 | 60 |
## 查詢執行輪詢參數
### 最小查詢執行輪詢間隔
輪詢 Athena 的查詢執行狀態之前要等待的最短時間 (以毫秒為單位)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| MinQueryExecutionPollingIntervalMillis | MinQueryExecutionPollingInterval (已廢除) | 選用 | 100 |
### 最大查詢執行輪詢間隔
輪詢 Athena 的查詢執行狀態之前要等待的最長時間 (以毫秒為單位)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| MaxQueryExecutionPollingIntervalMillis | MaxQueryExecutionPollingInterval (已廢除) | 選用 | 5000 |
### 查詢執行輪詢間隔倍數
增加輪詢期間的因數。依預設，輪詢會以 `MinQueryExecutionPollingIntervalMillis` 的值開始，並且每次輪詢都會加倍，直至達到 `MaxQueryExecutionPollingIntervalMillis` 的值為止。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| QueryExecutionPollingIntervalMultiplier | 無 | 選用 | 2 |
## 端點覆寫參數
### Athena 端點覆寫
驅動程式將用來對 Athena 進行 API 呼叫的端點。
請注意以下重點：
+ 如果提供的 URL 中未指定 `https://` 或 `http://` 通訊協定，則驅動程式會插入 `https://` 字首。
+ 若沒有指定此參數，則驅動程式會使用預設端點。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AthenaEndpoint | EndpointOverride (已廢除) | 選用 | 無 |
### Athena 串流服務端點覆寫
當驅動程式使用 Athena 串流服務時，將用來下載查詢結果的端點。Athena 串流服務可在連接埠 444 上使用。
請注意以下重點：
+ 如果提供的 URL 中未指定 `https://` 或 `http://` 通訊協定，則驅動程式會插入 `https://` 字首。
+ 如果未在提供的 URL 中指定連接埠，則驅動程式會插入串流服務連接埠 444。
+ 如果未指定 `AthenaStreamingEndpoint` 參數，驅動程式會使用 `AthenaEndpoint` 覆寫。如果 `AthenaStreamingEndpoint` 或 `AthenaEndpoint` 覆寫均未指定，則驅動程式會使用預設的串流端點。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AthenaStreamingEndpoint | StreamingEndpointOverride (已廢除) | 選用 | 無 |
### LakeFormation 端點覆寫
驅動程式使用 AWS Lake Formation [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) API 擷取臨時憑證時，將用於 Lake Formation 服務的端點。若沒有指定此參數，則驅動程式會使用預設的 Lake Formation 端點。
請注意以下重點：
+ 如果提供的 URL 中未指定 `https://` 或 `http://` 通訊協定，則驅動程式會插入 `https://` 字首。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| LakeFormationEndpoint | LfEndpointOverride (已廢除) | 選用 | 無 |
### S3 端點覆寫
當驅動程式使用 Amazon S3 擷取程式時，將用來下載查詢結果的端點。若沒有指定此參數，則驅動程式會使用預設的 Amazon S3 端點。
請注意以下重點：
+ 如果提供的 URL 中未指定 `https://` 或 `http://` 通訊協定，則驅動程式會插入 `https://` 字首。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| S3Endpoint | 無 | 選用 | 無 |
### STS 端點覆寫
使用 AWS STS [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API 擷取臨時憑證時，驅動程式將用於 AWS STS 服務的端點。如果未指定此參數，驅動程式會使用預設 AWS STS 端點。
請注意以下重點：
+ 如果提供的 URL 中未指定 `https://` 或 `http://` 通訊協定，則驅動程式會插入 `https://` 字首。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| StsEndpoint | StsEndpointOverride (已廢除) | 選用 | 無 |
### SSO OIDC 端點覆寫
使用 `ClientConfiguration.endpointOverride` 覆寫 SSO OIDC 用戶端的預設 HTTP 端點時，驅動器將使用的端點。如需詳細資訊，請參閱 [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| SSOOIDCEndpointOverride | | 選用 | 無 |
### SSO 管理員端點覆寫
使用 `ClientConfiguration.endpointOverride` 覆寫 SSO 管理員用戶端的預設 HTTP 端點時，驅動器將使用的端點。如需詳細資訊，請參閱 [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| SSOAdminEndpointOverride | | 選用 | 無 |
## 代理組態參數
### 代理主機
代理主機的 URL。如果您需要 Athena 請求透過代理傳送，請使用此參數。
**注意**
確定在 `ProxyHost` 的 URL 開頭包含通訊協定 `https://` 或 `http://`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ProxyHost | 無 | 選用 | 無 |
### 代理連接埠
要在代理主機上使用的連接埠。如果您需要 Athena 請求透過代理傳送，請使用此參數。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ProxyPort | 無 | 選用 | 無 |
### 代理使用者名稱
在代理伺服器上進行身分驗證的使用者名稱。如果您需要 Athena 請求透過代理傳送，請使用此參數。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ProxyUsername | ProxyUID (已廢除) | 選用 | 無 |
### 代理密碼
在代理伺服器上進行身分驗證的密碼。如果您需要 Athena 請求透過代理傳送，請使用此參數。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ProxyPassword | ProxyPWD (已廢除) | 選用 | 無 |
### 免除代理的主機
啟用代理後 (也就是設定 `ProxyHost` 和 `ProxyPort` 連線參數後)，驅動程式在不使用代理的情況下連線到的一組主機名稱。主機應以縱線 (`|`) 字元分隔 (例如，`host1.com|host2.com`)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ProxyExemptHosts | NonProxyHosts | 選用 | 無 |
### 為身分提供者啟用代理
指定當驅動程式連線至身分提供者時，是否應使用代理。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ProxyEnabledForIdP | UseProxyForIdP | 選用 | FALSE |
## 記錄日誌參數
本節說明與記錄日誌相關的參數。
### 日誌層級
指定驅動程式記錄日誌的層級。除非還設定了 `LogPath` 參數，否則不會記錄任何內容。
**注意**
除非您有特殊需求，否則建議您僅設定 `LogPath` 參數。僅設定 `LogPath` 參數會啟用記錄日誌，並使用預設的 `TRACE` 日誌層級。`TRACE` 日誌層級會提供最詳細的記錄。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 可能的值 |
| --- | --- | --- | --- | --- |
| LogLevel | 無 | 選用 | TRACE | OFF、ERROR、WARN、INFO、DEBUG、TRACE |
### 日誌路徑
執行驅動程式的電腦上儲存驅動程式日誌的目錄路徑。將在指定的目錄中建立具有唯一名稱的日誌檔。如果設定，則啟用驅動程式記錄日誌。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| LogPath | 無 | 選用 | 無 |
## Application name (應用程式名稱)
使用驅動程式的應用程式的名稱。如果指定此參數的值，則該值會包含在驅動程式對 Athena 進行之 API 呼叫的使用者代理字串中。
**注意**
您也可以透過呼叫 `setApplicationName` 物件上的 `DataSource` 來設定應用程式名稱。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ApplicationName | 無 | 選用 | 無 |
## 連線測試
如果設定為 `TRUE`，則即使未在連線上執行查詢，驅動程式也會在每次建立 JDBC 連線時進行連線測試。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ConnectionTest | 無 | 選用 | TRUE |
**注意**
連線測試會將 `SELECT 1` 查詢提交至 Athena，以確認連線設定正確。這表示兩個檔案將儲存在 Amazon S3 中 (結果集和中繼資料)，而且可能會根據 [Amazon Athena 定價](https://aws.amazon.com/athena/pricing)政策收取額外費用。
## 重試次數
驅動程式將可重試請求重新傳送至 Athena 的次數上限。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| NumRetries | MaxErrorRetry (已廢除) | 選用 | 無 |
## 網路逾時
網路逾時可控制驅動器等待建立網路連線的時間量。這包括傳送 API 請求所需的時間。在極少數情況下，變更網路逾時可能會非常實用。例如，您可能想要增加長時間垃圾回收暫停的逾時。設定此連線參數等同於在 `Connection` 物件上使用 `setNetworkTimeout` 方法。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| NetworkTimeoutMillis | 無 | 選用 | 無 |
# 身分驗證連線參數
Athena JDBC 3.x 驅動程式支援多種身分驗證方法。所需的連線參數視您使用的身分驗證方法而定。
**Topics**
+ [IAM](jdbc-v3-driver-iam-credentials.md)
+ [預設](jdbc-v3-driver-default-credentials.md)
+ [AWS 組態設定檔](jdbc-v3-driver-aws-configuration-profile-credentials.md)
+ [執行個體設定檔](jdbc-v3-driver-instance-profile-credentials.md)
+ [Custom](jdbc-v3-driver-custom-credentials.md)
+ [JWT](jdbc-v3-driver-jwt-credentials.md)
+ [JWT 可信身分傳播](jdbc-v3-driver-jwt-tip-credentials.md)
+ [瀏覽器信任的身分傳播](jdbc-v3-driver-browser-oidc-tip-credentials.md)
+ [Azure AD](jdbc-v3-driver-azure-ad-credentials.md)
+ [Okta](jdbc-v3-driver-okta-credentials.md)
+ [Ping](jdbc-v3-driver-ping-credentials.md)
+ [AD FS](jdbc-v3-driver-adfs-credentials.md)
+ [瀏覽器 Azure AD](jdbc-v3-driver-browser-azure-ad-credentials.md)
+ [瀏覽器 SAML](jdbc-v3-driver-browser-saml-credentials.md)
+ [DataZone IdC](jdbc-v3-driver-datazone-idc.md)
+ [DataZone IAM](jdbc-v3-driver-datazone-iamcp.md)
# IAM 憑證
您可以將 IAM 憑證與 JDBC 驅動程式配合使用，透過設定以下連線參數連線至 Amazon Athena。
## 使用者
您的 AWS 存取金鑰 ID。如需有關存取金鑰的資訊，請參閱**《IAM 使用者指南》中的 [AWS 安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 使用者 | AccessKeyId | 必要 | 無 |
## 密碼
您的 AWS 私密金鑰 ID。如需有關存取金鑰的資訊，請參閱**《IAM 使用者指南》中的 [AWS 安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 密碼 | SecretAccessKey | 選用 | 無 |
## 工作階段字符
如果您使用臨時 AWS 登入資料，則必須指定工作階段字符。如需有關暫時憑證的資訊，請參閱《*IAM 使用者指南*》中的 [IAM 中的暫時安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| SessionToken | 無 | 選用 | 無 |
# 預設憑證
您可以使用在用戶端系統上設定的預設憑證，透過設定以下連線參數連線至 Amazon Athena。如需有關使用預設憑證的資訊，請參閱《*適用於 Java 的 AWS SDK 開發人員指南*》中的[使用預設憑證提供者鏈結](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default)。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `DefaultChain`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | DefaultChain |
# AWS 組態設定檔登入資料
您可以透過設定下列連線參數來使用存放在 AWS 組態設定檔中的登入資料。 AWS 組態設定檔通常存放在 `~/.aws`目錄中的檔案中）。如需 AWS 組態設定檔的相關資訊，請參閱**《適用於 Java 的 AWS SDK 開發人員指南》中的[使用設定檔](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-profiles.html)。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `ProfileCredentials`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | ProfileCredentials |
## Profile name (設定檔名稱)
AWS 組態設定檔的名稱，其登入資料應該用來驗證對 Athena 的請求。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ProfileName | 無 | 必要 | 無 |
**注意**
設定檔名稱也可以指定為 `CredentialsProviderArguments` 參數的值，雖然此用法已廢除。
# 執行個體設定檔憑證
此身分驗證類型在 Amazon EC2 執行個體上使用。*執行個體設定檔*是連接至 Amazon EC2 執行個體的設定檔。使用執行個體描述檔登入資料提供者將 AWS 登入資料的管理委派給 Amazon EC2 執行個體中繼資料服務。如此一來，開發人員就無需在 Amazon EC2 執行個體上永久儲存憑證，也不用擔心輪換或管理臨時憑證。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `InstanceProfile`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | InstanceProfile |
# 自訂憑證
您可以使用此身分驗證類型，藉由使用實作 [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) 介面的 Java 類別來提供您自己的憑證。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設定為實作 [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) 介面之自訂類別的完全合格類別名稱。在執行期，該類別必須位於使用 JDBC 驅動程式之應用程式的 Java 類別路徑上。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | AwsCredentialsProvider 自訂實作的完全合格類別名稱 |
## 憑證提供者引數
自訂認證提供者建構函數的逗號分隔字串引數清單。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| CredentialsProviderArguments | AwsCredentialsProviderArguments (已廢除) | 選用 | 無 |
# JWT 憑證
藉由此身分驗證類型，您可以使用從外部身分提供者獲得的 JSON Web Token (JWT) 作為連線參數，向 Athena 進行身分驗證。外部登入資料提供者必須已經與 聯合 AWS。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `JWT`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | JWT |
## JWT web 身分權杖
從外部聯合身分提供者獲得的 JWT 權杖。此權杖將用於向 Athena 進行身分驗證。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| JwtWebIdentityToken | web\$1identity\$1token (已廢除) | 必要 | 無 |
## JWT 角色 ARN
要擔任之角色的 Amazon Resource Name (ARN)。如需有關擔任角色的資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| JwtRoleArn | role\$1arn (已廢除) | 必要 | 無 |
## JWT 角色工作階段名稱
使用 JWT 憑證進行身分驗證時的工作階段名稱。該名稱可以是您選擇的任何名稱。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| JwtRoleSessionName | role\$1session\$1name (已廢除) | 必要 | 無 |
## 角色工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱《AWS Security Token Service API 參考**》中的 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration (已廢除) | 選用 | 3600 |
# JWT 與身分中心整合
此身分驗證類型允許您使用從外部身分提供者獲得的 JSON Web Token (JWT) 作為連線參數，向 Athena 進行身分驗證。您可以使用此外掛程式，透過可信身分傳播啟用對企業身分的支援。如需有關如何搭配使用可信身分傳播與驅動器的詳細資訊，請參閱 [搭配使用可信身分傳播與 Amazon Athena 驅動器](using-trusted-identity-propagation.md)。您也可以[使用 CloudFormation 設定和部署資源](using-trusted-identity-propagation-cloudformation.md)。
透過信任的身分傳播，身分內容會新增至 IAM 角色，以識別請求存取 AWS 資源的使用者。如需有關啟用和使用可信身分傳播的資訊，請參閱[什麼是可信身分傳播？](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html)。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `JWT_TIP`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | JWT\$1TIP |
## JWT web 身分權杖
從外部聯合身分提供者獲得的 JWT 權杖。此權杖將用於向 Athena 進行身分驗證。權杖快取預設為啟用，並允許在不同的驅動器連線之間使用相同的 Identity Center 存取權杖。建議在「測試連線」時提供新的 JWT 權杖，因為交換的權杖僅在驅動器執行個體處於作用中狀態時才會存在。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| JwtWebIdentityToken | web\$1identity\$1token (已廢除) | 必要 | 無 |
## WorkgroupArn
Amazon Athena 工作群組的 Amazon Resource Name (ARN)。如需有關工作群組的詳細資訊，請參閱[工作群組](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| WorkGroupArn | 無 | 必要 | 主要 |
## JWT 應用程式角色 ARN
要擔任的角色 ARN。此角色可用於 JWT 交換、透過工作群組標籤取得 IAM Identity Center 客戶自管應用程式 ARN，以及取得存取角色 ARN。如需有關擔任角色的詳細資訊，請參閱 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ApplicationRoleArn | 無 | 必要 | 無 |
## JWT 角色工作階段名稱
使用 JWT 憑證進行身分驗證時的工作階段名稱。其可以是您選擇的任何名稱。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| JwtRoleSessionName | role\$1session\$1name (已廢除) | 必要 | 無 |
## 角色工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration (已廢除) | 選用 | 3600 |
## JWT 存取角色 ARN
要擔任的角色 ARN。這是 Athena 服務所擔任的角色，可代表您進行呼叫。如需有關擔任角色的詳細資訊，請參閱《AWS Security Token Service API 參考**》中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AccessRoleArn | 無 | 選用 | 無 |
## IAM Identity Center 客戶自管應用程式 ARN
IAM Identity Center 客戶自管應用程式的 ARN。如需詳細資訊，請參閱[客戶自管應用程式](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| CustomerIdcApplicationArn | 無 | 選用 | 無 |
# 以身分中心整合為基礎的瀏覽器
此身分驗證類型可讓您從外部身分提供者擷取新的 JSON Web 字符 (JWT)，並使用 Athena 進行身分驗證。您可以使用此外掛程式，透過可信身分傳播啟用對企業身分的支援。如需有關如何搭配使用可信身分傳播與驅動器的詳細資訊，請參閱 [搭配使用可信身分傳播與 Amazon Athena 驅動器](using-trusted-identity-propagation.md)。您也可以[使用 CloudFormation 設定和部署資源](using-trusted-identity-propagation-cloudformation.md)。
透過信任的身分傳播，身分內容會新增至 IAM 角色，以識別請求存取 AWS 資源的使用者。如需有關啟用和使用可信身分傳播的資訊，請參閱[什麼是可信身分傳播？](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html)。
**注意**
外掛程式專為單一使用者桌面環境而設計。在 Windows Server 等共用環境中，系統管理員負責建立和維護使用者之間的安全界限。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `BrowserOidcTip`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | BrowserOidcTip |
## Idp 已知組態 URL
IDP Well Known 組態 URL 是為您的身分提供者提供 OpenID Connect 組態詳細資訊的端點。此 URL 通常會以 結尾，`.well-known/openid-configuration`並包含有關身分驗證端點、支援的功能和字符簽署金鑰的基本中繼資料。例如，如果您使用的是 *Okta*，URL 可能看起來像 `https://your-domain.okta.com/.well-known/openid-configuration`。
針對疑難排解：如果您收到連線錯誤，請確認此 URL 可從您的網路存取，並傳回有效的 *OpenID Connect* 組態 JSON。此 URL 必須由安裝驅動程式的用戶端連線，且應由您的身分提供者管理員提供。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| IdpWellKnownConfigurationUrl | 無 | 必要 | 無 |
## 用戶端識別符
OpenID Connect 提供者向應用程式發出的用戶端識別符。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| OidcClientId | 無 | 必要 | 無 |
## WorkgroupArn
Amazon Athena 工作群組的 Amazon Resource Name (ARN)，其中包含信任的身分傳播組態標籤。如需有關工作群組的詳細資訊，請參閱[工作群組](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
**注意**
此參數與指定查詢執行位置的 `Workgroup` 參數不同。您必須設定這兩個參數：
`WorkgroupArn` - 指向工作群組，其中包含信任的身分傳播組態標籤
`Workgroup` - 指定執行查詢的工作群組
雖然這些參數通常會參考相同的工作群組，但必須明確設定這兩個參數才能正常運作。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| WorkGroupArn | 無 | 必要 | 主要 |
## JWT 應用程式角色 ARN
將在 JWT 交換中擔任的角色 ARN。此角色可用於 JWT 交換、透過工作群組標籤取得 IAM Identity Center 客戶自管應用程式 ARN，以及取得存取角色 ARN。如需有關擔任角色的詳細資訊，請參閱 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ApplicationRoleArn | 無 | 必要 | 無 |
## JWT 角色工作階段名稱
IAM 工作階段的名稱。名稱可隨意指定，但是一般來說，您會傳遞與應用程式使用者相關聯的名稱或識別碼。這樣一來，應用程式使用的臨時安全憑證會與該使用者相關聯。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| JwtRoleSessionName | role\$1session\$1name (已廢除) | 必要 | 無 |
## Client secret (用戶端密碼)
clientSecret 是由您的身分提供者發行的機密金鑰，用於驗證您的應用程式 （用戶端）。雖然此參數是選用的，而且可能不是所有身分驗證流程的必要項目，但在使用時提供額外的安全層。如果您的 IDP 組態需要用戶端秘密，您必須將此參數包含身分提供者管理員提供的值。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| OidcClientSecret | 無 | 選用 | 無 |
## Scope (範圍)
範圍會指定應用程式向身分提供者請求的存取層級。您必須在 `openid` 範圍內包含 ，才能接收包含基本使用者身分宣告的 ID 字符。您的範圍可能需要包含其他許可，例如 `email`或 `profile`，取決於哪些使用者宣告您的身分提供者 （例如 *Microsoft Entra ID*) 已設定為包含在 ID 字符中。這些宣告對於適當的*受信任身分傳播*映射至關重要。如果使用者身分映射失敗，請確認您的範圍包含所有必要的許可，且您的身分提供者已設定為在 ID 字符中包含必要的宣告。這些宣告必須符合 IAM Identity Center 中的*受信任權杖發行者*映射組態。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| Scope (範圍) | 無 | 選用 | openid email offline\$1access |
## 角色工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration (已廢除) | 選用 | 3600 |
## JWT 存取角色 ARN
Athena 代您呼叫所擔任角色的 ARN。如需有關擔任角色的詳細資訊，請參閱《AWS Security Token Service API 參考**》中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AccessRoleArn | 無 | 選用 | 無 |
## IAM Identity Center 客戶自管應用程式 ARN
IAM Identity Center 客戶自管應用程式的 ARN。如需詳細資訊，請參閱[客戶自管應用程式](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| CustomerIdcApplicationArn | 無 | 選用 | 無 |
## 身分提供者連接埠號碼
用於 OAuth 2.0 回呼伺服器的本機連接埠號碼。這用作 redirect\$1uri，您需要允許在 IDP 應用程式中將其列出。預設產生的 redirect\$1uri 為：http：//localhost：7890/athena
**警告**
在共用環境中，例如 Windows Terminal Server 或遠端桌面服務，循環連接埠 （預設值：7890) 會在相同機器上的所有使用者之間共用。系統管理員可以透過下列方式降低潛在的連接埠劫持風險：
為不同的使用者群組設定不同的連接埠號碼
使用 Windows 安全政策來限制連接埠存取
在使用者工作階段之間實作網路隔離
如果無法實作這些安全控制，建議您改用 [JWT 信任的身分傳播](jdbc-v3-driver-jwt-tip-credentials.md)外掛程式，這不需要迴路連接埠。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| IdpPortNumber | 無 | 選用 | 7890 |
## 識別提供者回應逾時
等待 OAuth 2.0 回呼回應的逾時，以秒為單位。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| IdpResponseTimeout | 無 | 選用 | 120 |
## 啟用權杖快取
EnableTokenCaching 參數會判斷驅動程式是否在連接之間快取身分驗證字符。將 EnableTokenCaching 設為 true 可減少身分驗證提示並改善使用者體驗，但應謹慎使用。此設定最適合單一使用者桌面環境。在 Windows Server 等共用環境中，建議將其停用，以防止具有類似連線字串的使用者之間進行潛在的字符共用。
對於使用 Tableau Server 等工具的企業部署，我們建議您使用 [JWT 信任的身分傳播](jdbc-v3-driver-jwt-tip-credentials.md)外掛程式，而不是此身分驗證方法。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| EnableTokenCaching | 無 | 選用 | FALSE |
# Azure AD 憑證
SAML 型身分驗證機制，可讓您使用 Azure AD 身分提供者向 Athena 進行身分驗證。此方法假設已經在 Athena 和 Azure AD 之間建立了聯合。
**注意**
本節中的某些參數名稱具有別名。別名是參數名稱的功能對等項目，並已提供與 JDBC 2.x 驅動程式的向後相容性。由於參數名稱已經過改進，以遵循更清晰、更一致的命名慣例，因此我們建議您使用參數名稱，而不是已被取代的別名。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `AzureAD`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | AzureAD |
## 使用者
Azure AD 使用者的電子郵件地址，用來透過 Azure AD 進行身分驗證。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 使用者 | UID (已廢除) | 必要 | 無 |
## 密碼
Azure AD 使用者的密碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 密碼 | PWD (已廢除) | 必要 | 無 |
## Azure AD 租用戶 ID
Azure AD 應用程式的租用戶 ID。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AzureAdTenantId | tenant\$1id (已廢除) | 必要 | 無 |
## Azure AD 用戶端 ID
Azure AD 應用程式的用戶端 ID。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AzureAdClientId | client\$1id (已廢除) | 必要 | 無 |
## Azure AD 用戶端秘密
Azure AD 應用程式的用戶端秘密。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AzureAdClientSecret | client\$1secret (已廢除) | 必要 | 無 |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如需有關 ARN 角色的資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role (已廢除) | 選用 | 無 |
## 角色工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration (已廢除) | 選用 | 3600 |
## Lake Formation 啟用
指定是否使用 [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 動作來擷取臨時 IAM 憑證，而非 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 動作。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | 無 | 選用 | FALSE |
# Okta 憑證
SAML 型身分驗證機制，可讓您使用 Okta 身分提供者向 Athena 進行身分驗證。此方法假設已經在 Athena 和 Okta 之間設定了聯合。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `Okta`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | Okta |
## 使用者
Okta 使用者的電子郵件地址，用來透過 Okta 進行身分驗證。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 使用者 | UID (已廢除) | 必要 | 無 |
## 密碼
Okta 使用者的密碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 密碼 | PWD (已廢除) | 必要 | 無 |
## Okta 主機名稱
您的 Okta 組織的 URL。您可以從 Okta 應用程式中的**內嵌連結** URL 擷取 `idp_host` 參數。如需這些步驟，請參閱 [從 Okta 擷取 ODBC 組態資訊](odbc-okta-plugin.md#odbc-okta-plugin-retrieve-odbc-configuration-information-from-okta)。`https://` 後的第一個區段、直到並包括 `okta.com`，即為您的 IdP 主機 (例如，以 `https://trial-1234567.okta.com` 開頭的 URL 為 `trial-1234567.okta.com`)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| OktaHostName | IdP\$1Host (已廢除) | 必要 | 無 |
## Okta 應用程式 ID
您應用程式的兩部分識別符。您可以從 Okta 應用程式中的**內嵌連結** URL 擷取應用程式 ID。如需這些步驟，請參閱 [從 Okta 擷取 ODBC 組態資訊](odbc-okta-plugin.md#odbc-okta-plugin-retrieve-odbc-configuration-information-from-okta)。應用程式 ID 是 URL 的最後兩個區段，包括中間的正斜線。這些區段是兩個由 20 個字元組成的字串，其中包含數字和大小寫字母的混合 (例如 `Abc1de2fghi3J45kL678/abc1defghij2klmNo3p4`)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| OktaAppId | App\$1ID (已廢除) | 必要 | 無 |
## Okta 應用程式名稱
Okta 應用程式的名稱。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| OktaAppName | App\$1Name (已廢除) | 必要 | 無 |
## Okta MFA 類型
如果您已將 Okta 設定為需要多重要素驗證 (MFA)，則需要根據您要使用的第二要素指定 Okta MFA 類型和其他參數。
Okta MFA 類型是用以透過 Okta 進行身分驗證的第二身分驗證要素類型 (在密碼之後)。支援的第二要素包括透過 Okta Verify 應用程式傳送的推送通知以及由 Okta Verify、Google Authenticator 生成的或透過簡訊發送的臨時一次性密碼 (TOTP)。個別組織安全政策會判斷使用者登入是否需要 MFA。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 可能的值 |
| --- | --- | --- | --- | --- |
| OktaMfaType | okta\$1mfa\$1type (已廢除) | 如果將 Okta 設定為需要 MFA，則為必要 | 無 | oktaverifywithpush, oktaverifywithtotp, googleauthenticator, smsauthentication |
## Okta 電話號碼
選擇 `smsauthentication` MFA 類型時，Okta 將使用簡訊將臨時一次性密碼傳送到的電話號碼。該電話號碼必須是美國或加拿大的電話號碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| OktaPhoneNumber | okta\$1phone\$1number (已廢除) | 如果 OktaMfaType 為 smsauthentication，則為必要 | 無 |
## Okta MFA 等待時間
在驅動程式擲出逾時例外狀況之前，等待使用者確認來自 Okta 的推送通知的持續時間 (以秒為單位)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| OktaMfaWaitTime | okta\$1mfa\$1wait\$1time (已廢除) | 選用 | 60 |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如需有關 ARN 角色的資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role (已廢除) | 選用 | 無 |
## 角色工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration (已廢除) | 選用 | 3600 |
## Lake Formation 啟用
指定是否使用 [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 動作來擷取臨時 IAM 憑證，而非 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 動作。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | 無 | 選用 | FALSE |
# Ping 憑證
SAML 型身分驗證機制，可讓您使用 Ping Federate 身分提供者向 Athena 進行身分驗證。此方法假設已經在 Athena 和 Ping Federate 之間設定了聯合。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `Ping`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | Ping |
## 使用者
Ping Federate 使用者的電子郵件地址，用於透過 Ping Federate 進行身分驗證。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 使用者 | UID (已廢除) | 必要 | 無 |
## 密碼
Ping Federate 使用者的密碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 密碼 | PWD (已廢除) | 必要 | 無 |
## PingHostName
Ping 伺服器的地址。若要尋找您的地址，請造訪下列 URL 並檢視 **SSO 應用程式端點**欄位。
```
https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections
```
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| PingHostName | IdP\$1Host (已廢除) | 必要 | 無 |
## PingPortNumber
用於連線至 IdP 主機的連接埠號碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| PingPortNumber | IdP\$1Port (已廢除) | 必要 | 無 |
## PingPartnerSpId
服務提供者地址。若要尋找服務提供者地址，請造訪下列 URL 並檢視 **SSO 應用程式端點**欄位。
```
https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections
```
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| PingPartnerSpId | Partner\$1SPID (已廢除) | 必要 | 無 |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如需有關 ARN 角色的資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role (已廢除) | 選用 | 無 |
## 角色工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration (已廢除) | 選用 | 3600 |
## Lake Formation 啟用
指定是否使用 [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 動作來擷取臨時 IAM 憑證，而非 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 動作。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | 無 | 選用 | FALSE |
# AD FS 憑證
SAML 型身分驗證機制，可讓您使用 Microsoft Active Directory Federation Services (AD FS) 向 Athena 進行身分驗證。此方法假設使用者已經在 Athena 和 AD FS 之間設定了聯合。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `ADFS`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | ADFS |
## 使用者
AD FS 使用者的電子郵件地址，用來透過 AD FS 進行身分驗證。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 使用者 | UID (已廢除) | 表單型身分驗證的必要項目。Windows 整合式身分驗證的選用項目。 | 無 |
## 密碼
AD FS 使用者的密碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 密碼 | PWD (已廢除) | 表單型身分驗證的必要項目。Windows 整合式身分驗證的選用項目。 | 無 |
## ADFS 主機名稱
AD FS 伺服器的地址。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AdfsHostName | IdP\$1Host (已廢除) | 必要 | 無 |
## ADFS 連接埠號碼
用於連線至 AD FS 伺服器的連接埠號碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AdfsPortNumber | IdP\$1Port (已廢除) | 必要 | 無 |
## ADFS 依賴方
可信依賴方。使用此參數來覆寫 AD FS 依賴方端點 URL。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AdfsRelyingParty | LoginToRP (已廢除) | 選用 | urn:amazon:webservices |
## ADFS WIA 啟用
布林值。使用此參數來啟用具有 AD FS 的 Windows 整合式身分驗證 (WIA)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AdfsWiaEnabled | none | 選用 | FALSE |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如需有關 ARN 角色的資訊，請參閱《AWS Security Token Service API 參考**》中的 [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role (已廢除) | 選用 | 無 |
## 角色工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱 *AWS Security Token Service API 參考*中的 [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration (已廢除) | 選用 | 3600 |
## Lake Formation 啟用
指定是否使用 [https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 動作來擷取臨時 IAM 登入資料，而非 [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 動作。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | none | 選用 | FALSE |
# 瀏覽器 Azure AD 憑證
瀏覽器 Azure AD 是 SAML 型身分驗證機制，可與 Azure AD 身分提供者搭配使用並支援多重因素認證。與標準 Azure AD 身分驗證不同，此機制不需要連線參數中的使用者名稱、密碼或用戶端密碼。如同標準 Azure AD 身分驗證機制，瀏覽器 Azure AD 也會假設使用者已經設定了 Athena 與 Azure AD 之間的聯合。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `BrowserAzureAD`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | BrowserAzureAD |
## Azure AD 租用戶 ID
Azure AD 應用程式的租用戶 ID
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AzureAdTenantId | tenant\$1id (已廢除) | 必要 | 無 |
## Azure AD 用戶端 ID
Azure AD 應用程式的用戶端 ID
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| AzureAdClientId | client\$1id (已廢除) | 必要 | 無 |
## 識別提供者回應逾時
驅動程式停止等待來自 Azure AD 之 SAML 回應之前的持續時間 (以秒為單位)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| IdpResponseTimeout | idp\$1response\$1timeout (已廢除) | 選用 | 120 |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如需有關 ARN 角色的資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role (已廢除) | 選用 | 無 |
## 角色工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration (已廢除) | 選用 | 3600 |
## Lake Formation 啟用
指定是否使用 [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 動作來擷取臨時 IAM 憑證，而非 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 動作。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | 無 | 選用 | FALSE |
# 瀏覽器 SAML 憑證
瀏覽器 SAML 是一般身分驗證外掛程式，可與 SAML 型身分提供者搭配使用並支援多重因素認證。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `BrowserSaml`。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | BrowserSaml |
## 單一登入登入 URL
您的應用程式在 SAML 型身分提供者上的單一登入 URL。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| SsoLoginUrl | login\$1url (已廢除) | 必要 | 無 |
## 接聽連接埠
用來接聽 SAML 回應的連接埠號碼。此值應與您設定 SAML 型身分提供者所使用的 URL 相符 (例如，`http://localhost:7890/athena`)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ListenPort | listen\$1port (已廢除) | 選用 | 7890 |
## 識別提供者回應逾時
驅動程式停止等待來自 Azure AD 之 SAML 回應之前的持續時間 (以秒為單位)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| IdpResponseTimeout | idp\$1response\$1timeout (已廢除) | 選用 | 120 |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如需有關 ARN 角色的資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role (已廢除) | 選用 | 無 |
## 角色工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration (已廢除) | 選用 | 3600 |
## Lake Formation 啟用
指定是否使用 [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 動作來擷取臨時 IAM 憑證，而非 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 動作。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | 無 | 選用 | FALSE |
# DataZone IdC 憑證提供者
身分驗證機制，可讓您使用 IAM Identity Center 連線至 Athena 中的 DataZone 管理的資料。
## 憑證提供者
將用來驗證對 AWS的請求的憑證提供者。將此參數的值設為 `DataZoneIdc`。請注意，`AWSCredentialsProviderClass` 別名已廢除；請改用 `CredentialsProvider` 參數名稱。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 將使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass (已廢除) | 必要 | 無 | DataZoneIdc |
## DataZone 網域識別碼
要使用的 DataZone 網域識別碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| DataZoneDomainId | 無 | 必要 | 無 |
## DataZone 環境識別碼
要使用的 DataZone 環境識別碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| DataZoneEnvironmentId | 無 | 必要 | 無 |
## DataZone 網域區域
佈建 DataZone 網域 AWS 區域 的 。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| DataZoneDomainRegion | 無 | 必要 | 無 |
## 區域
佈建 DataZone 環境和 Athena 工作群組 AWS 區域 的 。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 區域 | 無 | 必要 | 無 |
## IAM Identity Center 發行者 URL
DataZone 網域使用的 IAM Identity Center 執行個體的發行者 URL。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| IdentityCenterIssuerUrl | 無 | 必要 | 無 |
## DataZone 端點覆寫
要使用的 DataZone API 端點，而不是提供的 AWS 區域的預設值。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| DataZoneEndpointOverride | 無 | 選用 | 無 |
## 啟用權杖快取
啟用時，允許在不同的驅動器連線之間使用相同的 IAM Identity Center 存取權杖。這可避免建立多個驅動器連線的 SQL 工具啟動多個瀏覽器視窗。如果您啟用此參數，我們建議您在使用 SQL 工具清除權杖快取後立即將其關閉，並需要重新進行身分驗證。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| EnableTokenCaching | 無 | 選用 | FALSE |
## 接聽連接埠
接聽 IAM Identity Center 回應的連接埠號碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| ListenPort | 無 | 選用 | 8000 |
## 身分提供者回應逾時
驅動器停止等待來自 IAM Identity Center 回應之前的持續時間 (以秒為單位)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| IdpResponseTimeout | 無 | 選用 | 120 |
# DataZone IAM 憑證提供者
身分驗證機制，可使用 IAM 憑證連線到 Athena 中的 DataZone 受管理的資料。
## DataZone 網域識別碼
要使用的 DataZone 網域識別碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| DataZoneDomainId | 無 | 必要 | 無 |
## DataZone 環境識別碼
要使用的 DataZone 環境識別碼。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| DataZoneEnvironmentId | 無 | 必要 | 無 |
## DataZone 網域區域
佈建 DataZone 網域 AWS 區域 的 。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| DataZoneDomainRegion | 無 | 必要 | 無 |
## DataZone 端點覆寫
要使用的 DataZone API 端點，而不是提供的 AWS 區域的端點預設值。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| DataZoneEndpointOverride | 無 | 選用 | 無 |
## 使用者
您的 AWS 存取金鑰 ID。如需有關存取金鑰的詳細資訊，請參閱《IAM 使用者指南**》中的 [AWS 安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 使用者 | AccessKeyId | 選用 | 無 |
## 密碼
您的 AWS 私密金鑰 ID。如需有關存取金鑰的詳細資訊，請參閱《IAM 使用者指南**》中的 [AWS 安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)。
****
| 參數名稱 | Alias (別名) | 參數類型 | 預設值 |
| --- | --- | --- | --- |
| 密碼 | SecretAccessKey | 選用 | 無 |
# 其他 JDBC 3.x 組態
下列各節說明 JDBC 3.x 驅動程式的其他組態設定。
## 網路逾時
網路逾時可控制驅動器等待建立網路連線的時間量 (以毫秒為單位)。這包括傳送 API 請求所需的時間。在此時間之後，驅動程式會擲出逾時例外狀況。在極少數情況下，變更網路逾時可能會非常實用。例如，您可能想要增加長時間垃圾回收暫停的逾時。
要進行設定，請在 JDBC `Connection` 物件上呼叫 `setNetworkTimeout` 方法。此值可以在 JDBC 連線的生命週期中變更。如需詳細資訊，請參閱 Oracle JDBC API 文件中的 [setNetworkTimeout](https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html#setNetworkTimeout-java.util.concurrent.Executor-int-)。使用 `setNetworkTimeout` 方法等同於設定 [網路逾時](jdbc-v3-driver-advanced-connection-parameters.md#jdbc-v3-driver-networktimeoutmillis) 連線參數。
下列範例會將網路逾時設定為 5000 毫秒。
```
...
AthenaDriver driver = new AthenaDriver();
Connection connection = driver.connect(url, connectionParameters);
connection.setNetworkTimeout(null, 5000);
...
```
## 查詢逾時
提交查詢之後，驅動程式會在 Athena 上等待查詢完成的時間量，以秒為單位。在此時間之後，驅動程式會嘗試取消提交的查詢並擲出逾時例外狀況。
查詢逾時無法設定為連線參數。要進行設定，請在 JDBC `Statement` 物件上呼叫 `setQueryTimeout` 方法。這個值可以在 JDBC 陳述式的生命週期中變更。此參數的預設值為 `0` (零)。值 `0` 表示查詢可以執行直到完成 (受限於 [Service Quotas](service-limits.md))。
下列範例會將查詢逾時設定為 5 秒。
```
...
AthenaDriver driver = new AthenaDriver();
Connection connection = driver.connect(url, connectionParameters);
Statement statement = connection.createStatement();
statement.setQueryTimeout(5);
...
```
# Amazon Athena JDBC 3.x 版本備註
這些版本備註詳細說明了 Amazon Athena JDBC 3.x 驅動器中改進和修正。
## 3.7.0
版 2025-11-21
### 改進
+ **瀏覽器 OIDC 可信任身分傳播身分身分驗證外掛程式** – 新增了新的身分驗證外掛程式，可使用 OpenID Connect (OIDC) 身分提供者進行無縫的瀏覽器型身分驗證。此外掛程式會透過預設瀏覽器處理完整的 OAuth 2.0 流程、自動擷取 JSON Web Token (JWT)，並與信任的身分傳播整合。它專為單一使用者桌面環境而設計，相較於手動 JWT 處理，可提供更簡化的身分驗證體驗。如需受信任身分傳播的詳細資訊，請參閱[什麼是受信任身分傳播？](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html)。
### 修正項目
+ **增強型時間戳記精確度支援** – 驅動程式現在完全支援從 Athena 查詢透過 `getTimestamp()`方法傳回的時間戳記值中的毫秒和奈秒精確度。
+ **改善複雜類型處理** – 修正在 `DatabaseMetaData#getColumns`和一般中繼資料操作中剖析巢狀資料類型 （陣列、結構和映射） 的問題，確保複雜資料結構的類型資訊準確。
+ **增強型錯誤記錄** – 改善 S3 中繼資料擷取失敗的記錄，提供更清楚的錯誤訊息和更好的診斷資訊。
## 3.6.0
版 2025-09-10
### 改進
+ **JWT 可信身分傳播身分驗證外掛程式** – 新增了新的身分驗證外掛程式，可支援 JWT 可信身分傳播與 JDBC 驅動器的整合。此身分驗證類型允許您使用從外部身分提供者獲得的 JSON Web Token (JWT) 作為連線參數，向 Athena 進行身分驗證。透過受信任的身分傳播，身分內容會新增至 IAM 角色，以識別請求存取 AWS 資源的使用者。如需有關啟用和使用可信身分傳播的資訊，請參閱[什麼是可信身分傳播？](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html)。
+ **自訂 SSO OIDC 和 SSO 管理員端點支援** – 新增對 JDBC 驅動器中自訂 SSO OIDC 和 SSO 管理員端點的支援。此增強功能可讓您在 VPC 後方執行 JDBC 時，為 SSO 服務指定自己的端點。
+ **AWS 開發套件版本更新** – 我們已將驅動程式中使用的 AWS 開發套件版本更新至 2.32.16，並已更新 3.6.0 版的專案相依性。
## 3.5.1
版 2025-07-17
### 改進
+ **記錄功能** – 將日誌層級提升為 `INFO` 並新增資料列計數、位移和物件長度的指標，進而增強 S3 擷取記錄。實作了連線生命週期追蹤，並對整體記錄效能進行了最佳化。
+ **特殊字元處理** – 改善了對結構描述和目錄名稱中 `LIKE` 模式的特殊字元的處理。
+ **連線狀態管理** – 改善了連線狀態管理，即藉由在連線關閉後防止 API 呼叫，以及在關閉期間新增查詢操作的安全檢查，進而避免潛在錯誤。
### 修正項目
+ **DDL 查詢中繼資料** – 修正了 DDL 查詢中繼資料處理的 `NoSuchKeyFound` 問題。
## 3.5.0
2025-03-18 發布
### 改進
+ **結果組態參數** – 新增了對兩個新連線參數 `ExpectedBucketOwner` 和 `AclOption` 的支援。如需詳細資訊，請參閱[結果組態參數](jdbc-v3-driver-advanced-connection-parameters.md#jdbc-v3-driver-result-config)。
+ **AWS SDK 版本** – 驅動程式中使用的 AWS SDK 版本已更新至 2.30.22。
## 3.4.0
2025-02-18 發布
### 改進
+ **結果擷取程式** – 驅動器現在會自動選取下載查詢結果的最快速方法。如此一來，在大多數情況下都無需手動設定擷取程式。如需詳細資訊，請參閱[結果擷取參數](jdbc-v3-driver-advanced-connection-parameters.md#jdbc-v3-driver-result-fetching-parameters)。
### 修正項目
+ **ResultSet** – 驅動器現在能夠逐一處理在 S3 上不會產生結果物件的 DDL 陳述式結果集。當 `GetQueryResultsStream` 傳回完全空白的頁面時，它也會傳回空的 `ResultSet` 物件，而不是 null。
+ **ResultsStream** – 結果串流已透過移除不必要的呼叫來進行最佳化，進而計算內部緩衝區中的資料列數。
+ **getTables** – 已根據 `ListTableMetadata` 和 `GetTableMetadata` 回應處理資料表類型，進而最佳化 `GetTables` 呼叫。
## 3.3.0
版 2024-10-30
### 改進
+ **DataZone 身分驗證** – 新增了對 DataZone 身分驗證外掛程式 `DataZoneIdC` 和 `DataZoneIAM` 的支援。如需詳細資訊，請參閱[DataZone IdC 憑證提供者](jdbc-v3-driver-datazone-idc.md)及[DataZone IAM 憑證提供者](jdbc-v3-driver-datazone-iamcp.md)。
+ **網路逾時** – 現在可以使用 `NetworkTimeoutMillis` 連線參數設定網路逾時。先前，其只能在 `Connection` 物件本身上設定。如需詳細資訊，請參閱[網路逾時](jdbc-v3-driver-other-configuration.md#jdbc-v3-driver-network-timeout)。
### 修正項目
+ **S3 空物件處理** – 驅動器現在能在 S3 擷取程式中處理空物件，而不是擲回 Amazon S3 Range Not Satisfiable 例外狀況。
+ **記錄** – 驅動器不會再記錄查詢執行 [...] 請求的訊息項目，但訂閱會在取用查詢結果後取消這則訊息。
+ **空的參數字串** – 驅動器現在能處理連線參數中存在的空字串，就好像參數不存在一樣。這樣一來，即可解決某些 BI 工具因不小心傳遞空字串而導致意外身分驗證嘗試時發生的問題。
## 3.2.2
版 2024-07-29
### 改進
+ **資料類型映射** – 透過變更驅動器將 `tinyint`、`smallint`、`row` 和 `struct` 資料類型映射至 Java 物件的方式，提高了對 JDBC 規範的合規性。
+ **AWS SDK 版本更新** – AWS 驅動程式中使用的 SDK 版本已更新至 2.26.23。
### 修正項目
+ **註解** – 修正了陳述式結尾的行註解問題。
+ **資料庫清單** – 修正了下列問題：當分頁 `ListDatabases` API 傳回的最後一頁為空白時，列出資料庫可能會進入無限迴圈。
## 3.2.1
版 2024-07-03
### 改進
+ **JWT 憑證提供者** – 新增了對使用者指定的工作階段持續時間的支援。如需詳細資訊，請參閱[角色工作階段持續時間](jdbc-v3-driver-jwt-credentials.md#jdbc-v3-driver-jwt-role-session-duration)。
### 修正項目
+ **執行緒集區** – 針對非同步任務，已為每個連線建立一個 `ThreadPoolExecutor`，進而避免使用 `ForkJoin` 集區。
+ **憑證提供者** – 現在會剖析代理主機，以便在為外部 IdP 設定 HTTP 用戶端時取得結構描述和主機。
+ **預設憑證提供者** – 確保用戶端程式碼無法關閉預設憑證提供者。
+ **getColumns** – 修正了 `DatabaseMetaData#getColumns` 方法中的 `ORDINAL_COLUMN` 資料欄屬性問題。
+ **ResultSet** – 新增了對 `Infinity`、`-Infinity`、`NaN` 和 `ResultSet.` 的支援，修正了目錄操作傳回的資料欄類型與已完成查詢的結果集之間的差異。
## 3.2.0
2024-04-26 發布
### 改進
+ **目錄操作效能** – 對於不使用萬用字元的目錄操作，其效能有所提升。
+ **輪詢間隔下限變更** – 已修改輪詢間隔下限預設值，以減少驅動器對 Athena 發出的 API 呼叫次數。仍能盡快偵測到查詢完成。
+ **BI 工具可探索性** – 商業智慧工具能更輕鬆地探索到驅動器。
+ **資料類型映射** – 已改善 Athena `binary`、`array` 和 `struct` DDL 資料類型的資料類型映射。
+ **AWS SDK 版本** – 驅動程式中使用的 AWS SDK 版本已更新至 2.25.34。
### 修正項目
+ **聯合目錄資料表清單** – 修正了導致聯合目錄傳回空白資料表清單的問題。
+ **getSchemas** – 修正了導致 JDBC [DatabaseMetaData\$1getSchemas](https://docs.oracle.com/javase/8/docs/api/java/sql/DatabaseMetaData.html#getSchemas--) 方法僅從預設目錄而非所有目錄擷取資料庫的問題。
+ **getColumns** – 修正了使用 Null 目錄名稱呼叫 JDBC [DatabaseMetaData\$1getColumns](https://docs.oracle.com/javase/8/docs/api/java/sql/DatabaseMetaData.html#getColumns-java.lang.String-java.lang.String-java.lang.String-java.lang.String-) 方法時，導致傳回 Null 目錄的問題。
## 3.1.0
2024-02-15 發布
### 改進
+ 對 Microsoft Active Directory Federation Services (AD FS) Windows 整合式身分驗證和表單型身分驗證的支援。
+ 為了與 2.x 版保持回溯相容，現在接受 `awsathena` JDBC 子通訊協定，但會產生廢除警告。請改用 `athena` JDBC 子通訊協定。
+ `AwsDataCatalog` 現在是目錄參數的預設值，而 `default` 是資料庫參數的預設值。這些變更可確保傳回目前目錄和資料庫的正確值，而不是 Null。
+ 為了符合 JDBC 規格，`IS_AUTOINCREMENT` 和 `IS_GENERATEDCOLUMN` 現在會傳回空字串，而不是 `NO`。
+ Athena `int` 資料類型現在會映射至與 Athena 相同的 JDBC 類型 `integer`，而不是 `other`。
+ 當 Athena 的資料欄中繼資料不包含選用 `precision` 和 `scale` 欄位時，驅動器現在會針對 `ResultSet` 資料欄中的對應值傳回零。
+ AWS SDK 版本已更新至 2.21.39。
### 修正項目
+ 修正了與 `GetQueryResultsStream` 相關的問題，即當 Athena 的純文字結果資料欄計數與 Athena 結果中繼資料中的資料欄計數不一致時，會發生例外狀況。
## 3.0.0
版 2023-11-16
Athena JDBC 3.x 驅動器是新一代的驅動器，可提供更好的效能和相容性。JDBC 3.x 驅動器支援直接從 Amazon S3 讀取查詢結果，從而可提升應用程式的效能，其中這些應用程式會耗用大量查詢結果。新的驅動器降低了第三方相依性，因此可以更輕鬆地整合 BI 工具與自訂應用程式。
# 舊版 Athena JDBC 3.x 驅動器
強烈建議您使用[最新版本](jdbc-v3-driver.md)的 JDBC 3.x 驅動器。最新版本的驅動器包含最新的改善和修正。僅當您的應用程式與最新版本不相容時，才會使用較舊版本。
## JDBC 驅動程式 uber jar
下面的下載將驅動程式及其所有相依性包在同一個 `.jar` 檔案中。此下載通常用於第三方 SQL 用戶端。
+ [3.6.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.6.0/athena-jdbc-3.6.0-with-dependencies.jar)
+ [3.5.1 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.1/athena-jdbc-3.5.1-with-dependencies.jar)
+ [3.5.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.0/athena-jdbc-3.5.0-with-dependencies.jar)
+ [3.4.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.4.0/athena-jdbc-3.4.0-with-dependencies.jar)
+ [3.3.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.3.0/athena-jdbc-3.3.0-with-dependencies.jar)
+ [3.2.2 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.2/athena-jdbc-3.2.2-with-dependencies.jar)
+ [3.2.1 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.1/athena-jdbc-3.2.1-with-dependencies.jar)
+ [3.2.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.0/athena-jdbc-3.2.0-with-dependencies.jar)
+ [3.1.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.1.0/athena-jdbc-3.1.0-with-dependencies.jar)
+ [3.0.0 uber jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.0.0/athena-jdbc-3.0.0-with-dependencies.jar)
## JDBC 驅動程式 lean jar
下面的下載是一個 `.zip` 檔案，其中包含驅動程式的 lean `.jar` 和驅動程式相依性的單獨 `.jar` 檔案。此下載通常用於可能具有相依性與驅動程式使用的相依性衝突的自訂應用程式。如果您想選擇要包含在 lean jar 中的驅動程式相依性，以及要排除的驅動程式相依性 (如果您的自訂應用程式已包含一或多個驅動程式相依性)，則此下載非常有用。
+ [3.6.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.6.0/athena-jdbc-3.6.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.5.1 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.1/athena-jdbc-3.5.1-lean-jar-and-separate-dependencies-jars.zip)
+ [3.5.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.5.0/athena-jdbc-3.5.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.4.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.4.0/athena-jdbc-3.4.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.3.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.3.0/athena-jdbc-3.3.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.2.2 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.2/athena-jdbc-3.2.2-lean-jar-and-separate-dependencies-jars.zip)
+ [3.2.1 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.1/athena-jdbc-3.2.1-lean-jar-and-separate-dependencies-jars.zip)
+ [3.2.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.2.0/athena-jdbc-3.2.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.1.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.1.0/athena-jdbc-3.1.0-lean-jar-and-separate-dependencies-jars.zip)
+ [3.0.0 lean jar](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/3.0.0/athena-jdbc-3.0.0-lean-jar-and-separate-dependencies-jars.zip)
# Athena JDBC 2.x 驅動程式
您可以使用 JDBC 連接來將 Athena 連接到商業智慧工具和其他應用程式，例如 [SQL Workbench](http://www.sql-workbench.eu/downloads.html)。若要這樣做，請使用此頁面上的 Amazon S3 連結，以下載、安裝和設定 Athena JDBC 2.x 驅動程式。有關建置 JDBC 連接 URL 的資訊，請參閱可下載的[JDBC 驅動程式安裝和組態指南](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/Simba+Amazon+Athena+JDBC+Connector+Install+and+Configuration+Guide.pdf)。如需許可的相關資訊，請參閱[透過 JDBC 和 ODBC 連接控制存取](policy-actions.md)。要提交有關 JDBC 驅動程式的意見回饋，請傳送電子郵件至 [athena-feedback@amazon.com](mailto:athena-feedback@amazon.com)。從 2.0.24 版開始，提供兩種版本的驅動程式：一種包含 AWS SDK，另一種則不包含。
**重要**
當您使用 JDBC 驅動程式時，務必注意以下要求：
**打開連接埠 444** – 將 Athena 用來串流查詢結果的連接埠 444 保持開放給輸出流量。當您使用 PrivateLink 端點連接到 Athena 時，請確定連接至 PrivateLink 端點的安全群組已在連接埠 444 上開放給輸入流量。如果連接埠 444 遭到封鎖，您可能會收到錯誤訊息 [Simba][AthenaJDBC](100123) An error has occurred. ([Simba][AthenaJDBC](100123) 發生錯誤。) 資料欄初始化期間發生例外狀況。
**athena:GetQueryResultsStream 政策** – 新增針對使用 JDBC 驅動程式的 IAM 主體的 `athena:GetQueryResultsStream` 政策動作。此政策動作不會直接透過 API 公開。它僅與 ODBC 和 JDBC 驅動程式搭配使用，做為串流結果支援的一部分。如需政策範例，請參閱 [AWS 受管政策：AWSQuicksightAthenaAccess](security-iam-awsmanpol.md#awsquicksightathenaaccess-managed-policy)。
**使用用於多個資料目錄的 JDBC 驅動程式** – 若要將用於多個資料目錄的 JDBC 驅動程式與 Athena 搭配使用 (例如，在使用[外部 Hive 中繼存放區](connect-to-data-source-hive.md)或[聯合查詢](federated-queries.md)時)，在您的 JDBC 連線字串中包含 `MetadataRetrievalMethod=ProxyAPI`。
**4.1 驅動程式** – 從 2023 年起，將停止對 JDBC 4.1 版提供驅動程式支援。將不再發布進一步更新。如果您仍在使用 JDBC 4.1 驅動程式，強烈建議您改用 4.2 驅動程式。
## 搭配 AWS SDK 的 JDBC 2.x 驅動程式
JDBC 驅動程式 2.2.2 版符合 JDBC API 4.2 資料標準，且需要 JDK 8.0 或更新版本。如需檢查您使用之 Java 執行階段環境 (JRE) 版本的相關資訊，請參閱 Java [文件](https://www.java.com/en/download/help/version_manual.html)。
使用下列連結來下載 JDBC 4.2 驅動程式 `.jar` 檔案。
+ [AthenaJDBC42-2.2.2.1000.jarAthenaJDBC](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/AthenaJDBC42-2.2.2.1000.jar)
下列`.zip`檔案下載包含 JDBC 4.2 `.jar` 的檔案，並包含 AWS SDK 和隨附的文件、版本備註、授權和協議。
+ [SimbaAthenaJDBC-2.2.2.1000.zipSimbaAthenaJDBC](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/SimbaAthenaJDBC-2.2.2.1000.zip)
## 不含 AWS SDK 的 JDBC 2.x 驅動程式
JDBC 驅動程式 2.2.2 版符合 JDBC API 4.2 資料標準，且需要 JDK 8.0 或更新版本。如需檢查您使用之 Java 執行階段環境 (JRE) 版本的相關資訊，請參閱 Java [文件](https://www.java.com/en/download/help/version_manual.html)。
使用以下連結下載不含 AWS SDK 的 JDBC 4.2 驅動程式`.jar`檔案。
+ [AthenaJDBC42-2.2.2.1001.jarAthenaJDBC](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1001/AthenaJDBC42-2.2.2.1001.jar)
以下 `.zip` 檔案下載包含 JDBC 4.2 `.jar` 檔案及隨附的文件、版本備註、授權和協議。它不包含 AWS SDK。
+ [SimbaAthenaJDBC-2.2.2.1001.zipSimbaAthenaJDBC](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1001/SimbaAthenaJDBC-2.2.2.1001.zip)
## JDBC 2.x 驅動程式版本備註、授權合約和聲明
下載您需要的版本後，請閱讀版本備註，並檢閱授權合約和聲明。
+ [版本備註](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/release-notes.txt)
+ [授權合約](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/LICENSE.txt)
+ [通知](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/NOTICES.txt)
+ [第三方授權](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/third-party-licenses.txt)
## JDBC 2.x 驅動程式文件
下載驅動程式的下列文件：
+ [JDBC 驅動程式安裝和組態指南](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/Simba+Amazon+Athena+JDBC+Connector+Install+and+Configuration+Guide.pdf) 。使用此指南來安裝和設定驅動程式。
+ [JDBC 驅動程式遷移指南](https://downloads.athena.us-east-1.amazonaws.com/drivers/JDBC/SimbaAthenaJDBC-2.2.2.1000/docs/Simba+Amazon+Athena+JDBC+Connector+Migration+Guide.pdf) 。使用此指南從舊版遷移到目前的版本。
# 使用 ODBC 連接到 Amazon Athena
Amazon Athena 提供兩個 ODBC 驅動程序：版本 1.x 和 2.x。Athena ODBC 2.x 驅動器是支援 Linux、macOS ARM、macOS Intel 和 Windows 64 位元系統的新替代方案。Athena 2.x 驅動程式支援 1.x ODBC 驅動程式支援的所有身分驗證外掛程式，而且幾乎所有連線參數均可回溯相容。
+ 若要下載 ODBC 2.x 驅動程式，請參閱 [Amazon Athena ODBC 2.x](odbc-v2-driver.md)。
+ 若要下載 ODBC 1.x 驅動程式，請參閱 [Athena ODBC 1.x 驅動程式](connect-with-odbc-driver-and-documentation-download-links.md)。
**Topics**
+ [Amazon Athena ODBC 2.x](odbc-v2-driver.md)
+ [Athena ODBC 1.x 驅動程式](connect-with-odbc-driver-and-documentation-download-links.md)
+ [使用 Amazon Athena Power BI 連接器](connect-with-odbc-and-power-bi.md)
# Amazon Athena ODBC 2.x
您可以從許多第三方 SQL 用戶端工具和應用程式使用 ODBC 連線來連接至 Amazon Athena。在您的用戶端電腦上設定 ODBC 連線。
## 考量和限制
如需有關從 Athena ODBC 1.x 驅動程式遷移至 Athena 2.x ODBC 驅動程式的資訊，請參閱 [移轉至 ODBC 2.x 驅動器](odbc-v2-driver-migrating.md)。
## ODBC 2.x 驅動程式下載
若要下載 Amazon Athena 2.x ODBC 驅動器，請造訪此頁面上的連結。
**重要**
當您使用 ODBC 2.x 驅動程式時，務必注意以下要求：
**打開連接埠 444** – 將 Athena 用來串流查詢結果的連接埠 444 保持開放給輸出流量。當您使用 PrivateLink 端點連接到 Athena 時，請確定連接至 PrivateLink 端點的安全群組已在連接埠 444 上開放給輸入流量。
**athena:GetQueryResultsStream 政策** – 新增針對使用 ODBC 驅動程式的 IAM 主體的 `athena:GetQueryResultsStream` 政策動作。此政策動作不會直接透過 API 公開。它僅與 ODBC 和 JDBC 驅動程式搭配使用，做為串流結果支援的一部分。如需政策範例，請參閱 [AWS 受管政策：AWSQuicksightAthenaAccess](security-iam-awsmanpol.md#awsquicksightathenaaccess-managed-policy)。
**重要**
**安全更新：**2.1.0.0 版包含身分驗證、查詢處理和傳輸安全元件的安全增強功能。我們建議您升級至此版本，以從這些改進中獲益。如需詳細資訊，請參閱 [Amazon Athena ODBC 2.x 版本備註](odbc-v2-driver-release-notes.md)。
### Linux
| 驅動程式版本 | 下載連結 |
| --- | --- |
| 適用於 Linux 64 位元的 ODBC 2.1.0.0 | [Linux 64 位元 ODBC 驅動程式 2.1.0.0](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/AmazonAthenaODBC-2.1.0.0.rpm) |
### macOS (ARM)
| 驅動程式版本 | 下載連結 |
| --- | --- |
| 適用於 macOS 64 位元 (ARM) 的 ODBC 2.1.0.0 | [macOS 64 位元 ODBC 驅動程式 2.1.0.0 (ARM)](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Mac/arm/AmazonAthenaODBC-2.1.0.0_arm.pkg) |
### macOS (Intel)
| 驅動程式版本 | 下載連結 |
| --- | --- |
| 適用於 macOS 64 位元 (Intel) 的 ODBC 2.1.0.0 | [macOS 64 位元 ODBC 驅動程式 2.1.0.0 (Intel)](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Mac/Intel/AmazonAthenaODBC-2.1.0.0_x86.pkg) |
### Windows
| 驅動程式版本 | 下載連結 |
| --- | --- |
| 適用於 Windows 64 位元的 ODBC 2.1.0.0 | [Windows 64 位元 ODBC 驅動程式 2.1.0.0](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Windows/AmazonAthenaODBC-2.1.0.0.msi) |
### 授權
+ [AWS 授權](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/LICENSE.txt)
+ [第三方授權](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/THIRD_PARTY_LICENSES.txt)
## 可信身分傳播與 ODBC
您現在可以透過 AWS Identity and Access Management Identity Center 使用具有單一登入功能的 ODBC 驅動程式連線至 Amazon Athena。當您從 PowerBI、Tableau 或 DBeaver 等工具存取 Athena 時，您的身分和許可會透過 IAM Identity Center 自動傳播到 Athena。如需詳細資訊，請參閱[搭配使用可信身分傳播與 Amazon Athena 驅動器](using-trusted-identity-propagation.md)。
**Topics**
+ [考量和限制](#odbc-v2-driver-considerations-limitations)
+ [ODBC 2.x 驅動程式下載](#odbc-v2-driver-download)
+ [可信身分傳播與 ODBC](#odbc-v2-driver-trusted-identity)
+ [ODBC 2.x 驅動器入門](odbc-v2-driver-getting-started.md)
+ [Athena ODBC 2.x 連線參數](odbc-v2-driver-connection-parameters.md)
+ [移轉至 ODBC 2.x 驅動器](odbc-v2-driver-migrating.md)
+ [對 ODBC 2.x 驅動器進行疑難排解](odbc-v2-driver-troubleshooting.md)
+ [Amazon Athena ODBC 2.x 版本備註](odbc-v2-driver-release-notes.md)
# ODBC 2.x 驅動器入門
使用本節中的資訊，開始使用 Amazon Athena ODBC 2.x 驅動程式。Windows、Linux 和 macOS 作業系統支援此驅動器。
**Topics**
+ [Windows](odbc-v2-driver-getting-started-windows.md)
+ [Linux](odbc-v2-driver-getting-started-linux.md)
+ [macOS](odbc-v2-driver-getting-started-macos.md)
# Windows
如果您想要使用 Windows 用戶端電腦存取 Amazon Athena，則需要 Amazon Athena ODBC 驅動器。
## Windows 系統要求
在將直接存取 Amazon Athena 資料庫的用戶端電腦上安裝 Amazon Athena ODBC 驅動程式，而不是使用 Web 瀏覽器。
您使用的 Windows 系統必須符合下述要求：
+ 您擁有管理員權限
+ 下列其中一個操作系統：
+ Windows 11、10 或 8.1
+ Windows Server 2019、2016 或 2012
+ 支援的處理器架構：x86\$164 (64 位元)
+ 至少 100 MB 的可用磁碟空間
+ 已安裝 [Microsoft Visual C\$1\$1 Redistributable for Visual Studio](https://visualstudio.microsoft.com/downloads/#microsoft-visual-c-redistributable-for-visual-studio-2022)，適用於 Windows 64 位元。
## 安裝 Amazon Athena ODBC 驅動程式
**若要下載並安裝適用於 Windows 的 Amazon Athena ODBC 驅動程式**
1. [下載](odbc-v2-driver.md#odbc-v2-driver-download) `AmazonAthenaODBC-2.x.x.x.msi` 安裝檔案。
1. 啟動安裝檔案，然後選擇**下一步**。
1. 若要接受授權協議條款，請選取核取方塊，然後選擇**下一步**。
1. 若要變更安裝位置，請選擇**瀏覽**，瀏覽至所需的資料夾，然後選擇**確定**。
1. 若要接受安裝位置，請選擇**下一步**。
1. 選擇 **Install (安裝)**。
1. 完成安裝時，請選擇**完成**。
## 設定驅動程式組態選項的方法
若要控制 Windows 中 Amazon Athena ODBC 驅動程式的行為，您可以使用下列方式設定驅動程式組態選項：
+ 在 **ODBC 資料來源管理員**中設定資料來源名稱 (DSN) 時。
+ 透過在下列位置新增或變更 Windows 登錄機碼：
```
HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\YOUR_DSN_NAME
```
+ 以程式設計方式連線時，在連線字串中設定驅動程式選項。
## 在 Windows 上設定資料來源名稱
在下載並安裝 ODBC 驅動程式之後，您必須將資料來源名稱 (DSN) 項目新增至用戶端電腦或 Amazon EC2 執行個體。SQL 用戶端工具使用此資料來源以連接至並查詢 Amazon Athena。
**建立系統 DSN 項目**
1. 在 Windows 的**開始**選單中，以滑鼠右鍵按一下 **ODBC 資料來源 (64 位元)**，然後選擇**更多**，**以管理員身分執行**。
1. 在 **ODBC 資料來源管理員**中，選擇**驅動程式**索引標籤。
1. 在**名稱**資料欄中，確認是否存在 **Amazon Athena ODBC (x64)**。
1. 執行以下任意一項：
+ 若要為電腦上的所有使用者設定驅動程式，請選擇**系統 DSN** 索引標籤。由於使用不同帳戶載入資料的應用程式可能無法偵測來自其他帳戶的 DSN，因此建議您使用系統 DSN 組態選項。
**注意**
使用**系統 DSN** 選項需要管理權限。
+ 若要僅為您的使用者帳戶設定驅動程式，請選擇**使用者 DSN** 索引標籤。
1. 選擇**新增**。**建立新資料來源**對話方塊隨即開啟。
1. 選擇 **Amazon Athena ODBC (x64)**，然後選擇**完成**。
1. 請在 **Amazon Athena ODBC 組態**對話方塊中輸入下列資訊。如需這些選項的詳細資訊，請參閱 [主要 ODBC 2.x 連線參數](odbc-v2-driver-main-connection-parameters.md)。
+ 對於**資料來源名稱**，輸入您要用來識別資料來源的名稱。
+ 對於**描述**，輸入描述，以協助您識別資料來源。
+ 對於**區域**，輸入您將在 Athena 中使用的 AWS 區域 的名稱 (例如 ** us-west-1**)。
+ 對於**目錄**，輸入 Amazon Athena 目錄的名稱。預設值為 **AwsDataCatalog**，供 使用 AWS Glue。
+ 對於**資料庫**，輸入 Amazon Athena 資料庫的名稱。預設值為**預設**。
+ 對於**工作群組**，輸入 Amazon Athena 工作群組的名稱。預設值為**主要**。
+ 對於 **S3 輸出位置**，在 Amazon S3 中輸入要存放查詢結果的位置 (例如，**s3://amzn-s3-demo-bucket/**)。
+ (選用) 對於**加密選項**，請選擇加密選項。預設值為 `NOT_SET`。
+ (選用) 對於 **KMS 金鑰**，請視需要選擇加密 KMS 金鑰。
1. 若要指定 IAM 身分驗證的組態選項，請選擇**身分驗證選項。**
1. 輸入下列資訊：
+ 對於**身分驗證類型**，選擇 **IAM 憑證**。這是預設值。如需有關可用身分驗證類型的詳細資訊，請參閱 [身分驗證選項](odbc-v2-driver-authentication-options.md)。
+ 對於**使用者名稱**，輸入使用者名稱。
+ 對於**密碼**，輸入密碼。
+ 對於**工作階段字符**，如果您想要使用臨時 AWS 登入資料，請輸入工作階段字符。如需臨時登入資料的資訊，請參閱《*IAM 使用者指南*》中的[使用臨時登入資料搭配 AWS 資源](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html)。
1. 選擇**確定**。
1. 請在 **Amazon Athena ODBC 組態**對話方塊底部，選擇**測試**。如果用戶端電腦成功連線至 Amazon Athena，**連線測試**方塊會報告**連線成功**。如果沒有，方塊會報告**連線失敗**，並顯示對應的錯誤資訊。
1. 選擇**確定**以關閉連線測試。您建立的資料來源現在會顯示在資料來源清單中。
## 在 Windows 上使用無 DSN 連線
您可以使用無 DSN 連線來連接至沒有資料來源名稱 (DSN) 的資料庫。下列範例顯示連線至 Amazon Athena 的 Amazon Athena ODBC (x64) ODBC 驅動程式的連線字串。
```
DRIVER={Amazon Athena ODBC (x64)};Catalog=AwsDataCatalog;AwsRegion=us-west-1;Schema=test_schema;S3OutputLocation=
s3://amzn-s3-demo-bucket/;AuthenticationType=IAM Credentials;UID=YOUR_UID;PWD=YOUR_PWD;
```
# Linux
如果您想要使用 Linux 用戶端電腦存取 Amazon Athena，則需要 Amazon Athena ODBC 驅動器。
## Linux 系統要求
您安裝驅動器的每一台 Linux 電腦必須符合下列要求。
+ 您擁有根存取權。
+ 使用下列其中一個 Linux 發行版本：
+ Red Hat Enterprise Linux (RHEL) 7 或 8
+ CentOS 7 或 8。
+ 有 100 MB 的可用磁碟空間。
+ 使用 [unixODBC](https://www.unixodbc.org/) 版本 2.3.1 或更新版本。
+ 使用 [GNU C Library](https://www.gnu.org/software/libc/) (glibc) 版本 2.26 或更新版本。
## 在 Linux 上安裝 ODBC 資料連接器
使用下列程序來在 Linux 作業系統上安裝的 Amazon Athena ODBC 驅動器。
**在 Linux 上安裝 Amazon Athena ODBC 驅動器**
1. 輸入下列其中一個命令：
```
sudo rpm -Uvh AmazonAthenaODBC-2.X.Y.Z.rpm
```
或
```
sudo yum --nogpgcheck localinstall AmazonAthenaODBC-2.X.Y.Z.rpm
```
1. 安裝完成後，輸入下列其中一個命令，以驗證驅動器已安裝：
+
```
yum list | grep amazon-athena-odbc-driver
```
輸出：
```
amazon-athena-odbc-driver.x86_64 2.0.2.1-1.amzn2int installed
```
+
```
rpm -qa | grep amazon
```
輸出：
```
amazon-athena-odbc-driver-2.0.2.1-1.amzn2int.x86_64
```
## 在 Linux 上設定資料來源名稱
安裝驅動器後，您可以在下列位置中找到 `.odbc.ini` 和 `.odbcinst.ini` 檔案的範例：
+ `/opt/athena/odbc/ini/`.
使用 `.ini` 檔案作為設定 Amazon Athena ODBC 驅動器和資料來源名稱 (DSN) 的範例。
**注意**
依預設，ODBC 驅動器管理員會使用隱藏的組態檔案 `.odbc.ini` 和 `.odbcinst.ini`，這些組態檔案位於主目錄中。
若要使用 unixODBC 指定 `.odbc.ini` 和 `.odbcinst.ini` 檔案的路徑，請執行下列步驟。
**使用 unixODBC 指定 ODBC `.ini` 檔案位置**
1. 將 `ODBCINI` 設定為 `odbc.ini` 檔案的完整路徑和檔案名稱，如下列範例所示。
```
export ODBCINI=/opt/athena/odbc/ini/odbc.ini
```
1. 將 `ODBCSYSINI` 設定為包含 `odbcinst.ini` 檔案之目錄的完整路徑，如下列範例所示。
```
export ODBCSYSINI=/opt/athena/odbc/ini
```
1. 輸入下列命令，以驗證您使用的是 unixODBC 驅動器管理員且 `odbc*.ini` 檔案正確無誤：
```
username % odbcinst -j
```
範例輸出
```
unixODBC 2.3.1
DRIVERS............: /opt/athena/odbc/ini/odbcinst.ini
SYSTEM DATA SOURCES: /opt/athena/odbc/ini/odbc.ini
FILE DATA SOURCES..: /opt/athena/odbc/ini/ODBCDataSources
USER DATA SOURCES..: /opt/athena/odbc/ini/odbc.ini
SQLULEN Size.......: 8
SQLLEN Size........: 8
SQLSETPOSIROW Size.: 8
```
1. 如果您想要使用資料來源名稱 (DSN) 連線至資料存放區，請設定 `odbc.ini` 檔案來定義資料來源名稱 (DSN)。在 `odbc.ini` 檔案中設定屬性，以建立 DSN 來指定資料存放區的連線資訊，如下列範例所示。
```
[ODBC Data Sources]
athena_odbc_test=Amazon Athena ODBC (x64)
[ATHENA_WIDE_SETTINGS] # Special DSN-name to signal driver about logging configuration.
LogLevel=0 # To enable ODBC driver logs, set this to 1.
UseAwsLogger=0 # To enable AWS-SDK logs, set this to 1.
LogPath=/opt/athena/odbc/logs/ # Path to store the log files. Permissions to the location are required.
[athena_odbc_test]
Driver=/opt/athena/odbc/lib/libathena-odbc.so
AwsRegion=us-west-1
Workgroup=primary
Catalog=AwsDataCatalog
Schema=default
AuthenticationType=IAM Credentials
UID=
PWD=
S3OutputLocation=s3://amzn-s3-demo-bucket/
```
1. 設定 `odbcinst.ini` 檔案，如下列範例所示。
```
[ODBC Drivers]
Amazon Athena ODBC (x64)=Installed
[Amazon Athena ODBC (x64)]
Driver=/opt/athena/odbc/lib/libathena-odbc.so
Setup=/opt/athena/odbc/lib/libathena-odbc.so
```
1. 安裝和設定 Amazon Athena ODBC 驅動器之後，請使用 unixODBC `isql` 命令列工具來驗證連線，如下列範例所示。
```
username % isql -v "athena_odbc_test"
+---------------------------------------+
| Connected! |
| |
| sql-statement |
| help [tablename] |
| quit |
| |
+---------------------------------------+
SQL>
```
## 驗證 ODBC 驅動器簽章
**重要**
我們建議您先驗證 Athena ODBC 驅動器 RPM 簽章，然後再將其安裝在您的電腦上。
依照以下步驟，驗證 Athena ODBC 驅動器 RPM 套件的簽章：
1. **準備範本**
準備命令時，請使用適當的公有金鑰、RPM 簽章和 Amazon S3 儲存貯體中託管的 RPM 指令碼的對應存取連結。您必須將下列項目下載至您的裝置。
+ [Athena ODBC 驅動器](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/AmazonAthenaODBC-2.1.0.0.rpm)
+ [公有金鑰](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/public_key.pem)
+ [Athena ODBC RPM 簽章](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/v2.1.0.0/Linux/signature.bin)
1. 將 Athena ODBC 驅動器、公有金鑰和 Athena ODBC RPM 簽章下載至您的裝置。
1. 執行下列命令，驗證 ODBC 驅動器簽章：
```
openssl dgst -sha256 -verify public_key.pem -signature signature.bin AmazonAthenaODBC-2.1.0.0.rpm
```
如果驗證通過，您將會看到類似 `Verified OK` 的訊息。這表示您現在可以繼續安裝 Athena ODBC 驅動器。
如果失敗並顯示訊息 `Verification Failure`，則表示 RPM 上的簽章已遭到竄改。請確保步驟 1 中提及的所有三個檔案都存在、路徑已正確指定，而且檔案自下載後未曾修改，然後重試驗證程序。
# macOS
如果您想要使用 macOS 用戶端電腦存取 Amazon Athena，則需要 Amazon Athena ODBC 驅動器。
## macOS 系統要求
您安裝驅動器的每一台 macOS 電腦必須符合下列要求。
+ 使用 macOS 版本 14 或更新版本。
+ 有 100 MB 的可用磁碟空間。
+ 使用 [iODBC](https://www.iodbc.org/dataspace/doc/iodbc/wiki/iodbcWiki/WelcomeVisitors) 版本 3.52.16 或更新版本。
## 在 macOS 上安裝 ODBC 資料連接器
使用下列程序來下載並安裝適用於 macOS 作業系統的 Amazon Athena ODBC 驅動器。
**下載並安裝適用於 macOS 的 Amazon Athena ODBC 驅動器**
1. 下載 `.pkg` 套件檔案。
1. 按兩下 `.pkg` 檔案。
1. 請遵循精靈中的步驟安裝驅動器。
1. 在**授權合約**頁面上，按下**繼續**，然後選擇**同意**。
1. 選擇 **Install (安裝)**。
1. 完成安裝時，請選擇**完成**。
1. 輸入下列命令，以驗證已安裝驅動器：
```
> pkgutil --pkgs | grep athenaodbc
```
根據您的系統，輸出如下列其中之一所示。
```
com.amazon.athenaodbc-x86_64.Config
com.amazon.athenaodbc-x86_64.Driver
```
或
```
com.amazon.athenaodbc-arm64.Config
com.amazon.athenaodbc-arm64.Driver
```
## 在 macOS 上設定資料來源名稱
安裝驅動器後，您可以在下列位置中找到 `.odbc.ini` 和 `.odbcinst.ini` 檔案的範例：
+ Intel 處理器電腦：`/opt/athena/odbc/x86_64/ini/`
+ ARM 處理器電腦：`/opt/athena/odbc/arm64/ini/`
使用 `.ini` 檔案作為設定 Amazon Athena ODBC 驅動器和資料來源名稱 (DSN) 的範例。
**注意**
依預設，ODBC 驅動器管理員會使用隱藏的組態檔案 `.odbc.ini` 和 `.odbcinst.ini`，這些組態檔案位於主目錄中。
若要使用 iODBC 驅動器管理員指定 `.odbc.ini` 和 `.odbcinst.ini` 檔案的路徑，請執行下列步驟。
**使用 iODBC 驅動器管理員指定 ODBC `.ini` 檔案位置**
1. 將 `ODBCINI` 設定為 `odbc.ini` 檔案的完整路徑和檔案名稱。
+ 對於具有 Intel 處理器的 macOS 電腦，請使用下列語法。
```
export ODBCINI=/opt/athena/odbc/x86_64/ini/odbc.ini
```
+ 對於具有 ARM 處理器的 macOS 電腦，請使用下列語法。
```
export ODBCINI=/opt/athena/odbc/arm64/ini/odbc.ini
```
1. 將 `ODBCSYSINI` 設定為 `odbcinst.ini` 檔案的完整路徑和檔案名稱。
+ 對於具有 Intel 處理器的 macOS 電腦，請使用下列語法。
```
export ODBCSYSINI=/opt/athena/odbc/x86_64/ini/odbcinst.ini
```
+ 對於具有 ARM 處理器的 macOS 電腦，請使用下列語法。
```
export ODBCSYSINI=/opt/athena/odbc/arm64/ini/odbcinst.ini
```
1. 如果您想要使用資料來源名稱 (DSN) 連線至資料存放區，請設定 `odbc.ini` 檔案來定義資料來源名稱 (DSN)。在 `odbc.ini` 檔案中設定屬性，以建立 DSN 來指定資料存放區的連線資訊，如下列範例所示。
```
[ODBC Data Sources]
athena_odbc_test=Amazon Athena ODBC (x64)
[ATHENA_WIDE_SETTINGS] # Special DSN-name to signal driver about logging configuration.
LogLevel=0 # set to 1 to enable ODBC driver logs
UseAwsLogger=0 # set to 1 to enable AWS-SDK logs
LogPath=/opt/athena/odbc/logs/ # Path to store the log files. Permissions to the location are required.
[athena_odbc_test]
Description=Amazon Athena ODBC (x64)
# For ARM:
Driver=/opt/athena/odbc/arm64/lib/libathena-odbc-arm64.dylib
# For Intel:
# Driver=/opt/athena/odbc/x86_64/lib/libathena-odbc-x86_64.dylib
AwsRegion=us-west-1
Workgroup=primary
Catalog=AwsDataCatalog
Schema=default
AuthenticationType=IAM Credentials
UID=
PWD=
S3OutputLocation=s3://amzn-s3-demo-bucket/
```
1. 設定 `odbcinst.ini` 檔案，如下列範例所示。
```
[ODBC Drivers]
Amazon Athena ODBC (x64)=Installed
[Amazon Athena ODBC (x64)]
# For ARM:
Driver=/opt/athena/odbc/arm64/lib/libathena-odbc-arm64.dylib
Setup=/opt/athena/odbc/arm64/lib/libathena-odbc-arm64.dylib
# For Intel:
# Driver=/opt/athena/odbc/x86_64/lib/libathena-odbc-x86_64.dylib
# Setup=/opt/athena/odbc/x86_64/lib/libathena-odbc-x86_64.dylib
```
1. 安裝和設定 Amazon Athena ODBC 驅動器之後，請使用 `iodbctest` 命令列工具來驗證連線，如下列範例所示。
```
username@ % iodbctest
iODBC Demonstration program
This program shows an interactive SQL processor
Driver Manager: 03.52.1623.0502
Enter ODBC connect string (? shows list): ?
DSN | Driver
------------------------------------------------------------------------------
athena_odbc_test | Amazon Athena ODBC (x64)
Enter ODBC connect string (? shows list): DSN=athena_odbc_test;
Driver: 2.0.2.1 (Amazon Athena ODBC Driver)
SQL>
```
# Athena ODBC 2.x 連線參數
**Amazon Athena ODBC 組態**對話訪客選項包括**身分驗證選項**、**進階選項**、**記錄選項**、**端點覆寫**和**代理選項**。如需有關各項內容的詳細資訊，請造訪相應的連結。
+ [主要 ODBC 2.x 連線參數](odbc-v2-driver-main-connection-parameters.md)
+ [身分驗證選項](odbc-v2-driver-authentication-options.md)
+ [進階選項](odbc-v2-driver-advanced-options.md)
+ [記錄選項](odbc-v2-driver-logging-options.md)
+ [端點覆寫](odbc-v2-driver-endpoint-overrides.md)
+ [代理選項](odbc-v2-driver-proxy-options.md)
# 主要 ODBC 2.x 連線參數
下列各節會描述每個主要連線參數。
## 資料來源名稱
指定資料來源的名稱。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| DSN | 無 DSN 連線類型的選用項目 | none | DSN=AmazonAthenaOdbcUsWest1; |
## Description
包含資料來源的描述。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| Description | 選用 | none | Description=Connection to Amazon Athena us-west-1; |
## 目錄
指定資料目錄名稱。如需有關目錄的詳細資訊，請參閱《Amazon Athena API 參考》中的 [DataCatalog](https://docs.aws.amazon.com/athena/latest/APIReference/API_DataCatalog.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 目錄 | 選用 | AwsDataCatalog | Catalog=AwsDataCatalog; |
## 區域
指定 AWS 區域。如需 的詳細資訊 AWS 區域，請參閱 [區域和可用區域](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AwsRegion | 強制性 | none | AwsRegion=us-west-1; |
## 資料庫
指定資料庫名稱。如需有關資料庫的詳細資訊，請參閱《Amazon Athena API 參考》**中的[資料庫](https://docs.aws.amazon.com/athena/latest/APIReference/API_Database.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 結構描述 | 選用 | default | Schema=default; |
## 工作群組
指定工作群組名稱。如需有關工作群組的詳細資訊，請參閱《Amazon Athena API 參考》**中的 [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 工作群組 | 選用 | primary | Workgroup=primary; |
## 輸出位置
指定 Amazon S3 中儲存查詢結果的位置。如需有關輸出位置的詳細資訊，請參閱《Amazon Athena API 參考》**中的 [ResultConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| S3OutputLocation | 強制性 | none | S3OutputLocation=s3://amzn-s3-demo-bucket/; |
## 加密選項
**對話方塊參數名稱**：加密選項
指定加密選項。如需有關加密選項的詳細資訊，請參閱《Amazon Athena API 參考》**中的 [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **可能的值** | **連線字串範例** |
| --- | --- | --- | --- | --- |
| S3OutputEncOption | 選用 | none | NOT\$1SET, SSE\$1S3, SSE\$1KMS, CSE\$1KMS | S3OutputEncOption=SSE\$1S3; |
## KMS 金鑰
指定要加密的 KMS 金鑰。如需有關 KMS 金鑰的加密組態的詳細資訊，請參閱《Amazon Athena API 參考》**中的加密 [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| S3OutputEncKMSKey | 選用 | none | S3OutputEncKMSKey=your\$1key; |
## 連線測試
ODBC 資料來源管理員提供**測試**選項，您可以用來測試 ODBC 2.x 與 Amazon Athena 的連線。如需這些步驟，請參閱 [在 Windows 上設定資料來源名稱](odbc-v2-driver-getting-started-windows.md#odbc-v2-driver-configuring-dsn-on-windows)。當您測試連線時，ODBC 驅動程式會呼叫 [GetWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetWorkGroup.html) Athena API 動作。呼叫會使用您指定的身分驗證類型和對應的憑證提供者來擷取憑證。使用 ODBC 2.x 驅動程式時，可免費使用連線測試。測試不會在您的 Amazon S3 儲存貯體中產生查詢結果。
# 身分驗證選項
您可以使用下列身分驗證類型連線至 Amazon Athena。對於所有類型，連線字串名稱為 `AuthenticationType`，參數類型為 `Required`，預設值為 `IAM Credentials`。如需有關每種身分驗證類型的參數的資訊，請造訪對應的連結。如需常用身分驗證參數，請參閱 [常用身分驗證參數](odbc-v2-driver-common-authentication-parameters.md)。
****
| 身分驗證類型 | 連線字串範例 |
| --- | --- |
| [IAM 憑證](odbc-v2-driver-iam-credentials.md) | AuthenticationType=IAM Credentials; |
| [IAM 設定檔](odbc-v2-driver-iam-profile.md) | AuthenticationType=IAM Profile; |
| [AD FS](odbc-v2-driver-ad-fs.md) | AuthenticationType=ADFS; |
| [Azure AD](odbc-v2-driver-azure-ad.md) | AuthenticationType=AzureAD; |
| [瀏覽器 Azure AD](odbc-v2-driver-browser-azure-ad.md) | AuthenticationType=BrowserAzureAD; |
| [瀏覽器 SAML](odbc-v2-driver-browser-saml.md) | AuthenticationType=BrowserSAML; |
| [瀏覽器 SSO OIDC](odbc-v2-driver-browser-sso-oidc.md) | AuthenticationType=BrowserSSOOIDC; |
| [預設憑證](odbc-v2-driver-default-credentials.md) | AuthenticationType=Default Credentials; |
| [外部憑證](odbc-v2-driver-external-credentials.md) | AuthenticationType=External Credentials; |
| [執行個體設定檔](odbc-v2-driver-instance-profile.md) | AuthenticationType=Instance Profile; |
| [JWT](odbc-v2-driver-jwt.md) | AuthenticationType=JWT; |
| [JWT 可信身分傳播憑證提供者](odbc-v2-driver-jwt-tip.md) | AuthenticationType=JWT\$1TIP; |
| [瀏覽器信任的身分傳播憑證](odbc-v2-driver-browser-oidc-tip.md) | AuthenticationType=BrowserOidcTip; |
| [Okta](odbc-v2-driver-okta.md) | AuthenticationType=Okta; |
| [Ping](odbc-v2-driver-ping.md) | AuthenticationType=Ping; |
# IAM 憑證
您可以使用 IAM 憑證，以使用本節所述的連線字串參數，透過 ODBC 驅動程式連線至 Amazon Athena。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=IAM Credentials; |
## 使用者 ID
您的 AWS 存取金鑰 ID。如需有關存取金鑰的詳細資訊，請參閱《*IAM 使用者指南*》中的 [AWS 安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UID | 必要 | none | UID=AKIAIOSFODNN7EXAMPLE; |
## 密碼
您的 AWS 私密金鑰 ID。如需有關存取金鑰的詳細資訊，請參閱《*IAM 使用者指南*》中的 [AWS 安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| PWD | 必要 | none | PWD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKE; |
## 工作階段字符
如果您使用臨時 AWS 登入資料，則必須指定工作階段字符。如需有關暫時憑證的資訊，請參閱《*IAM 使用者指南*》中的 [IAM 中的暫時安全憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| SessionToken | 選用 | none | SessionToken=AQoDYXdzEJr...; |
# IAM 設定檔
您可以將具名設定檔設定為使用 ODBC 驅動程式連線到 Amazon Athena。您可以使用具名設定檔搭配下列其中一個登入資料來源：
+ `Ec2InstanceMetadata` – 從 Amazon EC2 執行個體中繼資料服務 (IMDS) 擷取憑證。在 Amazon EC2 執行個體上執行時使用此值。
+ `EcsContainer` – 從 Amazon ECS 任務角色端點擷取登入資料。在 Amazon ECS 容器中執行時使用此值。
+ `Environment` – 從環境變數 (`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、) 擷取登入資料`AWS_SESSION_TOKEN`。
將 AWS 設定檔組態中的 `credential_source` 參數設定為適合您環境的值。如果您要在具名設定檔中使用自訂憑證提供者，請在設定檔組態中指定 `plugin_name` 參數的值。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=IAM Profile; |
## AWS 設定檔
用於 ODBC 連線的設定檔名稱。如需有關描述檔的詳細資訊，請參閱《 *AWS Command Line Interface 使用者指南》*中的[使用具名描述檔](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AWS設定檔 | 必要 | none | AWSProfile=default; |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。當設定檔組態中的 `plugin_name` 參數指定自訂憑證提供者時，將使用偏好角色參數。如需有關 ARN 角色的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| preferred\$1role | 選用 | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; |
## 工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需有關工作階段持續時間的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。當設定檔組態中的 `plugin_name` 參數指定自訂憑證提供者時，將使用工作階段持續時間參數。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 持續時間 | 選用 | 900 | duration=900; |
## 外掛程式名稱
指定在具名設定檔中使用的自訂憑證提供者名稱。此參數可以採用與「ODBC 資料來源管理員」的「**驗證類型**」欄位中的值相同，但僅供 `AWSProfile` 組態使用。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| plugin\$1name | 選用 | none | plugin\$1name=AzureAD; |
# AD FS
AD FS 是 SAML 型身分驗證外掛程式，可與 Active Directory Federation Service (AD FS) 身分提供者搭配使用。該外掛程式支援[整合式 Windows 身分驗證](https://learn.microsoft.com/en-us/aspnet/web-api/overview/security/integrated-windows-authentication)和表單型身分驗證。如果您使用整合式 Windows 身分驗證，則可以省略使用者名稱和密碼。如需有關設定 AD FS 和 Athena 的資訊，請參閱 [使用 ODBC 用戶端為 Microsoft AD FS 使用者設定對 Amazon Athena 的聯合存取權](odbc-adfs-saml.md)。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=ADFS; |
## 使用者 ID
連線至 AD FS 伺服器的使用者名稱。對於整合式 Windows 身分驗證，您可以省略使用者名稱。如果您的 AD FS 設定需要使用者名稱，您必須在連線參數中予以提供。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UID | 對 Windows 整合式身分驗證為選用 | none | UID=domain\$1username; |
## 密碼
連線至 AD FS 伺服器的密碼。如同使用者名稱欄位，如果您使用整合式 Windows 身分驗證，您可以省略使用者名稱。如果您的 AD FS 設定需要密碼，您必須在連線參數中予以提供。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| PWD | 對 Windows 整合式身分驗證為選用 | none | PWD=password\$13EXAMPLE; |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如果您的 SAML 聲明具有多個角色，您可以指定此參數來選擇要擔任的角色。此角色應出現在 SAML 聲明中。如需有關 ARN 角色的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| preferred\$1role | 選用 | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; |
## 工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需有關工作階段持續時間的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 持續時間 | 選用 | 900 | duration=900; |
## IdP 主機
AD FS 服務主機的名稱。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| idp\$1host | 必要 | none | idp\$1host=.; |
## IdP 連接埠
用於連線至 AD FS 主機的連接埠。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| idp\$1port | 必要 | none | idp\$1port=443; |
## LoginToRP
可信依賴方。使用此參數來覆寫 AD FS 依賴方端點 URL。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| LoginToRP | 選用 | urn:amazon:webservices | LoginToRP=trustedparty; |
# Azure AD
Azure AD 是 SAML 型身分驗證外掛程式，可與 Azure AD 身分提供者搭配使用。本外掛程式不支援多重要素驗證 (MFA)。如果您需要 MFA 支援，請考慮改用 `BrowserAzureAD` 外掛程式。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=AzureAD; |
## 使用者 ID
連線至 Azure AD 的使用者名稱。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UID | 必要 | none | UID=jane.doe@example.com; |
## 密碼
連線至 Azure AD 的密碼。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| PWD | 必要 | none | PWD=password\$13EXAMPLE; |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如需有關 ARN 角色的資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| preferred\$1role | 選用 | none | preferred\$1role=arn:aws:iam::123456789012:id/user1; |
## 工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 持續時間 | 選用 | 900 | duration=900; |
## 租用戶 ID
指定您的應用程式租用戶 ID。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| idp\$1tenant | 必要 | none | idp\$1tenant=123zz112z-z12d-1z1f-11zz-f111aa111234; |
## 用戶端 ID
指定您的應用程式用戶端 ID。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| client\$1id | 必要 | none | client\$1id=9178ac27-a1bc-1a2b-1a2b-a123abcd1234; |
## Client secret (用戶端密碼)
指定您的用戶端密碼。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| client\$1secret | 必要 | none | client\$1secret=zG12q\$1.xzG1xxxZ1wX1.\$1ZzXXX1XxkHZizeT1zzZ; |
# 瀏覽器 Azure AD
瀏覽器 Azure AD 是 SAML 型身分驗證外掛程式，可與 Azure AD 身分提供者搭配使用並支援多重因素認證。與標準 Azure AD 外掛程式不同，此外掛程式不需要連線參數中的使用者名稱、密碼或用戶端密碼。
**注意**
**v2.1.0.0 安全更新：**從 v2.1.0.0 開始，BrowserAzureAD 外掛程式在 OAuth 2.0 授權流程中包含 PKCE （程式碼交換的驗證金鑰）。這可防止授權碼攔截對共用系統的攻擊。不需要變更組態。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=BrowserAzureAD; |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如果您的 SAML 聲明具有多個角色，您可以指定此參數來選擇要擔任的角色。指定的角色應出現在 SAML 聲明中。如需有關 ARN 角色的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| preferred\$1role | 選用 | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; |
## 工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需有關工作階段持續時間的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 持續時間 | 選用 | 900 | duration=900; |
## 租用戶 ID
指定您的應用程式租用戶 ID。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| idp\$1tenant | 必要 | none | idp\$1tenant=123zz112z-z12d-1z1f-11zz-f111aa111234; |
## 用戶端 ID
指定您的應用程式用戶端 ID。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| client\$1id | 必要 | none | client\$1id=9178ac27-a1bc-1a2b-1a2b-a123abcd1234; |
## Timeout (逾時)
外掛程式停止等待來自 Azure AD 之 SAML 回應之前的持續時間 (以秒為單位)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| timeout | 選用 | 120 | timeout=90; |
## 啟用 Azure 檔案快取
啟用臨時憑證快取。此連線參數可讓您在多個程序之間快取，及重複使用臨時憑證。使用此選項可減少當您使用 BI 工具 (如 Microsoft Power BI) 時，開啟瀏覽器視窗的數目。
**注意**
從 v2.1.0.0 開始，快取的憑證會以純文字 JSON 形式存放在 `user-profile/.athena-odbc/`目錄中，檔案許可僅限於擁有的使用者，與 AWS CLI 保護本機儲存憑證的方式一致。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| browser\$1azure\$1cache | 選用 | 1 | browser\$1azure\$1cache=0; |
# 瀏覽器 SAML
瀏覽器 SAML 是一般身分驗證外掛程式，可與 SAML 型身分提供者搭配使用並支援多重因素認證。如需詳細的組態資訊，請參閱 [使用 ODBC、SAML 2.0 和 Okta 身分提供者設定單一登入](okta-saml-sso.md)。
**注意**
**v2.1.0.0 安全性更新：**從 v2.1.0.0 開始，BrowserSAML 外掛程式會透過 RelayState 驗證包含 CSRF 保護。驅動程式會產生隨機狀態字符，將其做為 RelayState 參數包含在登入 URL 中，並在接受 SAML 聲明之前針對收到的回應進行驗證。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=BrowserSAML; |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如果您的 SAML 聲明具有多個角色，您可以指定此參數來選擇要擔任的角色。此角色應出現在 SAML 聲明中。如需有關 ARN 角色的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| preferred\$1role | 選用 | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; |
## 工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 持續時間 | 選用 | 900 | duration=900; |
## 登入 URL
為您的應用程式顯示的單一登入 URL。
**重要**
從 v2.1.0.0 開始，登入 URL 必須使用具有有效授權的 HTTP 或 HTTPS 通訊協定。驅動程式會在啟動身分驗證流程之前驗證 URL 格式。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| login\$1url | 必要 | none | login\$1url=https://trial-1234567.okta.com/app/trial-1234567\$1oktabrowsersaml\$11/zzz4izzzAzDFBzZz1234/sso/saml; |
## 接聽連接埠
用來接聽 SAML 回應的連接埠號碼。此值應與您設定 IdP 時使用的 IAM Identity Center URL 相符 (例如，`http://localhost:7890/athena`)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| listen\$1port | 選用 | 7890 | listen\$1port=7890; |
## Timeout (逾時)
外掛程式停止等待來自身分提供者的 SAML 回應之前的持續時間 (以秒為單位)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| timeout | 選用 | 120 | timeout=90; |
# 瀏覽器 SSO OIDC
瀏覽器 SSO OIDC 是可與 搭配使用的身分驗證外掛程式 AWS IAM Identity Center。如需有關啟用和使用 IAM Identity Center 的資訊，請參閱《*AWS IAM Identity Center 使用者指南*》中的[步驟 1：啟用 IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/get-started-enable-identity-center.html)
**注意**
**v2.1.0.0 安全更新：**從 2.1.0.0 版開始，BrowserSSOOIDC 外掛程式使用授權碼搭配 PKCE 而非裝置碼授權，以提高安全性。此變更會消除裝置程式碼顯示步驟，並提供更快速的身分驗證。OAuth 2.0 回呼伺服器會使用新`listen_port`參數 （預設 7890)。您可能需要允許列出您網路上的此連接埠。預設範圍已變更為 `sso:account:access`。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=BrowserSSOOIDC; |
## IAM Identity Center 啟動 URL
AWS 存取入口網站的 URL。IAM Identity Center [RegisterClient](https://docs.aws.amazon.com/singlesignon/latest/OIDCAPIReference/API_RegisterClient.html) API 動作會將此值用於 `issuerUrl` 參數。
**複製 AWS 存取入口網站 URL**
1. 登入 AWS 管理主控台 並在 https：//[https://console.aws.amazon.com/singlesignon/](https://console.aws.amazon.com/singlesignon/) 開啟 AWS IAM Identity Center 主控台。
1. 在導覽窗格中，選擇**設定**。
1. 在**設定**頁面的**身分來源**下，選擇 **AWS 存取入口網站 URL** 的剪貼簿圖示。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| sso\$1oidc\$1start\$1url | 必要 | none | sso\$1oidc\$1start\$1url=https://app\$1id.awsapps.com/start; |
## IAM Identity Center 區域
設定 SSO AWS 區域 的 。`SSOOIDCClient` 和 `SSOClient` AWS SDK 用戶端會針對 `region` 參數使用此值。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| sso\$1oidc\$1region | 必要 | none | sso\$1oidc\$1region=us-east-1; |
## 範圍
用戶端所定義的範圍清單。授權後，此清單會在授予存取字符時限制許可。IAM Identity Center [RegisterClient](https://docs.aws.amazon.com/singlesignon/latest/OIDCAPIReference/API_RegisterClient.html) API 動作會將此值用於 `scopes` 參數。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| sso\$1oidc\$1scopes | 選用 | sso:account:access | sso\$1oidc\$1scopes=sso:account:access; |
## 帳戶 ID
AWS 帳戶 指派給使用者的 識別符。IAM Identity Center [GetRoleCredentials](https://docs.aws.amazon.com/singlesignon/latest/PortalAPIReference/API_GetRoleCredentials.html) API 使用此值做為 `accountId` 參數。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| sso\$1oidc\$1account\$1id | 必要 | none | sso\$1oidc\$1account\$1id=123456789123; |
## 角色名稱
指派給使用者的角色的易記名稱。您為此許可集指定的名稱會在 AWS 存取入口網站中顯示為可用角色。IAM Identity Center [GetRoleCredentials](https://docs.aws.amazon.com/singlesignon/latest/PortalAPIReference/API_GetRoleCredentials.html) API 使用此值做為 `roleName` 參數。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| sso\$1oidc\$1role\$1name | 必要 | none | sso\$1oidc\$1role\$1name=AthenaReadAccess; |
## Timeout (逾時)
輪詢 SSO API 應檢查存取字符的秒數。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| sso\$1oidc\$1timeout | 選用 | 120 | sso\$1oidc\$1timeout=60; |
## 接聽連接埠
用於 OAuth 2.0 回呼伺服器的本機連接埠號碼。這用作重新導向 URI，您可能需要允許列出網路上的此連接埠。預設產生的重新導向 URI 為：`http://localhost:7890/athena`。此參數已在 v2.1.0.0 中新增，做為從 Device Code 遷移至 Authorization Code with PKCE 的一部分。
**警告**
在 Windows Terminal Server 或遠端桌面服務等共用環境中，循環連接埠 （預設值：7890) 會在相同機器上的所有使用者之間共用。系統管理員可以透過下列方式降低潛在的連接埠劫持風險：
為不同的使用者群組設定不同的連接埠號碼
使用 Windows 安全政策來限制連接埠存取
在使用者工作階段之間實作網路隔離
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| listen\$1port | 選用 | 7890 | listen\$1port=8080; |
## 啟用檔案快取
啟用臨時憑證快取。此連線參數可讓您在多個程序之間快取，及重複使用臨時憑證。使用此選項可減少當您使用 BI 工具 (如 Microsoft Power BI) 時，開啟瀏覽器視窗的數目。
**注意**
從 v2.1.0.0 開始，快取的憑證會以純文字 JSON 形式存放在 `user-profile/.athena-odbc/`目錄中，檔案許可僅限於擁有的使用者，與 AWS CLI 保護本機儲存憑證的方式一致。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| sso\$1oidc\$1cache | 選用 | 1 | sso\$1oidc\$1cache=0; |
# 預設憑證
您可以使用在用戶端系統上設定的預設憑證連線至 Amazon Athena。如需有關使用預設憑證的資訊，請參閱《*適用於 Java 的 AWS SDK 開發人員指南*》中的[使用預設憑證提供者鏈結](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default)。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=Default Credentials; |
# 外部憑證
外部憑證的一般身分驗證外掛程式，可用來連線至任何外部 SAML 型身分提供者的外掛程式。若要使用外掛程式，您可以傳遞可傳回 SAML 回應的可執行檔。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=External Credentials; |
## 可執行路徑
包含自訂 SAML 型憑證提供者的邏輯的可執行檔路徑。可執行檔的輸出必須是身分提供者所解析的 SAML 回應。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| ExecutablePath | 必要 | none | ExecutablePath=C:\$1Users\$1user\$1name\$1external\$1credential.exe |
## 引數清單
您要傳遞至可執行檔的引數清單。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| ArgumentList | 選用 | none | ArgumentList=arg1 arg2 arg3 |
# 執行個體設定檔
此身份驗證類型用於 EC2 執行個體，並透過 Amazon EC2 中繼資料服務傳遞。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=Instance Profile; |
# JWT
JWT (JSON Web Token) 外掛程式提供了一個介面，該介面使用 JSON Web Token 來擔任 Amazon IAM 角色。組態取決於身分提供者。如需設定 Google Cloud 聯合的相關資訊 AWS，請參閱 Google Cloud 文件中的[使用 AWS 或 Azure 設定工作負載聯合身分](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds)。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=JWT; |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如需有關 ARN 角色的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| preferred\$1role | 選用 | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; |
## 工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需有關工作階段持續時間的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 持續時間 | 選用 | 900 | duration=900; |
## JSON Web Token
用於使用 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) AWS STS API 動作擷取 IAM 臨時登入資料的 JSON Web 字符。如需有關為 Google Cloud Platform (GCP) 使用者產生 JSON Web Token 的資訊，請參閱 Google Cloud 文件中的[使用 JWT OAuth 字符](https://cloud.google.com/apigee/docs/api-platform/security/oauth/using-jwt-oauth)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| web\$1identity\$1token | 必要 | none | web\$1identity\$1token=eyJhbGc...; |
## 角色工作階段名稱
工作階段的名稱。一種常見技術是將應用程式使用者的名稱或識別符用作角色工作階段名稱。這可方便地將您應用程式使用的暫時安全憑證與對應的使用者建立關聯。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| role\$1session\$1name | 必要 | none | role\$1session\$1name=familiarname; |
# JWT 可信身分傳播憑證提供者
此身分驗證類型允許您使用從外部身分提供者獲得的 JSON Web Token (JWT) 作為連線參數，向 Athena 進行身分驗證。您可以使用此外掛程式，透過可信身分傳播啟用對企業身分的支援。
透過信任的身分傳播，身分內容會新增至 IAM 角色，以識別請求存取 AWS 資源的使用者。如需有關啟用和使用可信身分傳播的資訊，請參閱[什麼是可信身分傳播？](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html)。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=JWT\$1TIP; |
## JWT web 身分權杖
從外部聯合身分提供者獲得的 JWT 權杖。此權杖將用於向 Athena 進行身分驗證。權杖快取預設為啟用，並允許在不同的驅動器連線之間使用相同的 Identity Center 存取權杖。我們建議在「測試連線」時提供新的 JWT 權杖，因為交換的權杖僅在驅動器執行個體處於作用中狀態期間才會存在。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| web\$1identity\$1token | 必要 | none | web\$1identity\$1token=eyJhbGc...; |
## 工作群組 Arn
Amazon Athena 工作群組的 Amazon Resource Name (ARN)。如需有關工作群組的詳細資訊，請參閱[工作群組](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| WorkGroupArn | 必要 | none | WorkgroupArn=arn:aws:athena:us-west-2:111122223333:workgroup/primary |
## JWT 應用程式角色 ARN
要擔任的角色 ARN。此角色可用於 JWT 交換、透過工作群組標籤取得 IAM Identity Center 客戶自管應用程式 ARN，以及取得存取角色 ARN。如需有關擔任角色的詳細資訊，請參閱 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| ApplicationRoleArn | 必要 | none | ApplicationRoleArn=arn:aws:iam::111122223333:role/applicationRole; |
## 角色工作階段名稱
工作階段的名稱。名稱可隨意指定，但是一般來說，您會傳遞與應用程式使用者相關聯的名稱或識別碼。這樣一來，應用程式使用的臨時安全憑證會與該使用者相關聯。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| role\$1session\$1name | 必要 | none | role\$1session\$1name=familiarname; |
## 工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需有關工作階段持續時間的詳細資訊，請參閱 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 持續時間 | 選用 | 3600 | duration=900; |
## JWT 存取角色 ARN
要擔任的角色 ARN。此為 Athena 擔任的角色，可代表您進行呼叫。如需有關擔任角色的詳細資訊，請參閱 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AccessRoleArn | 選用 | none | AccessRoleArn=arn:aws:iam::111122223333:role/accessRole; |
## IAM Identity Center 客戶自管應用程式 ARN
IAM Identity Center 客戶自管 IDC 應用程式的 ARN。如需有關客戶受管應用程式的詳細資訊，請參閱[客戶自管應用程式](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| CustomerIdcApplicationArn | 選用 | none | CustomerIdcApplicationArn=arn:aws:sso::111122223333:application/ssoins-111122223333/apl-111122223333 |
## 啟用檔案快取
啟用臨時憑證快取。此連線參數可讓您在多個程序之間快取並重複使用臨時憑證。使用此選項可減少當您使用 BI 工具 (如 Microsoft Power BI) 時，Web 身分權杖的數目。依預設，驅動器會在 Windows 中使用 `%USERPROFILE%` 和 `HOME` 路徑來寫入檔案快取。請確保您為這兩個環境變數中存在的路徑提供讀取和寫入存取權，以獲得更好的體驗。
**注意**
從 v2.1.0.0 開始，快取的登入資料會以純文字 JSON 形式存放在 `user-profile/.athena-odbc/`目錄中，檔案許可僅限於擁有的使用者，與 AWS CLI 保護本機儲存的登入資料的方式一致。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| JwtTipFileCache | 選用 | 0 | JwtTipFileCache=1; |
# 瀏覽器信任的身分傳播憑證
此身分驗證類型可讓您從外部身分提供者擷取新的 JSON Web 字符 (JWT)，並使用 Athena 進行身分驗證。您可以使用此外掛程式，透過可信身分傳播啟用對企業身分的支援。如需有關如何搭配使用可信身分傳播與驅動器的詳細資訊，請參閱 [搭配使用可信身分傳播與 Amazon Athena 驅動器](using-trusted-identity-propagation.md)。您也可以[使用 CloudFormation 設定和部署資源](using-trusted-identity-propagation-cloudformation.md)。
透過信任的身分傳播，身分內容會新增至 IAM 角色，以識別請求存取 AWS 資源的使用者。如需有關啟用和使用可信身分傳播的資訊，請參閱[什麼是可信身分傳播？](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html)。
**注意**
外掛程式專為單一使用者桌面環境而設計。在 Windows Server 等共用環境中，系統管理員負責建立和維護使用者之間的安全界限。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | none | AuthenticationType=BrowserOidcTip; |
## IDP 已知組態 URL
IDP Well Known 組態 URL 是為您的身分提供者提供 OpenID Connect 組態詳細資訊的端點。此 URL 通常會以 結尾，`.well-known/openid-configuration`並包含有關身分驗證端點、支援的功能和字符簽署金鑰的基本中繼資料。例如，如果您使用的是 *Okta*，URL 可能看起來像 `https://your-domain.okta.com/.well-known/openid-configuration`。
針對疑難排解：如果您收到連線錯誤，請確認此 URL 可從您的網路存取，並傳回有效的 *OpenID Connect* 組態 JSON。此 URL 必須由安裝驅動程式的用戶端連線，且應由您的身分提供者管理員提供。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| IdpWellKnownConfigurationUrl | 必要 | none | IdpWellKnownConfigurationUrl=https:///.well-known/openid-configuration; |
## 用戶端識別符
OpenID Connect 提供者向應用程式發出的用戶端識別符。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| client\$1id | 必要 | none | client\$1id=00001111-aaaa-2222-bbbb-3333cccc4444; |
## 工作群組 ARN
Amazon Athena 工作群組的 Amazon Resource Name (ARN)，其中包含信任的身分傳播組態標籤。如需有關工作群組的詳細資訊，請參閱[工作群組](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
**注意**
此參數與指定查詢執行位置的 `Workgroup` 參數不同。您必須設定這兩個參數：
`WorkgroupArn` - 指向包含信任身分傳播組態標籤的工作群組
`Workgroup` - 指定要執行查詢的工作群組
雖然這些參數通常會參考相同的工作群組，但必須明確設定這兩個參數才能正常運作。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| WorkGroupArn | 必要 | none | WorkgroupArn=arn:aws:athena:us-west-2:111122223333:workgroup/primary |
## JWT 應用程式角色 ARN
將在 JWT 交換中擔任的角色 ARN。此角色可用於 JWT 交換、透過工作群組標籤取得 IAM Identity Center 客戶自管應用程式 ARN，以及取得存取角色 ARN。如需有關擔任角色的詳細資訊，請參閱 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| ApplicationRoleArn | 必要 | none | ApplicationRoleArn=arn:aws:iam::111122223333:role/applicationRole; |
## 角色工作階段名稱
IAM 工作階段的名稱。名稱可隨意指定，但是一般來說，您會傳遞與應用程式使用者相關聯的名稱或識別碼。這樣一來，應用程式使用的臨時安全憑證會與該使用者相關聯。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| role\$1session\$1name | 必要 | none | role\$1session\$1name=familiarname; |
## Client secret (用戶端密碼)
用戶端秘密是由您的身分提供者發行的機密金鑰，用於驗證您的應用程式。雖然此參數是選用的，而且可能不是所有身分驗證流程的必要項目，但在使用時提供額外的安全層。如果您的 IDP 組態需要用戶端秘密，您必須將此參數包含身分提供者管理員提供的值。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| client\$1secret | 選用 | none | client\$1secret=s0m3R@nd0mS3cr3tV@lu3Th@tS3cur3lyPr0t3ct5Th3Cl13nt;\$1 |
## Scope (範圍)
範圍會指定應用程式向身分提供者請求的存取層級。您必須在 `openid` 範圍內包含 ，才能接收包含基本使用者身分宣告的 ID 字符。您的範圍可能需要包含其他許可，例如 `email`或 `profile`，取決於哪些使用者宣告您的身分提供者 （例如 *Microsoft Entra ID*) 已設定為包含在 ID 字符中。這些宣告對於適當的*受信任身分傳播*映射至關重要。如果使用者身分映射失敗，請確認您的範圍包含所有必要的許可，且您的身分提供者已設定為在 ID 字符中包含必要的宣告。這些宣告必須符合 IAM Identity Center 中的*受信任權杖發行者*映射組態。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| Scope (範圍) | 選用 | openid email offline\$1access | Scope=openid email; |
## 工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 持續時間 | 選用 | 3600 | duration=900; |
## JWT 存取角色 ARN
Athena 代您呼叫所擔任角色的 ARN。如需有關擔任角色的詳細資訊，請參閱《AWS Security Token Service API 參考**》中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AccessRoleArn | 選用 | none | AccessRoleArn=arn:aws:iam::111122223333:role/accessRole; |
## IAM Identity Center 客戶自管應用程式 ARN
IAM Identity Center 客戶自管 IDC 應用程式的 ARN。如需有關客戶受管應用程式的詳細資訊，請參閱[客戶自管應用程式](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| CustomerIdcApplicationArn | 選用 | none | CustomerIdcApplicationArn=arn:aws:sso::111122223333:application/ssoins-111122223333/apl-111122223333; |
## 身分提供者連接埠號碼
用於 OAuth 2.0 回呼伺服器的本機連接埠號碼。這用作 redirect\$1uri，您需要允許在 IDP 應用程式中將其列出。預設產生的 redirect\$1uri 為：http：//localhost：7890/athena
**警告**
在共用環境中，例如 Windows Terminal Server 或遠端桌面服務，循環連接埠 （預設值：7890) 會在相同機器上的所有使用者之間共用。系統管理員可以透過下列方式降低潛在的連接埠劫持風險：
為不同的使用者群組設定不同的連接埠號碼
使用 Windows 安全政策來限制連接埠存取
在使用者工作階段之間實作網路隔離
如果無法實作這些安全控制，建議您改用 [JWT 信任的身分傳播](odbc-v2-driver-jwt-tip.md)外掛程式，這不需要迴路連接埠。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| listen\$1port | 選用 | 7890 | listen\$1port=8080; |
## 識別提供者回應逾時
等待 OAuth 2.0 回呼回應的逾時，以秒為單位。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| IdpResponseTimeout | 選用 | 120 | IdpResponseTimeout=140; |
## 啟用檔案快取
JwtTipFileCache 參數會判斷驅動程式是否在連線之間快取身分驗證字符。將 JwtTipFileCache 設為 true 可減少身分驗證提示並改善使用者體驗，但應謹慎使用。此設定最適合單一使用者桌面環境。在 Windows Server 等共用環境中，建議將其停用，以防止具有類似連線字串的使用者之間進行潛在的字符共用。
對於使用 PowerBI Server 等工具的企業部署，我們建議您使用 [JWT 信任的身分傳播](odbc-v2-driver-jwt-tip.md)外掛程式，而不是此身分驗證方法。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| JwtTipFileCache | 選用 | 0 | JwtTipFileCache=1; |
# Okta
Okta 是 SAML 型身分驗證外掛程式，可與 Okta 身分提供者搭配使用。如需有關設定 Okta 和 Amazon Athena 的聯合的資訊，請參閱 [使用 Okta 外掛程式和 Okta 身分提供者設定 ODBC 的 SSO](odbc-okta-plugin.md)。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=Okta; |
## 使用者 ID
您的 Okta 使用者名稱。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UID | 必要 | none | UID=jane.doe@org.com; |
## 密碼
您的 Okta 使用者密碼。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| PWD | 必要 | none | PWD=oktauserpasswordexample; |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如需有關 ARN 角色的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| preferred\$1role | 選用 | none | preferred\$1role=arn:aws:IAM::123456789012:id/user1; |
## 工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 持續時間 | 選用 | 900 | duration=900; |
## IdP 主機
您的 Okta 組織的 URL。您可以從 Okta 應用程式中的**內嵌連結** URL 擷取 `idp_host` 參數。如需這些步驟，請參閱 [從 Okta 擷取 ODBC 組態資訊](odbc-okta-plugin.md#odbc-okta-plugin-retrieve-odbc-configuration-information-from-okta)。`https://` 後的第一個區段、直到並包括 `okta.com` 即為您的 IdP 主機 (例如 `http://trial-1234567.okta.com`)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| idp\$1host | 必要 | None | idp\$1host=dev-99999999.okta.com; |
## IdP 連接埠
用於連線至 IdP 主機的連接埠號碼。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| idp\$1port | 必要 | None | idp\$1port=443; |
## Okta 應用程式 ID
您應用程式的兩部分識別符。您可以從 Okta 應用程式中的**內嵌連結** URL 擷取 `app_id` 參數。如需這些步驟，請參閱 [從 Okta 擷取 ODBC 組態資訊](odbc-okta-plugin.md#odbc-okta-plugin-retrieve-odbc-configuration-information-from-okta)。應用程式 ID 是 URL 的最後兩個區段，包括中間的正斜線。這些區段是兩個由 20 個字元組成的字串，其中包含數字和大小寫字母的混合 (例如 `Abc1de2fghi3J45kL678/abc1defghij2klmNo3p4`)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| app\$1id | 必要 | None | app\$1id=0oa25kx8ze9A3example/alnexamplea0piaWa0g7; |
## Okta 應用程式名稱
Okta 應用程式的名稱。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| app\$1name | 必要 | None | app\$1name=amazon\$1aws\$1redshift; |
## Okta 等待時間
指定等待多重要素驗證 (MFA) 程式碼的持續時間 (以秒為單位)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| okta\$1mfa\$1wait\$1time | 選用 | 10 | okta\$1mfa\$1wait\$1time=20; |
## Okta MFA 類型
MFA 因素類型。支援的類型包括 Google Authenticator、SMS (Okta)、Okta Verify with Push 和 Okta Verify with TOTP。個別組織安全政策會判斷使用者登入是否需要 MFA。
****
| **連線字串名稱** | **參數類型** | **預設值** | **可能的值** | **連線字串範例** |
| --- | --- | --- | --- | --- |
| okta\$1mfa\$1type | Optional | None | googleauthenticator, smsauthentication, oktaverifywithpush, oktaverifywithtotp | okta\$1mfa\$1type=oktaverifywithpush; |
## Okta 電話號碼
要與 AWS SMS 身分驗證搭配使用的電話號碼。僅多重要素註冊需要此參數。如果您的手機號碼已經註冊，或者安全政策未使用 AWS SMS 身分驗證，則可以忽略此欄位。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| okta\$1mfa\$1phone\$1number | 需要 MFA 註冊，否則為選用 | None | okta\$1mfa\$1phone\$1number=19991234567; |
## 啟用 Okta 檔案快取
啟用臨時憑證快取。此連線參數可讓您在 BI 應用程式開啟的多個程序之間快取及重複使用臨時憑證。使用此選項可避免 Okta API 限流限制。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| okta\$1cache | 選用 | 0 | okta\$1cache=1; |
# Ping
Ping 是 SAML 型外掛程式，可與 [PingFederate](https://www.pingidentity.com/en/platform/capabilities/authentication-authority/pingfederate.html) 身分提供者搭配使用。
## 身分驗證類型
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| AuthenticationType | 必要 | IAM Credentials | AuthenticationType=Ping; |
## 使用者 ID
PingFederate 伺服器的使用者名稱。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UID | 必要 | none | UID=pingusername@domain.com; |
## 密碼
PingFederate 伺服器的密碼。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| PWD | 必要 | none | PWD=pingpassword; |
## 偏好的角色
要擔任之角色的 Amazon Resource Name (ARN)。如果您的 SAML 聲明具有多個角色，您可以指定此參數來選擇要擔任的角色。此角色應出現在 SAML 聲明中。如需有關 ARN 角色的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| preferred\$1role | 選用 | none | preferred\$1role=arn:aws:iam::123456789012:id/user1; |
## 工作階段持續時間
角色工作階段的持續時間 (以秒為單位)。如需有關工作階段持續時間的詳細資訊，請參閱《AWS Security Token Service API 參考》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| 持續時間 | 選用 | 900 | duration=900; |
## IdP 主機
Ping 伺服器的地址。若要尋找您的地址，請造訪下列 URL 並檢視 **SSO 應用程式端點**欄位。
```
https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections
```
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| idp\$1host | 必要 | none | idp\$1host=ec2-1-83-65-12.compute-1.amazonaws.com; |
## IdP 連接埠
用於連線至 IdP 主機的連接埠號碼。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| idp\$1port | 必要 | None | idp\$1port=443; |
## 合作夥伴 SPID
服務提供者地址。若要尋找服務提供者地址，請造訪下列 URL 並檢視 **SSO 應用程式端點**欄位。
```
https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections
```
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| partner\$1spid | 必要 | None | partner\$1spid=https://us-east-1.signin.aws.amazon.com/platform/saml/<...>; |
## Ping URI 參數
將身分驗證請求的 URI 引數傳遞給 Ping。使用此參數可繞過 Lake Formation 的單一角色限制。設定 Ping 以識別傳遞的參數，並驗證傳遞的角色存在於分配給使用者的角色清單中。然後，在 SAML 聲明中傳送單個角色。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| ping\$1uri\$1param | 選用 | None | ping\$1uri\$1param=role=my\$1iam\$1role; |
# 常用身分驗證參數
如上所述，本節中的參數對於驗證類型而言非常常見。
## 將代理用於 IdP
透過代理 Proxy 啟用驅動程式與 IdP 之間的通訊。此選項適用於下列身分驗證外掛程式：
+ AD FS
+ Azure AD
+ 瀏覽器 Azure AD
+ 瀏覽器 SSO OIDC
+ JWT 可信身分傳播
+ JWT
+ JWT 可信身分傳播
+ 瀏覽器信任的身分傳播
+ Okta
+ Ping
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UseProxyForIdP | 選用 | 0 | UseProxyForIdP=1; |
## 使用 Lake Formation
使用 [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 動作來擷取臨時 IAM 登入資料，而不是 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 動作。此選項適用於 Azure AD、瀏覽器 Azure AD、瀏覽器 SAML、Okta、Ping 和 AD FS 身分驗證外掛程式。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| LakeformationEnabled | 選用 | 0 | LakeformationEnabled=1; |
## SSL 不安全 (IdP)
與 IdP 通訊時停用 SSL。此選項適用於 Azure AD、瀏覽器 Azure AD、Okta、Ping 和 AD FS 身分驗證外掛程式。
**重要**
v**2.1.0.0 中的重大變更：**連線至身分提供者時 SSL 憑證驗證的預設行為已變更。在 2.1.0.0 之前的版本中，預設為停用 SSL 驗證。從 v2.1.0.0 開始，所有 IdP 連線預設都會啟用 SSL 驗證。驅動程式也會強制執行 TLS 1.2 作為最低 TLS 版本。如果您使用沒有有效 SSL 憑證的本機身分提供者 （僅用於測試），請在連線字串`SSL_Insecure=1`中設定 。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| SSL\$1Insecure | 選用 | 0 | SSL\$1Insecure=1; |
# 端點覆寫
## Athena 端點覆寫
`endpointOverride ClientConfiguration` 類別會使用此值覆寫 Amazon Athena 用戶端的預設 HTTP 端點。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| EndpointOverride | 選用 | none | EndpointOverride=athena.us-west-2.amazonaws.com; |
## Athena 串流端點覆寫
`ClientConfiguration.endpointOverride` 方法會使用此值覆寫 Amazon Athena 串流用戶端的預設 HTTP 端點。如需詳細資訊，請參閱《*適用於 C\$1\$1 的 AWS SDK 開發人員指南*》中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。Athena 串流服務可透過連接埠 444 使用。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| StreamingEndpointOverride | 選用 | none | StreamingEndpointOverride=athena.us-west-1.amazonaws.com:444; |
## AWS STS 端點覆寫
`ClientConfiguration.endpointOverride` 方法使用此值來覆寫 AWS STS 用戶端的預設 HTTP 端點。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| StsEndpointOverride | 選用 | none | StsEndpointOverride=sts.us-west-1.amazonaws.com; |
## Lake Formation 端點覆寫
`ClientConfiguration.endpointOverride` 方法會使用此值覆寫 Lake Formation 用戶端的預設 HTTP 端點。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| LakeFormationEndpointOverride | 選用 | none | LakeFormationEndpointOverride=lakeformation.us-west-1.amazonaws.com; |
## SSO 端點覆寫
`ClientConfiguration.endpointOverride` 方法會使用此值覆寫 SSO 用戶端的預設 HTTP 端點。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| SSOEndpointOverride | 選用 | none | SSOEndpointOverride=portal.sso.us-east-2.amazonaws.com; |
## SSO OIDC 端點覆寫
`ClientConfiguration.endpointOverride` 方法會使用此值覆寫 SSO OIDC 用戶端的預設 HTTP 端點。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| SSOOIDCEndpointOverride | 選用 | none | SSOOIDCEndpointOverride=oidc.us-east-2.amazonaws.com |
## SSO 管理員端點覆寫
`ClientConfiguration.endpointOverride` 方法會使用此值覆寫 SSO 管理員用戶端的預設 HTTP 端點。如需詳細資訊，請參閱 [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| SSOAdminEndpointOverride | 選用 | 無 | SSOAdminEndpointOverride=sso.us-east-2.amazonaws.com |
## S3 端點覆寫
`ClientConfiguration.endpointOverride` 方法會使用此值覆寫 S3 用戶端的預設 HTTP 端點。當驅動程式使用 Amazon S3 擷取程式時，將用來下載查詢結果的端點。若沒有指定此參數，則驅動程式會使用預設的 Amazon S3 端點。如需詳細資訊，請參閱 [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| S3EndpointOverride | 選用 | 無 | S3EndpointOverride=s3.us-east-2.amazonaws.com |
# 進階選項
## 擷取大小
本次請求傳回結果 (列) 的最大數量。如需參數資訊，請參閱 [GetQuery MaxResults](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetQueryResults.html#athena-GetQueryResults-request-MaxResults)。對於串流 API，最大值為 10000000。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| RowsToFetchPerBlock | 選用 | 非串流為 `1000` 串流為 `20000` | RowsToFetchPerBlock=20000; |
## 結果擷取程式
預設的結果擷取程式會直接從 Amazon S3 下載查詢結果，而無需透過 Athena API 操作。當其偵測到無法直接下載 S3 的情況時，即會自動回退至使用 `GetQueryResultsStream` API 操作。例如，當使用 `CSE_KMS` 選項加密查詢結果時，就會發生這種情況。
在大多數情況下，建議使用 `auto` 擷取程式。不過，如果您的 IAM 政策或 S3 儲存貯體政策使用 `s3:CalledVia` 條件來限制存取來自 Athena 的 S3 物件請求，則自動擷取程式會先嘗試從 S3 下載結果，然後回退至使用 `GetQueryResultsStream`。在這種情況下，您可以想要將 `ResultFetcher` 設定為 `GetQueryResultsStream`，以避免額外的 API 呼叫。
**注意**
驅動器仍會識別啟用串流 API (`UseResultsetStreaming=1;`) 和啟用 S3 擷取程式 (`EnableS3Fetcher=1;`) 參數。不過，我們建議您使用 `ResultFetcher` 參數，以獲得更好的體驗。
****
| **連線字串名稱** | **參數類型** | **預設值** | **可能的值** | **連線字串範例** |
| --- | --- | --- | --- | --- |
| ResultFetcher | 選用 | auto | auto, S3, GetQueryResults, GetQueryResultsStream | ResultFetcher=auto |
## 啟用結果重複使用
指定執行查詢時是否可以重複使用之前的查詢結果。如需參數資訊，請參閱 ResultReuseByAgeConfiguration。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| EnableResultReuse | 選用 | 0 | EnableResultReuse=1; |
## 結果重複使用最長期限
指定 Athena 應考慮重複使用的之前查詢結果的最長期限 (以分鐘為單位)。如需參數資訊，請參閱 [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| ReusedResultMaxAgeInMinutes | 選用 | 60 | ReusedResultMaxAgeInMinutes=90; |
## 使用多個 S3 執行緒
使用多個執行緒從 Amazon S3 擷取資料。啟用此選項時，會使用多個執行緒平行擷取存放在 Amazon S3 儲存貯體中的結果檔案。
只有在網路頻寬良好時，才會啟用此選項。例如，在我們對 EC2 [c5.2xlarge](https://aws.amazon.com/ec2/instance-types/c5/) 執行個體的測量中，單一執行緒 S3 用戶端達到 1 Gbps，而多執行緒 S3 用戶端則達到 4 Gbps 的網路輸送量。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UseMultipleS3Threads | 選用 | 0 | UseMultipleS3Threads=1; |
## 使用單一目錄和結構描述
依預設，ODBC 驅動程式會查詢 Athena，以取得可用目錄和結構描述的清單。此選項會強制驅動程式使用「ODBC 資料來源管理員組態」對話方塊或連線參數指定的目錄和結構描述。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UseSingleCatalogAndSchema | 選用 | 0 | UseSingleCatalogAndSchema=1; |
## 使用查詢列出資料表
對於 `LAMBDA` 目錄類型，ODBC 驅動器可以提交 [SHOW TABLES](show-tables.md) 查詢，進而取得可用資料表的清單。此設定是預設值。如果此參數設定為 0，ODBC 驅動器會使用 Athena [ListTableMetadata](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListTableMetadata.html) API 來取得可用資料表的清單。請注意，對於 `LAMBDA` 目錄類型，使用 `ListTableMetadata` 會導致效能迴歸。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UseQueryToListTables | 選用 | 1 | UseQueryToListTables=1; |
## 針對字串類型使用 WCHAR
依預設，ODBC 驅動器對 Athena 使用 `SQL_CHAR` 和 `SQL_VARCHAR`，其中字串資料類型包括 `char`、`varchar`、`string`、`array`、`map<>`、`struct<>` 和 `row`。將此參數設定為 `1` 會強制驅動器針對字串資料類型使用 `SQL_WCHAR` 和 `SQL_WVARCHAR`。寬字元和寬變數字元類型可用於確保來自不同語言的字元可以正確儲存和擷取。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UseWCharForStringTypes | 選用 | 0 | UseWCharForStringTypes=1; |
## 查詢外部目錄
指定驅動程式是否需要從 Athena 查詢外部目錄。如需詳細資訊，請參閱[移轉至 ODBC 2.x 驅動器](odbc-v2-driver-migrating.md)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| QueryExternalCatalogs | 選用 | 0 | QueryExternalCatalogs=1; |
## 驗證 SSL
控制是否在使用 AWS SDK 時驗證 SSL 憑證。這個值會傳遞給 `ClientConfiguration.verifySSL` 參數。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| VerifySSL | 選用 | 1 | VerifySSL=0; |
## S3 結果區塊大小
指定單一 Amazon S3 [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API 請求下載的區塊大小 (以位元組為單位)。預設值為 67108864 (64 MB)。允許的最小值和最大值為 10485760 (10 MB) 和 2146435072 (約 2 GB)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| S3ResultBlockSize | 選用 | 67108864 | S3ResultBlockSize=268435456; |
## 字串資料欄長度
為具有 `string` 資料類型的資料欄指定資料欄長度。由於 Athena 使用沒有定義精確度的 [Apache Hive 字串資料類型](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types#LanguageManualTypes-StringsstringStrings)，因此 Athena 報告的預設長度為 2147483647 (`INT_MAX`)。由於 BI 工具通常會為資料欄預先配置記憶體，這可能會導致記憶體耗用量過高。若要避免這種情況，Athena ODBC 驅動器會限制報告的 `string` 資料類型的資料欄精確度，並公開 `StringColumnLength` 連線參數，以便可以變更預設值。
****
| 連線字串名稱 | 參數類型 | 預設值 | 連線字串範例 |
| --- | --- | --- | --- |
| StringColumnLength | 選用 | 255 | StringColumnLength=65535; |
## 複雜類型資料欄長度
為具有複雜資料類型 (例如 `map`、`struct` 和 `array`) 的資料欄指定資料欄長度。與 [StringColumnLength](#odbc-v2-driver-advanced-options-string-column-length) 類似，Athena 會針對具有複雜資料類型的資料欄報告 0 精確度。Athena ODBC 驅動器會設定複雜資料類型的資料欄預設精確度，並公開 `ComplexTypeColumnLength` 連線參數，以便可以變更預設值。
****
| 連線字串名稱 | 參數類型 | 預設值 | 連線字串範例 |
| --- | --- | --- | --- |
| ComplexTypeColumnLength | 選用 | 65535 | ComplexTypeColumnLength=123456; |
## 可信 CA 憑證
指示 HTTP 用戶端在何處找到您的 SSL 憑證信任存放區。這個值會傳遞給 `ClientConfiguration.caFile` 參數。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| TrustedCerts | 選用 | %INSTALL\$1PATH%/bin | TrustedCerts=C:\$1\$1Program Files\$1\$1Amazon Athena ODBC Driver\$1\$1bin\$1\$1cacert.pem; |
## 最短輪詢期間
指定輪詢 Athena 查詢執行狀態之前要等待的最小值 (以毫秒為單位)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| MinQueryExecutionPollingInterval | 選用 | 100 | MinQueryExecutionPollingInterval=200; |
## 最長輪詢期間
指定輪詢 Athena 查詢執行狀態之前要等待的最大值 (以毫秒為單位)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| MaxQueryExecutionPollingInterval | 選用 | 60000 | MaxQueryExecutionPollingInterval=1000; |
## 輪詢乘數
指定增加輪詢期間的因數。依預設，輪詢會以最短輪詢期間的值開始，並且每次輪詢都會加倍，直到達到最長輪詢期間的值為止。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| QueryExecutionPollingIntervalMultiplier | 選用 | 2 | QueryExecutionPollingIntervalMultiplier=2; |
## 最長輪詢持續時間
指定驅動程式可輪詢 Athena 查詢執行狀態的最大值 (以毫秒為單位)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| MaxPollDuration | 選用 | 1800000 | MaxPollDuration=1800000; |
## 連線逾時
HTTP 連線等待建立連線的時間量 (以毫秒為單位)。此值是針對 `ClientConfiguration.connectTimeoutMs` Athena 用戶端設定的。若未指定，則使用 curl 預設值。如需有關連線參數的資訊，請參閱《適用於 Java 的 AWS SDK 開發人員指南》**中的[用戶端組態](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/section-client-configuration.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| ConnectionTimeout | 選用 | 0 | ConnectionTimeout=2000; |
## 請求逾時
指定 HTTP 用戶端的通訊端讀取逾時。此值是為 Athena 用戶端的 `ClientConfiguration.requestTimeoutMs` 參數設定的。如需參數資訊，請參閱《適用於 Java 的 AWS SDK 開發人員指南》**中的[用戶端組態](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/section-client-configuration.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| RequestTimeout | 選用 | 10000 | RequestTimeout=30000; |
# 代理選項
## 代理主機
若您要求使用者通過代理，請使用此參數來設定代理主機。此參數對應至 AWS SDK 中的 `ClientConfiguration.proxyHost` 參數。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| ProxyHost | 選用 | none | ProxyHost=127.0.0.1; |
## 代理連接埠
使用此參數來設定代理連接埠。此參數對應至 AWS SDK 中的 `ClientConfiguration.proxyPort` 參數。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| ProxyPort | 選用 | none | ProxyPort=8888; |
## 代理使用者名稱
使用此參數來設定代理使用者名稱。此參數對應至 AWS SDK 中的 `ClientConfiguration.proxyUserName` 參數。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| ProxyUID | 選用 | none | ProxyUID=username; |
## 代理密碼
使用此參數來設定代理密碼。此參數對應至 AWS SDK 中的 `ClientConfiguration.proxyPassword` 參數。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| ProxyPWD | 選用 | none | ProxyPWD=password; |
## 非代理主機
使用此選用參數，指定驅動程式在不使用代理的情況下連線至的主機。此參數對應至 AWS SDK 中的 `ClientConfiguration.nonProxyHosts` 參數。如需詳細資訊，請參閱《適用於 C\$1\$1 的 AWS SDK 開發人員指南》**中的 [AWS 用戶端組態](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
該 `NonProxyHost` 連線參數會傳遞給 `CURLOPT_NOPROXY` curl 選項。如需 `CURLOPT_NOPROXY` 格式的相關資訊，請參閱 curl 文件中的 [CURLOPT\$1NOPROXY](https://curl.se/libcurl/c/CURLOPT_NOPROXY.html)。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| NonProxyHost | 選用 | none | NonProxyHost=.amazonaws.com,localhost,.example.net,.example.com; |
## 使用代理
啟用通過指定代理的使用者流量。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UseProxy | 選用 | none | UseProxy=1; |
# 記錄選項
**警告**
**安全性：**在詳細層級 (DEBUG 或 TRACE) 啟用記錄時，驅動程式使用的 AWS SDK 可能會以純文字記錄敏感資訊，例如身分驗證字符和登入資料。僅使用詳細記錄進行故障診斷，並確保日誌檔案安全存放，並在使用後刪除。請勿在生產環境中啟用詳細記錄。
需要管理員權限才能修改此處所述的設定。若要進行變更，您可以使用 ODBC 資料來源管理員**記錄選項**對話方塊或直接修改 Windows 登錄檔。
## 日誌層級
此選項會啟用不同細節層級的 ODBC 驅動程式日誌。在 Windows 中，您可以使用登錄檔或對話方塊來設定記錄。此選項位於以下登錄檔路徑：
```
Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Amazon Athena\ODBC\Driver
```
可用的日誌層級如下：
+ `OFF` - 已停用記錄
+ `ERROR` - 只會記錄錯誤訊息
+ `WARN` - 記錄警告訊息和錯誤
+ `INFO` - 記錄資訊性訊息、警告和錯誤
+ `DEBUG` - 記錄詳細的偵錯資訊以及所有較低層級的訊息
+ `TRACE` - 記錄的最詳細層級，包括所有訊息
**注意**
每個日誌層級都包含來自其下方層級的所有訊息。較高的日誌層級可能會影響效能並產生更大的日誌檔案。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| LogLevel | 選用 | OFF | LogLevel=INFO; |
## 日誌路徑
指定儲存 ODBC 驅動程式日誌的檔案路徑。您可以使用登錄檔或對話方塊來設定此值。此選項位於以下登錄檔路徑：
```
Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Amazon Athena\ODBC\Driver
```
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| LogPath | 選用 | none | LogPath=C:\$1Users\$1username\$1projects\$1internal\$1trunk\$1; |
## 使用 AWS 記錄器
指定是否啟用 AWS SDK 記錄。指定 1 表示啟用，0 表示停用。
****
| **連線字串名稱** | **參數類型** | **預設值** | **連線字串範例** |
| --- | --- | --- | --- |
| UseAwsLogger | 選用 | 0 | UseAwsLogger=1; |
# 移轉至 ODBC 2.x 驅動器
由於大多數的 Athena ODBC 2.x 連線參數都與 ODBC 1.x 驅動程式向後相容，因此您可以搭配 Athena ODBC 2.x 驅動程式重複使用大多數現有的連線字串。但是，下列連線參數需要修改。
## 日誌層級
雖然目前的 ODBC 驅動程式提供了一系列可用的記錄選項，但從 `LOG_OFF (0)`到 `LOG_TRACE (6)`，Amazon Athena ODBC 2.x 驅動程式最初只有兩個值：0 （停用） 和 1 （啟用）。從 2.0.6.0 版開始，驅動程式現在支援更精細的記錄層級與增強的記錄功能：
+ `OFF` - 已停用記錄
+ `ERROR` - 只會記錄錯誤訊息
+ `WARN` - 記錄警告訊息和錯誤
+ `INFO` - 記錄資訊性訊息、警告和錯誤
+ `DEBUG` - 記錄詳細的偵錯資訊以及所有較低層級的訊息
+ `TRACE` - 記錄的最詳細層級，包括所有訊息
如需有關記錄 ODBC 2.x 驅動程式的詳細資訊，請參閱 [記錄選項](odbc-v2-driver-logging-options.md)。
****
| | ODBC 1.x 驅動程式 | ODBC 2.x 驅動程式 |
| --- | --- | --- |
| 連線字串名稱 | LogLevel | LogLevel |
| 參數類型 | 選用 | 選用 |
| 預設值 | 0 | OFF |
| 可能的值 | 0-6 | 對於 2.0.6.0 之前的版本： `0,1` 對於 2.0.6.0 `WARN`版和更新版本：`OFF`、`ERROR`、`INFO`、`DEBUG`、 `TRACE` |
| 連線字串範例 | LogLevel=6; | LogLevel=INFO; |
**注意**
在 2.0.6.0 版及更新版本中，日誌架構已經過最佳化，可減少操作延遲和產生過多日誌檔案，同時透過這些精細日誌層級提供更詳細的診斷資訊。每個關卡都包含其下方關卡的所有訊息。
## MetadataRetrievalMethod
目前的 ODBC 驅動程式提供數個選項，以便從 Athena 擷取中繼資料。Amazon Athena ODBC 驅動程序取代了 `MetadataRetrievalMethod`，並始終使用 Amazon Athena API 來擷取中繼資料。
Athena 推出旗標 `QueryExternalCatalogs`，用於查詢外部目錄。若要使用目前的 ODBC 驅動程式查詢外部目錄，請將 `MetadataRetrievalMethod` 設定為 `ProxyAPI`。若要使用 Athena ODBC 驅動程式查詢外部目錄，請將 `QueryExternalCatalogs` 設定為 `1`。
****
| | ODBC 1.x 驅動程式 | ODBC 2.x 驅動程式 |
| --- | --- | --- |
| 連線字串名稱 | MetadataRetrievalMethod | QueryExternalCatalogs |
| 參數類型 | 選用 | 選用 |
| 預設值 | Auto | 0 |
| 可能的值 | Auto, AWS Glue, ProxyAPI, Query | 0,1 |
| 連線字串範例 | MetadataRetrievalMethod=ProxyAPI; | QueryExternalCatalogs=1; |
## 連線測試
當您測試 ODBC 1.x 驅動程式連線時，驅動程式會執行 `SELECT 1` 查詢，在 Amazon S3 儲存貯體中產生兩個檔案：一個用於結果集，另一個用於中繼資料。測試連線是根據 [Amazon Athena 定價](https://aws.amazon.com/athena/pricing/)政策收費。
當您測試 ODBC 2.x 驅動程式連線時，驅動程式會呼叫 [GetWorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetWorkGroup.html) Athena API 動作。呼叫會使用您指定的身分驗證類型和對應的憑證提供者來擷取憑證。使用 ODBC 2.x 驅動程式時，可免費使用連線測試，且測試不會在您的 Amazon S3 儲存貯體中產生查詢結果。
# 對 ODBC 2.x 驅動器進行疑難排解
如果您遇到 Amazon Athena ODBC 驅動程式的問題，您可以聯絡 支援 （在 中 AWS 管理主控台，選擇**支援**、**支援中心**)。
請確保包含下列資訊，並提供將協助支援團隊了解您的使用案例的任何其他詳細資訊。
+ **描述** – (必要) 包含以下詳細資訊的描述：您的使用案例以及預期行為和觀察到的行為之間的差異。包括任何可幫助支援工程師輕鬆解決問題的資訊。如果問題是間歇性出現，則指定發生問題的日期、時間戳記或間隔點。
+ **版本資訊** – (必要) 驅動程式版本、作業系統以及您使用的應用程式的相關資訊。例如，「ODBC 驅動程序 1.2.3 版、Windows 10 (x64)、Power BI。」
+ **日誌檔案** – (必要) 了解問題所需的 ODBC 驅動程式日誌檔案的數目下限。如需有關 ODBC 2.x 驅動程式的記錄選項的資訊，請參閱 [記錄選項](odbc-v2-driver-logging-options.md)。
+ **連線字串** – (必要) ODBC 連線字串或顯示您使用的連線參數的對話方塊的螢幕擷取畫面。如需有關連線參數的資訊，請參閱 [Athena ODBC 2.x 連線參數](odbc-v2-driver-connection-parameters.md)。
+ **問題步驟** – (選用) 如有可能，請包含可協助重現問題的步驟或獨立程式。
+ **查詢錯誤資訊** – (選用) 如果出現涉及 DML 或 DDL 查詢的錯誤，請包含以下資訊：
+ 失敗的 DML 或 DDL 查詢的完整版本或簡化版本。
+ AWS 區域 使用的帳戶 ID 和 ，以及查詢執行 ID。
+ **SAML 錯誤** – (選用) 如果您遇到有關使用 SAML 聲明進行身分驗證的問題，請包含以下資訊：
+ 使用的身分提供者和身分驗證外掛程式。
+ 使用 SAML 字符的範例。
# Amazon Athena ODBC 2.x 版本備註
這些版本備註提供了 Amazon Athena ODBC 2.x 驅動程式中的增強功能、功能、已知問題和工作流程變更的詳細資訊。
## 2.1.0.0
版 2026-03-20
Amazon Athena Amazon Athena ODBC 2.1.0.0 版驅動程式包含安全性改善。此版本可增強身分驗證流程、查詢處理和傳輸安全性。建議您盡快升級至此版本。
### 突破性變更
+ **預設啟用 SSL 憑證驗證** – 驅動程式現在會在連線至身分提供者時強制執行 SSL 憑證驗證。如果您使用沒有有效 SSL 憑證的本機身分提供者，您必須在連線字串`SSL_Insecure=1`中明確設定 。如需詳細資訊，請參閱[SSL 不安全 (IdP)](odbc-v2-driver-common-authentication-parameters.md#odbc-v2-driver-common-authentication-parameters-ssl-insecure-idp)。
+ **至少強制執行 TLS 1.2** – 驅動程式不再接受與身分提供者的 TLS 1.0 或 TLS 1.1 連線。所有 IdP 連線現在都需要 TLS 1.2 或更新版本。
+ **BrowserSSOOIDC 身分驗證流程已更新** – BrowserSSOOIDC 外掛程式現在使用授權碼搭配 PKCE，而非裝置碼授權。OAuth 2.0 回呼伺服器可使用新的選用參數 `listen_port`（預設 7890)。您可能需要允許列出您網路上的此連接埠。預設範圍已變更為 `sso:account:access`。如需詳細資訊，請參閱[瀏覽器 SSO OIDC](odbc-v2-driver-browser-sso-oidc.md)。
### 改進
+ **BrowserSSOOIDC** – 使用 PKCE 從裝置程式碼流程遷移至授權碼，以提高安全性。
+ **BrowserAzureAD** – 已將 PKCE （程式碼交換的驗證金鑰） 新增至 OAuth 2.0 授權流程，以防止授權碼攔截攻擊。
+ **BrowserSAML** – 新增 RelayState CSRF 保護，以防止 SAML 字符注入攻擊。
+ **登入資料快取** – 從 v2.1.0.0 開始，快取的登入資料會以純文字 JSON 形式存放在 `user-profile/.athena-odbc/`目錄中，檔案許可僅限於擁有的使用者，與 AWS CLI 保護本機儲存的登入資料的方式一致。
+ **IAM 設定檔** – 除了現有 之外，還新增對 `EcsContainer`和 `Environment`憑證來源的支援`Ec2InstanceMetadata`。
+ **連線字串剖析器** – 實作適當的 ODBC `}}`逸出處理。
+ **目錄查詢** – 新增結構描述名稱和資料表模式的 SQL 識別符逸出。
+ **ODBC 模式比對** – 以直接 ODBC LIKE 萬用字元比對程式取代以 regex 為基礎的比對。
+ **XML 剖析** – 新增 SAML 權杖的遞迴深度限制 (100 個層級） 和大小限制 (1MB)。
+ **ADFS 身分驗證** – 新增 ADFS 伺服器回應的回應大小限制 (200KB)。
### 修正項目
+ 已修正身分驗證元件中特殊元素的不當中和，這些元素可透過製作的連線參數允許程式碼執行或身分驗證流程重新導向。影響 BrowserSSOOIDC、 BrowserAzureAD 和 BrowserSAML 外掛程式。
+ 已修正查詢處理元件中特殊元素的不當中和，這些元素可能允許透過製作的資料表中繼資料拒絕服務或 SQL Injection。
+ 修正連線至身分提供者時的不當憑證驗證。
+ 修正瀏覽器型身分驗證流程中缺少的身分驗證安全控制，包括 OAuth 的 PKCE、SAML 的 CSRF 保護、安全登入資料快取，以及獨佔回呼連接埠繫結。
+ 已修正剖析元件中不受控制的資源耗用量，這些元件可透過製作的輸入模式、無限制的伺服器回應或深度巢狀 XML 承載來允許拒絕服務。
+ 修正在 Power BI Import 模式下`UseSingleCatalogAndSchema=1`搭配跨帳戶聯合目錄使用 時， `SQLColumns`和 未`SQLTables`傳回結果的問題。
若要下載新的 ODBC v2 驅動程式，請參閱 [ODBC 2.x 驅動程式下載](odbc-v2-driver.md#odbc-v2-driver-download)。如需連線資訊，請參閱 [Amazon Athena ODBC 2.x](odbc-v2-driver.md)。
## 2.0.6.0
版 2025-11-21
### 改進
+ **瀏覽器可信任身分傳播身分驗證外掛程式** – 新增了新的身分驗證外掛程式，以支援具有可信任身分傳播的瀏覽器型 OpenID Connect (OIDC) 身分驗證。此外掛程式透過預設瀏覽器處理完整的 OAuth 2.0 流程、自動擷取 JSON Web Token (JWT)，以及與信任的身分傳播整合，以提供無縫的身分驗證體驗。外掛程式專為單一使用者桌面環境而設計。如需有關啟用和使用可信身分傳播的資訊，請參閱[什麼是可信身分傳播？](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html)。
+ **增強型記錄架構** – 透過下列方式大幅改善驅動程式的記錄機制：
+ 推出比基本 0/1 選項更精細的日誌層級
+ 移除備援日誌陳述式
+ 最佳化記錄架構以包含診斷相關資訊
+ 解決造成操作延遲的效能問題
+ 減少啟用記錄時產生過多的日誌檔案
### 修正項目
+ **結果擷取器最佳化 – **修正擷取大小參數限制錯誤套用至串流和非串流結果擷取器的問題。限制現在僅正確套用至非串流結果擷取器。
若要下載新的 ODBC v2 驅動程式，請參閱 [ODBC 2.x 驅動程式下載](odbc-v2-driver.md#odbc-v2-driver-download)。如需連線資訊，請參閱 [Amazon Athena ODBC 2.x](odbc-v2-driver.md)。
## 2.0.5.1
版 2025-10-13
### 修正項目
Amazon Athena ODBC v2.0.5.1 驅動器包含下列針對瀏覽器型身分驗證外掛程式的修正。
+ 已實作登入 URL 驗證和結構描述檢查。
+ 改善了 Linux 上的瀏覽器啟動機制，可利用系統 API，進而提升穩定性和安全性。
若要下載新的 ODBC v2 驅動程式，請參閱 [ODBC 2.x 驅動程式下載](odbc-v2-driver.md#odbc-v2-driver-download)。如需連線資訊，請參閱 [Amazon Athena ODBC 2.x](odbc-v2-driver.md)。
## 2.0.5.0
版 2025-09-10
### 改進
+ **JWT 可信身分提供者 (TIP) 身分驗證外掛程式** – 新增了新的身分驗證外掛程式，可支援 JWT 可信身分提供者 (TIP) 與 ODBC 驅動器的整合。此身分驗證類型允許您使用從外部身分提供者獲得的 JSON Web Token (JWT) 作為連線參數，向 Athena 進行身分驗證。使用 TIP，身分內容會新增至 IAM 角色，以識別請求存取 AWS 資源的使用者。如需有關啟用和使用 TIP 的資訊，請參閱[什麼是可信身分傳播？](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html)。
+ **自訂 SSO 管理員端點支援** – 新增對 ODBC 驅動器中自訂 SSO 管理員端點的支援。此增強功能可讓您在 VPC 後方執行 ODBC 時，為 SSO 服務指定自己的端點。
+ **AWS 開發套件版本更新** – 我們已將驅動程式中使用的 AWS 開發套件版本更新至 2.32.16，並已更新 2.0.5.0 版的專案相依性。
## 2.0.4.0
版 2025-06-17
Amazon Athena ODBC 2.0.4.0 版驅動程式包含下列改進和修正。
### 改進
+ **結果擷取程式** – 驅動器現在會自動選取下載查詢結果的方法。如此一來，在大多數情況下都無需手動設定擷取程式。如需詳細資訊，請參閱[結果擷取程式](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-result-fetcher)。
+ Curl Library 已更新至 8.12.1。
### 修正項目
+ 修正了連線至 STS 時 IAM 設定檔的代理組態的問題。該修正可讓 IAM 設定檔用於成功的身分驗證。
+ 使用身分驗證外掛程式讀取 IAM 設定檔的所有其他組態選項。這包括 `UseProxyForIdP`、`SSL_Insecure`、`LakeformationEnabled` 和 `LoginToRP`，以解決受影響外掛程式的錯誤組態。
+ 修正了 round 函式，即允許其採用選用的第二個參數。它成功處理了包含逸出語法的查詢。
+ 修正了 `TIME WITH TIME ZONE` 和 `TIMESTAMP WITH TIME ZONE` 資料類型的資料欄大小。具有時間戳記和時區資料類型的值不會被截斷。
若要下載新的 ODBC v2 驅動程式，請參閱 [ODBC 2.x 驅動程式下載](odbc-v2-driver.md#odbc-v2-driver-download)。如需連線資訊，請參閱 [Amazon Athena ODBC 2.x](odbc-v2-driver.md)。
## 2.0.3.0
版 2024-04-08
Amazon Athena ODBC 2.0.3.0 版驅動程式包含下列改進和修正。
### 改進
+ 新增了對 Linux 和 Mac 平台上 Okta 身分驗證外掛程式的 MFA 支援。
+ 現在，`athena-odbc.dll` 程式庫和適用於 Windows 的 `AmazonAthenaODBC-2.x.x.x.msi` 安裝程式均已簽章。
+ 更新了與驅動器一起安裝的 CA 憑證 `cacert.pem` 檔案。
+ 改善了在 Lambda 目錄下列出資料表所需的時間。對於 `LAMBDA` 目錄類型，ODBC 驅動器現在可以提交 [SHOW TABLES](show-tables.md) 查詢，進而取得可用資料表的清單。如需詳細資訊，請參閱[使用查詢列出資料表](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-use-query-to-list-tables)。
+ 引入了使用 `SQL_WCHAR` 和 `SQL_WVARCHAR` 報告字串資料類型的 `UseWCharForStringTypes` 連線參數。如需詳細資訊，請參閱[針對字串類型使用 WCHAR](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-use-wchar-for-string-types)。
### 修正項目
+ 修正了使用 Get-OdbcDsn PowerShell 工具時發生的登錄檔損毀警告。
+ 更新了剖析邏輯，可處理查詢字串開頭的註解。
+ 現在，日期和時間戳記資料類型允許年份欄位中為零。
若要下載新的 ODBC v2 驅動程式，請參閱 [ODBC 2.x 驅動程式下載](odbc-v2-driver.md#odbc-v2-driver-download)。如需連線資訊，請參閱 [Amazon Athena ODBC 2.x](odbc-v2-driver.md)。
## 2.0.2.2
2024-02-13 發布
Amazon Athena ODBC 2.0.2.2 版驅動程式包含下列改進和修正。
### 改進
+ 新增了兩個連線參數 `StringColumnLength` 和 `ComplexTypeColumnLength`，可用來變更字串和複雜資料類型的預設資料欄長度。如需詳細資訊，請參閱[字串資料欄長度](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-string-column-length)及[複雜類型資料欄長度](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-complex-type-column-length)。
+ 新增了對 Linux 和 macOS (Intel 和 ARM) 作業系統的支援。如需詳細資訊，請參閱[Linux](odbc-v2-driver-getting-started-linux.md)及[macOS](odbc-v2-driver-getting-started-macos.md)。
+ AWS-SDK-CPP 已更新至 1.11.245 標籤版本。
+ curl 程式庫已更新至 8.6.0 版。
### 修正項目
+ 解決了在精確度資料欄中，針對類字串資料類型的結果集中繼資料中報告不正確值的問題。
若要下載 ODBC v2 驅動程式，請參閱 [ODBC 2.x 驅動程式下載](odbc-v2-driver.md#odbc-v2-driver-download)。如需連線資訊，請參閱 [Amazon Athena ODBC 2.x](odbc-v2-driver.md)。
## 2.0.2.1
2023-12-07 發布
Amazon Athena ODBC v2.0.2.1 驅動程式包含下列改善和修正。
### 改進
+ 改進了所有介面的 ODBC 驅動程式執行緒安全性。
+ 啟用日誌記錄時，現在會以毫秒級精確度記錄日期時間值。
+ 在使用 [瀏覽器 SSO OIDC](odbc-v2-driver-browser-sso-oidc.md) 外掛程式進行身分驗證期間，現在會開啟終端以向使用者顯示裝置代碼。
### 修正項目
+ 解決了剖析串流 API 結果時發生的記憶體釋放問題。
+ 介面 `SQLTablePrivileges()`、`SQLSpecialColumns()`、`SQLProcedureColumns()` 和 `SQLProcedures()` 的請求現在會傳回空白結果集。
若要下載 ODBC v2 驅動程式，請參閱 [ODBC 2.x 驅動程式下載](odbc-v2-driver.md#odbc-v2-driver-download)。如需連線資訊，請參閱 [Amazon Athena ODBC 2.x](odbc-v2-driver.md)。
## 2.0.2.0
2023-10-17 發布
Amazon Athena ODBC v2.0.2.0 驅動程式包含下列改善和修正。
### 改進
+ 為瀏覽器 Azure AD、瀏覽器 SSO OIDC 和 Okta 基於瀏覽器的身分驗證外掛程式新增了檔案快取功能。
BI 工具 (如 Power BI) 和基於瀏覽器的外掛程式使用多個瀏覽器視窗。新的檔案快取連線參數可讓您在 BI 應用程式開啟的多個程序之間快取及重複使用臨時憑證。
+ 應用程式現在可以在陳述式準備好後查詢結果集的相關資訊。
+ 預設連線和請求逾時已增加，以便用於速度較慢的用戶端網路。如需詳細資訊，請參閱[連線逾時](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-connection-timeout)及[請求逾時](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-request-timeout)。
+ 已針對 SSO 和 SSO OIDC 新增端點覆寫。如需詳細資訊，請參閱[端點覆寫](odbc-v2-driver-endpoint-overrides.md)。
+ 已新增連線參數，將身分驗證請求的 URI 引數傳遞至 Ping。您可以使用此參數繞過 Lake Formation 的單一角色限制。如需詳細資訊，請參閱[Ping URI 參數](odbc-v2-driver-ping.md#odbc-v2-driver-ping-uri-param)。
### 修正項目
+ 已修正使用資料列型繫結機制時發生的整數溢位問題。
+ 已從瀏覽器 SSO OIDC 身分驗證外掛程式的必要連線參數清單中移除逾時。
+ 為 `SQLStatistics()`、`SQLPrimaryKeys()`、`SQLForeignKeys()` 和 `SQLColumnPrivileges()` 新增了缺少的介面，並新增了依請求傳回空白結果集的功能。
若要下載新的 ODBC v2 驅動程式，請參閱 [ODBC 2.x 驅動程式下載](odbc-v2-driver.md#odbc-v2-driver-download)。如需連線資訊，請參閱 [Amazon Athena ODBC 2.x](odbc-v2-driver.md)。
## 2.0.1.1
2023-08-10 發布
Amazon Athena ODBC v2.0.1.1 驅動程式包含下列改進和修正。
### 改進
+ 新增 URI 記錄至 Okta 身分驗證外掛程式。
+ 新增偏好的角色參數至外部憑證提供者外掛程式
+ 在 AWS 組態檔案的描述檔名稱中新增對描述當字首的處理。
### 修正項目
+ 更正使用 Lake Formation 和 AWS STS 用戶端時發生 AWS 區域 的使用問題。
+ 將缺少的分割區索引鍵還原至資料表欄清單中。
+ 新增缺少的 `BrowserSSOOIDC` 身分驗證類型至 AWS 描述檔。
若要下載新的 ODBC v2 驅動程式，請參閱 [ODBC 2.x 驅動程式下載](odbc-v2-driver.md#odbc-v2-driver-download)。
## 2.0.1.0
2023-06-29 發布
Amazon Athena 發布 ODBC v2.0.1.0 驅動程式。
Athena 發布了新的 ODBC 驅動程式，可改善從相容 SQL 開發和商業智慧應用程式連線、查詢和視覺化資料的體驗。Athena ODBC 驅動程式最新版本支援現有驅動程式的功能，且可輕鬆升級。最新版本包含透過 [AWS IAM Identity Center](https://aws.amazon.com/iam/identity-center/) 對使用者進行身分驗證的支援。它還提供了讀取來自 Amazon S3 的查詢結果的選項，可讓您更快取得查詢結果。
如需詳細資訊，請參閱[Amazon Athena ODBC 2.x](odbc-v2-driver.md)。
# Athena ODBC 1.x 驅動程式
您可以從第三方 SQL 用戶端工具和應用程式使用 ODBC 連線來連接至 Athena。使用本頁面中的連結下載 Amazon Athena 1.x ODBC 驅動程式授權合約、ODBC 驅動程式和 ODBC 文件。有關 ODBC 連接字串的相關資訊，請參閱《ODBC 驅動程式安裝和組態指南》PDF 檔案，可從本頁面下載該檔案。如需許可的相關資訊，請參閱[透過 JDBC 和 ODBC 連接控制存取](policy-actions.md)。
**重要**
當您使用 ODBC 1.x 驅動程式時，務必注意以下要求：
**打開連接埠 444** – 將 Athena 用來串流查詢結果的連接埠 444 保持開放給輸出流量。當您使用 PrivateLink 端點連接到 Athena 時，請確定連接至 PrivateLink 端點的安全群組已在連接埠 444 上開放給輸入流量。
**athena:GetQueryResultsStream 政策** – 新增針對使用 ODBC 驅動程式的 IAM 主體的 `athena:GetQueryResultsStream` 政策動作。此政策動作不會直接透過 API 公開。它僅與 ODBC 和 JDBC 驅動程式搭配使用，做為串流結果支援的一部分。如需政策範例，請參閱 [AWS 受管政策：AWSQuicksightAthenaAccess](security-iam-awsmanpol.md#awsquicksightathenaaccess-managed-policy)。
## Windows
| 驅動程式版本 | 下載連結 |
| --- | --- |
| 適用於 Windows 32 位元的 ODBC 1.2.3.1000 | [Windows 32 位元 ODBC 驅動程式 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/Windows/SimbaAthena_1.2.3.1000_32-bit.msi) |
| 適用於 Windows 64 位元的 ODBC 1.2.3.1000 | [Windows 64 位元 ODBC 驅動程式 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/Windows/SimbaAthena_1.2.3.1000_64-bit.msi) |
## Linux
| 驅動程式版本 | 下載連結 |
| --- | --- |
| 適用於 Linux 32 位元的 ODBC 1.2.3.1000 | [Linux 32 位元 ODBC 驅動程式 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/Linux/simbaathena-1.2.3.1000-1.el7.i686.rpm) |
| 適用於 Linux 64 位元的 ODBC 1.2.3.1000 | [Linux 64 位元 ODBC 驅動程式 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/Linux/simbaathena-1.2.3.1000-1.el7.x86_64.rpm) |
## OSX
| 驅動程式版本 | 下載連結 |
| --- | --- |
| 適用於 OSX 的 ODBC 1.2.3.1000 | [OSX ODBC 驅動程式 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/OSX/SimbaAthena_1.2.3.1000.dmg) |
## 文件
| 內容 | 文件連結 |
| --- | --- |
| Amazon Athena ODBC 驅動程式授權合約 | [授權合約](https://downloads.athena.us-east-1.amazonaws.com/agreement/ODBC/Amazon+Athena+ODBC+Driver+License+Agreement.pdf) |
| ODBC 1.2.3.1000 的文件 | [ODBC 驅動程式安裝和組態指南 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/docs/Simba+Amazon+Athena+ODBC+Connector+Install+and+Configuration+Guide.pdf) |
| ODBC 1.2.3.1000 的版本備註 | [ODBC 驅動程式版本備註 1.2.3.1000](https://downloads.athena.us-east-1.amazonaws.com/drivers/ODBC/SimbaAthenaODBC_1.2.3.1000/docs/release-notes.txt) |
## ODBC 驅動程式備註
**不使用 Proxy 之連線**
如果您要指定驅動程式在不使用 Proxy 的情況下連線的特定主機，您可以使用 ODBC 連線字串中的選用 `NonProxyHost` 屬性。
該 `NonProxyHost` 屬性會指定一份以逗號分隔的主機清單，讓連接器可以在啟用 Proxy 連接時，無需經過代理伺服器即可存取，如下列範例所示：
```
.amazonaws.com,localhost,.example.net,.example.com
```
該 `NonProxyHost` 連線參數會傳遞給 `CURLOPT_NOPROXY` curl 選項。如需 `CURLOPT_NOPROXY` 格式的相關資訊，請參閱 curl 文件中的 [CURLOPT\$1NOPROXY](https://curl.se/libcurl/c/CURLOPT_NOPROXY.html)。
# 使用 ODBC 用戶端為 Microsoft AD FS 使用者設定對 Amazon Athena 的聯合存取權
若要使用 ODBC 用戶端為 Microsoft Active Directory Federation Services (AD FS) 使用者設定 Amazon Athena 的聯合存取權，您必須先在 AD FS 和您的 AWS 帳戶之間建立信任。有了此信任，您的 AD 使用者可以 AWS 使用其 AD 登入資料[聯合](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml.html#CreatingSAML-configuring-IdP)到 ，並擔任 [AWS Identity and Access Management](https://aws.amazon.com/iam/)(IAM) 角色的許可，以存取 AWS Athena API 等資源。
若要建立此信任，請將 AD FS 做為 SAML 提供者新增至 ， AWS 帳戶 並建立聯合身分使用者可以擔任的 IAM 角色。在 AD FS 方面，您可以將 新增 AWS 為依賴方，並撰寫 SAML 宣告規則，將正確的使用者屬性傳送至 AWS 以進行授權 （特別是 Athena 和 Amazon S3)。
設定 AD FS 存取 Athena，主要步驟如下所示：
[1. 設定 IAM SAML 提供者和角色](#odbc-adfs-saml-setting-up-an-iam-saml-provider-and-role)
[2. 設定 AD FS](#odbc-adfs-saml-configuring-ad-fs)
[3. 建立 Active Directory 使用者和群組](#odbc-adfs-saml-creating-active-directory-users-and-groups)
[4. 設定 AD FS ODBC 與 Athena 之間的連線](#odbc-adfs-saml-configuring-the-ad-fs-odbc-connection-to-athena)
## 1. 設定 IAM SAML 提供者和角色
在本節中，您將 AD FS 作為 SAML 提供者新增至 AWS 您的帳戶，並建立聯合身分使用者可擔任的 IAM 角色。
**若要設定 SAML 提供者**
1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 IAM 主控台。
1. 在導覽窗格中，請選擇 **Identity providers** (身分提供者)。
1. 選擇 **Add provider** (新增提供者)。
1. 在 **Provider type** (提供者類型) 選擇 **SAML**。
![\[選擇 SAML。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-1.png)
1. 對於 **Provider name** (供應商名稱)，輸入 **adfs-saml-provider**。
1. 在瀏覽器中，輸入下列位址，以下載 AD FS 伺服器的聯合 XML 檔案。若要執行此步驟，您的瀏覽器必須能夠存取 AD FS 伺服器。
```
https://adfs-server-name/federationmetadata/2007-06/federationmetadata.xml
```
1. 在 IAM 主控台中，針對**中繼資料文件**，選擇**選擇選擇檔案**，然後將聯合中繼資料檔案上傳至其中 AWS。
1. 若要完成，請選擇 **Add provider** (新增提供者)。
接著，建立聯合身分使用者可擔任的 IAM 角色。
**若要為聯合身分使用者建立 IAM 角色**
1. 在 IAM 主控台導覽窗格中，選擇 **Roles** (角色)。
1. 選擇建**立角色**。
1. 在 **Trusted entity type** (可信實體類型) 中，選擇 **SAML 2.0 federation** (SAML 2.0 聯合)。
1. 對於 **SAML 2.0-based provider** (以 SAML 2.0 為基礎的提供者)，請選擇您建立的 **adfs-saml-provider** 提供者。
1. 選擇**允許程式設計 AWS 和管理主控台存取**，然後選擇**下一步**。
![\[選擇 SAML 作為可信實體類型。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-2.png)
1. 在 **Add permissions** (新增許可) 頁面上，篩選此角色所需的 IAM 許可政策，然後選取對應的核取方塊。本教學課程會連接 `AmazonAthenaFullAccess` 和 `AmazonS3FullAccess` 政策。
![\[將 Athena 完整存取政策連接到角色。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-3.png)
![\[將 Amazon S3 完整存取政策連接到角色。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-4.png)
1. 選擇**下一步**。
1. 在 **Name, review, and create** (名稱、檢閱和建立) 頁面的 **Role name** (角色名稱) 中，輸入角色的名稱。本教學課程使用名稱 **adfs-data-access**。
在 **Step 1: Select trusted entities** (步驟 1：選取可信實體) 中，應使用 `"Federated:" "arn:aws:iam::account_id:saml-provider/adfs-saml-provider"` 自動填入 **Principal** (主體) 欄位。`Condition` 欄位應包含 `"SAML:aud"` 和 `"https://signin.aws.amazon.com/saml"`。
![\[可信實體 JSON。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-5.png)
**Step 2: Add permissions** (步驟 2：新增許可) 會說明您已連接至角色的政策。
![\[連接至角色的政策清單。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-6.png)
1. 選擇建**立角色**。橫幅訊息會確認角色的建立。
1. 請在 **Roles** (角色) 頁面上，選擇您剛剛建立的角色名稱。角色的摘要頁面會說明已連接的政策。
![\[角色的摘要頁面。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-7.png)
## 2. 設定 AD FS
現在，您可以新增 AWS 做為依賴方並撰寫 SAML 宣告規則，以便將正確的使用者屬性傳送至 AWS 以進行授權。
以 SAML 為基礎的聯合有兩個參與者：IdP (Active Directory) 和依存方 (AWS)，這是使用 IdP 身分驗證的服務或應用程式。
若要設定 AD FS，請先新增依存方信任，然後為依存方設定 SAML 宣告規則。AD FS 使用宣告規則來形成傳送給依存方的 SAML 聲明。SAML 聲明指出 AD 使用者的相關資訊為 true，並且已對使用者進行身分驗證。
### 新增依存方信任
若要在 AD FS 中新增依存方信任，您可以使用 AD FS 伺服器管理員。
**若要在 AD FS 中新增依存方信任**
1. 登入 AD FS 伺服器。
1. 在 **Start** (開始) 選單上，開啟 **Server Manager** (服器管理員)。
1. 選擇 **Tools** (工具)，然後選擇 **AD FS Management** (AD FS 管理)。
![\[選擇 Tools (工具)、AD FS Management (AD FS 管理)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-8.png)
1. 在導覽窗格的 **Trust Relationships** (信任關係) 下，選擇 **Relying Party Trusts** (依存方信任)。
1. 在 **Actions** (動作) 下，選擇 **Add Relying Party Trust** (新增依存方信任)。
![\[選擇 Add Relying Party Trust (新增依存方信任)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-9.png)
1. 在 **Add Relying Party Trust Wizard (新增信賴方信任精靈)** 頁面上，選擇 **Start (開始)**。
![\[選擇 開始使用。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-10.png)
1. 在 **Select Data Source** (選取資料來源) 頁面上，選取 **Import data about the relying party published online or on a local network** (匯入關於在線上或本機網路上發佈依存方的資料) 選項。
1. 針對 **Federation metadata address (host name or URL)** (聯合中繼資料地址 (主機名稱或 URL))，輸入 URL ** https://signin.aws.amazon.com/static/saml-metadata.xml**
1. 選擇**下一步**。
![\[設定資料來源\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-11.png)
1. 在 **Specify Display Name** (指定顯示名稱) 頁面上，對於 **Display name** (顯示名稱)，輸入您的依存方的顯示名稱，然後選擇 **Next** (下一步)。
![\[輸入依存方的顯示名稱。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-12.png)
1. 在 **Configure Multi-factor Authentication Now** (現在設定多重要素驗證) 頁面上，此教學課程會選取 **I do not want to configure multi-factor authentication for this relying party trust at this time** (我不想此時針對該依存方設定多重要素驗證)。
為了提高安全性，我們建議您設定多重驗證，以協助保護您的 AWS 資源。因為使用範例資料集，因此本教學課程不會啟用多重要素驗證。
![\[設定多重要素驗證。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-13.png)
1. 選擇**下一步**。
1. 在 **Choose Issuance Authorization Rules** (選擇發行授權規則) 頁面上，選取 **Permit all users to access this relying party** (允許所有使用者存取此依存方)。
此選項允許 Active Directory 中的所有使用者搭配使用 AD FS 和 AWS 作為依存方。您應該考量您的安全要求，並適當地對此組態進行調整。
![\[設定使用者對依存方的存取權。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-14.png)
1. 選擇**下一步**。
1. 在 **Ready to Add Trust** (準備新增信任) 頁面上，選擇 **Next** (下一步) 以將依存方信任新增至 AD FS 組態資料庫。
![\[選擇下一步。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-15.png)
1. 在 **Finish** (完成) 頁面上，選擇 **Close** (關閉)。
![\[選擇關閉。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-16.png)
### 設定依存方的 SAML 宣告規則
在此任務中，您會建立兩組宣告規則。
第一組規則 1–4,包含基於 AD 群組成員資格擔任 IAM 角色所需的 AD FS 宣告規則。如果您想要建立 [AWS 管理主控台](https://aws.amazon.com/console) 的聯合存取權，這些規則與您建立的規則相同。
第二組規則 5–6 是 Athena 存取控制所需的宣告規則。
**若要建立 AD FS 宣告規則**
1. 在 AD FS 管理主控台導覽窗格中，選擇 **Trust Relationships** (信任關係)、**Relying Party Trusts** (依存方信任)。
1. 尋找您在上一節建立的依存方。
1. 在依存方上按一下滑鼠右鍵，選擇 **Edit Claim Rules** (編輯宣告規則)，或從 **Actions** (動作) 選單中選擇 **Edit Claim Rules** (編輯宣告規則)。
![\[選擇 Edit Claim Rules (編輯宣告規則)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-17.png)
1. 選擇 **Add Rule** (新增規則)。
1. 在 Add Transform Claim Rule Wizard (新增轉換宣告規則精靈) 的 **Configure Rule** (設定規則) 頁面上，輸入下列資訊以建立宣告規則 1，然後選擇 **Finish** (完成)。
+ 針對 **Claim Rule name** (宣告規則名稱)，輸入 **NameID**。
+ 針對 **Rule template** (規則範本)，使用 **Transform an Incoming Claim** (轉換傳入宣告)。
+ 針對 **Incoming claim type** (傳入宣告類型)，選擇 **Windows account name** (Windows 帳戶名稱)。
+ 針對 **Outgoing claim type** (傳出宣告類型)，選擇 **Name ID** (名稱 ID)。
+ 針對 **Outgoing name ID format (傳出名稱 ID 格式)**，選擇 **Persistent Identifier (持久性標識符)**。
+ 選取 **Pass through all claim values** (傳遞所有宣告值)。
![\[建立第一個宣告規則。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-18.png)
1. 選擇 **Add Rule** (新增規則)，然後輸入下列資訊以建立宣告規則 2，然後選擇 **Finish** (完成)。
+ 針對 **Claim rule name** (宣告規則名稱)，輸入 **RoleSessionName**。
+ 針對 **Rule template** (規則範本)，使用 **Send LDAP Attribute as Claims** (將 LDAP 屬性傳送為宣告)。
+ 針對 **Attribute store (屬性存放區)**，選擇 **Active Directory**。
+ 針對 **Mapping of LDAP attributes to outgoing claim types** (將 LDAP 屬性映射至傳出宣告類型)，新增屬性 **E-Mail-Addresses**。針對 **Outgoing Claim Type** (傳出宣告類型)，輸入 ** https://aws.amazon.com/SAML/Attributes/RoleSessionName**。
![\[建立第二個宣告規則。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-19.png)
1. 選擇 **Add Rule** (新增規則)，然後輸入下列資訊以建立宣告規則 3，然後選擇 **Finish** (完成)。
+ 針對 **Claim rule name** (宣告規則名稱)，輸入 **Get AD Groups**。
+ 針對 **Rule template** (規則範本)，使用 **Send Claims Using a Custom Rule** (使用自訂規則傳送宣告)。
+ 針對 **Custom rule** (自訂規則)，輸入下列程式碼。
```
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname",
Issuer == "AD AUTHORITY"]=> add(store = "Active Directory", types = ("http://temp/variable"),
query = ";tokenGroups;{0}", param = c.Value);
```
![\[建立第三個宣告規則。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-20.png)
1. 選擇 **Add Rule** (新增規則)。輸入下列資訊以建立宣告規則 4，然後選擇 **Finish** (完成)。
+ 針對 **Claim rule name** (宣告規則名稱)，輸入 **Role**。
+ 針對 **Rule template** (規則範本)，使用 **Send Claims Using a Custom Rule** (使用自訂規則傳送宣告)。
+ 針對 **Custom rule** (自訂規則)，輸入下列含有您先前建立的帳戶號碼和 SAML 提供者的名稱的程式碼：
```
c:[Type == "http://temp/variable", Value =~ "(?i)^aws-"]=> issue(Type = "https://aws.amazon.com/SAML/Attributes/Role",
Value = RegExReplace(c.Value, "aws-", "arn:aws:iam::AWS_ACCOUNT_NUMBER:saml-provider/adfs-saml-provider,arn:aws:iam:: AWS_ACCOUNT_NUMBER:role/"));
```
![\[建立第四個宣告規則。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-21.png)
## 3. 建立 Active Directory 使用者和群組
現在，您已準備好建立可存取 Athena 的 AD 使用者，以及可將其放入的 AD 群組，以便您可以依群組控制存取層級。建立可分類資料存取模式的 AD 群組之後，您可以將使用者新增至這些群組。
**若要建立 AD 使用者以存取 Athena**
1. 在 Server Manager Dashboard (伺服器管理員儀表板) 上，選擇 **Tools** (工具)，然後選擇 **Active Directory Users and Computers** (Active Directory 使用者和電腦)。
![\[選擇 Tools (工具)、Active Directory Users and Computers (Active Directory 使用者和電腦)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-22.png)
1. 在導覽窗格中，選擇**使用者** 。
1. 在 **Active Directory Users and Computers** (Active Directory 使用者和電腦) 工具列上，選擇 **Create user** (建立使用者) 選項。
![\[選擇 Create user (建立使用者)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-23.png)
1. 在 **New Object – User** (新建 – 使用者) 對話方塊中，對於 **First name** (名字)、**Last name** (姓氏) 和 **Full name** (全名)，輸入名稱。本教學課程使用的是 **Jane Doe**。
![\[輸入使用者名稱。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-24.png)
1. 選擇**下一步**。
1. 對於 **Password** (密碼)，輸入密碼，然後再次輸入以確認。
為了簡單起見，本教學課程取消選取 **User must change password at next sign on** (使用者必須在下次登入時變更密碼)。在真實世界的案例中，您應該要求新建立的使用者變更其密碼。
![\[輸入密碼。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-25.png)
1. 選擇**下一步**。
1. 選擇**完成**。
![\[選擇完成。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-26.png)
1. 在 **Active Directory Users and Computers** (Active Directory 使用者和電腦) 上，選擇使用者名稱。
1. 在使用者的 **Properties** (屬性) 對話方塊中，對於 **E-mail** (電子郵件)，輸入電子郵件地址。本教學課程使用的是 **jane@example.com**。
![\[輸入電子郵件地址。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-27.png)
1. 選擇**確定**。
### 建立 AD 群組，以代表資料存取模式
您可以建立 AD 群組，其成員在登入時擔任 IAM `adfs-data-access` 角色 AWS。下列範例會建立一個名為 aws-adfs-data-access 的 AD 群組。
**若要建立 AD 群組**
1. 在 Server Manager Dashboard (伺服器管理員儀表板) 上，從 **Tools** (工具) 選單上，選擇 **Active Directory Users and Computers** (Active Directory 使用者和電腦)。
1. 在工具列上，選擇 **Create new group** (建立新的群組) 選項。
![\[選擇 Create new group (建立新群組)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-28.png)
1. 在 **New Object - Group** (新增物件 - 群組) 對話方塊中，輸入下列資訊：
+ 針對 **Group name** (群組名稱)，輸入 **aws-adfs-data-access**。
+ 針對 **Group scope** (群組範圍)，選取 **Global** (全域)。
+ 針對 **Group type** (群組類型)，選取 **Security** (安全)。
![\[在 AD 中建立全域安全群組。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-29.png)
1. 選擇**確定**。
### 將 AD 使用者新增至相應群組
既然您已建立 AD 使用者和 AD 群組，您可以將使用者新增至群組。
**若要將 AD 使用者新增至 AD 群組**
1. 在 Server Manager Dashboard (伺服器管理員儀表板) 上的 **Tools** (工具) 選單上，選擇 **Active Directory Users and Computers** (Active Directory 使用者和電腦)。
1. 針對 **First name** (名字) 和 **Last name** (姓氏)，選擇使用者 (例如，**Jane Doe**)。
1. 在使用者的 **Properties** (屬性) 對話框中的 **Member Of** (成員群組) 標籤上，選擇 **Add** (新增)。
![\[選擇新增。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-30.png)
1. 根據您的需求新增一或多個 AD FS 群組。本教學課程新增了 **aws-adfs-data-access** 群組。
1. 在 **Select Groups** (選取群組) 對話方塊中，針對 **Enter the object names to select** (輸入要選取的物件名稱)，輸入您建立的 AD FS 群組的名稱 (例如，**aws-adfs-data-access**)，然後選擇 **Check Names** (檢查名稱)。
![\[選擇 Check Names (檢查名稱)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-31.png)
1. 選擇**確定**。
在使用者的 **Properties** (屬性) 對話方塊中，AD 群組的名稱會顯示在 **Member of** (成員群組) 清單中。
![\[AD 群組已新增至使用者屬性。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-32.png)
1. 選擇 **Apply** (套用)，然後選擇 **OK** (確定)。
## 4. 設定 AD FS ODBC 與 Athena 之間的連線
建立 AD 使用者和群組之後，您便準備好使用 Windows 中的 ODBC 資料來源程式來設定 Athena ODBC 與 AD FS 的連線。
**若要設定 AD FS ODBC 與 Athena 之間的連線**
1. 安裝適用於 Athena 的 ODBC 驅動程式。如需下載連結，請參閱[使用 ODBC 連接到 Amazon Athena](connect-with-odbc.md)。
1. 在 Windows 中，選擇 **Start** (開始)，**ODBC Data Sources** (ODBC 資料來源)。
1. 在 **ODBC Data Source Administrator** (ODBC 資料來源管理員) 程式中，選擇 **Add** (新增)。
![\[選擇 Add (新增) 以新增 ODBC 資料來源。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-33.png)
1. 在 **Create New Data Source** (建立新的資料來源) 對話方塊中，選擇 **Simba Athena ODBC Driver** (Simba Athena ODBC 驅動程式)，然後選擇 **Finish** (完成)。
![\[選擇 Simba Athena ODBC Driver (Simba Athena ODBC 驅動程式)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-34.png)
1. 在 **Simba Athena ODBC Driver DSN Setup** (Simba Athena ODBC 驅動程式 DSN 設定) 對話方塊中，輸入以下值：
+ 在 **Data Source Name** (資料來源名稱)，為您的資料來源輸入名稱，例如 ** Athena-odbc-test**。
+ 在 **Description** (描述) 輸入對資料來源的描述。
+ 針對 **AWS 區域**，輸入 AWS 區域 您正在使用的 （例如 ** us-west-1**)。
+ 在 **S3 Output Location** (S3 輸出位置) 輸入您要存放輸出內容的 Amazon S3 路徑。
![\[輸入 Simba Athena ODBC Driver DSN Setup (Simba Athena ODBC 驅動程式 DSN 設定) 的值。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-35.png)
1. 選擇 **Authentication Options** (身分驗證選項)。
1. 在 **Authentication Options** (身分驗證選項) 對話方塊中，指定以下值：
+ 在 **Authentication Type** (身分驗證類型) 中，選擇 **ADFS**。
+ 在 **User** (使用者) 中，輸入使用者的電子郵件地址 (例如，**jane@example.com**)。
+ 在 **Password** (密碼) 中，輸入使用者的 ADFS 密碼。
+ 在 **IdP Host** (IdP 主機) 中，輸入 AD FS 伺服器名稱 (例如，**adfs.example.com**)。
+ 在 **IdP Port** (IdP 主機) 中，使用預設值 **443**。
+ 選取 **SSL Insecure** (SSL 不安全) 選項。
![\[設定身分驗證選項。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-adfs-saml-37.png)
1. 選擇 **OK** (確定)，以關閉 **Authentication Options** (身分驗證選項)。
1. 選擇 **Test** (測試) 以測試連接，或 **OK** (確定) 以完成操作。
# 使用 Okta 外掛程式和 Okta 身分提供者設定 ODBC 的 SSO
本頁面說明如何設定 Amazon Athena ODBC 驅動程式和 Okta 外掛程式，以使用 Okta 身分提供者新增單一登入 (SSO) 功能。
## 先決條件
完成本教學課程中的步驟需要以下項目：
+ Amazon Athena ODBC 驅動程式。如需下載連結，請查看[使用 ODBC 連接到 Amazon Athena](connect-with-odbc.md)。
+ 您要搭配 SAML 使用的 IAM 角色。如需詳細資訊，請參閱*《IAM 使用者指南》*中的[為 SAML 2.0 聯合身分建立角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)。
+ Okta 帳戶。如需詳細資訊，請前往 [Okta.com](https://www.okta.com/)。
## 在 Okta 中建立應用程式整合作業
首先，使用 Okta 儀表板建立及設定 SAML 2.0 應用程式，以透過單一登入機制存取 Athena。您可以使用 Okta 中現有的 Redshift 應用程式，設定對 Athena 的存取權。
**在 Okta 中建立應用程式整合作業**
1. 在 [Okta.com](https://www.okta.com/) 上登入您帳戶的管理頁面。
1. 在導覽窗格中，依序選擇 **Applications** (應用程式) 和 **Applications** (應用程式)。
1. 在 **Applications** (應用程式) 頁面上，選擇 **Browse App Catalog** (瀏覽應用程式目錄)。
1. 在 **Browse App Integration Catalog** (瀏覽應用程式整合目錄) 頁面的 **Use Case** (使用案例) 區段中，選擇 **All Integrations** (所有整合)。
1. 在搜尋方塊中輸入 **Amazon Web Services Redshift**，然後選擇 **Amazon Web Services Redshift SAML**。
1. 選擇 **Add Integration** (新增整合作業)。
![\[選擇 Add Integration (新增整合作業)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-1.png)
1. 在 **General Settings Required** (必要的一般設定) 區段中，針對 **Application ** (應用程式) 標籤輸入應用程式的名稱。本教學課程使用的名稱為 **Athena-ODBC-Okta**。
![\[輸入 Okta 應用程式的名稱。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-2.png)
1. 選擇 **Done** (完成)。
1. 在 Okta 應用程式的頁面上 (例如 **Athena-ODBC-Okta**)，選擇 **Sign On** (登入)。
![\[選擇 Sign On (登入) 標籤。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-3.png)
1. 在 **Settings** (設定) 區段中，選擇 **Edit** (編輯)。
![\[選擇 Edit (編輯)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-4.png)
1. 在 **Advanced Sign-on Settings** (進階登入設定) 區段設定下列值。
+ 對於 **IdP ARN 和角色 ARN**，請以逗號分隔值輸入您的 AWS IDP ARN 和角色 ARN。如需 IAM 角色格式的相關資訊，請參閱[《IAM 使用者指南》](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html)的*為身分驗證回應設定 SAML 聲明*。
+ 在 **Session Duration** (工作階段持續時間) 輸入 900 秒到 43200 秒之間的值。本教學課程使用預設值 3600 (亦即 1 小時)。
![\[輸入進階登入設定。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-5.png)
Athena 不需使用 **DbUser Format** (DbUser 格式)、**AutoCreate** 和 **Allowed DBGroups** (允許的 DBGroups) 設定，因此您不必設定這些欄位。
1. 選擇**儲存**。
## 從 Okta 擷取 ODBC 組態資訊
既然您已建立 Okta 應用程式，您可以準備擷取應用程式的 ID 和 IdP 主機 URL。稍後設定 ODBC 以連線至 Athena 時，您會需要這些資訊。
**從 Okta 擷取 ODBC 組態資訊**
1. 選擇 Okta 應用程式的 **General** (一般) 標籤，接著向下捲動至 **App Embed Link** (應用程式內嵌連結) 區段。
![\[Okta 應用程式的內嵌連結 URL。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-6.png)
**Embed Link** (內嵌連結) URL 的格式如下：
```
https://trial-1234567.okta.com/home/amazon_aws_redshift/Abc1de2fghi3J45kL678/abc1defghij2klmNo3p4
```
1. 從您的 **Embed Link** (內嵌連結) URL 擷取及儲存以下部分：
+ 第一個區段中 `https://` 之後到 `okta.com` (含) 的內容 (例如 **trial-1234567.okta.com**)。這是您的 IdP 主機。
+ URL 的最後兩小段，包括中間的正斜線。這些區段是兩個由 20 個字元組成的字串，其中包含數字和大小寫字母的混合 (例如 **Abc1de2fghi3J45kL678/abc1defghij2klmNo3p4**)。這是您的應用程式 ID。
## 將使用者新增至 Okta 應用程式
現在您可以準備將使用者新增至 Okta 應用程式。
**將使用者新增至 Okta 應用程式**
1. 在左側導覽窗格中，選擇 **Directory** (目錄)，然後選擇 **People** (人員)。
1. 選擇 **Add Person** (新增人員)。
![\[選擇 Add Person (新增人員)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-7.png)
1. 在 **Add Person** (新增人員) 對話方塊中輸入下列資訊。
+ 輸入 **First name** (名字) 和 **Last name** (姓氏) 的值。本教學課程使用的是 **test user**。
+ 輸入 **Username** (使用者名稱) 和 **Primary email** (主要電子郵件) 的值。對於這兩個欄位，本教學課程皆使用 **test@amazon.com**。您對密碼的安全要求可能不盡相同。
![\[輸入使用者憑證。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-8.png)
1. 選擇**儲存**。
現在，您可以準備將所建立的使用者指派給您的應用程式。
**將使用者指派給應用程式**
1. 在導覽窗格中，依序選擇 **Applications** (應用程式) 和 **Applications** (應用程式)，然後選擇您應用程式的名稱 (例如 **Athena-ODBC-Okta**)。
1. 選擇 **Assign** (指派)，然後選擇 **Assign to People** (指派給人員)。
![\[選擇 Assign to People (指派給人員)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-9.png)
1. 為您的使用者選擇 **Assign** (指派) 選項，然後選擇 **Done** (完成)。
![\[選擇 Assign (指派)，然後選擇 Done (完成)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-10.png)
1. 畫面出現提示時，選擇 **Save and Go Back** (儲存並返回)。對話方塊會顯示使用者的狀態為 **Assigned** (已指派)。
1. 選擇**完成**。
1. 選擇 **Sign On** (登入) 標籤。
1. 向下捲動至 **SAML Signing Certificates** (SAML 簽署憑證) 區段。
1. 選擇 **Actions** (動作)。
1. 開啟內容功能表 (按一下滑鼠右鍵)，選擇 **View IdP metadata** (檢視 IdP 中繼資料)，然後選擇瀏覽器選項以儲存檔案。
1. 以 `.xml` 為副檔名儲存檔案。
![\[將 IdP 中繼資料儲存至本機 XML 檔案。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-11.png)
## 建立 AWS SAML 身分提供者和角色
現在您已準備好將中繼資料 XML 檔案上傳至其中的 IAM 主控台 AWS。您將使用此檔案來建立 AWS SAML 身分提供者和角色。請使用 AWS 服務管理員帳戶執行這些步驟。
**在 中建立 SAML 身分提供者和角色 AWS**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/IAM/](https://console.aws.amazon.com/IAM/) 開啟 IAM 主控台。
1. 在導覽窗格中，選擇 **Identity providers** (身分提供者)，然後選擇 **Add provider** (新增提供者)。
![\[選擇 Add provider (新增提供者)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-12.png)
1. 在 **Add an Identity provider** (新增身分提供者) 頁面的 **Configure provider** (設定提供者) 位置，輸入下列資訊。
+ 在 **Provider type** (提供者類型) 選擇 **SAML**。
+ 在 **Provider name** (提供者名稱) 輸入提供者的名稱，例如 ** AthenaODBCOkta**。
+ 在 **Metadata document** (中繼資料文件) 使用 **Choose file** (選擇檔案) 選項，上傳您所下載的身分提供者 (IdP) 中繼資料 XML 檔案。
![\[輸入身分提供者的名稱。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-13.png)
1. 選擇 **Add provider** (新增提供者)。
### 為 Athena 和 Amazon S3 存取作業建立 IAM 角色
現在，您可以準備為 Athena 和 Amazon S3 存取作業建立 IAM 角色。您會將這個角色指派給您的使用者，如此一來，該使用者就能透過單一登入機制存取 Athena。
**為使用者建立 IAM 角色**
1. 在 IAM 主控台導覽窗格中，選擇 **Roles** (角色)，然後選擇 **Create role** (建立角色)。
![\[選擇建立角色。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-14.png)
1. 在 **Create role** (建立角色) 頁面上選擇下列選項：
+ 在 **Select type of trusted entity** (選取信任的實體類型) 選擇 **SAML 2.0 Federation** (SAML 2.0 聯合)。
+ 在 **SAML 2.0-based provider** (SAML 2.0 提供者) 選擇您所建立的 SAML 身分提供者，例如 **AthenaODBCOkta**。
+ 選取**允許程式設計和 AWS 管理主控台 存取**。
![\[選擇 Create role (建立角色) 頁面上的選項。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-15.png)
1. 選擇**下一步**。
1. 在 **Add Permissions** (新增許可) 頁面上的 **Filter policies** (篩選政策) 位置，輸入 **AthenaFull**，然後按 Enter 鍵。
1. 選取 `AmazonAthenaFullAccess` 受管政策，然後選擇 **Next** (下一步)。
![\[選擇 AmazonAthenaFullAccess 受管政策。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-16.png)
1. 在 **Name, review, and create** (命名、檢閱及建立) 頁面上的 **Role name** (角色名稱) 位置，輸入角色的名稱 (例如 **Athena-ODBC-OktaRole**)，然後選擇 **Create role (建立角色)**。
## 設定 Okta ODBC 與 Athena 之間的連線
現在，您可以準備使用 Windows 的 ODBC 資料來源程式，設定 Okta ODBC 與 Athena 的連線。
**設定 Okta ODBC 與 Athena 的連線**
1. 啟動 Windows 的 **ODBC 資料來源**程式。
1. 在 **ODBC Data Source Administrator** (ODBC 資料來源管理員) 程式中，選擇 **Add** (新增)。
![\[選擇新增。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-17.png)
1. 選擇 **Simba Athena ODBC Driver** (Simba Athena ODBC 驅動程式)，然後選擇 **Finish** (完成)。
![\[選擇 Athena ODBC 驅動程式。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-18.png)
1. 在 **Simba Athena ODBC Driver DSN Setup** (Simba Athena ODBC 驅動程式 DSN 設定) 對話方塊中，輸入所述的值。
+ 在 **Data Source Name** (資料來源名稱)，為您的資料來源輸入名稱，例如 **Athena ODBC 64**。
+ 在 **Description** (描述) 輸入對資料來源的描述。
+ 針對 **AWS 區域**，輸入 AWS 區域 您正在使用的 （例如 **us-west-1**)。
+ 在 **S3 Output Location** (S3 輸出位置) 輸入您要存放輸出內容的 Amazon S3 路徑。
![\[輸入您為資料來源名稱設定的值。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-19.png)
1. 選擇 **Authentication Options** (身分驗證選項)。
1. 在 **Authentication Options** (身分驗證選項) 對話方塊中，選擇或輸入以下值。
+ 在 **Authentication Type** (身分驗證類型) 選擇 **Okta**。
+ 在 **User** (使用者) 輸入您的 Okta 使用者名稱。
+ 在 **Password** (密碼) 輸入您的 Okta 密碼。
+ 在 **IdP Host** (IdP 主機) 輸入您先前記下的值，例如 **trial-1234567.okta.com**。
+ 在 **IdP Port** (IdP 連接埠) 輸入 **443**。
+ 在 **App ID** (應用程式 ID) 輸入您先前記下的值 (Okta 內嵌連結的最後兩個區段)。
+ 在 **Okta App Name** (Okta 應用程式名稱) 輸入 **amazon\$1aws\$1redshift**。
![\[輸入身分驗證選項。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/odbc-okta-plugin-20.png)
1. 選擇 **OK** (確定)。
1. 選擇 **Test** (測試) 來測試連線，或選擇 **OK** (確定) 完成操作。
# 使用 ODBC、SAML 2.0 和 Okta 身分提供者設定單一登入
若要連接到資料來源，您可以將 Amazon Athena 與 PingOne、Okta、OneLogin 等身分提供者 (IdP) 一起使用。從 Athena ODBC 驅動程式 1.1.13 版和 Athena JDBC 驅動程式 2.0.25 版開始，包含瀏覽器 SAML 外掛程式，您可以將其設定為與任何 SAML 2.0 提供者一起使用。此主題說明如何設定 Amazon Athena ODBC 驅動程式和以瀏覽器為基礎的 SAML 外掛程式，以使用 Okta 身分提供者新增單一登入 (SSO) 功能。
## 先決條件
完成本教學課程中的步驟需要以下內容：
+ Athena ODBC 驅動程式 1.1.13 版或更高版本。1.1.13 版及更新版本包括瀏覽器 SAML 支援。如需下載連結，請參閱[使用 ODBC 連接到 Amazon Athena](https://docs.aws.amazon.com/athena/latest/ug/connect-with-odbc.html)。
+ 您要搭配 SAML 使用的 IAM 角色。如需詳細資訊，請參閱*《IAM 使用者指南》*中的[為 SAML 2.0 聯合身分建立角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html)。
+ Okta 帳戶。如需詳細資訊，請造訪 [okta.com](https://www.okta.com/)。
## 在 Okta 中建立應用程式整合作業
首先，使用 Okta 儀表板建立和設定 SAML 2.0 應用程式，以進行單一登入至 Athena。
**使用 Okta 儀表板設定 Athena 的單一登入**
1. 登入 Okta 管理頁面，網址為 `okta.com`。
1. 在導覽窗格中，選擇 **Applications** (應用程式)、**Applications** (應用程式)。
1. 在 **Applications** (應用程式) 頁面，選擇 **Create App Integration** (建立應用程式整合)。
![\[選擇 Create App Integration (建立應用程式整合)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-1.png)
1. 在 **Create a new app integration** (建立新的應用程式整合) 對話方塊中，為 **Sign-in method** (登入方法) 選取 **SAML 2.0**，然後選擇 **Next** (下一步)。
![\[選擇 SAML 2.0\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-2.png)
1. 在 **Create SAML Integration** (建立 SAML 整合) 頁面的 **General Settings** (一般設定) 區段中，輸入應用程式的名稱。本教學課程使用名稱 **Athena SSO**。
![\[輸入 Okta 應用程式的名稱。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-3.png)
1. 選擇 **Next** (下一步)。
1. 在 **Configure SAML** (設定 SAML) 頁面的 **SAML Settings** (SAML 設定) 區段中，輸入以下值：
+ **Single sign on URL** (URL 上的單一登入)：輸入 **http://localhost:7890/athena**
+ **Audience URI** (對象 URI)：輸入 **urn:amazon:webservices**
![\[輸入 SAML 設定。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-4.png)
1. **Attribute Statements (optional)** (屬性陳述式 (選用))：輸入以下兩個名稱/值對。這些是必要的映射屬性。
+ 於 **Name** (名稱) 輸入下列 URL：
**https://aws.amazon.com/SAML/Attributes/Role**
**Value** (值)：輸入 IAM 角色名稱。如需 IAM 角色格式的相關資訊，請參閱《*IAM 使用者指南*》的[為身分驗證回應設定 SAML 聲明](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html)。
+ 於 **NAME** (名稱) 輸入下列 URL：
**https://aws.amazon.com/SAML/Attributes/RoleSessionName**
於 **Value** (數值) 輸入 **user.email**。
![\[為 Athena 輸入 SAML 屬性。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-5.png)
1. 選擇 **Next** (下一步)，然後選擇 **Finish** (完成)。
Okta 建立應用程式時還會建立您的登入 URL；接下來會擷取該 URL。
## 從 Okta 儀表板取得登入 URL
現在您的應用程式已建立完畢，您可以從 Okta 儀表板取得其登入 URL 和其他中繼資料。
**從 Okta 儀表板取得登入 URL**
1. 在 Okta 導覽窗格中，選擇 **Applications** (應用程式)、**Applications** (應用程式)。
1. 選擇您要尋找登入 URL 的應用程式，(例如 **AthenaSSO**)。
1. 在您應用程式的頁面中，選擇 **Sign On** (登入)。
![\[選擇 Sign On (登入)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-6.png)
1. 選擇 **View Setup Instructions** (檢視設定指示)。
![\[選擇 View Setup Instructions (檢視設定指示)。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-7.png)
1. 在 **How to Configure SAML 2.0 for Athena SSO** (如何為 Athena SSO 設定 SAML 2.0) 頁面上，尋找身分提供者**身分提供者發行者**的 URL。Okta 儀表板中的某些位置會將此 URL 視為 **SAML 發行者 ID**。
![\[身分提供者發行者的值為您的登入 URL。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-8.png)
1. 複製或存放身分提供者**身分提供者單一登入 URL** 的值。
在下一區段中，當您設定 ODBC 連接時，您將提供這個值作為瀏覽器 SAML 外掛程式的**登入 URL** 連接參數。
## 設定瀏覽器 SAML ODBC 連接至 Athena
現在，您已經準備好在 Windows 中使用 ODBC 資料來源程式來設定瀏覽器 SAML 與 Athena 的連接。
**設定瀏覽器 SAML ODBC 連接至 Athena**
1. 在 Windows 中，啟動 **ODBC 資料來源**程式。
1. 在 **ODBC Data Source Administrator** (ODBC 資料來源管理員) 程式中，選擇 **Add** (新增)。
![\[選擇新增。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-9.png)
1. 選擇 **Simba Athena ODBC Driver** (Simba Athena ODBC 驅動程式)，然後選擇 **Finish** (完成)。
![\[選擇 Simba Athena Driver (Simba Athena 驅動程式)\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-10.png)
1. 在 **Simba Athena ODBC Driver DSN Setup** (Simba Athena ODBC 驅動程式 DSN 設定) 對話方塊中，輸入描述的值。
![\[輸入 DSN 設定值。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-11.png)
+ **Data Source Name** (資料來源名稱)：輸入您的資料來源名稱 (例如 **Athena ODBC 64**)。
+ 於 **Description** (描述) 輸入您資料來源的描述。
+ 針對 **AWS 區域**，輸入 AWS 區域 您正在使用的 （例如，**us-west-1**)。
+ 在 **S3 Output Location** (S3 輸出位置) 輸入您要存放輸出內容的 Amazon S3 路徑。
1. 選擇 **Authentication Options** (身分驗證選項)。
1. 在 **Authentication Options** (身分驗證選項) 對話方塊中，選擇或輸入以下值。
![\[輸入身分驗證選項。\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/okta-saml-sso-12.png)
+ **Authentication Type** (身分驗證類型)：選擇 **BrowserSAML**。
+ 對於**登入 URL**，輸入您從 Okta 儀表板取得的身分提供者**身分提供者單一登入 URL**。
+ 於 **Listen Port** (接聽連接埠) 輸入 **7890**。
+ **Timeout (sec)** (逾時 (秒))：輸入連接逾時值 (以秒為單位)。
1. 選擇 **OK** (確定)，以關閉 **Authentication Options** (身分驗證選項)。
1. 選擇 **Test** (測試) 以測試連接，或 **OK** (確定) 以完成操作。
# 使用 Amazon Athena Power BI 連接器
您可以在 Windows 作業系統上，使用 Amazon Athena 的 Microsoft Power BI 連接器，以在 Microsoft Power BI 桌面版中分析 Amazon Athena 的資料。如需 Power BI 的相關資訊，請參閱 [Microsoft Power BI](https://powerbi.microsoft.com/)。在您將內容發佈至 Power BI 服務後，便可使用 2021 年 7 月或更新版本的 [Power BI 閘道](https://powerbi.microsoft.com/gateway/)，透過隨需或排程的重新整理，讓內容保持在最新狀態。
## 先決條件
在您開始前，請確定您的環境符合下列要求。需使用 Amazon Athena ODBC 驅動程式。
+ [AWS 帳戶](https://aws.amazon.com/)
+ [使用 Athena 的許可](policy-actions.md)
+ [Amazon Athena ODBC 驅動程式](connect-with-odbc.md)
+ [Power BI 桌面版](https://powerbi.microsoft.com/en-us/desktop/)
## 支援的功能
+ **匯入** - 將選取的資料表和資料欄匯入 Power BI 桌面版，以進行查詢。
+ **DirectQuery** - 不會將任何資料匯入或複製至 Power BI 桌面版。Power BI 桌面版會直接查詢基礎資料來源。
+ **Power BI 閘道** – 您 中的內部部署資料閘道 AWS 帳戶 ，運作方式類似 Microsoft Power BI Service 和 Athena 之間的橋樑。需要有閘道才能查看您在 Microsoft Power BI 服務上的資料。
## 連接至 Amazon Athena
若要將 Power BI 桌面版連接至您的 Amazon Athena 資料，請執行下列步驟。
**從 Power BI 桌面版連接至 Athena 資料**
1. 啟動 Power BI 桌面版。
1. 執行以下任意一項：
+ 選擇 **File** (檔案)，然後選取 **Get Data** (取得資料)
+ 從 **Home** (首頁) 功能區中，選擇 **Get Data** (取得資料)。
1. 在搜尋方塊中，輸入 **Athena**。
1. 選取 **Amazon Athena**，然後選擇 **Connect** (連接)。
![\[選擇 Amazon Athena 連接器\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connect-with-odbc-and-power-bi-1.png)
1. 在 **Amazon Athena** 連接頁面上，輸入以下資訊。
+ 若為 **DSN**，請輸入您要使用的 ODBC DSN 名稱。如需有關設定 DSN 的指示，請參閱 [ODBC 驅動程式文件](connect-with-odbc-driver-and-documentation-download-links.md#connect-with-odbc-driver-documentation)。
+ 若為**資料連線模式**，請依照以下一般準則選擇一個適合您使用案例的模式：
+ 若為較小的資料集，請選擇 **Import** (匯入)。在使用匯入模式時，Power BI 會與 Athena 搭配運作，以匯入整個資料集的內容，以便在視覺效果中使用。
+ 若為較大的資料集，請選擇 **DirectQuery**。在 DirectQuery 模式中，系統不會下載任何資料至您的工作站。在您建立視覺效果或與其互動時，Microsoft Power BI 會與 Athena 搭配運作，動態查詢基礎資料來源，讓您隨時都能檢視目前資料。如需 DirectQuery 的詳細資訊，請參閱 Microsoft 文件中的[在 Power BI 桌面版中使用 DirectQuery](https://docs.microsoft.com/power-bi/connect-data/desktop-use-directquery)。
![\[輸入您的資料連接資訊\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connect-with-odbc-and-power-bi-2.png)
1. 選擇**確定**。
1. 在設定資料來源身分驗證的提示中，選擇 **Use Data Source Configuration** (使用資料來源組態) 或**AAD Authentication** (AAD 身分驗證)，然後選擇 **Connect** (連接)。
![\[選擇一個資料來源身分驗證方法\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connect-with-odbc-and-power-bi-3.png)
您的資料目錄、資料庫和資料表會顯示在 **Navigator** (導覽器) 對話方塊中。
![\[導覽器會顯示您的資料\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connect-with-odbc-and-power-bi-4.png)
1. 在 **Display Options** (顯示選項) 窗格中，選取您要使用之資料集的核取方塊。
1. 如果您要在匯入資料集之前轉換資料集，請前往對話方塊底部，並選擇 **Transform Data** (轉換資料)。這會開啟 Power Query 編輯器，以便您篩選和精簡要使用的資料集。
1. 選擇**載入**。載入完成後，您便可以建立視覺效果 (如下圖所示)。如果您選取 **DirectQuery** 作為匯入模式，Power BI 會就您要求的視覺效果向 Athena 發出查詢。
![\[範例資料視覺效果\]](http://docs.aws.amazon.com/zh_tw/athena/latest/ug/images/connect-with-odbc-and-power-bi-5.png)
## 設定內部部署閘道
您可以將儀表板和資料集發佈至 Power BI 服務，讓其他使用者可以透過 Web、行動裝置和內嵌應用程式與其互動。若要在 Microsoft Power BI 服務中查看您的資料，請在 AWS 帳戶中安裝 Microsoft Power BI 內部部署資料閘道。閘道會如同 Microsoft Power BI 服務和 Athena 之間的橋樑般運作。
**下載、安裝及測試內部部署資料閘道**
1. 請前往 [Microsoft Power BI gateway download](https://powerbi.microsoft.com/en-us/gateway/) (Microsoft Power BI 閘道下載)頁面，然後選擇個人模式或標準模式。個人模式適用於在本機測試 Athena 連接器。標準模式適用於多名使用者生產設定。
1. 若要安裝內部部署閘道 (個人或標準模式)，請參閱 Microsoft 文件中的[安裝內部部署資料閘道](https://docs.microsoft.com/en-us/data-integration/gateway/service-gateway-install)。
1. 若要測試閘道，請依照 Microsoft 文件中的[搭配使用自訂資料連接器和內部部署資料閘道](https://docs.microsoft.com/en-us/power-bi/connect-data/service-gateway-custom-connectors)。
如需內部部署資料閘道的詳細資訊，請參閱以下 Microsoft 資源。
+ [什麼是內部部署資料閘道？](https://docs.microsoft.com/en-us/power-bi/connect-data/service-gateway-onprem)
+ [部署 Power BI 資料閘道的指引](https://docs.microsoft.com/en-us/power-bi/connect-data/service-gateway-deployment-guidance)
如需設定 Power BI Gateway 與 Athena 搭配使用的範例，請參閱 AWS 大數據部落格文章[使用 amazon Athena 在 Microsoft power BI 上快速建立儀表板](https://aws.amazon.com/blogs/big-data/creating-dashboards-quickly-on-microsoft-power-bi-using-amazon-athena/)。
# 搭配使用可信身分傳播與 Amazon Athena 驅動器
可信身分傳播為希望集中管理資料許可並根據其 IdP 身分跨服務界限授權請求的組織提供了新的身分驗證選項。使用 IAM Identity Center，您可以設定現有的 IdP 來管理使用者和群組，並使用 AWS Lake Formation 為這些 IdP 身分定義目錄資源的精細存取控制許可。Athena 支援在查詢資料時進行身分傳播，以稽核透過 IdP 身分的資料存取，進而協助您的組織滿足其法規和合規要求。
您現在可以使用 Java 資料庫連線 (JDBC) 或開放式資料庫連線 (ODBC) 驅動器，透過 IAM Identity Center 使用單一登入功能連線至 Athena。當您從 PowerBI、Tableau 或 DBeaver 等工具存取 Athena 時，您的身分和許可會透過 IAM Identity Center 自動傳播到 Athena。這表示在查詢資料時，會直接強制執行您的個別資料存取許可，而不需要單獨的身分驗證步驟或憑證管理。
對於管理員，此功能會透過 IAM Identity Center 和 Lake Formation 集中存取控制，進而確保在連接到 Athena 的所有支援分析工具中強制執行一致的許可。若要開始使用，請確保您的組織已將 IAM Identity Center 設定為您的身分來源，並為使用者設定適當的資料存取許可。
**Topics**
+ [關鍵定義](#using-trusted-identity-propagation-key-definitions)
+ [考量事項](#using-trusted-identity-propagation-considerations)
+ [先決條件](#using-trusted-identity-propagation-prerequisites)
+ [將 Athena 連線至 IAM Identity Center](using-trusted-identity-propagation-setup.md)
+ [使用 設定和部署資源 AWS CloudFormation](using-trusted-identity-propagation-cloudformation.md)
## 關鍵定義
1. **應用程式角色** – 交換字符、擷取工作群組和客戶受管 AWS IAM Identity Center 應用程式 ARN 的角色。
1. **存取角色** – 搭配 Athena 驅動器使用的角色，以便透過身分增強憑證執行客戶工作流程。這表示需要此角色才能存取下游服務。
1. **客戶自管應用程式** – AWS IAM Identity Center 應用程式。如需詳細資訊，請參閱[客戶自管應用程式](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html)。
## 考量事項
1. 此功能僅適用於已全面推出具有可信身分傳播的 Athena 的區域。如需有關可用性的詳細資訊，請參閱[考量事項和限制](https://docs.aws.amazon.com/athena/latest/ug/workgroups-identity-center.html)。
1. JDBC 和 ODBC 驅動程式支援啟用 IAM 的工作群組的受信任身分傳播。
1. 您可以使用 JDBC 和 ODBC 作為獨立驅動器，或搭配任何具有信任身分傳播的 BI 或 SQL 工具使用此身分驗證外掛程式。
## 先決條件
1. 您必須啟用 AWS IAM Identity Center 執行個體。如需詳細資訊，請參閱[什麼是 IAM Identity Center？](https://docs.aws.amazon.com/singlesignon/latest/userguide/identity-center-instances.html)。
1. 您必須有運作中的外部身分提供者，且使用者或群組必須存在於 AWS IAM Identity Center 中。您可以自動佈建使用者或群組，或是手動或透過 SCIM 佈建。如需詳細資訊，請參閱[使用 SCIM 將外部身分提供者佈建至 IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/provision-automatically.html)。
1. 您必須將 Lake Formation 許可授予目錄、資料庫和資料表的使用者或群組。如需詳細資訊，請參閱[使用 Athena 透過 Lake Formation 查詢資料](https://docs.aws.amazon.com/athena/latest/ug/security-athena-lake-formation.html)。
1. 您必須擁有正常運作中的 BI 工具或 SQL 用戶端，才能使用 JDBC 或 ODBC 驅動器執行 Athena 查詢。
# 將 Athena 連線至 IAM Identity Center
下節列出將 Athena 連線至 IAM Identity Center 的程序。
## 設定可信權杖發行者
遵循[設定可信權杖發行者](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)指南，以便設定可信權杖發行者。這將建立 AWS IAM Identity Center。
**注意**
對於**提供者問題**，選擇 **OpenID Connect**。在**提供者 URL** 中，輸入身分提供者的發行者 URL。對於**對象**，指定您應用程式身分提供者發出的用戶端 ID。
複製 IAM Identity Provider 的應用程式資源名稱 AWS (ARN)。如需相關資訊，請參閱《[身分提供者和聯合](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html)》。
## 設定 IAM 角色
### 設定 IAM 應用程式角色
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在左側導覽窗格中，選擇**角色**，然後選擇**建立角色**。
1. 對於**信任的實體類型**，選擇**自訂信任政策**：
1. 對於**聯合主體**，新增您在可信權杖發行者設定期間複製的 AWS IAM 身分提供者的 ARN。
1. 對於政策條件，從外部聯合身分提供者新增對象。
1. 新增下列內嵌政策，以授予使用者對 [CreateTokenWithIAM](https://docs.aws.amazon.com/singlesignon/latest/OIDCAPIReference/API_CreateTokenWithIAM.html)、[ListTagsForResource](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListTagsForResource.html) 和 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) 許可的存取權。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:ListTags*",
"sso:ListTags*"
],
"Resource": "*"
}
]
}
```
------
**注意**
`CreateTokenWithIam` 許可會在客戶自管的 IAM Identity Center 應用程式中授予。
1. 複製應用程式角色的 ARN。
### 設定 IAM 存取角色
1. 前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。
1. 在左側導覽窗格中，選擇**角色**，然後選擇**建立角色**。
1. 對於**信任的實體類型**，選擇**自訂信任政策**：
1. 對於**聯合主體**，新增您在可信權杖發行者設定期間複製的 AWS IAM Identity Center 的 ARN。
1. 對於 **AWS 主體**，新增在 IAM 應用程式角色設定期間複製的 AWS IAM 應用程式角色 ARN。
1. 新增下列**內嵌政策**，以授予驅動器工作流程的存取權：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:StartQueryExecution",
"athena:GetQueryExecution",
"athena:GetQueryResults",
"athena:ListWorkGroups",
"athena:ListDataCatalogs",
"athena:ListDatabases",
"athena:ListTableMetadata"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetObject",
"s3:PutObject"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"glue:GetDatabase",
"glue:GetDatabases",
"glue:CreateTable",
"glue:GetTable",
"glue:GetTables",
"glue:UpdateTable",
"glue:DeleteTable",
"glue:BatchDeleteTable",
"glue:GetTableVersion",
"glue:GetTableVersions",
"glue:DeleteTableVersion",
"glue:BatchDeleteTableVersion",
"glue:CreatePartition",
"glue:BatchCreatePartition",
"glue:GetPartition",
"glue:GetPartitions",
"glue:BatchGetPartition",
"glue:UpdatePartition",
"glue:DeletePartition",
"glue:BatchDeletePartition"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"lakeformation:GetDataAccess"
],
"Resource": "*"
}
]
}
```
------
1. 複製存取角色的 ARN。
## 設定 AWS IAM Identity Center 客戶受管應用程式
若要設定客戶受管應用程式，請遵循[設定客戶受管 OAuth 2.0 應用程式以取得受信任身分傳播中的步驟](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-trusted-identity-propagation-set-up-your-own-app-OAuth2.html)，並考量 Athena 的下列事項。
+ 對於**標籤**，新增下列鍵值對：
+ **索引鍵** – **AthenaDriverOidcAppArn**
+ **值** – 在 IAM 存取角色設定期間複製的 **AccessRoleARN**。
+ [指定應用程式登入](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps-trusted-identity-propagation-set-up-your-own-app-OAuth2.html#customermanagedapps-trusted-identity-propagation-set-up-your-own-app-OAuth2-specify-application-credentials)資料時，請新增您在 AWS IAM 應用程式角色設定期間複製的 IAM 應用程式角色 ARN。
+ 對於**可接收請求的應用程式**，選擇 **AWS-Lake-Formation-AWS-Glue-Data-Catalog-**。
+ 針對**要套用的存取範圍**，選取啟用 IAM 的工作群組的 **lakeformation：query**，或選取啟用 Identity Center 的工作群組的 **lakeformation：query**、**athena：workgroup：read\$1write** 和 **s3：access\$1grants：read\$1write**。
## 設定工作群組關聯
1. 在 Athena 主控台導覽窗格中，選擇 **Workgroups** (工作群組)。
1. 從清單中選擇工作群組，然後開啟**標籤**索引標籤。
1. 選擇**管理標籤**，然後輸入下列內容：
1. **索引鍵**：`AthenaDriverOidcAppArn`
1. **值** – AWS IAM Identity Center 應用程式的 ARN。
1. 選擇**儲存**。
管理員完成一次性設定後，他們可以將基本連線詳細資訊分發給使用者。使用者需要這五個強制性參數才能執行 SQL 工作負載：
1. **ApplicationRoleARN** – 應用程式角色的 ARN
1. **JwtWebIdentityToken** – 用於身分驗證的 JWT 權杖
1. **WorkgroupARN** – Athena 工作群組的 ARN
1. **JwtRoleSessionName** – JWT 角色的工作階段名稱
1. **CredentialsProvider** – 憑證提供者組態
**注意**
我們已透過策略標記簡化連線字串組態。透過正確標記 Athena 工作群組和 AWS IAM Identity Center 客戶受管應用程式，管理員無需使用者提供 `AccessRoleArn`和 `CustomerIdcApplicationArn`。外掛程式會使用應用程式角色來尋找必要的標籤，並擷取其工作流程的對應 ARN 值，進而自動處理此問題。
管理員仍然可以視需要調整應用程式角色許可，從而讓使用者在連線字串中提供 `AccessRoleArn` 或 `CustomerIdcApplicationArn`。
## 使用已啟用可信身分傳播的 Athena 驅動器執行查詢
下載要使用的最新版本驅動器。如需有關 JDBC 安裝的詳細資訊，請參閱 [JDBC 3.x 驅動器入門](jdbc-v3-driver-getting-started.md)。您可以根據支援的平台選擇安裝 ODBC 驅動器。如需詳細資訊，請參閱[ODBC 2.x 驅動器入門](odbc-v2-driver-getting-started.md)。根據您要使用的驅動器，提供下文列出的參數：
+ [JDBC 身分驗證外掛程式連線參數](jdbc-v3-driver-jwt-tip-credentials.md)
+ [ODBC 身分驗證外掛程式連線參數](odbc-v2-driver-jwt-tip.md)
**注意**
具有驅動器的可信身分傳播僅適用於 JDBC 3.6.0 版或更高版本和 ODBC 2.0.5.0 版或更高版本。
## 搭配使用 Athena 驅動器與具有 DBeaver 的可信身分傳播
1. 從 Athena 下載具有相依性的最新 JDBC jar。如需詳細資訊，請參閱[Athena JDBC 3.x 驅動程式](jdbc-v3-driver.md)。
1. 在電腦上開啟 DBeaver 應用程式。
1. 導覽至螢幕頂端的**資料庫**選單，然後選擇**驅動器管理員**。
1. 選擇**新增**，然後選擇**程式庫**。
1. 新增最新的驅動器，然後選擇**尋找類別**。這將為您提供類似 `com.amazon.athena.jdbc.AthenaDriver` 的檔案路徑。
1. 開啟**設定**索引標籤並提供下列欄位
1. **驅動器名稱** – Athena JDBC 可信身分傳播
1. **類別名稱**– `com.amazon.athena.jdbc.AthenaDriver`
1. 選取選項**無身分驗證**。
1. 選擇**連接至資料庫**並尋找 Athena JDBC 可信身分傳播。這會將您導向至 JDBC URL。如需詳細資訊，請參閱[設定驅動程式](jdbc-v3-driver-getting-started.md#jdbc-v3-driver-configuring-the-driver)。
1. 提供下列詳細資訊
1. **工作群組** – 您要在其中執行查詢的工作群組。如需有關工作群組的資訊，請參閱[工作群組](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
1. **區域** – 將執行查詢 AWS 區域 的 。如需區域清單，請參閱 [Amazon Athena 端點和配額](https://docs.aws.amazon.com/general/latest/gr/athena.html)。
1. **OutputLocation** – Amazon S3 中您要存放查詢結果的位置。如需有關輸出位置的資訊，請參閱 [ResultConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html)。
1. **CredentialsProvider** – 輸入 `JWT_TIP`。
1. **ApplicationRoleArn** – 要啟用 `AssumeRoleWithWebIdentity` 的角色的 ARN。如需 ARN 角色的詳細資訊，請參閱 AWS Security Token Service API 參考中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
1. **WorkgroupArn** – 將執行查詢的工作群組的 ARN。其必須與**工作群組**欄位中提供的工作群組相同。如需有關工作群組的資訊，請參閱[工作群組](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
1. **JwtRoleSessionName** – 使用 JWT 憑證進行身分驗證時的工作階段名稱。其可以是您選擇的任何名稱。
1. **JwtWebIdentityToken** – 從外部聯合身分提供者獲得的 JWT 權杖。此權杖可用於向 Athena 進行身分驗證。
```
jdbc:athena://Workgroup=;Region=;OutputLocation=;CredentialsProvider=JWT_TIP;ApplicationRoleArn=;WorkgroupArn=;JwtRoleSessionName=JDBC_TIP_SESSION;JwtWebIdentityToken=;
```
1. 選擇**確定**並關閉視窗。完成此步驟後，DBeaver 會開始載入中繼資料，而您應該會開始看到您的目錄、資料庫和資料表逐漸被填入。
**注意**
如果權杖中存在 JTI 宣告，並且您在選擇**確定**之前選擇**測試連線**，則可防止重複使用相同的 JTI 進行權杖交換。如需詳細資訊，請參閱[可信權杖發行者的先決條件和考量事項](https://docs.aws.amazon.com/singlesignon/latest/userguide/using-apps-with-trusted-token-issuer.html#trusted-token-issuer-prerequisites)。為了處理此問題，JDBC 會實作記憶體快取，而其生命週期取決於主要驅動器執行個體。對於 ODBC，[檔案快取](odbc-v2-driver-jwt-tip.md#odbc-v2-driver-jwt-tip-file-cache)是選擇性存在的，可快取和重複使用臨時憑證，以減少工作階段生命週期期間使用的 Web 身分權杖數量。
1. 開啟 **SQL 查詢編輯器**，然後開始執行查詢。請參閱 [Cloudtrail 日誌](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html)，驗證使用者的傳播身分。
# 使用 設定和部署資源 AWS CloudFormation
您可以使用 CloudFormation 範本來設定和部署資源，以開始使用受信任身分傳播搭配 Athena 驅動程式，如下所示。
1. 下載 CloudFormation 範本以設定 IAM Identity Center 客戶受管應用程式和存取角色，以及工作群組和 IAM Identity Center 應用程式標籤。您可以從此[CloudFormation 範本連結](https://downloads.athena.us-east-1.amazonaws.com/drivers/CFNTemplate/AthenaDriversTrustedIdentityPropagationCFNTemplate.yaml)下載。
1. 執行 `create-stack` AWS CLI 命令來部署將佈建已設定資源的 CloudFormation 堆疊，如下所示。
```
aws cloudformation create-stack \
--stack-name my-stack \
--template-url URL_of_the_file_that_contains_the_template_body \
--parameters file://params.json
```
1. 若要檢視資源佈建的狀態，請導覽至 CloudFormation 主控台。叢集建立完成後，請在 Identity Center 主控台中檢視新的 IAM Identity Center 應用程式。您可以在 IAM 主控台中檢視 IAM 角色。
這些標籤會在工作群組以及 IAM Identity Center 應用程式中建立關聯。
1. 利用建立的角色和應用程式，您即可立即使用 Athena 驅動器。若要使用 JDBC 驅動器，請參閱 [JDBC 身分驗證外掛程式連線參數](jdbc-v3-driver-jwt-tip-credentials.md)。若要使用 ODBC 驅動器，請參閱 [ODBC 身分驗證外掛程式連線參數](odbc-v2-driver-jwt-tip.md)。