# 通过 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 之间的信任并使用 ODBC 驱动程序借助 Active Directory 凭证连接到 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 读取查询结果，此举可提高使用大型查询结果的应用程序的性能。该新驱动程序还减少了第三方依赖项，让与商业智能工具和自定义应用程序的集成变得更加容易。在大多数情况下，您都可以直接使用该新驱动程序，无需对现有配置进行任何更改，或者只需进行极少更改。
+ 要下载 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 驱动程序
您可以使用 Athena JDBC 驱动程序从许多第三方 SQL 客户端工具和自定义应用程序连接到 Amazon Athena。
## 系统要求
+ Java 8（或更高版本）的运行时系统环境
+ 至少 20MB 可用磁盘空间
## 注意事项和限制
以下是 Athena JDBC 3.x 驱动程序的一些注意事项和限制。
+ **日志记录** – 3.x 驱动程序使用 [SLF4J](https://www.slf4j.org/manual.html)，这是一个抽象层，支持在运行时系统中使用多种日志记录系统中的任一系统。
+ **加密** – 当使用具有 `CSE_KMS` 加密选项的 Amazon S3 提取器时，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 策略** — 将 `athena:GetQueryResultsStream` 策略操作添加到使用 JDBC 驱动程序的 IAM 主体。此策略操作并不通过 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 版本 2 驱动程序升级](#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 版本 2 驱动程序升级
大多数 JDBC 版本 3 的连接参数都向后兼容版本 2（Simba）JDBC 驱动程序。这表示版本 2 的连接字符串可以在版本 3 的驱动程序中重用。不过，某些连接参数已发生更改。此处对这些更改进行了介绍。在升级到 JDBC 驱动程序版本 3 时，如有必要，请更新现有配置。
### 驱动程序类
部分 BI 工具会要求您提供 JDBC 驱动程序 `.jar` 文件中的驱动程序类。大多数工具都会自动找到这个类。这个类在版本 3 驱动程序中的完全限定名称是 `com.amazon.athena.jdbc.AthenaDriver`。在版本 2 驱动程序中，这个类是 `com.simba.athena.jdbc.Driver`。
### 连接字符串
版本 3 驱动程序在 JDBC 连接字符串 URL 的开头使用 `jdbc:athena://` 作为协议。版本 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 驱动程序实现来自新 适用于 Java 的 AWS SDK 的 [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) 接口。
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 endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/athena.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 区域 | AwsRegion（已弃用） | 必填项（但如果未提供，将使用 [DefaultAwsRegionProviderChain](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/regions/providers/DefaultAwsRegionProviderChain.html) 进行搜索） | none |
## 目录
包含将使用驱动程序访问的数据库和表的目录。有关目录的信息，请参阅 [DataCatalog](https://docs.aws.amazon.com/athena/latest/APIReference/API_DataCatalog.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 目录 | none | 可选 | AwsDataCatalog |
## 数据库
将运行查询的数据库。未使用数据库名称显示限定的表将解析到此数据库。有关数据库的信息，请参阅 [Database](https://docs.aws.amazon.com/athena/latest/APIReference/API_Database.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 数据库 | 架构 | 可选 | 默认 |
## 工作组
将运行查询的工作组。有关工作组的信息，请参阅 [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 工作组 | none | 可选 | 主 |
## 输出位置
在 Amazon S3 中存储查询结果的位置。有关输出位置的信息，请参阅 [ResultConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultConfiguration.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| OutputLocation | S3OutputLocation（已弃用） | 必填项（除非工作组指定输出位置） | none |
# 高级连接参数
以下各节旨在介绍 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)
## 结果加密参数
请注意以下几点：
+ 当 `EncryptionOption` 为 `SSE_KMS` 或 `CSE_KMS` 时，必须指定 AWS KMS 密钥。
+ 当未指定 `EncryptionOption` 或当 `EncryptionOption` 为 `SSE_S3` 时，无法指定 AWS KMS 密钥。
### 加密选项
查询结果存储在 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 密钥
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 |
## 结果提取参数
### 结果提取器
将用于下载查询结果的提取器。
默认的结果提取器 `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 |
### 提取大小
此参数的值用作内部缓冲区的最小值，也在提取结果时用作目标页面大小。值 0（零）表示驱动程序应使用其默认值，如下所述。最大值为 1,000,000。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| FetchSize | RowsToFetchPerBlock（已弃用） | 可选 | 0 |
+ `GetQueryResults` 提取器将始终使用 1,000 的页面大小，因为这是 API 调用支持的最大值。当提取大小超出 1,000 时，为了填充超过最小值的缓冲区，会连续进行多次 API 调用。
+ `GetQueryResultsStream` 提取器将使用配置的提取大小或默认值 10,000 作为页面大小。
+ `S3` 提取器将使用配置的提取大小或默认值 10,000 作为页面大小。
## 结果配置参数
### 预期存储桶拥有者
预期的 S3 存储桶拥有者的账户 ID。如果您提供的账户 ID 与存储桶的实际拥有者不匹配，则请求将失败。有关验证 S3 存储桶拥有者的更多信息，请参阅[验证存储桶所有权](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-owner-condition.html#bucket-owner-condition-use)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ExpectedBucketOwner | none | 可选 | none |
### Acl 选项
表示应设置 Amazon S3 标准 ACL 以控制存储的查询结果的所有权。有关 `AclOption` 的更多信息，请参阅 [AclConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_AclConfiguration.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 可能的值 |
| --- | --- | --- | --- | --- |
| AclOption | none | 可选 | none | BUCKET\$1OWNER\$1FULL\$1CONTROL |
## 查询结果重用参数
### 启用结果重用
指定在运行查询时是否可以重用同一查询的先前结果。有关查询结果重用的信息，请参阅 [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| EnableResultReuseByAge | none | 可选 | FALSE |
### 结果重用最长使用期限
Athena 应考虑的先前查询结果的重用最长使用期限（以分钟为单位）。有关结果重用最长使用期限的信息，请参阅 [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| MaxResultReuseAgeInMinutes | none | 可选 | 60 |
## 查询执行轮询参数
### 查询执行的最小轮询间隔
在 Athena 中轮询查询执行状态之前要等待的最短时间（以毫秒为单位）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| MinQueryExecutionPollingIntervalMillis | MinQueryExecutionPollingInterval（已弃用） | 可选 | 100 |
### 查询执行的最大轮询间隔
在 Athena 中轮询查询执行状态之前要等待的最长时间（以毫秒为单位）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| MaxQueryExecutionPollingIntervalMillis | MaxQueryExecutionPollingInterval（已弃用） | 可选 | 5000 |
### 查询执行轮询间隔乘数
用于增加轮询期的系数。默认情况下，轮询将以 `MinQueryExecutionPollingIntervalMillis` 的值开始，每次轮询时都翻倍，直到达到 `MaxQueryExecutionPollingIntervalMillis` 的值。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| QueryExecutionPollingIntervalMultiplier | none | 可选 | 2 |
## 端点覆盖参数
### Athena 端点覆盖
驱动程序用于对 Athena 进行 API 调用的端点。
请注意以下几点：
+ 如果未在提供的 URL 中指定 `https://` 或 `http://` 协议，则驱动程序会插入 `https://` 前缀。
+ 如果未指定此参数，驱动程序会使用默认的端点。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AthenaEndpoint | EndpointOverride（已弃用） | 可选 | none |
### Athena 流式传输服务端点覆盖
驱动程序在使用 Athena 流式传输服务时用于下载查询结果的端点。Athena 流式传输服务在端口 444 上可用。
请注意以下几点：
+ 如果未在提供的 URL 中指定 `https://` 或 `http://` 协议，则驱动程序会插入 `https://` 前缀。
+ 如果未在提供的 URL 中指定端口，则驱动程序会插入流式传输服务端口 444。
+ 如果未指定 `AthenaStreamingEndpoint` 参数，则驱动程序将使用 `AthenaEndpoint` 覆盖。如果既未指定 `AthenaStreamingEndpoint` 也未指定 `AthenaEndpoint` 覆盖，则驱动程序将使用默认的流式传输端点。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AthenaStreamingEndpoint | StreamingEndpointOverride（已弃用） | 可选 | none |
### Lake Formation 端点覆盖
当使用 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 端点覆盖
驱动程序在使用 Amazon S3 提取器时用于下载查询结果的端点。如果未指定此参数，驱动程序会使用默认的 Amazon S3 端点。
请注意以下几点：
+ 如果未在提供的 URL 中指定 `https://` 或 `http://` 协议，则驱动程序会插入 `https://` 前缀。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| S3Endpoint | 无 | 可选 | none |
### STS 端点覆盖
当使用 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 端点覆盖
使用 `ClientConfiguration.endpointOverride` 覆盖 SSO OIDC 客户端的默认 HTTP 端点时驱动程序会使用的端点。有关更多信息，请参阅 [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| SSOOIDCEndpointOverride | | 可选 | none |
### SSO 管理端点覆盖
使用 `ClientConfiguration.endpointOverride` 覆盖 SSO 管理客户端的默认 HTTP 端点时驱动程序会使用的端点。有关更多信息，请参阅 [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| SSOAdminEndpointOverride | | 可选 | none |
## 代理配置参数
### 代理主机
代理主机的 URL。如果需要 Athena 请求来通过代理，请使用此参数。
**注意**
请务必在 `ProxyHost` 的 URL 的开头处包含 `https://` 或 `http://` 协议。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ProxyHost | none | 可选 | none |
### 代理端口
要在代理主机上使用的端口。如果需要 Athena 请求来通过代理，请使用此参数。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ProxyPort | none | 可选 | none |
### 代理用户名
用于对代理服务器进行身份验证的用户名。如果需要 Athena 请求来通过代理，请使用此参数。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ProxyUsername | ProxyUID（已弃用） | 可选 | none |
### 代理密码
用于对代理服务器进行身份验证的密码。如果需要 Athena 请求来通过代理，请使用此参数。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ProxyPassword | ProxyPWD（已弃用） | 可选 | none |
### 代理豁免主机
启用代理后（即设置了 `ProxyHost` 和 `ProxyPort` 连接参数），驱动程序在不使用代理的情况下连接到的一组主机名。主机应用管道 (`|`) 字符分隔（例如 `host1.com|host2.com`）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ProxyExemptHosts | NonProxyHosts | 可选 | none |
### 为身份提供者启用代理
指定当驱动程序连接到身份提供者时是否应使用代理。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ProxyEnabledForIdP | UseProxyForIdP | 可选 | FALSE |
## 日志记录参数
本节旨在介绍与日志记录相关的参数。
### 日志级别
指定驱动程序日志记录的级别。除非还设置了 `LogPath` 参数，否则不会记录任何内容。
**注意**
除非有特殊要求，否则建议仅设置 `LogPath` 参数。仅设置 `LogPath` 参数即可启用日志记录并使用默认的 `TRACE` 日志级别。`TRACE` 日志级别提供了最详细的日志记录。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 可能的值 |
| --- | --- | --- | --- | --- |
| LogLevel | none | 可选 | TRACE | OFF、ERROR、WARN、INFO、DEBUG、TRACE |
### 日志路径
运行驱动程序的计算机上存储驱动程序日志的目录路径。将在指定目录中创建的具有唯一名称的日志文件。如果已设置，则启用驱动程序日志记录。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| LogPath | none | 可选 | none |
## 应用程序名称
使用该驱动程序的应用程序的名称。如果为此参数指定了值，则该值将包含在驱动程序对 Athena 进行的 API 调用的用户代理字符串中。
**注意**
您也可以通过调用 `DataSource` 对象上的 `setApplicationName` 来设置应用程序名称。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ApplicationName | none | 可选 | none |
## 连接测试
如果设置为 `TRUE`，则每次创建 JDBC 连接时，驱动程序都会执行连接测试，即使未对该连接执行查询也是如此。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ConnectionTest | none | 可选 | TRUE |
**注意**
连接测试会向 Athena 提交 `SELECT 1` 查询来验证连接配置是否正确。这意味着两个文件将存储在 Amazon S3 中（结果集和元数据），并且可能会根据[Amazon Athena 定价](https://aws.amazon.com/athena/pricing)策略收取额外费用。
## 重试次数
驱动程序应向 Athena 重新发送可检索请求的最大次数。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| NumRetries | MaxErrorRetry（已弃用） | 可选 | none |
## 网络超时
网络超时控制驱动程序等待建立网络连接的时间。这包括发送 API 请求所需的时间。在极少数情况下，更改网络超时可能会有用。例如，您可能想要增加长时间垃圾回收暂停的超时时间。设置此连接参数等同于在 `Connection` 对象上使用 `setNetworkTimeout` 方法。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| NetworkTimeoutMillis | none | 可选 | none |
# 身份验证连接参数
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)
+ [自定义](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)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 用户 | AccessKeyId | 必需 | none |
## 密码
您的 AWS 密钥 ID。有关访问密钥的信息，请参阅《IAM 用户指南》**中的 [AWS 安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 密码 | SecretAccessKey | 可选 | none |
## 会话令牌
如果您使用的是临时 AWS 凭证，则必须指定会话令牌。有关临时凭证的更多信息，请参阅《*IAM 用户指南*》中的 [IAM 临时安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| SessionToken | none | 可选 | none |
# 默认凭证
您可以通过设置以下连接参数，使用在客户端系统上配置的默认凭证来连接 Amazon Athena。有关使用默认凭证的信息，请参阅《适用于 Java 的 AWS SDK 开发人员指南》**中的[使用默认凭证提供程序链](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default)。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `DefaultChain`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | DefaultChain |
# AWS 配置文件凭证
您可以通过设置以下连接参数来使用存储在 AWS 配置文件中的凭证。AWS 配置文件通常存储在 `~/.aws` 目录的文件中。有关 AWS 配置文件的信息，请参阅《适用于 Java 的 AWS SDK Developer Guide》**中的 [Use profiles](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-profiles.html)。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `ProfileCredentials`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | ProfileCredentials |
## 配置文件名称
AWS 配置文件的名称，其凭证应该用于对 Athena 的请求进行身份验证。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ProfileName | none | 必需 | none |
**注意**
您也可以将配置文件名称指定为 `CredentialsProviderArguments` 参数的值，虽然这种用法已被弃用。
# 实例配置文件凭证
此身份验证类型用于 Amazon EC2 实例。*实例配置文件*是附加到 Amazon EC2 实例的配置文件。使用实例配置文件凭证提供程序，将 AWS 凭证的管理委托给 Amazon EC2 实例元数据服务。如此，开发人员就无需在 Amazon EC2 实例上永久存储凭证，也不必担心轮换或管理临时凭证了。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `InstanceProfile`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | 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 类路径上。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | AwsCredentialsProvider 的自定义实现的完全限定类名 |
## 凭证提供程序参数
自定义凭证提供程序构造函数的字符串参数的逗号分隔列表。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| CredentialsProviderArguments | AwsCredentialsProviderArguments（已弃用） | 可选 | none |
# JWT 凭证
凭借此身份验证类型，您可以使用从外部身份提供者处获得的 JSON Web 令牌（JWT）作为连接参数，对 Athena 进行身份验证。外部凭证提供程序必须已经与 AWS 联合。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `JWT`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | JWT |
## JWT Web 身份令牌
从外部联合身份提供者处获得的 JWT 令牌。此令牌将用于向 Athena 进行身份验证。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| JwtWebIdentityToken | web\$1identity\$1token（已弃用） | 必需 | none |
## JWT 角色 ARN
要代入的角色的 Amazon 资源名称（ARN）。有关代入角色的信息，请参阅《AWS Security Token Service API Reference》**中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| JwtRoleArn | role\$1arn（已弃用） | 必需 | none |
## JWT 角色会话名称
使用 JWT 凭证进行身份验证时的会话名称。此名称可以是您选择的任何名称。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| JwtRoleSessionName | role\$1session\$1name（已弃用） | 必需 | none |
## 角色会话持续时间
角色会话的持续时间（以秒为单位）。有关更多信息，请参阅 *AWS Security Token Service API 参考*中的 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration（已弃用） | 可选 | 3600 |
# JWT 与身份中心集成
通过此身份验证类型，您可以使用从外部身份提供者处获得的 JSON Web 令牌（JWT）作为连接参数，在 Athena 进行身份验证。您可以使用此插件，通过可信身份传播，实现对企业身份的支持。有关如何将可信身份传播与驱动程序结合使用的更多信息，请参阅[将可信身份传播与 Amazon Athena 驱动程序结合使用](using-trusted-identity-propagation.md)。您还可以[使用 CloudFormation 配置和部署资源](using-trusted-identity-propagation-cloudformation.md)。
使用可信身份传播，可以向 IAM 角色添加身份上下文，以识别请求访问 AWS 资源的用户身份。有关启用和使用可信身份传播的信息，请参阅 [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html)。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `JWT_TIP`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | JWT\$1TIP |
## JWT Web 身份令牌
从外部联合身份提供者处获得的 JWT 令牌。此令牌将用于向 Athena 进行身份验证。令牌缓存默认为启用，以允许在驱动程序连接之间使用相同的 Identity Center 访问令牌。建议在“测试连接”时提供新的 JWT 令牌，因为交换的令牌仅在驱动程序实例处于活动状态期间才存在。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| JwtWebIdentityToken | web\$1identity\$1token（已弃用） | 必需 | none |
## WorkgroupArn
Amazon Athena 工作组的 Amazon 资源名称（ARN）。有关工作组的更多信息，请参阅 [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| WorkGroupArn | none | 必需 | 主 |
## JWT 应用程序角色 ARN
要代入的角色的 ARN。此角色用于 JWT 交换、通过工作组标签获取 IAM Identity Center 客户管理的应用程序 ARN，以及获取访问角色 ARN。有关代入角色的信息，请参阅 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ApplicationRoleArn | none | 必需 | none |
## JWT 角色会话名称
使用 JWT 凭证进行身份验证时的会话名称。它可以是您选择的任何名称。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| JwtRoleSessionName | role\$1session\$1name（已弃用） | 必需 | none |
## 角色会话持续时间
角色会话的持续时间（以秒为单位）。有关更多信息，请参阅 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration（已弃用） | 可选 | 3600 |
## JWT 访问角色 ARN
要代入的角色的 ARN。这是 Athena 服务代表您进行调用时代入的角色。有关代入角色的更多信息，请参阅 *AWS Security Token Service API Reference* 中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AccessRoleArn | none | 可选 | none |
## IAM Identity Center 客户管理的应用程序 ARN
IAM Identity Center 客户管理的应用程序 ARN。有关更多信息，请参阅 [Customer Managed Application](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| CustomerIdcApplicationArn | none | 可选 | none |
# 基于浏览器的身份中心集成
通过此身份验证类型，您可以从外部身份提供者处获取新的 JSON Web 令牌（JWT），并使用 Athena 进行身份验证。您可以使用此插件，通过可信身份传播，实现对企业身份的支持。有关如何将可信身份传播与驱动程序结合使用的更多信息，请参阅[将可信身份传播与 Amazon Athena 驱动程序结合使用](using-trusted-identity-propagation.md)。您还可以[使用 CloudFormation 配置和部署资源](using-trusted-identity-propagation-cloudformation.md)。
使用可信身份传播，可以向 IAM 角色添加身份上下文，以识别请求访问 AWS 资源的用户身份。有关启用和使用可信身份传播的信息，请参阅 [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html)。
**注意**
该插件专为单用户桌面环境而设计。在 Windows Server 等共享环境中，系统管理员负责建立和维护用户之间的安全边界。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `BrowserOidcTip`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | BrowserOidcTip |
## Idp 公开配置 URL
IDP 公开配置 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 | 必需 | none |
## 客户端标识符
OpenID Connect 提供商向应用程序颁发的客户端标识符。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| OidcClientId | none | 必需 | none |
## WorkgroupArn
包含可信身份传播配置标签的 Amazon Athena 工作组的 Amazon 资源名称（ARN）。有关工作组的更多信息，请参阅 [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
**注意**
此参数与指定查询运行位置的 `Workgroup` 参数不同。必须同时设置两个参数：
`WorkgroupArn`：指向包含可信身份传播配置标签的工作组
`Workgroup`：指定将在其中执行查询的工作组
虽然这两个参数通常指向同一个工作组，但必须显式设置两个参数以确保正常运行。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| WorkGroupArn | none | 必需 | 主 |
## JWT 应用程序角色 ARN
JWT 交换时将代入角色的 ARN。此角色用于 JWT 交换、通过工作组标签获取 IAM Identity Center 客户管理的应用程序 ARN，以及获取访问角色 ARN。有关代入角色的信息，请参阅 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ApplicationRoleArn | none | 必需 | none |
## JWT 角色会话名称
IAM 会话的名称。它可以是任意名称，但通常，人们会填写与使用自身应用程序的用户关联的名称或标识符。这样，您的应用程序使用的临时安全凭证会与该用户相关联。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| JwtRoleSessionName | role\$1session\$1name（已弃用） | 必需 | none |
## 客户端密钥
clientSecret 是您的身份提供者颁发的机密密钥，用于对您的应用程序（客户端）进行身份验证。虽然此参数是可选的，可能并非所有身份验证流程必需，但其使用可提了额外的安全层。如果您的 IDP 配置需要客户端密钥，则必须将此参数与身份提供者管理员提供的值一起包括在内。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| OidcClientSecret | none | 可选 | none |
## 范围
该范围指定您的应用程序向身份提供者请求的访问级别。要接收包含基本用户身份声明的 ID 令牌，您必须在范围内包含 `openid`。您的范围可能需要包括 `email` 或 `profile` 等其他权限，具体取决于您的身份提供者（例如 *Microsoft Entra ID*）配置为包含在 ID 令牌中的用户声明。这些声明对于正确的*可信身份传播*映射至关重要。如果用户身份映射失败，请验证您的范围是否包含所有必需的权限，并且您的身份提供者已配置为在 ID 令牌中包含所需的声明。这些声明必须与 IAM Identity Center 中的*可信令牌发布者*映射配置相匹配。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 范围 | none | 可选 | openid email offline\$1access |
## 角色会话持续时间
角色会话的持续时间（以秒为单位）。有关更多信息，请参阅 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration（已弃用） | 可选 | 3600 |
## JWT 访问角色 ARN
Athena 代表您进行调用时所代入角色的 ARN。有关代入角色的更多信息，请参阅 *AWS Security Token Service API Reference* 中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AccessRoleArn | none | 可选 | none |
## IAM Identity Center 客户管理的应用程序 ARN
IAM Identity Center 客户管理的应用程序 ARN。有关更多信息，请参阅 [Customer Managed Application](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| CustomerIdcApplicationArn | none | 可选 | none |
## 身份提供者端口号
用于 OAuth 2.0 回调服务器的本地端口号。此项用作 redirect\$1uri，您需要在 IDP 应用程序中将其列入允许列表。默认生成的 redirect\$1uri 为：http://localhost:7890/athena
**警告**
在 Windows 终端服务器或远程桌面服务等共享环境中，环回端口（默认值：7890）在同一台计算机上的所有用户之间共享。系统管理员可通过以下方式降低潜在的端口劫持风险：
为不同用户组配置不同的端口号
使用 Windows 安全策略限制端口访问权限
在用户会话之间实现网络隔离
如果无法实现这些安全控制措施，我们建议改用 [JWT 可信身份传播](jdbc-v3-driver-jwt-tip-credentials.md)插件，该插件不需要环回端口。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| IdpPortNumber | none | 可选 | 7890 |
## 身份提供者响应超时
等待 OAuth 2.0 回调响应的超时时间（秒）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| IdpResponseTimeout | none | 可选 | 120 |
## 启用令牌缓存
EnableTokenCaching 参数决定驱动程序是否在两次连接之间缓存身份验证令牌。将 EnableTokenCaching 设置为 true 可减少身份验证提示并改善用户体验，但应谨慎使用。此设置最适合单用户桌面环境。在 Windows Server 等共享环境中，建议禁用此项，以防止连接字符串相似的用户之间可能共享令牌。
对于使用 Tableau Server 等工具的企业部署，我们建议使用 [JWT 可信身份传播](jdbc-v3-driver-jwt-tip-credentials.md)插件，而不是这种身份验证方法。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| EnableTokenCaching | none | 可选 | FALSE |
# Azure AD 凭证
这是一种基于 SAML 的身份验证机制，允许使用 Azure AD 身份提供者对 Athena 进行身份验证。此方法假设 Athena 和 Azure AD 之间已经建立了联合身份验证。
**注意**
本节中的某些参数名称具有别名。这些别名在功能上等同于参数名称，提供这些别名的目的是与 JDBC 2.x 驱动程序向后兼容。由于参数名称经过改进以遵循更清晰、更一致的命名约定，因此建议使用这些名称而不是已经弃用的别名。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `AzureAD`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | AzureAD |
## 用户
将用于对 Azure AD 进行身份验证的 Azure AD 用户的电子邮件地址。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 用户 | UID（已弃用） | 必需 | none |
## 密码
Azure AD 用户的密码。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 密码 | PWD（已弃用） | 必需 | none |
## Azure AD 租户 ID
Azure AD 应用程序的租户 ID。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AzureAdTenantId | tenant\$1id（已弃用） | 必需 | none |
## Azure AD 客户端 ID
Azure AD 应用程序的客户端 ID。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AzureAdClientId | client\$1id（已弃用） | 必需 | none |
## Azure AD 客户端密钥
Azure AD 应用程序的客户端密钥。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AzureAdClientSecret | client\$1secret（已弃用） | 必需 | none |
## Preferred role
要代入的角色的 Amazon 资源名称（ARN）。有关 ARN 角色的信息，请参阅 *AWS Security Token Service API 参考*中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role（已弃用） | 可选 | none |
## 角色会话持续时间
角色会话的持续时间（以秒为单位）。有关更多信息，请参阅 *AWS Security Token Service API 参考*中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration（已弃用） | 可选 | 3600 |
## Lake Formation 已启用
指定是否使用 [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 操作（而非 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 操作）来检索临时 IAM 凭证。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | none | 可选 | FALSE |
# Okta 凭证
这是一种基于 SAML 的身份验证机制，允许使用 Okta 身份提供者对 Athena 进行身份验证。此方法假设 Athena 和 Okta 之间已经建立了联合身份验证。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `Okta`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | Okta |
## 用户
将用于对 Okta 进行身份验证的 Okta 用户的电子邮件地址。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 用户 | UID（已弃用） | 必需 | none |
## 密码
Okta 用户的密码。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 密码 | PWD（已弃用） | 必需 | none |
## 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`）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| OktaHostName | IdP\$1Host（已弃用） | 必需 | none |
## 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`）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| OktaAppId | App\$1ID（已弃用） | 必需 | none |
## Okta 应用程序名称
Okta 应用程序的名称。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| OktaAppName | App\$1Name（已弃用） | 必需 | none |
## Okta MFA 类型
如果您已将 Okta 设置为要求多重身份验证（MFA），则需要根据要使用的第二个因素指定 Okta MFA 类型和其他参数。
Okta MFA 类型是用于向 Okta 进行身份验证的第二种身份验证因素类型（仅次于密码）。受支持的第二个因素包括通过 Okta Verify 应用程序传送的推送通知，以及由 Okta Verify、Google Authenticator 生成或通过 SMS 发送的临时一次性密码（TOTP）。各个组织的安全策略决定用户登录是否需要 MFA。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 可能的值 |
| --- | --- | --- | --- | --- |
| OktaMfaType | okta\$1mfa\$1type（已弃用） | 如果将 Okta 设置为需要 MFA，则为必填项 | none | oktaverifywithpush, oktaverifywithtotp, googleauthenticator, smsauthentication |
## Okta 电话号码
选择 `smsauthentication` MFA 类型时，Okta 将使用 SMS 向其发送临时一次性密码的电话号码。该电话号码必须是美国或加拿大电话号码。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| OktaPhoneNumber | okta\$1phone\$1number（已弃用） | 如果 OktaMfaType 是 smsauthentication，则为必填项 | none |
## Okta MFA 等待时间
在驱动程序引发超时异常之前，等待用户确认来自 Okta 的推送通知的时长（以秒为单位）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| OktaMfaWaitTime | okta\$1mfa\$1wait\$1time（已弃用） | 可选 | 60 |
## Preferred role
要代入的角色的 Amazon 资源名称（ARN）。有关 ARN 角色的信息，请参阅 *AWS Security Token Service API 参考*中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role（已弃用） | 可选 | none |
## 角色会话持续时间
角色会话的持续时间（以秒为单位）。有关更多信息，请参阅 *AWS Security Token Service API 参考*中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration（已弃用） | 可选 | 3600 |
## Lake Formation 已启用
指定是否使用 [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 操作（而非 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 操作）来检索临时 IAM 凭证。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | none | 可选 | FALSE |
# Ping 凭证
这是一种基于 SAML 的身份验证机制，允许使用 Ping Federate 身份提供者对 Athena 进行身份验证。此方法假设 Athena 和 Ping Federate 之间已经建立了联合身份验证。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `Ping`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | Ping |
## 用户
Ping Federate 用户用于通过 Ping Federate 进行身份验证的电子邮件地址。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 用户 | UID（已弃用） | 必需 | none |
## 密码
Ping Federate 用户的密码。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 密码 | PWD（已弃用） | 必需 | none |
## PingHostName
您的 Ping 服务器的地址。要查找您的地址，请访问以下 URL 并查看 **SSO 应用程序端点**字段。
```
https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections
```
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| PingHostName | IdP\$1Host（已弃用） | 必需 | none |
## PingPortNumber
用于连接 IdP 主机的端口号。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| PingPortNumber | IdP\$1Port（已弃用） | 必需 | none |
## PingPartnerSpId
服务提供商地址。要查找服务提供商地址，请访问以下 URL 并查看 **SSO 应用程序端点**字段。
```
https://your-pf-host-#:9999/pingfederate/your-pf-app#/spConnections
```
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| PingPartnerSpId | Partner\$1SPID（已弃用） | 必需 | none |
## Preferred role
要代入的角色的 Amazon 资源名称（ARN）。有关 ARN 角色的信息，请参阅 *AWS Security Token Service API 参考*中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role（已弃用） | 可选 | none |
## 角色会话持续时间
角色会话的持续时间（以秒为单位）。有关更多信息，请参阅 *AWS Security Token Service API 参考*中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration（已弃用） | 可选 | 3600 |
## Lake Formation 已启用
指定是否使用 [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 操作（而非 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 操作）来检索临时 IAM 凭证。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | none | 可选 | FALSE |
# AD FS 凭证
这是一种基于 SAML 的身份验证机制，允许使用 Microsoft Active Directory 联合身份验证服务（AD FS）对 Athena 进行身份验证。此方法假设用户已在 Athena 和 AD FS 之间建立了联合身份验证。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `ADFS`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | ADFS |
## 用户
AD FS 用户的电子邮件地址，用于对 AD FS 进行身份验证。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 用户 | UID（已弃用） | 基于表单的身份验证的必要项。Windows 集成式身份验证的可选项。 | none |
## 密码
AD FS 用户的密码。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 密码 | PWD（已弃用） | 基于表单的身份验证的必要项。Windows 集成式身份验证的可选项。 | none |
## ADFS 主机名
AD FS 服务器的地址。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AdfsHostName | IdP\$1Host（已弃用） | 必需 | none |
## ADFS 端口号
用于连接 AD FS 服务器的端口号。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AdfsPortNumber | IdP\$1Port（已弃用） | 必需 | none |
## ADFS 依赖方
受信任的依赖方。使用此参数覆盖 AD FS 依赖方端点 URL。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AdfsRelyingParty | LoginToRP（已弃用） | 可选 | urn:amazon:webservices |
## 已启用 ADFS WIA
布尔值。使用此参数可通过 AD FS 启用 Windows 集成式身份验证（WIA）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AdfsWiaEnabled | none | 可选 | FALSE |
## Preferred role
要代入的角色的 Amazon 资源名称（ARN）。有关 ARN 角色的信息，请参阅《AWS Security Token Service API Reference》**中的 [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role（已弃用） | 可选 | none |
## 角色会话持续时间
角色会话的持续时间（以秒为单位）。有关更多信息，请参阅《AWS Security Token Service API Reference》**中的 [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 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 操作（而非 [https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS 操作）来检索临时 IAM 凭证。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | none | 可选 | FALSE |
# 浏览器 Azure AD 凭证
浏览器 Azure AD 是一个基于 SAML 的身份验证机制，可与 Azure AD 身份提供者配合使用并支持多重身份验证。与标准 Azure AD 身份验证机制不同，该机制不需要在连接参数中输入用户名、密码或客户端密钥。与标准 Azure AD 身份验证机制一样，浏览器 Azure AD 还假设用户已经在 Athena 和 Azure AD 之间建立了联合身份验证。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `BrowserAzureAD`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | BrowserAzureAD |
## Azure AD 租户 ID
Azure AD 应用程序的租户 ID
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AzureAdTenantId | tenant\$1id（已弃用） | 必需 | none |
## Azure AD 客户端 ID
Azure AD 应用程序的客户端 ID
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| AzureAdClientId | client\$1id（已弃用） | 必需 | none |
## 身份提供者响应超时
驱动程序停止等待 Azure AD 发出 SAML 响应之前的时长（以秒为单位）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| IdpResponseTimeout | idp\$1response\$1timeout（已弃用） | 可选 | 120 |
## Preferred role
要代入的角色的 Amazon 资源名称（ARN）。有关 ARN 角色的信息，请参阅 *AWS Security Token Service API 参考*中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role（已弃用） | 可选 | none |
## 角色会话持续时间
角色会话的持续时间（以秒为单位）。有关更多信息，请参阅 *AWS Security Token Service API 参考*中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration（已弃用） | 可选 | 3600 |
## Lake Formation 已启用
指定是否使用 [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 操作（而非 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 操作）来检索临时 IAM 凭证。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | none | 可选 | FALSE |
# 浏览器 SAML 凭证
浏览器 SAML 是一个通用身份验证插件，可与基于 SAML 的身份提供者配合使用并支持多重身份验证。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `BrowserSaml`。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | BrowserSaml |
## 单点登录的登录 URL
应用程序在基于 SAML 的身份提供者上的单点登录 URL。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| SsoLoginUrl | login\$1url（已弃用） | 必需 | none |
## 侦听端口
用于侦听 SAML 响应的端口号。此值应与配置基于 SAML 的身份提供者时所用的 URL 相匹配（例如：`http://localhost:7890/athena`）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ListenPort | listen\$1port（已弃用） | 可选 | 7890 |
## 身份提供者响应超时
驱动程序停止等待 Azure AD 发出 SAML 响应之前的时长（以秒为单位）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| IdpResponseTimeout | idp\$1response\$1timeout（已弃用） | 可选 | 120 |
## Preferred role
要代入的角色的 Amazon 资源名称（ARN）。有关 ARN 角色的信息，请参阅 *AWS Security Token Service API 参考*中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| PreferredRole | preferred\$1role（已弃用） | 可选 | none |
## 角色会话持续时间
角色会话的持续时间（以秒为单位）。有关更多信息，请参阅 *AWS Security Token Service API 参考*中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| RoleSessionDuration | Duration（已弃用） | 可选 | 3600 |
## Lake Formation 已启用
指定是否使用 [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) Lake Formation API 操作（而非 [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) AWS STS API 操作）来检索临时 IAM 凭证。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| LakeFormationEnabled | none | 可选 | FALSE |
# DataZone IdC 凭证提供程序
一种身份验证机制，允许使用 IAM Identity Center 连接到 Athena 中受 DataZone 管理的数据。
## 凭证提供程序
将用于对 AWS 的请求进行身份验证的凭证提供程序。将此参数的值设置为 `DataZoneIdc`。请注意，`AWSCredentialsProviderClass` 别名已被弃用；请改用 `CredentialsProvider` 参数名称。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 | 要使用的值 |
| --- | --- | --- | --- | --- |
| CredentialsProvider | AWSCredentialsProviderClass（已弃用） | 必需 | none | DataZoneIDC |
## DataZone 域标识符
要使用的 DataZone 域的标识符。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| DataZoneDomainId | none | 必需 | none |
## DataZone 环境标识符
要使用的 DataZone 环境的标识符。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| DataZoneEnvironmentId | none | 必需 | none |
## DataZone 域区域
预置您的 DataZone 域的 AWS 区域。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| DataZoneDomainRegion | none | 必需 | none |
## 区域
预置您的 DataZone 环境和 Athena 工作组的 AWS 区域。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 区域 | none | 必需 | none |
## IAM Identity Center 发布者 URL
DataZone 域使用的 IAM Identity Center 实例的发布者 URL。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| IdentityCenterIssuerUrl | none | 必需 | none |
## DataZone 端点覆盖
要使用的 DataZone API 端点，而不是提供的 AWS 区域的默认端点。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| DataZoneEndpointOverride | none | 可选 | none |
## 启用令牌缓存
启用后，允许在驱动程序连接之间使用相同的 IAM Identity Center 访问令牌。这可以防止创建多个驱动程序连接的 SQL 工具启动多个浏览器窗口。如果启用此参数，我们建议您在使用后立即关闭 SQL 工具，以清除令牌缓存并要求重新进行身份验证。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| EnableTokenCaching | none | 可选 | FALSE |
## 侦听端口
侦听 IAM Identity Center 响应的端口号。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| ListenPort | none | 可选 | 8000 |
## 身份提供者响应超时
驱动程序停止等待 IAM Identity Center 发出响应之前的时长（以秒为单位）。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| IdpResponseTimeout | none | 可选 | 120 |
# DataZone IAM 凭证提供程序
一种身份验证机制，使用 IAM 凭证连接到 Athena 中受 DataZone 管理的数据。
## DataZone 域标识符
要使用的 DataZone 域的标识符。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| DataZoneDomainId | none | 必需 | none |
## DataZone 环境标识符
要使用的 DataZone 环境的标识符。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| DataZoneEnvironmentId | none | 必需 | none |
## DataZone 域区域
预置您的 DataZone 域的 AWS 区域。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| DataZoneDomainRegion | none | 必需 | none |
## DataZone 端点覆盖
要使用的 DataZone API 端点，而不是提供的 AWS 区域的默认端点。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| DataZoneEndpointOverride | none | 可选 | none |
## 用户
您的 AWS 访问密钥 ID。有关访问密钥的更多信息，请参阅《*IAM 用户指南*》中的 [AWS 安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 用户 | AccessKeyId | 可选 | none |
## 密码
您的 AWS 密钥 ID。有关访问密钥的更多信息，请参阅《*IAM 用户指南*》中的 [AWS 安全凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)。
****
| 参数名称 | 别名 | 参数类型 | 默认 值 |
| --- | --- | --- | --- |
| 密码 | SecretAccessKey | 可选 | none |
# 其他 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-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 令牌（JWT），并与可信身份传播集成。其专为单用户桌面环境而设计，提供比手动 JWT 处理更简化的身份验证体验。有关可信身份传播的更多信息，请参阅 [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html)。
### 修复
+ **增强的时间戳精度支持**：该驱动程序现已完全支持通过 `getTimestamp()` 方法从 Athena 查询返回的时间戳值的毫秒级和纳秒级精度。
+ **改进的复杂类型处理**：修复了在 `DatabaseMetaData#getColumns` 和常规元数据操作中解析嵌套数据类型（数组、结构和映射）的问题，确保复杂数据结构的类型信息准确无误。
+ **增强的错误日志记录**：改进了 S3 元数据提取失败的日志记录，提供了更清晰的错误消息和更完善的诊断信息。
## 3.6.0
发布时间：2025 年 9 月 10 日
### 改进
+ **JWT 可信身份传播身份验证插件**：添加了新的身份验证插件，以支持 JWT 可信身份传播与 JDBC 驱动程序集成。通过此身份验证类型，您可以使用从外部身份提供者处获得的 JSON Web 令牌（JWT）作为连接参数，在 Athena 进行身份验证。使用可信身份传播，可以向 IAM 角色添加身份上下文，以识别请求访问 AWS 资源的用户身份。有关启用和使用可信身份传播的信息，请参阅 [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html)。
+ **自定义 SSO OIDC 和 SSO 管理端点支持**：增加了对 JDBC 驱动程序中自定义 SSO OIDC 和 SSO 管理端点的支持。在 VPC 后面运行 JDBC 时，此增强功能可以为 SSO 服务指定自有端点。
+ **AWSSDK 版本更新**：我们已将驱动程序中使用的 AWS SDK 版本更新到 2.32.16，并更新了 3.6.0 版本的项目依赖关系。
## 3.5.1
发布时间：2025 年 7 月 17 日
### 改进
+ **日志功能** — 通过将日志级别提升到 `INFO` 并添加行数、偏移量和对象长度等指标，改善了 S3 获取日志记录。实现了连接生命周期的跟踪并优化了整体日志记录性能。
+ **特殊字符处理** — 改进了对架构和目录名称中 `LIKE` 模式的特殊字符的处理。
+ **连接状态管理** — 改进了连接状态管理，防止出现潜在错误，方法是在连接关闭后防止 API 调用，并在关闭期间为查询操作添加安全检查。
### 修复
+ **DDL 查询元数据** — 修复了 DDL 查询元数据处理的 `NoSuchKeyFound` 问题。
## 3.5.0
发布时间：2025 年 3 月 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 年 2 月 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 异常。
+ **日志记录** – 驱动程序在使用查询结果后不再记录消息 Items requested for query execution [...], but subscription is cancelled。
+ **空参数字符串** – 驱动程序现在处理连接参数中存在的空字符串，就好像该参数不存在一样。这解决了某些 BI 工具无意中传递空字符串而导致意外的身份验证尝试时发生的问题。
## 3.2.2
发布时间：2024 年 7 月 29 日
### 改进
+ **数据类型映射**：通过更改驱动程序将 `tinyint`、`smallint`、`row` 和 `struct` 数据类型映射到 Java 对象的方式，提高了对 JDBC 规范的合规性。
+ **AWS SDK 版本更新**：驱动程序中使用的 AWS SDK 版本已更新至 2.26.23。
### 修复
+ **注释**：修复了语句末尾的行注释问题。
+ **数据库列表**：修复了当分页 `ListDatabases` API 返回的最后一页为空时，列出数据库可能会进入无限循环的问题。
## 3.2.1
发布时间：2024 年 7 月 3 日
### 改进
+ **JWT 凭证提供程序** – 添加了对用户指定的会话持续时间的支持。有关更多信息，请参阅 [角色会话持续时间](jdbc-v3-driver-jwt-credentials.md#jdbc-v3-driver-jwt-role-session-duration)。
### 修复
+ **线程池** – 为异步任务的每个连接创建一个 `ThreadPoolExecutor`，以避免使用 `ForkJoin` 池。
+ **凭证提供程序** – 当为 HTTP 客户端配置了外部 IdP 时，现在会解析代理主机以获取架构和主机。
+ **默认凭证提供程序** – 确保客户端代码无法关闭默认凭证提供程序。
+ **getColumns** – 修复了 `DatabaseMetaData#getColumns` 方法中的 `ORDINAL_COLUMN` 列属性问题。
+ **ResultSet** – 向 `ResultSet.` 添加了对 `Infinity`、`-Infinity` 和 `NaN` 的支持 修复了从目录操作返回的列类型与已完成查询的结果集之间的差异。
## 3.2.0
发布时间：2024 年 4 月 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** – 修复了使用空目录名称调用 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-) 方法时导致返回空目录的问题。
## 3.1.0
发布时间：2024 年 2 月 15 日
### 改进
+ 添加了对 Microsoft Active Directory 联合身份验证服务（AD FS）Windows 集成身份验证和基于表单的身份验证的支持。
+ 为了与 2.x 版本向后兼容，现在接受 `awsathena` JDBC 子协议，但会产生弃用警告。请改用 `athena` JDBC 子协议。
+ `AwsDataCatalog` 现在是目录参数的默认值，`default` 是数据库参数的默认值。这些更改确保返回当前目录和数据库的正确值，而不是 null。
+ 为符合 JDBC 规范，`IS_AUTOINCREMENT` 和 `IS_GENERATEDCOLUMN` 现在返回的是空字符串，而不是 `NO`。
+ 现在，Athena `int` 数据类型映射到与 Athena `integer` 相同的 JDBC 类型，而不是映射到 `other`。
+ 现在，当 Athena 中的列元数据不包含可选 `precision` 和 `scale` 字段时，驱动程序会为 `ResultSet` 列中的相应值返回零。
+ AWS SDK 版本已更新为 2.21.39。
### 修复
+ 修复了当来自 Athena 的纯文本结果的列数与 Athena 结果元数据中的列数不一致时导致出现异常的 `GetQueryResultsStream` 问题。
## 3.0.0
发布时间：2023 年 11 月 16 日
Athena JDBC 3.x 驱动程序是新一代的驱动程序，具有更好的性能和兼容性。JDBC 3.x 驱动程序支持直接从 Amazon S3 读取查询结果，此举可提高使用大型查询结果的应用程序的性能。该新驱动程序还减少了第三方依赖项，让与商业智能工具和自定义应用程序的集成变得更加容易。
# 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. Exception during column initialization（[Simba][AthenaJDBC](100123) 出现错误。列初始化期间出现异常）。
**athena:GetQueryResultsStream 策略** — 将 `athena:GetQueryResultsStream` 策略操作添加到使用 JDBC 驱动程序的 IAM 主体。此策略操作并不通过 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)时），请将 `MetadataRetrievalMethod=ProxyAPI` 包含在 JDBC 连接字符串中。
**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.jar](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 开发工具包和随附文档、发布说明、许可和协议。
+ [SimbaAthenaJDBC-2.2.2.1000.zip](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 开发工具包的 JDBC 4.2 驱动程序 `.jar` 文件。
+ [AthenaJDBC42-2.2.2.1001.jar](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.zip](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
您可以使用 ODBC 连接从许多第三方 SQL 客户端工具和应用程序连接到 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 策略** — 将 `athena:GetQueryResultsStream` 策略操作添加到使用 ODBC 驱动程序的 IAM 主体。此策略操作并不通过 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 位的 ODBC 2.1.0.0（ARM） | [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（英特尔）
| 驱动程序版本 | 下载链接 |
| --- | --- |
| 适用于 macOS 64 位的 ODBC 2.1.0.0（Intel） | [macOS 64 位 ODBC 驱动程序 2.1.0.0（英特尔）](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 可用磁盘空间
+ 已安装适用于 64 位 Windows 的 [Microsoft Visual C\$1\$1 Redistributable for Visual Studio](https://visualstudio.microsoft.com/downloads/#microsoft-visual-c-redistributable-for-visual-studio-2022)。
## 安装 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. 选择**安装**。
1. 在安装完成时，选择**完成**。
## 设置驱动程序配置选项的方法
要在 Windows 中控制 Amazon Athena ODBC 驱动程序的行为，可通过以下方式设置驱动程序配置选项：
+ 配置数据来源名称（DSN）时，在 **ODBC 数据来源管理器**程序中。
+ 通过在以下位置添加或更改 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。
+ 有 100MB 可用磁盘空间。
+ 使用版本 2.3.1 或更高版本的 [unixODBC](https://www.unixodbc.org/)。
+ 使用版本 2.26 或更高版本的 [GNU C 库](https://www.gnu.org/software/libc/)（glibc）。
## 在 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 或更高版本。
+ 有 100MB 可用磁盘空间。
+ 使用版本 3.52.16 或更高版本的 [iODBC](https://www.iodbc.org/dataspace/doc/iodbc/wiki/iodbcWiki/WelcomeVisitors)。
## 在 macOS 上安装 ODBC 数据连接器
参照以下过程下载并安装适用于 macOS 操作系统的 Amazon Athena ODBC 驱动程序。
**下载并安装适用于 macOS 的 Amazon Athena ODBC 驱动程序**
1. 下载 `.pkg` 包文件。
1. 双击 `.pkg` 文件。
1. 按照向导中的步骤安装驱动程序。
1. 在**许可协议**页面上，按**继续**，然后选择**同意**。
1. 选择**安装**。
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` 文件：
+ 英特尔处理器计算机：`/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` 文件的完整路径和文件名。
+ 对于配备了英特尔处理器的 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` 文件的完整路径和文件名。
+ 对于配备了英特尔处理器的 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 连接参数
以下各节介绍了每个主要连接参数。
## Data source name
指定数据来源的名称。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| DSN | 无 DSN 连接类型的可选项 | none | DSN=AmazonAthenaOdbcUsWest1; |
## 说明
包含数据来源的描述。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| 说明 | 可选 | 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 参考*中的[工作组](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; |
## Preferred role
要代入的角色的 Amazon 资源名称（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` 参数中指定自定义凭证提供程序时，将使用会话持续时间参数。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| duration | 可选 | 900 | duration=900; |
## 插件名称
指定命名配置文件中使用的自定义凭证提供程序的名称。此参数可以采用与 ODBC 数据来源管理器的**身份验证类型**字段相同的值，但只能在 `AWSProfile` 配置中使用。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| plugin\$1name | 可选 | none | plugin\$1name=AzureAD; |
# AD FS
AD FS 是一个基于 SAML 的身份验证插件，可与 Active Directory 联合身份验证服务（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; |
## Preferred role
担任角色的 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)。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| duration | 可选 | 900 | duration=900; |
## IdP host
AD FS 服务主机的名称。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| idp\$1host | Require | none | idp\$1host=.; |
## IdP port
用于连接 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; |
## Preferred role
担任角色的 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)。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| duration | 可选 | 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\$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; |
## Preferred role
要代入的角色的 Amazon 资源名称（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)。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| duration | 可选 | 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; |
## 超时
插件停止等待 Azure AD 发出 SAML 响应之前的持续时间，以秒为单位。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| timeout | 可选 | 120 | timeout=90; |
## 启用 Azure 文件缓存
启用临时凭证缓存。此连接参数允许在多个进程之间缓存和重复使用临时凭证。当您使用 Microsoft Power BI 等 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; |
## Preferred role
要代入的角色的 Amazon 资源名称（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)。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| duration | 可选 | 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; |
## 超时
插件停止等待身份提供商发出 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 授权码而不是设备代码授权，以提高安全性。此更改取消了设备代码显示步骤，并提供更快的身份验证。有一个新参数 `listen_port`（默认值为 7890）用于 OAuth 2.0 回调服务器。您可能需要将此端口添加到您的网络允许列表中。默认范围已更改为 `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 管理控制台，打开 AWS IAM Identity Center 控制台：[https://console.aws.amazon.com/singlesignon/](https://console.aws.amazon.com/singlesignon/)。
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; |
## 超时
轮询 SSO API 需要检查是否存在访问令牌的秒数。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| sso\$1oidc\$1timeout | 可选 | 120 | sso\$1oidc\$1timeout=60; |
## 侦听端口
用于 OAuth 2.0 回调服务器的本地端口号。这用作重定向 URI，您可能需要将此端口添加到您的网络允许列表中。生成的默认重定向 URI 为：`http://localhost:7890/athena`。此参数是在 v2.1.0.0 中添加的，属于从设备代码迁移到 PKCE 授权码的一部分。
**警告**
在 Windows 终端服务器或远程桌面服务等共享环境中，环回端口（默认值：7890）在同一台计算机上的所有用户之间共享。系统管理员可通过以下方式降低潜在的端口劫持风险：
为不同用户组配置不同的端口号
使用 Windows 安全策略限制端口访问权限
在用户会话之间实现网络隔离
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| listen\$1port | 可选 | 7890 | listen\$1port=8080; |
## 启用文件缓存
启用临时凭证缓存。此连接参数允许在多个进程之间缓存和重复使用临时凭证。当您使用 Microsoft Power BI 等 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 令牌）插件提供了一个使用 JSON Web 令牌担任 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; |
## Preferred role
担任角色的 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)。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| duration | 可选 | 900 | duration=900; |
## JSON Web 令牌
用于使用 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) AWS STS API 操作检索 IAM 临时凭证的 JSON Web 令牌。有关为 Google Cloud Platform（GCP）用户生成 JSON Web 令牌的信息，请参阅 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 令牌（JWT）作为连接参数，在 Athena 进行身份验证。您可以使用此插件，通过可信身份传播，实现对企业身份的支持。
使用可信身份传播，可以向 IAM 角色添加身份上下文，以识别请求访问 AWS 资源的用户身份。有关启用和使用可信身份传播的信息，请参阅 [What is trusted identity propagation?](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 资源名称（ARN）。有关工作组的更多信息，请参阅 [WorkGroup](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)。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| duration | 可选 | 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。有关客户管理的应用程序的更多信息，请参阅 [Customer Managed Applications](https://docs.aws.amazon.com/singlesignon/latest/userguide/customermanagedapps.html)。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| CustomerIdcApplicationArn | 可选 | none | CustomerIdcApplicationArn=arn:aws:sso::111122223333:application/ssoins-111122223333/apl-111122223333 |
## 启用文件缓存
启用临时凭证缓存。使用此连接参数，您可在多个进程之间缓存和重复使用临时凭证。当您使用 Microsoft Power BI 等 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 资源的用户身份。有关启用和使用可信身份传播的信息，请参阅 [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation.html)。
**注意**
该插件专为单用户桌面环境而设计。在 Windows Server 等共享环境中，系统管理员负责建立和维护用户之间的安全边界。
## 身份验证类型
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| AuthenticationType | 必需 | none | AuthenticationType=BrowserOidcTip; |
## IDP 公开配置 URL
IDP 公开配置 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 资源名称（ARN）。有关工作组的更多信息，请参阅 [WorkGroup](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; |
## 客户端密钥
客户端密钥是您的身份提供商颁发的机密密钥，用于对您的应用程序进行身份验证。虽然此参数是可选的，可能并非所有身份验证流程必需，但其使用可提了额外的安全层。如果您的 IDP 配置需要客户端密钥，则必须将此参数与身份提供商管理员提供的值一起包括在内。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| client\$1secret | 可选 | none | client\$1secret=s0m3R@nd0mS3cr3tV@lu3Th@tS3cur3lyPr0t3ct5Th3Cl13nt;\$1 |
## 范围
该范围指定您的应用程序向身份提供商请求的访问级别。要接收包含基本用户身份声明的 ID 令牌，您必须在范围内包含 `openid`。您的范围可能需要包括 `email` 或 `profile` 等其他权限，具体取决于您的身份提供商（例如 *Microsoft Entra ID*）配置为包含在 ID 令牌中的用户声明。这些声明对于正确的*可信身份传播*映射至关重要。如果用户身份映射失败，请验证您的范围是否包含所有必需的权限，并且您的身份提供商已配置为在 ID 令牌中包含所需的声明。这些声明必须与 IAM Identity Center 中的*可信令牌发布者*映射配置相匹配。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| 范围 | 可选 | openid email offline\$1access | Scope=openid email; |
## 会话持续时间
角色会话的持续时间（以秒为单位）。有关更多信息，请参阅 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| duration | 可选 | 3600 | duration=900; |
## JWT 访问角色 ARN
Athena 代表您进行调用时所代入角色的 ARN。有关代入角色的更多信息，请参阅 *AWS Security Token Service API Reference* 中的 [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。有关客户管理的应用程序的更多信息，请参阅 [Customer Managed Applications](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 终端服务器或远程桌面服务等共享环境中，环回端口（默认值：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; |
## Preferred role
担任角色的 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)。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| duration | 可选 | 900 | duration=900; |
## IdP host
您的 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 port
用于连接 IdP 主机的端口号。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| idp\$1port | 必需 | None | idp\$1port=443; |
## Okta app 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; |
## Preferred role
担任角色的 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)。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| duration | 可选 | 900 | duration=900; |
## IdP host
您的 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 port
用于连接 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 使用代理
通过代理在驱动程序和 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 身份验证插件。
**重要**
**v2.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 | 可选 | none | 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 | 可选 | none | 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` 条件将对 S3 对象的访问限制为来自 Athena 的请求，则自动提取器将首先尝试从 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 客户端的网络吞吐量达到了 1Gbps，而多线程 S3 客户端达到了 4Gbps。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| 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（64MB）。允许的最小值和最大值分别为 10485760（10MB）和 2146435072（约 2GB）。
****
| **连接字符串名称** | **参数类型** | **默认值** | **连接字符串示例** |
| --- | --- | --- | --- |
| S3ResultBlockSize | 可选 | 67108864 | S3ResultBlockSize=268435456; |
## 字符串列长度
为具有 `string` 数据类型的列指定列长度。由于 Athena 使用 [Apache Hive 字符串数据类型](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+Types#LanguageManualTypes-StringsstringStrings)，但该数据类型并未定义精度，所以 Athena 报告的默认长度为 2147483647 (`INT_MAX`)。商业智能工具通常会为列预先分配内存，这可能会导致内存消耗较高。为避免这种情况，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 及更高版本：`OFF`、`ERROR`、`WARN`、`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 查询的完整版或简化版。
+ 所用的账户 ID 和 AWS 区域，以及查询执行 ID。
+ **SAML 错误** -（可选）如果您遇到与使用 SAML 断言进行身份验证有关的问题，包含以下信息：
+ 所用的身份提供商和身份验证插件。
+ SAML 令牌示例。
# Amazon Athena ODBC 2.x 发布说明
这些发布说明详细介绍了 Amazon Athena ODBC 2.x 驱动程序中的增强功能、特征、已知问题和工作流变更。
## 2.1.0.0
发布时间：2026 年 3 月 20 日
Amazon Athena Amazon Athena ODBC v2.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 授权码，而非设备代码授权。有一个新的可选参数 `listen_port`（默认值为 7890）可用于 OAuth 2.0 回调服务器。您可能需要将此端口添加到您的网络允许列表中。默认范围已更改为 `sso:account:access`。有关更多信息，请参阅 [浏览器 SSO OIDC](odbc-v2-driver-browser-sso-oidc.md)。
### 改进
+ **BrowserSSOOIDC**：从设备代码流程迁移到 PKCE 授权码以提高安全性。
+ **BrowserAzureAD**：在 OAuth 2.0 授权流程中添加了 PKCE（代码交换的证明密钥），以防止授权码截取攻击。
+ **BrowserSAML**：添加了 RelayState CSRF 保护以防止 SAML 令牌注入攻击。
+ **凭证缓存**：从 v2.1.0.0 开始，缓存的凭证以纯文本 JSON 格式存储在 `user-profile/.athena-odbc/` 目录中，文件权限仅限于拥有用户，这与 AWS CLI 保护本地存储凭证的方式一致。
+ **IAM 配置文件**：除了现有 `Ec2InstanceMetadata` 之外，还增加了对 `EcsContainer` 和 `Environment` 凭证源的支持。
+ **连接字符串解析器**：实现了正确的 ODBC `}}` 转义处理。
+ **目录查询**：为架构名称和表模式添加了 SQL 标识符转义。
+ **ODBC 模式匹配**：将基于正则表达式的匹配替换为直接 ODBC LIKE 通配符匹配器。
+ **XML 解析**：为 SAML 令牌添加了递归深度限制（100 个级别）和大小限制（1MB）。
+ **ADFS 身份验证**：为 ADFS 服务器响应添加了响应大小限制（200KB）。
### 修复
+ 修复了身份验证组件中特殊元素的不当中和问题，该问题可能导致通过精心设计的连接参数执行代码或重定向身份验证流程。影响 BrowserSSOOIDC、BrowserAzureAD 和 BrowserSAML 插件。
+ 修复了查询处理组件中特殊元素的不当中和问题，该问题可能导致通过精心设计的表元数据进行拒绝服务攻击或 SQL 注入。
+ 修复了连接到身份提供者时证书验证不正确的问题。
+ 修复了基于浏览器的身份验证流程中缺失的身份验证安全控件，包括 OAuth 的 PKCE、SAML 的 CSRF 保护、安全凭证缓存和独占回调端口绑定。
+ 修复了解析组件中不受控制的资源消耗问题，该问题可能导致通过精心设计的输入模式、无限制的服务器响应或深度嵌套的 XML 有效载荷来进行拒绝服务攻击。
+ 修复了在 Power BI 导入模式下对跨账户联合目录使用 `UseSingleCatalogAndSchema=1` 时 `SQLColumns` 和 `SQLTables` 未返回任何结果的问题。
要下载新的 ODBC 版本 2 驱动程序，请参阅 [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 令牌（JWT），并与可信身份传播集成，从而提供无缝的身份验证体验。该插件专为单用户桌面环境而设计。有关启用和使用可信身份传播的信息，请参阅 [What is trusted identity propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html)。
+ **增强的日志记录框架**：通过以下方式显著改进了驱动程序的日志记录机制：
+ 除基本的 0/1 选项外，引入了更精细的日志级别
+ 删除冗余日志语句
+ 优化日志记录框架以包含与诊断相关的信息
+ 解决导致运营延误的性能问题
+ 启用日志记录时减少过多的日志文件生成
### 修复
+ **结果提取器优化**：修复了将提取大小参数限制错误地应用于流式和非流式结果提取器的问题。现在，该限制仅正确应用于非流式结果提取器。
要下载新的 ODBC 版本 2 驱动程序，请参阅 [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 版本 2.0.5.1 驱动程序包含以下针对基于浏览器的身份验证插件的修复。
+ 实现了登录 URL 和架构检查验证。
+ 改进了 Linux 上的浏览器启动机制以利用系统 API，从而提高了稳定性和安全性。
要下载新的 ODBC 版本 2 驱动程序，请参阅 [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 年 9 月 10 日
### 改进
+ **JWT 可信身份提供者（TIP）身份验证插件**：添加了新的身份验证插件，以支持 JWT 可信身份提供者（TIP）与 ODBC 驱动程序集成。通过此身份验证类型，您可以使用从外部身份提供者处获得的 JSON Web 令牌（JWT）作为连接参数，在 Athena 进行身份验证。使用 TIP，可以向 IAM 角色添加身份上下文，以识别请求访问 AWS 资源的用户身份。有关启用和使用 TIP 的信息，请参阅 [What is Trusted Identity Propagation?](https://docs.aws.amazon.com/singlesignon/latest/userguide/trustedidentitypropagation-overview.html)。
+ **自定义 SSO 管理端点支持**：增加了对 ODBC 驱动程序中自定义 SSO 管理端点的支持。在 VPC 后面运行 ODBC 时，此增强功能可以为 SSO 服务指定自有端点。
+ **AWSSDK 版本更新**：我们已将驱动程序中使用的 AWS SDK 版本更新到 2.32.16，并更新了 2.0.5.0 版本的项目依赖关系。
## 2.0.4.0
发布时间：2025 年 6 月 17 日
Amazon Athena ODBC 版本 2.0.4.0 驱动程序包含以下改进和修复。
### 改进
+ **结果提取器** – 此驱动程序现在会自动选择方法来下载查询结果。这样在大多数情况下就无需手动配置提取器。有关更多信息，请参阅 [结果提取器](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-result-fetcher)。
+ Curl 库已更新至 8.12.1。
### 修复
+ 修复了在连接到 STS 时 IAM 配置文件的代理配置。该修复允许使用 IAM 配置文件进行成功身份验证。
+ 读取带有身份验证插件的 IAM 配置文件的所有其他配置选项。这包括 `UseProxyForIdP`、`SSL_Insecure`、`LakeformationEnabled` 和 `LoginToRP` 以解决受影响插件的错误配置。
+ 通过允许接受可选的第二个参数来修复了 round 函数。它成功处理包含转义语法的查询。
+ 修复了 `TIME WITH TIME ZONE` 和 `TIMESTAMP WITH TIME ZONE` 数据类型的列大小。具有时间戳和时区数据类型的值不会被截断。
要下载新的 ODBC 版本 2 驱动程序，请参阅 [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 年 4 月 8 日
Amazon Athena ODBC 版本 2.0.3.0 驱动程序包含以下改进和修复。
### 改进
+ Linux 和 Mac 平台上添加了对 Okta 身份验证插件的 MFA 支持。
+ 适用于 Windows 的 `athena-odbc.dll` 库和 `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)。
+ 引入了 `UseWCharForStringTypes` 连接参数，以便使用 `SQL_WCHAR` 和 `SQL_WVARCHAR` 来报告字符串数据类型。有关更多信息，请参阅 [使用 WCHAR 作为字符串类型](odbc-v2-driver-advanced-options.md#odbc-v2-driver-advanced-options-use-wchar-for-string-types)。
### 修复
+ 修复了使用 Get-OdbcDsn PowerShell 工具时出现的注册表损坏警告。
+ 更新了解析逻辑，以便处理查询字符串开头的注释。
+ 日期和时间戳数据类型现在允许年份字段为零。
要下载新的 ODBC 版本 2 驱动程序，请参阅 [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 年 2 月 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（英特尔和 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 版本 2 驱动程序，请参阅 [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 月 7 日
Amazon Athena ODBC 版本 2.0.2.1 驱动程序包含以下改进和修复。
### 改进
+ 改进了所有接口的 ODBC 驱动程序线程安全性。
+ 启用日志记录后，现在会以毫秒精度记录日期时间值。
+ 在使用 [浏览器 SSO OIDC](odbc-v2-driver-browser-sso-oidc.md) 插件进行身份验证期间，终端现在会打开，向用户显示设备代码。
### 修复
+ 解决了在解析流式传输 API 的结果时出现的内存释放问题。
+ 针对接口 `SQLTablePrivileges()`、`SQLSpecialColumns()` `SQLProcedureColumns()` 和 `SQLProcedures()` 的请求现在会返回空结果集。
要下载 ODBC 版本 2 驱动程序，请参阅 [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 版本 2.0.2.0 驱动程序包含以下改进和修复。
### 改进
+ 为浏览器 Azure AD、浏览器 SSO OIDC 和 Okta 基于浏览器的身份验证插件添加了文件缓存功能。
像 Power BI 这样的 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 版本 2 驱动程序，请参阅 [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 年 8 月 10 日
Amazon Athena ODBC 版本 2.0.1.1 驱动程序包含以下改进和修复。
### 改进
+ 在 Okta 身份验证插件中添加了 URI 日志记录。
+ 向外部凭证提供程序插件添加了首选角色参数。
+ 在 AWS 配置文件的配置文件名称中添加了对配置文件前缀的处理。
### 修复
+ 更正了 Lake Formation 和 AWS STS 客户端一起使用时出现的 AWS 区域 使用问题。
+ 已将缺少的分区键还原到表列列表中。
+ 在 AWS 配置文件中添加了缺少的 `BrowserSSOOIDC` 身份验证类型。
要下载新的 ODBC 版本 2 驱动程序，请参阅 [ODBC 2.x 驱动程序下载](odbc-v2-driver.md#odbc-v2-driver-download)。
## 2.0.1.0
发布时间：2023 年 6 月 29 日
Amazon Athena 发布了 ODBC 版本 2.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 驱动程序
您可以使用 ODBC 连接从第三方 SQL 客户端工具和应用程序连接到 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 策略** — 将 `athena:GetQueryResultsStream` 策略操作添加到使用 ODBC 驱动程序的 IAM 主体。此策略操作并不通过 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 驱动程序注释
**不使用代理进行连接**
如果要指定驱动程序不使用代理连接到的某些主机，则可以在 ODBC 连接字符串中使用可选 `NonProxyHost` 属性。
`NonProxyHost` 属性指定了启用代理连接时连接器可以无需通过代理服务器访问的主机列表（以逗号分隔），如下例所示：
```
.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 联合身份验证服务（AD FS）用户设置对 Amazon Athena 的联合访问权限，您首先要在 AD FS 和 AWS 账户之间建立信任。获得信任后，您的 AD 用户便可使用其 AD 凭证对 AWS 进行[联合身份验证](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）角色权限以访问 Athena API 等 AWS 资源。
要创建这种信任，您需要将 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 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在导航窗格中，选择 **Identity providers**（身份提供程序）。
1. 选择**添加提供程序**。
1. 对于 **Provider type**（提供程序类型），选择 **SAML**。
![\[选择 SAML。\]](http://docs.aws.amazon.com/zh_cn/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 控制台中，对于 **Metadata document**（元数据文档），选择 **Choose file**（选择文件），然后将联合身份验证元数据文件上传到 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_cn/athena/latest/ug/images/odbc-adfs-saml-2.png)
1. 在 **Add permissions**（添加权限）页面上，筛选此角色所需的 IAM 权限策略，然后选中相应的复选框。本教程附加了 `AmazonAthenaFullAccess` 和 `AmazonS3FullAccess` 策略。
![\[为角色附加 Athena 完全访问策略。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-adfs-saml-3.png)
![\[为角色附加 Amazon S3 完全访问策略。\]](http://docs.aws.amazon.com/zh_cn/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：选择受信任实体）中，**Principal**（主体）字段应自动填充为 `"Federated:" "arn:aws:iam::account_id:saml-provider/adfs-saml-provider"`。`Condition` 字段应包含 `"SAML:aud"` 和 `"https://signin.aws.amazon.com/saml"`。
![\[受信任实体 JSON。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-adfs-saml-5.png)
**Step 2: Add permissions**（步骤 2：添加权限）将显示已附加到该角色的策略。
![\[附加到角色的策略列表。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-adfs-saml-6.png)
1. 选择**创建角色**。横幅消息会确认角色是否创建。
1. 在 **Roles**（角色）页面上，选择您刚刚创建的角色名称。该角色的摘要页面会显示已附加的策略。
![\[角色的摘要页面。\]](http://docs.aws.amazon.com/zh_cn/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 用户的信息是真实信息，并且已对用户进行身份验证。
### 添加依赖方信任
要在 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_cn/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_cn/athena/latest/ug/images/odbc-adfs-saml-9.png)
1. 在**添加信赖方信任向导**页面上，选择**开始**。
![\[选择启动。\]](http://docs.aws.amazon.com/zh_cn/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_cn/athena/latest/ug/images/odbc-adfs-saml-11.png)
1. 在 **Specify Display Name**（指定显示名称）页面上，为 **Display name**（显示名称）输入依赖方的显示名称，然后选择 **Next**（下一步）。
![\[输入依赖方显示名称。\]](http://docs.aws.amazon.com/zh_cn/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_cn/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_cn/athena/latest/ug/images/odbc-adfs-saml-14.png)
1. 选择**下一步**。
1. 在 **Ready to Add Trust**（准备添加信任）页面上，选择 **Next**（下一步）将依赖方信任添加到 AD FS 配置数据库。
![\[选择下一步。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-adfs-saml-15.png)
1. 在 **Finish**（完成）页面上，选择 **Close**（关闭）。
![\[选择关闭。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-adfs-saml-16.png)
### 为依赖方配置 SAML 声明规则
在此任务中，您将创建两组声明规则。
第一组规则 1-4 包含 AD FS 声明规则，这些规则需要基于 AD 组成员关系担任 IAM 角色。如果您想建立对 [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_cn/athena/latest/ug/images/odbc-adfs-saml-17.png)
1. 选择**添加规则**。
1. 在“添加转换声明规则向导”的 **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）。
+ 对于**传出名称 ID 格式**，请选择**持久性标识符**。
+ 选择 **Pass through all claim values**（传递所有声明值）。
![\[创建第一条声明规则。\]](http://docs.aws.amazon.com/zh_cn/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 属性作为声明发送）。
+ 对于**特性存储**，请选择 **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_cn/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_cn/athena/latest/ug/images/odbc-adfs-saml-20.png)
1. 选择**添加规则**。输入以下信息以创建声明规则 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_cn/athena/latest/ug/images/odbc-adfs-saml-21.png)
## 3. 创建 Active Directory 用户和组
现在，您可以创建要访问 Athena 的 AD 用户以及置放这些用户的 AD 组，以便按组控制访问级别。创建对数据访问模式进行分类的 AD 组后，您可以将用户添加到这些组中。
**创建要访问 Athena 的 AD 用户**
1. 在“服务器管理器”控制面板上，选择 **Tools**（工具），然后选择 **Active Directory Users and Computers**（Active Directory 用户和计算机）。
![\[依次选择 Tools（工具）、Active Directory Users and Computers（Active Directory 用户和计算机）。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-adfs-saml-22.png)
1. 在导航窗格中，选择 **Users**（用户）。
1. 在 **Active Directory Users and Computers**（Active Directory 用户和计算机）工具栏上，选择 **Create user**（创建用户）选项。
![\[选择创建用户。\]](http://docs.aws.amazon.com/zh_cn/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_cn/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_cn/athena/latest/ug/images/odbc-adfs-saml-25.png)
1. 选择**下一步**。
1. 选择**结束**。
![\[选择结束。\]](http://docs.aws.amazon.com/zh_cn/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_cn/athena/latest/ug/images/odbc-adfs-saml-27.png)
1. 选择**确定**。
### 创建 AD 组来表示数据访问模式
您可以创建 AD 组，其成员在登录 AWS 时担任 `adfs-data-access` IAM 角色。以下示例创建了一个名为 aws-adfs-data-access 的 AD 组。
**创建 AD 组**
1. 在“服务器管理器”控制面板上，从 **Tools**（工具）菜单中，选择 **Active Directory Users and Computers**（Active Directory 用户和计算机）。
1. 在工具栏上，选择 **Create new group**（创建新组）选项。
![\[选择 Create New Group（创建新组）。\]](http://docs.aws.amazon.com/zh_cn/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_cn/athena/latest/ug/images/odbc-adfs-saml-29.png)
1. 选择**确定**。
### 将 AD 用户添加到相应的组
现在，您已创建 AD 用户和 AD 组，可将该用户添加到该组。
**将 AD 用户添加到 AD 组**
1. 在“服务器管理器”控制面板上，在 **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_cn/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_cn/athena/latest/ug/images/odbc-adfs-saml-31.png)
1. 选择**确定**。
在用户的 **Properties**（属性）对话框中，AD 组名称将在 **Member of**（隶属于）列表中显示。
![\[AD 组已添加到用户属性。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-adfs-saml-32.png)
1. 选择 **Apply**（应用），然后选择 **OK**（确定）。
## 4. 配置 AD FS ODBC 与 Athena 的连接
创建 AD 用户和组后，您就可以使用 Windows 中的 ODBC 数据来源程序为 AD FS 配置 Athena ODBC 连接。
**配置 AD FS ODBC 与 Athena 的连接**
1. 为 Athena 安装 ODBC 驱动程序。有关下载链接，请参阅 [通过 ODBC 连接到 Amazon Athena](connect-with-odbc.md)。
1. 在 Windows 中，依次选择 **Start**（开始）、**ODBC Data Sources**（ODBC 数据来源）。
1. 在 **ODBC 数据来源管理器**程序中，选择 **Add**（添加）。
![\[选择 Add（添加）以添加 ODBC 数据来源。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-adfs-saml-33.png)
1. 在 **Create New Data Source**（创建新数据来源）对话框中，选择 **Simba Athena ODBC 驱动程序**，然后选择 **Finish**（完成）。
![\[选择 Simba Athena ODBC Driver（Simba Athena ODBC 驱动程序）。\]](http://docs.aws.amazon.com/zh_cn/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_cn/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_cn/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_cn/athena/latest/ug/images/odbc-okta-plugin-1.png)
1. 在 **General Settings Required**（必填常规设置）部分中，对于 **Application label**（应用程序标注），输入应用程序的名称。本教程使用的名称是 **Athena-ODBC-Okta**。
![\[输入 Oktak 应用程序的名称。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-okta-plugin-2.png)
1. 选择**完成**。
1. 在 Okta 应用程序页面（例如，**Athena-ODBC-Okta**）上，选择 **Sign On**（登录）。
![\[选择 Sign On（登录）选项卡。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-okta-plugin-3.png)
1. 在 **Settings**（设置）部分中，选择 **Edit**（编辑）。
![\[选择编辑。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-okta-plugin-4.png)
1. 在 **Advanced Sign-on Settings**（高级登录设置）部分中，配置以下值。
+ 对于 **IdP ARN and Role ARN**（IdP ARN 和角色 ARN），输入您的 AWS IDP ARN 和角色 ARN，用逗号分隔。有关 IAM 角色格式的信息，请参阅《*IAM 用户指南*》中的[为身份验证响应配置 SAML 断言](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_saml_assertions.html)。
+ 对于 **Session Duration**（会话持续时间），输入一个介于 900 到 43200 秒之间的值。本教程使用的是默认值 3600（1 小时）。
![\[输入高级登录设置。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-okta-plugin-5.png)
Athena 不使用 **DbUser Format**（DbUser 格式）、**AutoCreate**（自动创建）和 **Allowed 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_cn/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_cn/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_cn/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_cn/athena/latest/ug/images/odbc-okta-plugin-9.png)
1. 为您的用户选择 **Assign**（分配）选项，然后选择 **Done**（完成）。
![\[选择 Assign（分配），然后选择 Done（完成）。\]](http://docs.aws.amazon.com/zh_cn/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. 选择**操作**。
1. 打开 **View IdP metadata**（查看 IdP 元数据）的上下文（右键单击），然后选择浏览器选项以保存文件。
1. 使用 `.xml` 扩展名保存文件。
![\[将 IdP 元数据保存到本地 XML 文件。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-okta-plugin-11.png)
## 创建一个 AWS SAML 身份提供者和角色
现在您可以在 AWS 中将元数据 XML 文件上传到 IAM 控制台。您将使用此文件来创建一个 AWSSAML 身份提供者和角色。使用 AWS 服务管理员帐户来执行这些步骤。
**在 AWS 中创建一个 SAML 身份提供者和角色**
1. 登录 AWS 管理控制台，然后通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/IAM/](https://console.aws.amazon.com/IAM/)。
1. 在导航窗格中，选择 **Identity providers**（身份提供程序），然后选择 **Add provider**（添加提供商）。
![\[选择添加提供程序。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-okta-plugin-12.png)
1. 在 **Add an Identity provider**（添加身份提供者）页面上，对于 **Configure provider**（配置提供者），输入以下信息。
+ 对于 **Provider type**（提供程序类型），选择 **SAML**。
+ 对于 **Provider name**（提供者名称），为您的提供者输入一个名称（例如 ** AthenaODBCOkta**）。
+ 对于 **Metadata document**（元数据文档），请使用 **Select file**（选择文件）选项上载您下载的身份提供程序 (IdP) 元数据 XML 文件。
![\[输入身份提供程序的信息。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-okta-plugin-13.png)
1. 选择**添加提供程序**。
### 创建一个用于访问 Athena 和 Amazon S3 的 IAM 角色
您现在可以创建一个用于访问 Athena 和 Amazon S3 的 IAM 角色。您需要将此角色分配给您的用户，从而可以为该用户提供对 Athena 的单点登录访问权限。
**为您的用户创建一个 IAM 角色**
1. 在 IAM 控制台的导航窗格中，选择 **Roles**（角色），然后选择 **Create role**（创建角色）。
![\[选择创建角色。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-okta-plugin-14.png)
1. 在 **Create role**（创建角色）页面上，选择以下选项：
+ 对于 **Select type of trusted entity**（选择受信任实体的类型），选择 **SAML 2.0 Federation**。
+ 对于 **SAML 2.0–based provider**（基于 SAML 2.0 的提供者），请选择您创建的 SAML 身份提供者（例如，**AthenaODBCOkta**）。
+ 选择 **Allow programmatic and AWS 管理控制台 access**（允许编程和访问）。
![\[选择 Create role（创建角色）页面上的选项。\]](http://docs.aws.amazon.com/zh_cn/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_cn/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 数据源管理器**程序中，选择 **Add**（添加）。
![\[选择添加。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-okta-plugin-17.png)
1. 选择 **Simba Athena ODBC 驱动程序**，然后选择 **Finish**（完成）。
![\[选择 Athena ODBC 驱动程序。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/odbc-okta-plugin-18.png)
1. 在 **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_cn/athena/latest/ug/images/odbc-okta-plugin-19.png)
1. 选择 **Authentication Options**（身份验证选项）。
1. 在 **Authentication Options**（身份验证选项）对话框中，选择或输入以下值。
+ 对于 **Authentication Type**（身份验证类型），选择 **Okta**。
+ 对于**用户**，请输入您的 Okta 用户名。
+ 对于**密码**，请输入您的 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_cn/athena/latest/ug/images/odbc-okta-plugin-20.png)
1. 选择**确定**。
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 或更高版本。支持浏览器 SAML 的1.1.13 及更高版本。有关下载链接，请参阅[使用 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.com` 上登录到 Okta 管理员页面。
1. 在导航窗格中，选择 **Application**（应用程序），**Application**（应用程序）。
1. 在 **Applications**（应用程序）页面上，选择 **Create App Integration**（创建应用程序集成）。
![\[选择 Create App Integration（创建应用程序集成）。\]](http://docs.aws.amazon.com/zh_cn/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_cn/athena/latest/ug/images/okta-saml-sso-2.png)
1. 在 **Create SAML Integration**（创建 SAML 集成）页面的 **General Settings**（常规设置）部分中，输入应用程序的名称。本教程使用名称 **SSO Athena**。
![\[输入 Oktak 应用程序的名称。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/okta-saml-sso-3.png)
1. 选择**下一步**。
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_cn/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**
对于**值**，请输入 **user.email**。
![\[输入 Athena 的 SAML 属性。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/okta-saml-sso-5.png)
1. 选择**下一步**，然后选择**完成**。
当 Okta 创建应用程序时，它还会创建您的登录 URL，接下来您将检索该 URL。
## 从 Okta 控制面板获取登录 URL
现在您的应用程序已经创建完毕，您可以从 Okta 控制面板获取其登录 URL 和其他元数据。
**从 Okta 控制面板获取登录 URL**
1. 在 Okta 导航窗格中，选择 **Application**（应用程序），**Application**（应用程序）。
1. 选择要查找登录 URL 的应用程序（例如，**AthenNasso**)。
1. 在应用程序页面上，选择 **Sign On**（登录）。
![\[选择 Sign On（登录）。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/okta-saml-sso-6.png)
1. 选择 **View Setup Instructions**（查看设置说明）。
![\[选择 View Setup Instructions（查看设置说明）。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/okta-saml-sso-7.png)
1. 在 **How to Configure SAML 2.0 for Athena SSO**（如何为 Athena SSO 配置 SAML 2.0）页面中，找到 **Identity Provider Issuer**（身份提供商发布者）的 URL。Okta 控制面板中的某些地方会将此 URL 称为 **SAML 发布者 ID**。
![\[Identity Provider Issuer（身份提供商发布者）的值。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/okta-saml-sso-8.png)
1. 复制或存储 **Identity Provider Single Sign-On URL**（身份提供商单点登录 URL）的值。
在下一节中，配置 ODBC 连接时，您将提供此值作为 SAML 浏览器插件的**登录 URL** 连接参数。
## 配置浏览器 SAML ODBC 与 Athena 的连接
现在，您可以在 Windows 中使用 ODBC 数据源程序配置浏览器 SAML 到 Athena 的连接。
**配置浏览器 SAML ODBC 到 Athena 的连接**
1. 在 Windows 中，启动 **ODBC 数据源**程序。
1. 在 **ODBC 数据源管理器**程序中，选择 **Add**（添加）。
![\[选择添加。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/okta-saml-sso-9.png)
1. 选择 **Simba Athena ODBC 驱动程序**，然后选择 **Finish**（完成）。
![\[选择 Simba Athena 驱动程序\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/okta-saml-sso-10.png)
1. 在 **SIMBA Athena ODBC 驱动程序 DSN 设置**对话框中，输入描述的值。
![\[输入 DSN 设置值。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/okta-saml-sso-11.png)
+ 在 **Data Source Name**（数据源名称）中，输入数据源的名称（例如，**64 Athena ODBC**）。
+ 在 **Description**（说明）中，为数据源输入说明。
+ 在 **AWS 区域** 中，输入您正在使用的 AWS 区域（例如 **us-west-1**）。
+ 在 **S3 Output Location**（S3 输出位置）中，输入要存储输出的 Amazon S3 路径。
1. 选择 **Authentication Options**（身份验证选项）。
1. 在 **Authentication Options**（身份验证选项）对话框中，选择或输入以下值。
![\[输入身份验证选项。\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/okta-saml-sso-12.png)
+ 在 **Authentication Type**（身份验证类型）中，选择 **BrowserSAML**。
+ 在 **Login URL**（登录 URL）中，输入您从 Okta 控制面板中获得的 **Identity Provider Single Sign-On URL**（身份提供商单点登录 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 服务和 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_cn/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)。
+ 对于 **Data Connectivity mode**（数据连接模式），选择适合您的使用案例的模式，并遵循以下常规指南：
+ 对于较小的数据集，请选择 **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_cn/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_cn/athena/latest/ug/images/connect-with-odbc-and-power-bi-3.png)
您的数据目录、数据库和表将显示在 **Navigator**（导航）对话框。
![\[导航将显示您的数据\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connect-with-odbc-and-power-bi-4.png)
1. 在 **Display Options**（显示选项）窗格中，为数据集选中要使用的复选框。
1. 如果要在导入数据集之前对其进行转换，请转到对话框底部，然后选择 **Transform Data**（转换数据）。这将打开 Power 查询编辑器，以便您筛选和优化要使用的数据集。
1. 选择 **Load**（加载）。加载完成后，您可以创建类似于以下图像中的可视化。如果您选择 **DirectQuery** 作为导入模式，Power BI 会向 Athena 发出查询，以用于您请求的可视化效果。
![\[示例数据可视化\]](http://docs.aws.amazon.com/zh_cn/athena/latest/ug/images/connect-with-odbc-and-power-bi-5.png)
## 设置本地部署网关
您可以将控制面板和数据集发布到 Power BI 服务，以便其他用户可以通过 Web、移动端和嵌入式应用与它们进行交互。若要在 Microsoft Power BI 服务中查看您的数据，请将 Microsoft Power BI 本地部署数据网关安装在 AWS 账户 中。该网关的职责类似于在 Microsoft Power BI 服务和 Athena 之间搭建桥梁。
**要下载、安装和测试本地部署数据网关**
1. 访问 [Microsoft Power BI 网关下载](https://powerbi.microsoft.com/en-us/gateway/)页面，然后选择个人模式或标准模式。个人模式对于在本地测试 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 网关以与 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 身份数据访问权限时，进行身份传播，以帮助您的组织满足监管和合规要求。
现在，您可以通过 IAM Identity Center 的单点登录功能，连接到使用 Java 数据库连接（JDBC）或开放式数据库连接（ODBC）驱动程序的 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 应用程序。有关更多信息，请参阅 [Customer Managed Application](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 实例。有关更多信息，请参阅 [What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/identity-center-instances.html)。
1. 您必须有一个有效的外部身份提供者，并且用户或组必须存在于 AWS IAM Identity Center 中。您可以手动配置用户或群组或使用 SCIM 自动配置用户或群组。有关更多信息，请参阅 [Provisioning an external identity provider into IAM Identity Center using SCIM](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. 要使用 JDBC 或 ODBC 驱动程序运行 Athena 查询，您必须有有效的 BI 工具或 SQL 客户端。
# 将 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。
复制 AWS IAM 身份提供者的应用程序资源名称（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 客户托管的应用程序
要配置客户管理型应用程序，请按照 [Set up customer managed OAuth 2.0 applications for trusted identity propagation](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)时，添加您在 IAM 应用程序角色设置期间复制的 AWS IAM 应用程序角色 ARN。
+ 对于**可以接收请求的应用程序**，选择 **AWS-Lake-Formation-AWS-Glue-Data-Catalog-**。
+ 对**要应用的访问范围**，选择 **lakeformation:query** 用于启用 IAM 的工作组，或者选择 **lakeformation:query**、**athena:workgroup:read\$1write** 和 **s3:access\$1grants:read\$1write** 用于启用 Identity Center 的工作组。
## 配置工作组关联
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. **Workgroup**：您要在其中运行查询的工作组。有关工作组的信息，请参阅 [WorkGroup](https://docs.aws.amazon.com/athena/latest/APIReference/API_WorkGroup.html)。
1. **Region**：将在其中运行查询的 AWS 区域。有关区域列表，请参阅 [Amazon Athena endpoints and quotas](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 Reference 中的 [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
1. **WorkgroupArn**：将在其中运行查询的工作组 ARN。它必须与 **Workgroup** 字段中提供的工作组一致。有关工作组的信息，请参阅 [WorkGroup](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 被重复用于令牌交换。有关更多信息，请参阅 [Prerequisites and considerations for trusted token issuers](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 logs](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)。要使用 JDBC 驱动程序，请参阅 [ODBC 身份验证插件连接参数](odbc-v2-driver-jwt-tip.md)。