在這個快速入門中，你會用 Java 建立一個基本的 Azure DocumentDB 應用程式。 Azure DocumentDB 是一個 NoSQL 資料儲存庫，允許應用程式將文件儲存在雲端，並透過官方 MongoDB 驅動程式存取。 本指南說明如何在 Azure DocumentDB 叢集中使用 Java 建立文件並執行基本任務。
先決條件
Azure 訂用帳戶
- 如果您沒有 Azure 訂用帳戶，請建立 免費帳戶
- Java 21 或更新版本
建立 Azure DocumentDB 叢集
要開始，你首先需要建立一個 Azure DocumentDB 叢集，作為儲存和管理 NoSQL 資料的基礎。
登入 Azure 入口網站 （https://portal.azure.com）。
從 Azure 入口網站功能表或 [首頁] 頁面，選取 [建立資源]。
在 新頁面 搜尋並選擇 Azure DocumentDB。
在「建立 Azure DocumentDB 叢集」頁面及「基礎」區塊中，選擇叢集層級區塊中的「配置」選項。
在 縮放 頁面中，設定這些選項，然後選擇 儲存 ，將你的變更永久化到叢集層級。
價值觀 叢集層 M30 tier, 2 vCore, 8-GiB RAM每個分區的儲存體 128 GiB
回到 基礎 部分，設定以下選項：
價值觀 Subscription 選取您的 Azure 訂用帳戶 資源群組 建立新的資源群組，或選取現有的資源群組 叢集名稱 提供全域唯一名稱 地點 為您的訂用帳戶選取支援的 Azure 區域 MongoDB 版本 選取 8.0系統管理員使用者名稱 建立使用者名稱以以使用者管理員身份存取叢集 密碼 使用與使用者名稱相關的獨特密碼 
小提示
記錄你用來輸入 使用者名稱 和 密碼的數值。 這些數值會在本指南後面使用。 關於有效數值的更多資訊，請參見 叢集限制。
請選取「下一步：網路」。
在網路標籤的防火牆規則區塊中，設定以下選項：
價值觀 連線方法 Public access允許從 Azure 內的服務和資源對此叢集進行公開存取 Enabled 為你目前的客戶端裝置新增防火牆規則，透過選擇 + 新增目前的客戶端 IP 位址來授權存取叢集。
小提示
在許多公司環境中，開發人員機器 IP 位址會因為 VPN 或其他公司網路設定而遭到隱藏。 在這種情況下，你可以透過新增一個包含
0.0.0.0-255.255.255.255的 IP 位址範圍至防火牆規則中，來暫時允許所有 IP 位址的存取。 此防火牆規則僅暫時用於連線測試與開發。選擇 檢閱 + 創建。
檢閱您提供的設定，然後選取 建立。 建立叢集需要幾分鐘的時間。 等待資源部署完成。
最後，選擇 「前往資源 」以導航至入口網站中的 Azure DocumentDB 叢集。
![螢幕擷取畫面顯示 [移至資源] 選項。](includes/media/quickstart-portal/go-to-resource.png)
取得叢集認證
取得你用來連接叢集的憑證。
在叢集頁面，選擇資源選單中的 連線字串 選項。
在 Connection 字串 區塊，複製或記錄 Connection 字串 欄位的值。
這很重要
入口網站中的連接字串不包含密碼值。 您必須將 <password> 佔位符替換為建立叢集時輸入的憑證，或以互動方式輸入密碼。
初始化專案
在你目前的目錄中建立一個新的 Maven 專案。
從空白目錄開始。
在目前目錄中開啟終端機。
用快速入門原型建立一個新的 Maven 專案。
mvn archetype:generate -DgroupId=com.example -DartifactId=azure-documentdb-java-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false導航到產生的專案目錄。
cd azure-documentdb-java-quickstart建立專案以確保它成功完成。
mvn compile
安裝用戶端程式庫
客戶端函式庫透過 Maven 以 mongodb-driver-sync 元件提供。
把 MongoDB Java 驅動程式的相依性加入你的
pom.xml檔案。<dependency> <groupId>org.mongodb</groupId> <artifactId>mongodb-driver-sync</artifactId> <version>5.2.0</version> </dependency>打開並檢查 pom.xml 檔案，確認相依項目是否存在。
將所需的套件匯入您的應用程式碼：
import com.mongodb.client.MongoClient; import com.mongodb.client.MongoClients; import com.mongodb.client.MongoCollection; import com.mongodb.client.MongoDatabase; import com.mongodb.client.model.Filters; import com.mongodb.client.model.ReplaceOptions; import org.bson.Document; import org.bson.conversions.Bson; import java.util.Arrays; import java.util.List;
物件模型
| 名稱 | Description |
|---|---|
MongoClient |
用來連線到 MongoDB 的類型。 |
MongoDatabase |
表示叢集中的資料庫。 |
MongoCollection<Document> |
表示叢集中資料庫內的集合。 |
程式碼範例
此應用程式中的程式碼連接一個名為 adventureworks 的資料庫與一個名為 products的集合。 該 products 收藏包含名稱、類別、數量、獨特識別碼及每項產品的銷售標誌等細節。 這裡的程式碼範例執行在處理集合時最常見的操作。
驗證用戶端
首先，使用基本的連接字串連接到用戶端。
建立主要方法並設定連接字串。 將
<your-cluster-name>、<your-username>和<your-password>替換為您實際的叢集資訊。public class App { public static void main(String[] args) { // Connection string for Azure DocumentDB cluster String connectionString = "mongodb+srv://<your-username>:<your-password>@<your-cluster-name>.global.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000";建立 MongoDB 客戶端並驗證連線。
// Create a new client and connect to the server try (MongoClient mongoClient = MongoClients.create(connectionString)) { // Ping the server to verify connection MongoDatabase database = mongoClient.getDatabase("admin"); database.runCommand(new Document("ping", 1)); System.out.println("Successfully connected and pinged Azure DocumentDB");
取得集合
現在，取得您的資料庫和集合。 如果資料庫和集合還不存在，可以用驅動程式自動幫你建立。
取得資料庫的參考資料。
// Get database reference MongoDatabase adventureWorksDatabase = mongoClient.getDatabase("adventureworks"); System.out.println("Connected to database: " + adventureWorksDatabase.getName());取得資料庫內的集合參考。
// Get collection reference MongoCollection<Document> productsCollection = adventureWorksDatabase.getCollection("products"); System.out.println("Connected to collection: products");
建立文件
接著，在你的收藏中新增幾份文件。 將文件 upsert 或更新，以確保若已存在具有相同唯一識別碼的文件，則會取代此文件。
使用 Document 類別建立範例產品文件。
// Create sample products List<Document> products = Arrays.asList( new Document("_id", "00000000-0000-0000-0000-000000004018") .append("name", "Windry Mittens") .append("category", "apparel-accessories-gloves-and-mittens") .append("quantity", 121) .append("price", 35.00) .append("sale", false), new Document("_id", "00000000-0000-0000-0000-000000004318") .append("name", "Niborio Tent") .append("category", "gear-camp-tents") .append("quantity", 140) .append("price", 420.00) .append("sale", true) );使用 upsert 作業插入文件。
// Insert documents with upsert for (Document product : products) { Bson filter = Filters.eq("_id", product.getString("_id")); ReplaceOptions options = new ReplaceOptions().upsert(true); productsCollection.replaceOne(filter, product, options); System.out.println("Upserted product: " + product.getString("name")); }
擷取文件
接著，執行點讀取操作，從你的收藏中擷取特定文件。
定義篩選器，透過 ID 尋找特定文件。
// Retrieve a specific document by ID Bson filter = Filters.eq("_id", "00000000-0000-0000-0000-000000004018");執行查詢並取得結果。
Document retrievedProduct = productsCollection.find(filter).first(); if (retrievedProduct != null) { System.out.println("Retrieved product: " + retrievedProduct.getString("name") + " - $" + retrievedProduct.getDouble("price")); } else { System.out.println("Product not found"); }
查詢文件
最後，使用 MongoDB 查詢語言（MQL）查詢多份文件。
定義一個查詢以尋找符合特定條件的文件。
// Query for products on sale Bson saleFilter = Filters.eq("sale", true);透過游標遍歷以取得所有符合的相關文件。
System.out.println("Products on sale:"); for (Document product : productsCollection.find(saleFilter)) { System.out.printf("- %s: $%.2f (Category: %s)%n", product.getString("name"), product.getDouble("price"), product.getString("category")); } } catch (Exception e) { System.err.println("An error occurred: " + e.getMessage()); e.printStackTrace(); } } }
使用 Visual Studio Code 探索您的資料
在 Visual Studio Code 中使用 DocumentDB 擴充功能來執行核心資料庫操作，包括查詢、插入、更新及刪除資料。
開啟 Visual Studio Code。
請導覽至 擴充功能 檢視並搜尋該詞
DocumentDB。 請找到 DocumentDB for VS Code 擴充功能。選擇擴充功能的 安裝 按鈕。 等候安裝完成。 如果系統提示，請重新載入 Visual Studio Code。
請在活動欄中選擇對應圖示，導向 DocumentDB 擴充功能。
在 DocumentDB 連接 面板中，選擇 + 新連線...。
在對話框中，選擇 Service Discovery ，然後選擇 Azure DocumentDB - Azure Service Discovery。
選擇您的 Azure 訂閱及新建立的 Azure DocumentDB 叢集。
小提示
在許多公司環境中，開發人員機器 IP 位址會因為 VPN 或其他公司網路設定而遭到隱藏。 在這種情況下，你可以透過新增一個包含
0.0.0.0-255.255.255.255的 IP 位址範圍至防火牆規則中，來暫時允許所有 IP 位址的存取。 此防火牆規則僅暫時用於連線測試與開發。 如需詳細資訊，請參閱 設定防火牆。回到 DocumentDB 的連接 面板，展開叢集節點，並導覽到現有的文件和集合節點。
打開該收藏的右鍵選單，然後選擇 DocumentDB 剪貼簿 > 新設 DocumentDB 剪貼簿。
輸入以下 MongoDB 查詢語言（MQL）指令，然後選擇「全部執行」。 觀察指令的輸出。
db.products.find({ price: { $gt: 200 }, sale: true }) .sort({ price: -1 }) .limit(3)
清理資源
完成 Azure DocumentDB 叢集後，你可以刪除你建立的 Azure 資源，避免額外收費。
在 Azure 入口網站的搜尋列中，搜尋並選取 [資源群組]。
在清單中，選取您在此快速入門中使用的資源群組。
在 [資源群組] 頁面中，選取 [刪除資源群組]。
在刪除確認對話方塊中，輸入資源群組的名稱，以確認您要將其刪除。 最後，選取 [刪除] 以永久刪除資源群組。
