本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 進階連線參數
<a name="jdbc-v3-driver-advanced-connection-parameters"></a>

下列各節說明 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)

## 結果加密參數
<a name="jdbc-v3-driver-result-encryption-parameters"></a>

請注意以下重點：
+ 金鑰 AWS KMS 必須在 `EncryptionOption`為 `SSE_KMS`或 時指定`CSE_KMS`。
+ `EncryptionOption` 若未指定 或 `EncryptionOption`為 ，則無法指定 AWS KMS 金鑰`SSE_S3`。

### 加密選項
<a name="jdbc-v3-driver-encryption-option"></a>

查詢結果存放在 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 金鑰
<a name="jdbc-v3-driver-kms-key"></a>

如果選擇 `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 (已廢除) | 選用 | 無 | 

## 結果擷取參數
<a name="jdbc-v3-driver-result-fetching-parameters"></a>

### 結果擷取程式
<a name="jdbc-v3-driver-result-fetcher"></a>

將用於下載查詢結果的擷取程式。

預設的結果擷取程式 `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 | 

### 擷取大小
<a name="jdbc-v3-driver-fetch-size"></a>

這個參數的值用做內部緩衝區的最小值，以及擷取結果時的目標頁面大小。值 0 (零) 表示驅動程式應使用其預設值，如下所述。最大值為 1,000,000。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| FetchSize | RowsToFetchPerBlock (已廢除) | 選用 | 0 | 
+ `GetQueryResults` 擷取程式一律會使用 1,000 的頁面大小，這是 API 呼叫所支援的最大值。當擷取大小大於 1,000 時，會進行多次連續的 API 呼叫，以填滿高於最小值的緩衝區。
+ `GetQueryResultsStream` 擷取程式會使用設定的擷取大小做為頁面大小，或依預設使用 10,000。
+ `S3` 擷取程式會使用設定的擷取大小做為頁面大小，或依預設使用 10,000。

## 結果組態參數
<a name="jdbc-v3-driver-result-config"></a>

### Expected bucket owner (預期的儲存貯體擁有者)
<a name="jdbc-v3-driver-exp-bucket-owner"></a>

預期的 S3 儲存貯體擁有者的帳戶 ID。如果您提供的帳戶 ID 與儲存貯體的實際擁有者不相符，則請求會失敗。如需有關驗證 s3 儲存貯體擁有者的詳細資訊，請參閱[驗證儲存貯體擁有權](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-owner-condition.html#bucket-owner-condition-use)。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| ExpectedBucketOwner | 無 | 選用 | 無 | 

### Acl 選項
<a name="jdbc-v3-driver-acl"></a>

指出 Amazon S3 標準 ACL 應設定為控制儲存查詢結果的擁有權。如需有關 `AclOption` 的詳細資訊，請參閱 [AclConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_AclConfiguration.html)。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 可能的值 | 
| --- | --- | --- | --- | --- | 
| AclOption | 無 | 選用 | 無 | BUCKET\$1OWNER\$1FULL\$1CONTROL | 

## 查詢結果重複使用參數
<a name="jdbc-v3-driver-query-result-reuse-parameters"></a>

### 啟用結果重複使用
<a name="jdbc-v3-driver-enable-result-reuse"></a>

指定執行查詢時是否可以重複使用同一查詢之前的結果。如需有關查詢結果重複使用的資訊，請參閱 [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html)。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| EnableResultReuseByAge | 無 | 選用 | FALSE | 

### 結果重複使用最長期限
<a name="jdbc-v3-driver-result-reuse-max-age"></a>

Athena 應考慮重複使用的之前查詢結果的最長期限 (以分鐘為單位)。如需有關結果重複使用最長期限的資訊，請參閱 [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html)。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| MaxResultReuseAgeInMinutes | 無 | 選用 | 60 | 

## 查詢執行輪詢參數
<a name="jdbc-v3-driver-query-execution-polling-parameters"></a>

### 最小查詢執行輪詢間隔
<a name="jdbc-v3-driver-minimum-query-execution-polling-interval"></a>

輪詢 Athena 的查詢執行狀態之前要等待的最短時間 (以毫秒為單位)。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| MinQueryExecutionPollingIntervalMillis | MinQueryExecutionPollingInterval (已廢除) | 選用 | 100 | 

### 最大查詢執行輪詢間隔
<a name="jdbc-v3-driver-maximum-query-execution-polling-interval"></a>

輪詢 Athena 的查詢執行狀態之前要等待的最長時間 (以毫秒為單位)。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| MaxQueryExecutionPollingIntervalMillis | MaxQueryExecutionPollingInterval (已廢除) | 選用 | 5000 | 

### 查詢執行輪詢間隔倍數
<a name="jdbc-v3-driver-query-execution-polling-interval-multiplier"></a>

增加輪詢期間的因數。依預設，輪詢會以 `MinQueryExecutionPollingIntervalMillis` 的值開始，並且每次輪詢都會加倍，直至達到 `MaxQueryExecutionPollingIntervalMillis` 的值為止。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| QueryExecutionPollingIntervalMultiplier | 無 | 選用 | 2 | 

## 端點覆寫參數
<a name="jdbc-v3-driver-endpoint-override-parameters"></a>

### Athena 端點覆寫
<a name="jdbc-v3-driver-athena-endpoint-override"></a>

驅動程式將用來對 Athena 進行 API 呼叫的端點。

請注意以下重點：
+ 如果提供的 URL 中未指定 `https://` 或 `http://` 通訊協定，則驅動程式會插入 `https://` 字首。
+ 若沒有指定此參數，則驅動程式會使用預設端點。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| AthenaEndpoint | EndpointOverride (已廢除) | 選用 | 無 | 

### Athena 串流服務端點覆寫
<a name="jdbc-v3-driver-athena-streaming-service-endpoint-override"></a>

當驅動程式使用 Athena 串流服務時，將用來下載查詢結果的端點。Athena 串流服務可在連接埠 444 上使用。

請注意以下重點：
+ 如果提供的 URL 中未指定 `https://` 或 `http://` 通訊協定，則驅動程式會插入 `https://` 字首。
+ 如果未在提供的 URL 中指定連接埠，則驅動程式會插入串流服務連接埠 444。
+ 如果未指定 `AthenaStreamingEndpoint` 參數，驅動程式會使用 `AthenaEndpoint` 覆寫。如果 `AthenaStreamingEndpoint` 或 `AthenaEndpoint` 覆寫均未指定，則驅動程式會使用預設的串流端點。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| AthenaStreamingEndpoint | StreamingEndpointOverride (已廢除) | 選用 | 無 | 

### LakeFormation 端點覆寫
<a name="jdbc-v3-driver-athena-lake-formation-endpoint-override"></a>

驅動程式使用 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 端點覆寫
<a name="jdbc-v3-driver-athena-s3-endpoint-override"></a>

當驅動程式使用 Amazon S3 擷取程式時，將用來下載查詢結果的端點。若沒有指定此參數，則驅動程式會使用預設的 Amazon S3 端點。

請注意以下重點：
+ 如果提供的 URL 中未指定 `https://` 或 `http://` 通訊協定，則驅動程式會插入 `https://` 字首。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| S3Endpoint | 無 | 選用 | 無 | 

### STS 端點覆寫
<a name="jdbc-v3-driver-athena-sts-endpoint-override"></a>

使用 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 端點覆寫
<a name="jdbc-v3-driver-athena-sso-oidc-endpoint-override"></a>

使用 `ClientConfiguration.endpointOverride` 覆寫 SSO OIDC 用戶端的預設 HTTP 端點時，驅動器將使用的端點。如需詳細資訊，請參閱 [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| SSOOIDCEndpointOverride |  | 選用 | 無 | 

### SSO 管理員端點覆寫
<a name="jdbc-v3-driver-athena-sso-admin-endpoint-override"></a>

使用 `ClientConfiguration.endpointOverride` 覆寫 SSO 管理員用戶端的預設 HTTP 端點時，驅動器將使用的端點。如需詳細資訊，請參閱 [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| SSOAdminEndpointOverride |  | 選用 | 無 | 

## 代理組態參數
<a name="jdbc-v3-driver-proxy-configuration-parameters"></a>

### 代理主機
<a name="jdbc-v3-driver-proxy-host"></a>

代理主機的 URL。如果您需要 Athena 請求透過代理傳送，請使用此參數。

**注意**  
 確定在 `ProxyHost` 的 URL 開頭包含通訊協定 `https://` 或 `http://`。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| ProxyHost | 無 | 選用 | 無 | 

### 代理連接埠
<a name="jdbc-v3-driver-proxy-port"></a>

要在代理主機上使用的連接埠。如果您需要 Athena 請求透過代理傳送，請使用此參數。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| ProxyPort | 無 | 選用 | 無 | 

### 代理使用者名稱
<a name="jdbc-v3-driver-proxy-username"></a>

在代理伺服器上進行身分驗證的使用者名稱。如果您需要 Athena 請求透過代理傳送，請使用此參數。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| ProxyUsername | ProxyUID (已廢除) | 選用 | 無 | 

### 代理密碼
<a name="jdbc-v3-driver-proxy-password"></a>

在代理伺服器上進行身分驗證的密碼。如果您需要 Athena 請求透過代理傳送，請使用此參數。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| ProxyPassword | ProxyPWD (已廢除) | 選用 | 無 | 

### 免除代理的主機
<a name="jdbc-v3-driver-proxy-exempt-hosts"></a>

啟用代理後 (也就是設定 `ProxyHost` 和 `ProxyPort` 連線參數後)，驅動程式在不使用代理的情況下連線到的一組主機名稱。主機應以縱線 (`|`) 字元分隔 (例如，`host1.com|host2.com`)。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| ProxyExemptHosts | NonProxyHosts | 選用 | 無 | 

### 為身分提供者啟用代理
<a name="jdbc-v3-driver-proxy-enabled-for-identity-providers"></a>

指定當驅動程式連線至身分提供者時，是否應使用代理。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| ProxyEnabledForIdP | UseProxyForIdP | 選用 | FALSE | 

## 記錄日誌參數
<a name="jdbc-v3-driver-logging-parameters"></a>

本節說明與記錄日誌相關的參數。

### 日誌層級
<a name="jdbc-v3-driver-logging-parameters-log-level"></a>

指定驅動程式記錄日誌的層級。除非還設定了 `LogPath` 參數，否則不會記錄任何內容。

**注意**  
除非您有特殊需求，否則建議您僅設定 `LogPath` 參數。僅設定 `LogPath` 參數會啟用記錄日誌，並使用預設的 `TRACE` 日誌層級。`TRACE` 日誌層級會提供最詳細的記錄。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 可能的值 | 
| --- | --- | --- | --- | --- | 
| LogLevel | 無 | 選用 | TRACE | OFF、ERROR、WARN、INFO、DEBUG、TRACE | 

### 日誌路徑
<a name="jdbc-v3-driver-logging-parameters-log-path"></a>

執行驅動程式的電腦上儲存驅動程式日誌的目錄路徑。將在指定的目錄中建立具有唯一名稱的日誌檔。如果設定，則啟用驅動程式記錄日誌。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| LogPath | 無 | 選用 | 無 | 

## Application name (應用程式名稱)
<a name="jdbc-v3-driver-application-name"></a>

使用驅動程式的應用程式的名稱。如果指定此參數的值，則該值會包含在驅動程式對 Athena 進行之 API 呼叫的使用者代理字串中。

**注意**  
您也可以透過呼叫 `setApplicationName` 物件上的 `DataSource` 來設定應用程式名稱。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| ApplicationName | 無 | 選用 | 無 | 

## 連線測試
<a name="jdbc-v3-driver-connection-test"></a>

如果設定為 `TRUE`，則即使未在連線上執行查詢，驅動程式也會在每次建立 JDBC 連線時進行連線測試。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| ConnectionTest | 無 | 選用 | TRUE | 

**注意**  
連線測試會將 `SELECT 1` 查詢提交至 Athena，以確認連線設定正確。這表示兩個檔案將儲存在 Amazon S3 中 (結果集和中繼資料)，而且可能會根據 [Amazon Athena 定價](https://aws.amazon.com/athena/pricing)政策收取額外費用。

## 重試次數
<a name="jdbc-v3-driver-number-of-retries"></a>

驅動程式將可重試請求重新傳送至 Athena 的次數上限。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
| NumRetries | MaxErrorRetry (已廢除) | 選用 | 無 | 

## 網路逾時
<a name="jdbc-v3-driver-networktimeoutmillis"></a>

網路逾時可控制驅動器等待建立網路連線的時間量。這包括傳送 API 請求所需的時間。在極少數情況下，變更網路逾時可能會非常實用。例如，您可能想要增加長時間垃圾回收暫停的逾時。設定此連線參數等同於在 `Connection` 物件上使用 `setNetworkTimeout` 方法。


****  

| 參數名稱 | Alias (別名) | 參數類型 | 預設值 | 
| --- | --- | --- | --- | 
|  NetworkTimeoutMillis  | 無 | 選用 | 無 |