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

# JDBC 3.x 驅動器入門
<a name="jdbc-v3-driver-getting-started"></a>

使用本節中的資訊，開始使用 Amazon Athena JDBC 3.x 驅動程式。

**Topics**
+ [安裝說明](#jdbc-v3-driver-installation-instructions)
+ [執行驅動程式](#jdbc-v3-driver-running-the-driver)
+ [設定驅動程式](#jdbc-v3-driver-configuring-the-driver)
+ [從 Athena JDBC v2 驅動程式升級](#jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3)

## 安裝說明
<a name="jdbc-v3-driver-installation-instructions"></a>

您可以在自訂應用程式或第三方 SQL 用戶端中，使用 JDBC 3.x 驅動程式。

### 在自訂應用程式中
<a name="jdbc-v3-driver-installation-in-a-custom-application"></a>

下載包含驅動程式 jar 及其相依性的 `.zip` 檔案。每個相依性都有自己的 `.jar` 檔案。在自訂應用程式中新增驅動程式 jar 作為相依性。根據您是否已經從另一個來源新增這些相依性至應用程式中，選擇性地新增驅動程式 jar 的相依性。

### 在第三方 SQL 用戶端中
<a name="jdbc-v3-driver-installation-in-a-third-party-sql-client"></a>

下載驅動程式 uber jar 檔案，並依照該用戶端的指示將其新增至第三方 SQL 用戶端。

## 執行驅動程式
<a name="jdbc-v3-driver-running-the-driver"></a>

若要執行驅動程式，您可以使用自訂應用程式或第三方 SQL 用戶端。

### 在自訂應用程式中
<a name="jdbc-v3-driver-running-in-a-custom-application"></a>

使用 JDBC 介面與程式的 JDBC 驅動程式進行互動。下列程式碼顯示了一個自訂 Java 應用程式範例。

```
public static void main(String args[]) throws SQLException {
    Properties connectionParameters = new Properties();
    connectionParameters.setProperty("Workgroup", "primary");
    connectionParameters.setProperty("Region", "us-east-2");
    connectionParameters.setProperty("Catalog", "AwsDataCatalog");
    connectionParameters.setProperty("Database","sampledatabase");
    connectionParameters.setProperty("OutputLocation","s3://amzn-s3-demo-bucket");
    connectionParameters.setProperty("CredentialsProvider","DefaultChain");
    String url = "jdbc:athena://";
    AthenaDriver driver = new AthenaDriver();
    Connection connection = driver.connect(url, connectionParameters);
    Statement statement = connection.createStatement();
    String query = "SELECT * from sample_table LIMIT 10";
    ResultSet resultSet = statement.executeQuery(query);
    printResults(resultSet); // A custom-defined method for iterating over a
                             // result set and printing its contents
}
```

### 在第三方 SQL 用戶端中
<a name="jdbc-v3-driver-running-in-a-third-party-sql-client"></a>

遵循您所使用之 SQL 用戶端的文件。一般而言，您可以使用 SQL 用戶端的圖形化使用者介面來輸入及提交查詢，而查詢結果會顯示在相同的介面中。

## 設定驅動程式
<a name="jdbc-v3-driver-configuring-the-driver"></a>

您可以使用連線參數來設定 Amazon Athena JDBC 驅動程式。如需支援的連線參數，請參閱 [Amazon Athena JDBC 3.x 連線參數](jdbc-v3-driver-connection-parameters.md)。

### 在自訂應用程式中
<a name="jdbc-v3-driver-configuring-in-a-custom-application"></a>

若要在自訂應用程式中設定 JDBC 驅動程式的連線參數，請執行下列其中一個動作：
+ 將參數名稱及其值新增至 `Properties` 物件。當您呼叫 `Connection#connect` 時，將該物件與 URL 一起傳遞。如需範例，請參閱 [執行驅動程式](#jdbc-v3-driver-running-the-driver) 中的 Java 範例應用程式。
+ 在連線字串 (URL) 中，使用下列格式將參數名稱及其值直接新增至通訊協定字首之後。

  ```
  {{<parameterName>}}={{<parameterValue>}};
  ```

  在每個參數名稱/參數值配對的末尾使用分號，分號後不留空格，如下列範例所示。

  ```
  String url = "jdbc:athena://WorkGroup=primary;Region=us-east-1;...;";AthenaDriver driver = new AthenaDriver();Connection connection = driver.connect(url, null);
  ```
**注意**  
如果在連線字串和 `Properties` 物件中同時指定參數，則連線字串中的值優先。不建議在兩個位置指定相同的參數。
+ 將參數值作為引數新增至 `AthenaDataSource` 的方法，如下列範例所示。

  ```
  AthenaDataSource dataSource = new AthenaDataSource();
      dataSource.setWorkGroup("primary");
      dataSource.setRegion("us-east-2");
      ...
      Connection connection = dataSource.getConnection();
      ...
  ```

### 在第三方 SQL 用戶端中
<a name="jdbc-v3-driver-configuring-in-a-third-party-sql-client"></a>

依照您所使用之 SQL 用戶端的指示進行。通常，用戶端會提供圖形化使用者介面來輸入參數名稱及其值。

## 從 Athena JDBC v2 驅動程式升級
<a name="jdbc-v3-driver-upgrading-from-the-athena-jdbc-v2-driver-to-v3"></a>

大多數 JDBC 第 3 版驅動器連線參數都與 JDBC 驅動器第 2 版 (Simba) 回溯相容。這意味著第 2 版連線字串可以與第 3 版驅動程式重複使用。但是，某些連線參數已更改。此處會有這些變更的相關說明。如有必要，當您升級至 JDBC 驅動器第 3 版時，請更新現有的組態。

### 驅動程式類別
<a name="jdbc-v3-driver-upgrading-driver-class"></a>

有些 BI 工具會要求您從 JDBC 驅動程式 `.jar` 檔案提供驅動程式類別。大多數工具都會自動尋找這個類別。第 3 版驅動程式中完全合格的類別名稱為 `com.amazon.athena.jdbc.AthenaDriver`。在第 2 版驅動程式中，該類別為 `com.simba.athena.jdbc.Driver`。

### 連接字串
<a name="jdbc-v3-driver-upgrading-connection-string"></a>

第 3 版驅動器將 `jdbc:athena://` 用於 JDBC 連線字串 URL 開頭的通訊協定。第 3 版驅動器還支援第 2 版通訊協定 `jdbc:awsathena://`，但第 2 版通訊協定已廢除。為了避免出現未定義的行為，如果第 2 版 (或接受以 `jdbc:awsathena://` 為開頭的連線字串的任何其他驅動器) 已向 [DriverManager](https://docs.oracle.com/javase/8/docs/api/java/sql/DriverManager.html) 類別註冊，則第 3 版不接受以 `jdbc:awsathena://` 為開頭的連線字串。

### 憑證提供者
<a name="jdbc-v3-driver-upgrading-credentials-providers"></a>

第 2 版驅動程式會使用完全合格的名稱來辨識不同的憑證提供者 (例如 `com.simba.athena.amazonaws.auth.DefaultAWSCredentialsProviderChain`)。第 3 版驅動程式則使用較短的名稱 (例如 `DefaultChain`)。新名稱會在每個憑證提供者的對應章節中說明。

為第 2 版驅動程式編寫的自訂憑證提供者需要修改第 3 版驅動程式，才能從新的 實作 [AwsCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/AwsCredentialsProvider.html) 介面， 適用於 Java 的 AWS SDK 而不是從先前的 [AWSCredentialsProvider](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html) 介面 適用於 Java 的 AWS SDK。

JDBC 3.x 驅動器不支援 `PropertiesFileCredentialsProvider`。提供者已在 JDBC 2.x 驅動程式中使用，但屬於舊版的適用於 Java 的 AWS SDK，即將終止支援。若要在 JDBC 3.x 驅動器中實現相同的功能，請改用 [AWS 組態設定檔登入資料](jdbc-v3-driver-aws-configuration-profile-credentials.md) 提供者。

### 日誌層級
<a name="jdbc-v3-driver-upgrading-log-level"></a>

下表顯示 JDBC 第 2 版和第 3 版驅動程式中的 `LogLevel` 參數差異。


****  

| JDBC 驅動程式版本 | 參數名稱 | 參數類型 | 預設值 | 可能的值 | 連線字串範例 | 
| --- | --- | --- | --- | --- | --- | 
|   v2 | LogLevel | 選用 | 0 | 0-6 | LogLevel=6; | 
| v3 | LogLevel | 選用 | TRACE | OFF、ERROR、WARN、INFO、DEBUG、TRACE | LogLevel=INFO; | 

### 查詢 ID 擷取
<a name="jdbc-v3-driver-upgrading-query-id-retrieval"></a>

在第 2 版驅動程式中，您可以將 `Statement` 執行個體取消包裝至 `com.interfaces.core.IStatementQueryInfoProvider`，一個具有兩種方法 `#getPReparedQueryId` 和 `#getQueryId` 的介面。您可以使用這些方法來取得已執行之查詢的查詢執行 ID。

在第 3 版驅動程式中，您可以將 `Statement`、`PreparedStatement` 和 `ResultSet` 執行個體取消包裝至 `com.amazon.athena.jdbc.AthenaResultSet` 介面。該介面有一種方法：`#getQueryExecutionId`。