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

# 使用 MongoDB Java 驅動程式連線至 Amazon DocumentDB MongoDB
<a name="java-pg-connect-mongo-driver"></a>

本節提供使用 Java 驅動程式連線至 Amazon DocumentDB step-by-step指南。這將協助您開始將 DocumentDB 整合到您的 Java 應用程式。

**Topics**
+ [步驟 1：設定您的 專案](#step1-set-up)
+ [步驟 2：建立連線字串](#step2-create-connection-string)
+ [步驟 3：撰寫連線程式碼](#step3-write-connect-code)
+ [步驟 4：處理連線例外狀況](#step4-handle-connect-exceptions)
+ [步驟 5：執行程式碼](#step5-running-code)
+ [連線最佳實務](#java-connect-best-practices)

## 步驟 1：設定您的 專案
<a name="step1-set-up"></a>

1. 使用 Maven 建立 Java 專案：

   ```
   mvn archetype:generate -DgroupId=com.docdb.guide -DartifactId=my-docdb-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
   ```

1. 新增 MongoDB Java 驅動程式做為「pom.xml」檔案中專案的相依性：

   ```
   <dependency>
       <groupId>org.mongodb</groupId>
       <artifactId>mongodb-driver-sync</artifactId> 
       <version>5.3.0</version> 
   </dependency>
   ```

## 步驟 2：建立連線字串
<a name="step2-create-connection-string"></a>

Amazon DocumentDB 連線字串對於在您的應用程式與 DocumentDB 叢集之間建立連線至關重要。此字串會封裝重要資訊，例如叢集端點、連接埠、身分驗證詳細資訊和各種連線選項。若要建置 DocumentDB 連線字串，您通常會以基本格式開頭：

```
"mongodb://{{username}}:{{password}}@cluster-endpoint:port/?[connection options]"
```

您需要將 "username" 和 "password" 取代為實際的登入資料。您可以在 以及透過 找到叢集的端點 AWS 管理主控台 和連接埠號碼 AWS CLI。請參閱 [尋找叢集的端點](db-cluster-endpoints-find.md) 尋找叢集的叢集端點。DocumentDB 的預設連接埠為 27017。

**連線字串範例**
+ 使用傳輸中的加密與 DocumentDB 建立連線，並確保讀取請求移至僅供讀取複本並寫入主要複本：

  ```
  "mongodb://username:password@cluster-endpoint:27017/?tls=true& 
     tlsCAFile=global-bundle.pem& 
     readPreference=secondaryPreferred&
     retryWrites=false"
  ```
+ 使用 IAM 身分驗證與 DocumentDB 建立連線：

  ```
  "mongodb://cluster-endpoint:27017/?tls=true& 
     tlsCAFile=global-bundle.pem& 
     readPreference=secondaryPreferred&
     retryWrites=false&
     authSource=%24external&
     authMechanism=MONGODB-AWS"
  ```

連線字串可用的不同選項如下：
+ [TLS 憑證](#connection-string-tls)
+ [從僅供讀取複本讀取](#connection-string-read-rep)
+ [撰寫疑慮和日誌](#connection-string-write-journal)
+ [RetryWrites](#connection-string-retry-writes)
+ [IAM 身分驗證](#connection-string-iam-auth)
+ [連線集區](#connection-string-pool)
+ [連線逾時參數](#connection-string-timeout)

### TLS 憑證
<a name="connection-string-tls"></a>

**`tls=true|false`** — 此選項啟用或停用 Transport Layer Security (TLS)。根據預設，Amazon DocumentDB 叢集上會啟用傳輸中加密，因此，除非在叢集層級停用 TLS，否則此選項的值應為 `true`。

使用 TLS 時，程式碼需要在建立 DocumentDB 叢集的連線時提供 SSL 憑證。下載與叢集進行安全連線所需的憑證：[https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem)。有兩種方式可以使用 `global-bundle.pem` 檔案。
+ **選項 1** — 從 `global-bundle.pem` 檔案擷取所有憑證，並使用 Java 的 keytool 將它們存放在`.jks`檔案，之後可在程式碼中使用。請參閱 中的 Java 索引標籤，[使用已啟用的 TLS 連線](connect_programmatically.md#connect_programmatically-tls_enabled)以取得示範如何執行此操作的指令碼。
+ **選項 2** — 在程式碼中動態新增 `global-bundle.pem` 檔案、建置記憶體內金鑰存放區，並使用 `SSLContext`提供憑證做為建立連線的一部分。

### 從僅供讀取複本讀取
<a name="connection-string-read-rep"></a>

**`replicaSet=rs0&readPreference=secondaryPreferred`** — 指定這兩個選項會將所有讀取請求路由至僅供讀取複本，並將請求寫入主要執行個體。在連線字串`replicaSet=rs0`中使用 可讓 MongoDB 驅動程式維護自動更新的叢集拓撲檢視，允許應用程式在新增或移除執行個體時維持目前節點組態的可見性。不提供這些選項或指定 會將`readPreference=primary`所有讀取和寫入傳送到主要執行個體。如需 的更多選項`readPreference`，請參閱 [讀取偏好設定選項](how-it-works.md#durability-consistency-isolation)。

### 撰寫疑慮和日誌
<a name="connection-string-write-journal"></a>

寫入考量會決定從資料庫請求寫入操作的確認層級。MongoDB 驅動程式提供調整寫入考量和日誌檔案的選項。Amazon DocumentDB 不預期您設定寫入考量和日誌，並忽略針對 `w`和 `j`(`writeConcern` 和 ) 傳送的值`journal`。DocumentDB 一律使用 `writeConcern`： `majority`和 `journal`： 寫入資料，`true`因此在將確認傳送給用戶端之前，會在大多數節點上持久記錄寫入。

### RetryWrites
<a name="connection-string-retry-writes"></a>

**`retryWrites=false`** — DocumentDB 不支援可重試的寫入，因此此屬性應一律設定為 `false`。

### IAM 身分驗證
<a name="connection-string-iam-auth"></a>

**`authSource=%24external` 和 `authMechanism=MONGODB-AWS`** — 這兩個參數用於使用 進行身分驗證 AWS Identity and Access Management。IAM 身分驗證目前僅適用於執行個體型叢集 5.0 版。如需詳細資訊，請參閱[使用 IAM 身分進行身分驗證](iam-identity-auth.md)。

### 連線集區
<a name="connection-string-pool"></a>

這些選項可用於連線集區：
+ **`maxPoolSize`** — 設定可在集區中建立的連線數目上限。當所有連線都在使用中，並且有新的請求進來時，它會等待連線變成可用。MongoDB Java 驅動程式的預設值為 100。
+ **`minPoolSize`** — 表示應隨時在集區中維護的連線數下限。MongoDB Java 驅動程式的預設值為 0。
+ **`maxIdleTimeMS`** — 決定在關閉和移除連線之前，連線可以在集區中保持閒置的時間長度。MongoDB Java 驅動程式的預設值為 100 毫秒。
+ **`waitQueueTimeoutMS`** — 設定當集區達到其大小上限時，執行緒應等待連線可用的時間長度。如果連線在此期間內無法使用，則會擲回例外狀況。MongoDB Java 驅動程式的預設值為 120，000 毫秒 (2 分鐘）。

### 連線逾時參數
<a name="connection-string-timeout"></a>

逾時是一種機制，可限制操作或連線嘗試在被視為失敗之前可能需要的時間。下列逾時參數可用於防止無限期等待和管理資源配置：
+ **`connectTimeoutMS`** — 設定驅動程式等待建立叢集連線的時間長度。預設值為 10，000 毫秒 (10 秒）。
+ **`socketTimeoutMS`** — 指定驅動程式等待伺服器回應進行非寫入操作的時間長度。預設值為 0， （無逾時或無限）。
+ **`serverSelectionTimeoutMS`** — 指定驅動程式在叢集中尋找可用伺服器的等待時間。此設定的預設值為 30 秒，足以在容錯移轉期間選擇新的主要執行個體。

## 步驟 3：撰寫連線程式碼
<a name="step3-write-connect-code"></a>

下列程式碼範例示範如何與 Amazon DocumentDB 建立 TLS 連線：
+ 它會建立 Java 和 [https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html) [`SSLContext`>](https://docs.oracle.com/javase/8/docs/api/javax/net/ssl/SSLContext.html) 物件。
+ 它也會透過將[https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html)物件傳遞至物件來建立[https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html)物件。若要進行 TLS 連線，您必須使用 `MongoClientSettings` 物件來繫結 `connectionstring`和 `sslcontext`。
+ 使用 [https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClients.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClients.html)取得[https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html)物件。

```
public static MongoClient makeDbConnection(String dbName, String DbUserName, String DbPassword,
    String DbClusterEndPoint, String keyStorePass) throws Exception {
    MongoClient connectedClient;
    String connectionOptions = "?replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false";
    String connectionUrl = "mongodb://" + DbUserName + ":" + DbPassword + "@" + DbClusterEndPoint + ":27017/" +
        dbName + connectionOptions;

    try {
        KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType());
        try (FileInputStream fis = new FileInputStream("src/main/resources/certs/truststore.jks")) {
            trustStore.load(fis, keyStorePass.toCharArray());
            TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
            tmf.init(trustStore);

            SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
            sslContext.init(null, tmf.getTrustManagers(), new SecureRandom());
            ConnectionString connectionString = new ConnectionString(connectionUrl);
            MongoClientSettings settings = MongoClientSettings.builder()
                .applyConnectionString(connectionString)
                .applyToSslSettings(builder - > {
                    builder.enabled(true);
                    builder.context(sslContext);
                })
                .build();
            connectedClient = MongoClients.create(settings);
        }
        return connectedClient;
    } catch (MongoException e5) {
        throw new RuntimeException(e5);
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}
```

## 步驟 4：處理連線例外狀況
<a name="step4-handle-connect-exceptions"></a>

在 Java 應用程式中使用 DocumentDB 時，處理連線例外狀況對於維護強大且可靠的資料庫操作至關重要。適當地管理這些例外狀況不僅有助於快速診斷問題，還可確保您的應用程式可以正常地處理暫時網路中斷或伺服器無法使用，進而改善穩定性和使用者體驗。與建立連線相關的一些重要例外狀況包括：
+ **`MongoException`** — 一般例外狀況，可在更具體例外狀況未涵蓋的各種情況下發出。確定在所有其他特定例外狀況之後處理此例外狀況，因為這是一般擷取所有 MongoDB 例外狀況。
+ **`MongoTimeoutException`** — 操作逾時時發出。例如，查詢不存在的叢集端點。
+ **`MongoSocketException`** — 針對網路相關問題發行。例如，在 操作期間突然中斷網路連線。
+ **`MongoSecurityException`** — 身分驗證失敗時發出。例如，使用不正確的登入資料進行連線。
+ **`MongoConfigurationException`** — 用戶端組態發生錯誤時發出。例如，使用無效的連線字串。

## 步驟 5：執行程式碼
<a name="step5-running-code"></a>

下列程式碼範例會建立 Amazon DocumentDB 連線並列印所有資料庫：

```
public static void TestConnection() {
    try (MongoClient mongoClient = makeDbConnection(DATABASE_NAME, DB_USER_NAME, DB_PASSWORD, DB_CLUSTER_ENDPOINT, KEYSTORE_PASSWORD)) {
        List < String > databases = mongoClient.listDatabaseNames().into(new ArrayList < > ());
        System.out.println("Databases: " + databases);
    } catch (MongoException e) {
        System.err.println("MongoDB error: " + e.getMessage());
        throw new RuntimeException(e);
    }
}
```

## 連線最佳實務
<a name="java-connect-best-practices"></a>

以下是使用 MongoDB Java 驅動程式連線至 Amazon DocumentDB 時應考慮的最佳實務：
+ 當您不再需要用戶端釋出資源[https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html)時，請務必關閉您的 。
+ 適當地處理例外狀況並實作適當的錯誤記錄。
+ 使用環境變數或 AWS Secrets Manager 來存放敏感資訊，例如使用者名稱和密碼。