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