# 高级连接参数
<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)
+ [应用程序名称](#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>

请注意以下几点：
+ 当 `EncryptionOption` 为 `SSE_KMS` 或 `CSE_KMS` 时，必须指定 AWS KMS 密钥。
+ 当未指定 `EncryptionOption` 或当 `EncryptionOption` 为 `SSE_S3` 时，无法指定 AWS KMS 密钥。

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

查询结果存储在 Amazon S3 中时使用的加密类型。有关查询结果加密的信息，请参阅《Amazon Athena API Reference》**中的 [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html)。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 可能的值 | 
| --- | --- | --- | --- | --- | 
| EncryptionOption | S3OutputEncOption（已弃用） | 可选 | none | SSE\$1S3、SSE\$1KMS、CSE\$1KMS | 

### KMS 密钥
<a name="jdbc-v3-driver-kms-key"></a>

KMS 密钥 ARN 或 ID（如果选择 `SSE_KMS` 或 `CSE_KMS` 作为加密选项）。有关更多信息，请参阅《Amazon Athena API Reference》**中的 [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html)。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| KmsKey | S3OutputEncKMSKey（已弃用） | 可选 | none | 

## 结果提取参数
<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 调用。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 可能的值 | 
| --- | --- | --- | --- | --- | 
| ResultFetcher | none | 可选 | 自动 | auto、S3、GetQueryResults、GetQueryResultsStream | 

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

此参数的值用作内部缓冲区的最小值，也在提取结果时用作目标页面大小。值 0（零）表示驱动程序应使用其默认值，如下所述。最大值为 1,000,000。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| FetchSize | RowsToFetchPerBlock（已弃用） | 可选 | 0 | 
+ `GetQueryResults` 提取器将始终使用 1,000 的页面大小，因为这是 API 调用支持的最大值。当提取大小超出 1,000 时，为了填充超过最小值的缓冲区，会连续进行多次 API 调用。
+ `GetQueryResultsStream` 提取器将使用配置的提取大小或默认值 10,000 作为页面大小。
+ `S3` 提取器将使用配置的提取大小或默认值 10,000 作为页面大小。

## 结果配置参数
<a name="jdbc-v3-driver-result-config"></a>

### 预期存储桶拥有者
<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)。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| ExpectedBucketOwner | none | 可选 | none | 

### Acl 选项
<a name="jdbc-v3-driver-acl"></a>

表示应设置 Amazon S3 标准 ACL 以控制存储的查询结果的所有权。有关 `AclOption` 的更多信息，请参阅 [AclConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_AclConfiguration.html)。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 可能的值 | 
| --- | --- | --- | --- | --- | 
| AclOption | none | 可选 | none | 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)。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| EnableResultReuseByAge | none | 可选 | FALSE | 

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

Athena 应考虑的先前查询结果的重用最长使用期限（以分钟为单位）。有关结果重用最长使用期限的信息，请参阅 [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html)。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| MaxResultReuseAgeInMinutes | none | 可选 | 60 | 

## 查询执行轮询参数
<a name="jdbc-v3-driver-query-execution-polling-parameters"></a>

### 查询执行的最小轮询间隔
<a name="jdbc-v3-driver-minimum-query-execution-polling-interval"></a>

在 Athena 中轮询查询执行状态之前要等待的最短时间（以毫秒为单位）。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| MinQueryExecutionPollingIntervalMillis | MinQueryExecutionPollingInterval（已弃用） | 可选 | 100 | 

### 查询执行的最大轮询间隔
<a name="jdbc-v3-driver-maximum-query-execution-polling-interval"></a>

在 Athena 中轮询查询执行状态之前要等待的最长时间（以毫秒为单位）。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| MaxQueryExecutionPollingIntervalMillis | MaxQueryExecutionPollingInterval（已弃用） | 可选 | 5000 | 

### 查询执行轮询间隔乘数
<a name="jdbc-v3-driver-query-execution-polling-interval-multiplier"></a>

用于增加轮询期的系数。默认情况下，轮询将以 `MinQueryExecutionPollingIntervalMillis` 的值开始，每次轮询时都翻倍，直到达到 `MaxQueryExecutionPollingIntervalMillis` 的值。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| QueryExecutionPollingIntervalMultiplier | none | 可选 | 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://` 前缀。
+ 如果未指定此参数，驱动程序会使用默认的端点。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| AthenaEndpoint | EndpointOverride（已弃用） | 可选 | none | 

### 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` 覆盖，则驱动程序将使用默认的流式传输端点。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| AthenaStreamingEndpoint | StreamingEndpointOverride（已弃用） | 可选 | none | 

### Lake Formation 端点覆盖
<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://` 前缀。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| LakeFormationEndpoint |  LfEndpointOverride（已弃用）  | 可选 | none | 

### S3 端点覆盖
<a name="jdbc-v3-driver-athena-s3-endpoint-override"></a>

驱动程序在使用 Amazon S3 提取器时用于下载查询结果的端点。如果未指定此参数，驱动程序会使用默认的 Amazon S3 端点。

请注意以下几点：
+ 如果未在提供的 URL 中指定 `https://` 或 `http://` 协议，则驱动程序会插入 `https://` 前缀。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| S3Endpoint | 无 | 可选 | none | 

### 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://` 前缀。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| StsEndpoint | StsEndpointOverride（已弃用） | 可选 | none | 

### 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)。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| SSOOIDCEndpointOverride |  | 可选 | none | 

### 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)。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| SSOAdminEndpointOverride |  | 可选 | none | 

## 代理配置参数
<a name="jdbc-v3-driver-proxy-configuration-parameters"></a>

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

代理主机的 URL。如果需要 Athena 请求来通过代理，请使用此参数。

**注意**  
 请务必在 `ProxyHost` 的 URL 的开头处包含 `https://` 或 `http://` 协议。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| ProxyHost | none | 可选 | none | 

### 代理端口
<a name="jdbc-v3-driver-proxy-port"></a>

要在代理主机上使用的端口。如果需要 Athena 请求来通过代理，请使用此参数。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| ProxyPort | none | 可选 | none | 

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

用于对代理服务器进行身份验证的用户名。如果需要 Athena 请求来通过代理，请使用此参数。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| ProxyUsername | ProxyUID（已弃用） | 可选 | none | 

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

用于对代理服务器进行身份验证的密码。如果需要 Athena 请求来通过代理，请使用此参数。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| ProxyPassword | ProxyPWD（已弃用） | 可选 | none | 

### 代理豁免主机
<a name="jdbc-v3-driver-proxy-exempt-hosts"></a>

启用代理后（即设置了 `ProxyHost` 和 `ProxyPort` 连接参数），驱动程序在不使用代理的情况下连接到的一组主机名。主机应用管道 (`|`) 字符分隔（例如 `host1.com|host2.com`）。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| ProxyExemptHosts | NonProxyHosts | 可选 | none | 

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

指定当驱动程序连接到身份提供者时是否应使用代理。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| 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` 日志级别提供了最详细的日志记录。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 可能的值 | 
| --- | --- | --- | --- | --- | 
| LogLevel | none | 可选 | TRACE | OFF、ERROR、WARN、INFO、DEBUG、TRACE | 

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

运行驱动程序的计算机上存储驱动程序日志的目录路径。将在指定目录中创建的具有唯一名称的日志文件。如果已设置，则启用驱动程序日志记录。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| LogPath | none | 可选 | none | 

## 应用程序名称
<a name="jdbc-v3-driver-application-name"></a>

使用该驱动程序的应用程序的名称。如果为此参数指定了值，则该值将包含在驱动程序对 Athena 进行的 API 调用的用户代理字符串中。

**注意**  
您也可以通过调用 `DataSource` 对象上的 `setApplicationName` 来设置应用程序名称。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| ApplicationName | none | 可选 | none | 

## 连接测试
<a name="jdbc-v3-driver-connection-test"></a>

如果设置为 `TRUE`，则每次创建 JDBC 连接时，驱动程序都会执行连接测试，即使未对该连接执行查询也是如此。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| ConnectionTest | none | 可选 | TRUE | 

**注意**  
连接测试会向 Athena 提交 `SELECT 1` 查询来验证连接配置是否正确。这意味着两个文件将存储在 Amazon S3 中（结果集和元数据），并且可能会根据[Amazon Athena 定价](https://aws.amazon.com/athena/pricing)策略收取额外费用。

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

驱动程序应向 Athena 重新发送可检索请求的最大次数。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
| NumRetries | MaxErrorRetry（已弃用） | 可选 | none | 

## 网络超时
<a name="jdbc-v3-driver-networktimeoutmillis"></a>

网络超时控制驱动程序等待建立网络连接的时间。这包括发送 API 请求所需的时间。在极少数情况下，更改网络超时可能会有用。例如，您可能想要增加长时间垃圾回收暂停的超时时间。设置此连接参数等同于在 `Connection` 对象上使用 `setNetworkTimeout` 方法。


****  

| 参数名称 | 别名 | 参数类型 | 默认 值 | 
| --- | --- | --- | --- | 
|  NetworkTimeoutMillis  | none | 可选 | none |