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

# ODBC 2.x 驅動器入門
<a name="odbc-v2-driver-getting-started"></a>

使用本節中的資訊，開始使用 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
<a name="odbc-v2-driver-getting-started-windows"></a>

如果您想要使用 Windows 用戶端電腦存取 Amazon Athena，則需要 Amazon Athena ODBC 驅動器。

## Windows 系統要求
<a name="odbc-v2-driver-system-requirements-windows"></a>

在將直接存取 Amazon Athena 資料庫的用戶端電腦上安裝 Amazon Athena ODBC 驅動程式，而不是使用 Web 瀏覽器。

您使用的 Windows 系統必須符合下述要求：
+ 您擁有管理員權限
+ 下列其中一個操作系統：
  + Windows 11、10 或 8.1
  + Windows Server 2019、2016 或 2012
  + 支援的處理器架構：x86\$164 (64 位元)
+ 至少 100 MB 的可用磁碟空間
+ 已安裝 [Microsoft Visual C\$1\$1 Redistributable for Visual Studio](https://visualstudio.microsoft.com/downloads/#microsoft-visual-c-redistributable-for-visual-studio-2022)，適用於 Windows 64 位元。

## 安裝 Amazon Athena ODBC 驅動程式
<a name="odbc-v2-driver-installing"></a>

**若要下載並安裝適用於 Windows 的 Amazon Athena ODBC 驅動程式**

1. [下載](odbc-v2-driver.md#odbc-v2-driver-download) `AmazonAthenaODBC-2.x.x.x.msi` 安裝檔案。

1. 啟動安裝檔案，然後選擇**下一步**。

1. 若要接受授權協議條款，請選取核取方塊，然後選擇**下一步**。

1. 若要變更安裝位置，請選擇**瀏覽**，瀏覽至所需的資料夾，然後選擇**確定**。

1. 若要接受安裝位置，請選擇**下一步**。

1. 選擇 **Install (安裝)**。

1. 完成安裝時，請選擇**完成**。

## 設定驅動程式組態選項的方法
<a name="odbc-v2-driver-ways-to-set-options"></a>

若要控制 Windows 中 Amazon Athena ODBC 驅動程式的行為，您可以使用下列方式設定驅動程式組態選項：
+ 在 **ODBC 資料來源管理員**中設定資料來源名稱 (DSN) 時。
+ 透過在下列位置新增或變更 Windows 登錄機碼：

  ```
  HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\YOUR_DSN_NAME
  ```
+ 以程式設計方式連線時，在連線字串中設定驅動程式選項。

## 在 Windows 上設定資料來源名稱
<a name="odbc-v2-driver-configuring-dsn-on-windows"></a>

在下載並安裝 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 連線
<a name="odbc-v2-driver-dsn-less-connection"></a>

您可以使用無 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
<a name="odbc-v2-driver-getting-started-linux"></a>

如果您想要使用 Linux 用戶端電腦存取 Amazon Athena，則需要 Amazon Athena ODBC 驅動器。

## Linux 系統要求
<a name="odbc-v2-driver-getting-started-linux-linux-system-requirements"></a>

您安裝驅動器的每一台 Linux 電腦必須符合下列要求。
+ 您擁有根存取權。
+ 使用下列其中一個 Linux 發行版本：
  + Red Hat Enterprise Linux (RHEL) 7 或 8
  + CentOS 7 或 8。
+ 有 100 MB 的可用磁碟空間。
+ 使用 [unixODBC](https://www.unixodbc.org/) 版本 2.3.1 或更新版本。
+ 使用 [GNU C Library](https://www.gnu.org/software/libc/) (glibc) 版本 2.26 或更新版本。

## 在 Linux 上安裝 ODBC 資料連接器
<a name="odbc-v2-driver-getting-started-linux-installing-the-odbc-data-connector-on-linux"></a>

使用下列程序來在 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 上設定資料來源名稱
<a name="odbc-v2-driver-getting-started-linux-configuring-a-data-source-name-on-linux"></a>

安裝驅動器後，您可以在下列位置中找到 `.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 驅動器簽章
<a name="verify-odbc-linux-signature"></a>

**重要**  
我們建議您先驗證 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
<a name="odbc-v2-driver-getting-started-macos"></a>

如果您想要使用 macOS 用戶端電腦存取 Amazon Athena，則需要 Amazon Athena ODBC 驅動器。

## macOS 系統要求
<a name="odbc-v2-driver-getting-started-macos-macos-system-requirements"></a>

您安裝驅動器的每一台 macOS 電腦必須符合下列要求。
+ 使用 macOS 版本 14 或更新版本。
+ 有 100 MB 的可用磁碟空間。
+ 使用 [iODBC](https://www.iodbc.org/dataspace/doc/iodbc/wiki/iodbcWiki/WelcomeVisitors) 版本 3.52.16 或更新版本。

## 在 macOS 上安裝 ODBC 資料連接器
<a name="odbc-v2-driver-getting-started-macos-installing-the-odbc-data-connector-on-macos"></a>

使用下列程序來下載並安裝適用於 macOS 作業系統的 Amazon Athena ODBC 驅動器。

**下載並安裝適用於 macOS 的 Amazon Athena ODBC 驅動器**

1. 下載 `.pkg` 套件檔案。

1. 按兩下 `.pkg` 檔案。

1. 請遵循精靈中的步驟安裝驅動器。

1. 在**授權合約**頁面上，按下**繼續**，然後選擇**同意**。

1. 選擇 **Install (安裝)**。

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 上設定資料來源名稱
<a name="odbc-v2-driver-getting-started-macos-configuring-a-data-source-name-on-macos"></a>

安裝驅動器後，您可以在下列位置中找到 `.odbc.ini` 和 `.odbcinst.ini` 檔案的範例：
+ Intel 處理器電腦：`/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` 檔案的完整路徑和檔案名稱。
   + 對於具有 Intel 處理器的 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` 檔案的完整路徑和檔案名稱。
   + 對於具有 Intel 處理器的 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>
   ```