本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# ODBC
ODBC

的开源 [ODBC 驱动程序](https://github.com/awslabs/aws-iotsitewise-odbc-driver)为开发人员 Amazon IoT SiteWise 提供了 SQL 关系接口，并支持从 Power BI Desktop 和 Microsoft Excel 等商业智能 (BI) 工具进行连接。 Amazon IoT SiteWise Amazon IoT SiteWise ODBC 驱动程序目前在 [Windows](https://github.com/awslabs/aws-iotsitewise-odbc-driver/releases) 上可用，支持 Okta 的 SSO 和微软 Azure Active Directory (AD)。

有关更多信息，请参阅[上的Amazon IoT SiteWise ODBC 驱动程序文档。 GitHub](https://github.com/awslabs/aws-iotsitewise-odbc-driver/blob/main/docs/markdown/index.md)

**Topics**
+ [

# ODBC 驱动程序的连接字符串语法及选项
](query-ODBC-connecting.md)
+ [

# Amazon IoT SiteWise ODBC 驱动程序的连接字符串示例
](query-ODBC-connecting-examples.md)
+ [

# 对 ODBC 驱动程序连接进行故障排除
](query-ODBC-connecting-troubleshooting.md)

# ODBC 驱动程序的连接字符串语法及选项
连接字符串语法

用于指定 ODBC 驱动程序连接字符串选项的语法如下：

```
Driver={Amazon IoT SiteWise ODBC Driver};(option)=(value);
```

可用选项如下：

**驱动程序连接选项**
+ **`Driver`**   *（必填）*：与 ODBC 结合使用的驱动程序。

  默认值为 Amazon IoT SiteWise。
+ **`DSN`**：用于配置连接的数据来源名称（DSN）。

  默认值为 `NONE`。
+ **`Auth`**：身份验证模式。其必须是以下内容之一：
  + `Amazon_PROFILE`：使用默认凭证链。
  + `IAM`— 使用 Amazon IAM 证书。
  + `AAD`：使用 Azure Active Directory（AD）身份提供商。
  + `OKTA`：使用 Okta 身份提供商。

  默认值为 `Amazon_PROFILE`。

**端点配置选项**
+ **`EndpointOverride`**— Amazon IoT SiteWise 服务的终端节点覆盖。这是用于覆盖区域的高级选项。例如：

  ```
  iotsitewise.us-east-1.amazonaws.com
  ```
+ **`Region`**— Amazon IoT SiteWise 服务终端节点的签名区域。

  默认值为 `us-east-1`。

**凭证提供程序选项**
+ **`ProfileName`**— 配置文件中的 Amazon 配置文件名称。

  默认值为 `NONE`。

**Amazon IAM 身份验证选项**
+ **`UID`**或 **`AccessKeyId`**- Amazon 用户访问密钥 ID。如果连接字符串中同时提供 `UID` 和 `AccessKeyId`，则将使用 `UID` 值，除非该值为空。

  默认值为 `NONE`。
+ **`PWD`** 或 **`SecretKey`**：AWS 用户秘密访问密钥。如果连接字符串中同时提供 `PWD` 和 `SecretKey`，则将使用带 的 `PWD` 值，除非该值为空。

  默认值为 `NONE`。
+ **`SessionToken`**：访问已启用多重身份验证（MFA）的数据库所需的临时会话令牌。请勿在输入中包含尾随 ` = `。

  默认值为 `NONE`。

**适用于 Okta 的基于 SAML 的身份验证选项**
+ **`IdPHost`**：指定 IdP 的主机名。

  默认值为 `NONE`。
+ **`UID`** 或 **`IdPUserName`**：指定 IdP 账户的用户名。如果连接字符串中同时提供 `UID` 和 `IdPUserName`，则将使用 `UID` 值，除非该值为空。

  默认值为 `NONE`。
+ **`PWD`** 或 **`IdPPassword`**：指定 IdP 账户的密码。如果连接字符串中同时提供 `PWD` 和 `IdPPassword`，则将使用 `PWD` 值，除非该值为空。

  默认值为 `NONE`。
+ **`OktaApplicationID`**— Okta 提供的与应用程序关联的唯一 ID。 Amazon IoT SiteWise 在应用程序元数据中提供的`entityID`字段中可以找到应用程序 ID (AppId)。例如：

  ```
  entityID="http://www.okta.com//(IdPAppID)
  ```

  默认值为 `NONE`。
+ **`RoleARN`**：调用方所代入角色的 Amazon 资源名称（ARN）。

  默认值为 `NONE`。
+ **`IdPARN`**：描述 IdP 的 IAM 中 SAML 提供商的 Amazon 资源名称（ARN）。

  默认值为 `NONE`。

**适用于 Azure Active Directory 的基于 SAML 的身份验证选项**
+ **`UID`** 或 **`IdPUserName`**：指定 IdP 账户的用户名。

  默认值为 `NONE`。
+ **`PWD`** 或 **`IdPPassword`**：指定 IdP 账户的密码。

  默认值为 `NONE`。
+ **`AADApplicationID`**：Azure AD 上已注册应用程序的唯一 ID。

  默认值为 `NONE`。
+ **`AADClientSecret`**：与 Azure AD 上已注册应用程序关联的客户端密钥，用于授权获取令牌。

  默认值为 `NONE`。
+ **`AADTenant`**：Azure AD 租户 ID。

  默认值为 `NONE`。
+ **`RoleARN`**：调用方所代入角色的 Amazon 资源名称（ARN）。

  默认值为 `NONE`。
+ **`IdPARN`**：描述 IdP 的 IAM 中 SAML 提供商的 Amazon 资源名称（ARN）。

  默认值为 `NONE`。

**Amazon SDK（高级）选项**
+ **`RequestTimeout`**— Amazon SDK 在超时之前等待查询请求的时间（以毫秒为单位）。任何非正值都表示禁用请求超时。

  默认值为 `3000`。
+ **`ConnectionTimeout`**— Amazon SDK 在超时之前等待通过打开的连接传输数据的时间（以毫秒为单位）。值为 0 时，将禁用连接超时。该值不得为负。

  默认值为 `1000`。
+ **`MaxRetryCountClient`**：SDK 中可重试错误（错误代码为 5xx）的最大重试次数。值不得为负。

  默认值为 `0`。
+ **`MaxConnections`**— 允许与该 Amazon IoT SiteWise 服务同时打开的 HTTP 连接的最大数量。值必须为正。

  默认值为 `25`。

**ODBC 驱动程序日志记录选项**
+ **`LogLevel`**：驱动程序日志记录的日志级别。必须为以下值之一：
  + **0**：（关闭）。
  + **1**：（错误）。
  + **2**：（警告）。
  + **3**：（信息）。
  + **4**：（调试）。

  默认为 `1`（错误）。

  **警告：**使用调试日志记录模式时，驱动程序可能会记录个人信息。
+ **`LogOutput`**：用于存储日志文件的文件夹。

  默认为：
  + **Windows：**`%USERPROFILE%`，或者如果不可用，则为 `%HOMEDRIVE%%HOMEPATH%`。
  + **macOS 和 Linux：**`$HOME`，或者如果不可用，则函数 `getpwuid(getuid())` 中的字段 `pw_dir` 返回值。

**SDK 日志记录选项**

S Amazon DK 日志级别与 Amazon IoT SiteWise ODBC 驱动程序日志级别是分开的。设置其中一个不会影响另一个。

SDK 日志级别使用环境变量 `SW_AWS_LOG_LEVEL` 进行设置。有效值为：
+ `OFF`
+ `ERROR`
+ `WARN`
+ `INFO`
+ `DEBUG`
+ `TRACE`
+ `FATAL`

如果未设置 `SW_AWS_LOG_LEVEL`，则将 SDK 日志级别设置为默认值，即 `WARN`。

## 通过代理进行连接
代理连接

ODBC 驱动程序支持 Amazon IoT SiteWise 通过代理进行连接。要使用此功能，请根据代理设置配置以下环境变量：
+ **`SW_PROXY_HOST`**：代理主机。
+ **`SW_PROXY_PORT`**：代理端口号。
+ **`SW_PROXY_SCHEME`**：代理方案，`http` 或 `https`。
+ **`SW_PROXY_USER`**：代理身份验证的用户名。
+ **`SW_PROXY_PASSWORD`**：代理身份验证的用户密码。
+ **`SW_PROXY_SSL_CERT_PATH`**：用于连接到 HTTPS 代理的 SSL 证书文件。
+ **`SW_PROXY_SSL_CERT_TYPE`**：代理客户端 SSL 证书的类型。
+ **`SW_PROXY_SSL_KEY_PATH`**：用于连接到 HTTPS 代理的私钥文件。
+ **`SW_PROXY_SSL_KEY_TYPE`**：用于连接到 HTTPS 代理的私钥文件类型。
+ **`SW_PROXY_SSL_KEY_PASSWORD`**：用于连接到 HTTPS 代理的私钥文件密码。

# Amazon IoT SiteWise ODBC 驱动程序的连接字符串示例
连接字符串示例

## 使用 IAM 凭证连接到 ODBC 驱动程序的示例
使用 IAM 凭证连接

```
Driver={Amazon IoT SiteWise ODBC Driver};Auth=IAM;AccessKeyId=(your access key ID);SecretKey=(your secret key);SessionToken=(your session token);Region=us-east-1;
```

## 使用配置文件连接到 ODBC 驱动程序的示例
使用配置文件连接

```
Driver={Amazon IoT SiteWise ODBC Driver};ProfileName=(the profile name);region=us-east-1;
```

驱动程序将尝试使用 `~/.aws/credentials` 中提供的凭证进行连接，或者如果在环境变量 `Amazon_SHARED_CREDENTIALS_FILE` 中指定文件，则使用该文件中的凭证进行连接。

## 使用 Okta 连接到 ODBC 驱动程序的示例
使用 Okta 连接

```
Driver={Amazon IoT SiteWise ODBC Driver};Auth=OKTA;region=us-east-1;idPHost=(your host at Okta);idPUsername=(your user name);idPPassword=(your password);OktaApplicationID=(your Okta AppId);roleARN=(your role ARN);idPARN=(your Idp ARN);
```

## 使用 Azure Active Directory（AAD）连接到 ODBC 驱动程序的示例
使用 AAD 连接

```
Driver={Amazon IoT SiteWise ODBC Driver};Auth=AAD;region=us-east-1;idPUsername=(your user name);idPPassword=(your password);aadApplicationID=(your AAD AppId);aadClientSecret=(your AAD client secret);aadTenant=(your AAD tenant);roleARN=(your role ARN);idPARN=(your idP ARN);
```

## 使用指定端点和日志级别 2（警告）连接到 ODBC 驱动程序的示例
连接到端点

```
Driver={Amazon IoT SiteWise ODBC Driver};Auth=IAM;AccessKeyId=(your access key ID);SecretKey=(your secret key);EndpointOverride=iotsitewise.us-east-1.amazonaws.com;Region=us-east-1;LogLevel=2;
```

# 对 ODBC 驱动程序连接进行故障排除
问题排查

**注意**  
如果已在 DSN 中指定了用户名和密码，则在 ODBC 驱动程序管理器要求提供用户名和密码时，不要再次指定它们。

当连接字符串中多次传递连接字符串选项时，就会出现错误代码 `01S02` 并显示消息 `Re-writing (connection string option) (have you specified it several times?)`。多次指定同一选项将引发错误。使用 DSN 和连接字符串建立连接时，如果已在 DSN 中指定连接选项，则无需在连接字符串中再次指定。