快速入門:在 Azure Cosmos DB 中使用 Java 和 MongoDB API 建立主控台應用程式Quickstart: Create a console app with Java and the MongoDB API in Azure Cosmos DB

Azure Cosmos DB 是 Microsoft 的全域分散式多模型資料庫服務。Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. 您可以快速建立及查詢文件、索引鍵/值及圖形資料庫,所有這些都受惠於位於 Cosmos DB 核心的全域散發和水平調整功能。You can quickly create and query document, key/value and graph databases, all of which benefit from the global distribution and horizontal scale capabilities at the core of Cosmos DB.

本快速入門示範如何使用 Azure Cosmos DB 適用於 MongoDB 的 API 來建立 Cosmos 帳戶。This quickstart demonstrates how to create a Cosmos account with Azure Cosmos DB's API for MongoDB. 您會接著使用 MongoDB Java 驅動程式建置和部署主控台應用程式。You'll then build and deploy a console app built using the MongoDB Java driver.

必要條件Prerequisites

您必須具備下列必要條件,才能執行此範例:Before you can run this sample, you must have the following prerequisites:

如果您沒有 Azure 訂用帳戶,請在開始前建立免費帳戶If you don't have an Azure subscription, create a free account before you begin.

或者,您可以免費試用 Azure Cosmos DB,無須 Azure 訂用帳戶,也無須任何費用和約定付款。Alternatively, you can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. 或者,您可以使用 Azure Cosmos DB 模擬器來進行本教學課程,連接字串為Or you can use the Azure Cosmos DB Emulator for this tutorial with a connection string of

mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true

建立資料庫帳戶Create a database account

  1. 在新的視窗中,登入 Azure 入口網站In a new window, sign in to the Azure portal.

  2. 在左側功能表中,依序選取 [建立資源] 、[資料庫] ,然後在 [Azure Cosmos DB] 下選取 [建立] 。In the left menu, select Create a resource, select Databases, and then under Azure Cosmos DB, select Create.

    Azure 入口網站的螢幕擷取畫面,其中反白顯示 [其他服務] 和 Azure Cosmos DB

  3. 在 [建立 Azure Cosmos DB 帳戶] 頁面中,輸入新的 Azure Cosmos DB 帳戶的設定。In the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    設定Setting Value 說明Description
    SubscriptionSubscription 您的訂用帳戶Your subscription 選取要用於此 Azure Cosmos DB 帳戶的 Azure 訂用帳戶。Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    資源群組Resource Group 新建Create new

    然後輸入識別碼中所提供的同一個唯一名稱Then enter the same unique name as provided in ID
    選取 [建立新的] 。Select Create new. 然後為您的帳戶輸入新的資源群組名稱。Then enter a new resource-group name for your account. 為求簡化,請使用和識別碼相同的名稱。For simplicity, use the same name as your ID.
    帳戶名稱Account Name 輸入唯一名稱Enter a unique name 輸入唯一名稱來識別您的 Azure Cosmos DB 帳戶。Enter a unique name to identify your Azure Cosmos DB account. 因為 documents.azure.com 會附加到您所提供的識別碼以建立 URI,請使用唯一識別碼。Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    識別碼只能使用小寫字母、數字及連字號 (-) 字元。The ID can use only lowercase letters, numbers, and the hyphen (-) character. 長度必須介於 3 到 31 個字元之間。It must be between 3 and 31 characters in length.
    APIAPI 適用於 MongoDB 的 Azure Cosmos DB APIAzure Cosmos DB's API for MongoDB API 會決定要建立的帳戶類型。The API determines the type of account to create. Azure Cosmos DB 提供五個 API:Core (SQL) (適用於文件資料庫)、Gremlin (適用於圖形資料庫)、Azure Cosmos DB MongoDB API (適用於文件資料庫)、「Azure 資料表」及 Cassandra。Azure Cosmos DB provides five APIs: Core (SQL) for document databases, Gremlin for graph databases, Azure Cosmos DB's API MongoDB for document databases, Azure Table, and Cassandra. 目前,您必須為每個 API 建立個別個帳戶。Currently, you must create a separate account for each API.

    選取 [MongoDB] ,因為在此快速入門中,您會建立可搭配 MongoDB 使用的資料表。Select MongoDB because in this quickstart you are creating a table that works with the MongoDB.
    LocationLocation 選取最接近使用者的區域Select the region closest to your users 選取用來裝載 Azure Cosmos DB 帳戶的地理位置。Select a geographic location to host your Azure Cosmos DB account. 使用最接近使用者的位置,以便他們能以最快速度存取資料。Use the location that's closest to your users to give them the fastest access to the data.

    請選取 [檢閱 + 建立] 。Select Review+Create. 您可以略過 [網路] 和 [標記] 區段。You can skip the Network and Tags section.

    Azure Cosmos DB 的新帳戶頁面

  4. 建立帳戶需要幾分鐘的時間。The account creation takes a few minutes. 等候入口網站顯示 [恭喜!具有 MongoDB 有線通訊協定相容性的 Cosmos 帳戶已就緒] 頁面。Wait for the portal to display the Congratulations! Your Cosmos account with wire protocol compatibility for MongoDB is ready page.

    Azure 入口網站的 [通知] 窗格

新增集合Add a collection

將新資料庫命名為 db,以即將新集合命名為 collName your new database, db, and your new collection, coll.

您現在可以在 Azure 入口網站中使用 [資料總管] 工具,建立資料庫和容器。You can now use the Data Explorer tool in the Azure portal to create a database and container.

  1. 選取 [資料總管] > [新增容器] 。Select Data Explorer > New Container.

    [新增容器] 區域會顯示在最右邊,您可能需要向右捲動才能看到它。The Add Container area is displayed on the far right, you may need to scroll right to see it.

    Azure 入口網站資料總管,[新增容器] 窗格

  2. 在 [新增容器] 頁面上,輸入新容器的設定。In the Add container page, enter the settings for the new container.

    設定Setting 建議的值Suggested value 說明Description
    資料庫識別碼Database ID 工作Tasks 輸入 ToDoList 作為新資料庫的名稱。Enter ToDoList as the name for the new database. 資料庫名稱必須包含從 1 到 255 個字元,且不能包含 /, \\, #, ? 或尾端空格。Database names must contain from 1 through 255 characters, and they cannot contain /, \\, #, ?, or a trailing space. 核取 [佈建資料庫輸送量] 選項,它可讓您在資料庫中的所有容器內共用佈建到資料庫的輸送量。Check the Provision database throughput option, it allows you to share the throughput provisioned to the database across all the containers within the database. 此選項也有助於節省成本。This option also helps with cost savings.
    輸送量Throughput 400400 讓輸送量保持在每秒 400 個要求單位 (RU/秒)。Leave the throughput at 400 request units per second (RU/s). 如果您想要降低延遲,稍後可以相應增加輸送量。If you want to reduce latency, you can scale up the throughput later.
    容器識別碼Container ID 項目Items 輸入 Items 作為新容器的名稱。Enter Items as the name for your new container. 容器識別碼與資料庫名稱具有相同的字元需求。Container IDs have the same character requirements as database names.
    分割區索引鍵Partition key /類別/category 本文中所述的範例使用 /category 作為分割區索引鍵。The sample described in this article uses /category as the partition key.

    除了上述的設定,您可以選擇性地為容器新增 [唯一索引鍵] 。In addition to the preceding settings, you can optionally add Unique keys for the container. 在此範例中,讓我們將欄位保留空白。Let's leave the field empty in this example. 唯一索引鍵可讓開發人員在資料庫中新增一層資料完整性。Unique keys provide developers with the ability to add a layer of data integrity to the database. 您可在建立容器時建立唯一索引鍵原則,以確保每個資料分割索引鍵一或多個值的唯一性。By creating a unique key policy while creating a container, you ensure the uniqueness of one or more values per partition key. 若要深入了解,請參閱 Azure Cosmos DB 中的唯一索引鍵一文。To learn more, refer to the Unique keys in Azure Cosmos DB article.

    選取 [確定] 。Select OK. [資料總管] 會顯示新的資料庫和容器。The Data Explorer displays the new database and container.

複製範例應用程式Clone the sample application

現在,我們將從 GitHub 複製應用程式、設定連接字串,然後加以執行。Now let's clone an app from GitHub, set the connection string, and run it. 您會看到,以程式設計方式來處理資料有多麼的容易。You'll see how easy it is to work with data programmatically.

  1. 開啟命令提示字元,建立名為 git-samples 的新資料夾,然後關閉命令提示字元。Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. 開啟 git 終端機視窗 (例如 git bash),並使用 cd 命令變更至要安裝範例應用程式的新資料夾。Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. 執行下列命令來複製範例存放庫。Run the following command to clone the sample repository. 此命令會在您的電腦上建立範例應用程式副本。This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/azure-cosmos-db-mongodb-java-getting-started.git
    
  4. 然後在您慣用的編輯器中開啟程式碼。Then open the code in your favorite editor.

檢閱程式碼Review the code

此為選用步驟。This step is optional. 若您想要瞭解如何在程式碼中建立資料庫資源,則可檢閱下列程式碼片段。If you're interested in learning how the database resources are created in the code, you can review the following snippets. 或者也可以直接跳至更新您的連接字串Otherwise, you can skip ahead to Update your connection string.

下列程式碼片段全部取自 Program.java 檔案。The following snippets are all taken from the Program.java file.

  • 已初始化 DocumentClient。The DocumentClient is initialized.

    MongoClientURI uri = new MongoClientURI("FILLME");`
    
    MongoClient mongoClient = new MongoClient(uri);            
    
  • 已建立新的資料庫和集合。A new database and collection are created.

    MongoDatabase database = mongoClient.getDatabase("db");
    
    MongoCollection<Document> collection = database.getCollection("coll");
    
  • 已使用 MongoCollection.insertOne 插入一些文件Some documents are inserted using MongoCollection.insertOne

    Document document = new Document("fruit", "apple")
    collection.insertOne(document);
    
  • 已使用 MongoCollection.find 執行一些查詢Some queries are performed using MongoCollection.find

    Document queryResult = collection.find(Filters.eq("fruit", "apple")).first();
    System.out.println(queryResult.toJson());       
    

更新您的連接字串Update your connection string

現在,返回 Azure 入口網站以取得連接字串資訊,並將它複製到應用程式中。Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. 從 [帳戶] 選取 [快速入門] ,選取 [Java] ,然後將連接字串複製到剪貼簿。From the Account, select Quick Start, select Java, then copy the connection string to your clipboard.

  2. 開啟 Program.java 檔案,以連接字串取代 MongoClientURI 建構函式的引數。Open the Program.java file, replace the argument to the MongoClientURI constructor with the connection string. 您現已更新應用程式,使其具有與 Azure Cosmos DB 通訊所需的所有資訊。You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

執行主控台應用程式Run the console app

  1. 在終端機中執行 mvn package 以安裝必要的 npm 模組Run mvn package in a terminal to install required npm modules

  2. 在終端機中執行 mvn exec:java -D exec.mainClass=GetStarted.Program 來啟動您的 Java 應用程式。Run mvn exec:java -D exec.mainClass=GetStarted.Program in a terminal to start your Java application.

您現在可以使用 Robomongo / Studio 3T 來查詢、修改及處理這項新資料。You can now use Robomongo / Studio 3T to query, modify, and work with this new data.

在 Azure 入口網站中檢閱 SLAReview SLAs in the Azure portal

Azure 入口網站會監視您的 Cosmos DB 帳戶輸送量、儲存體、可用性、延遲和一致性。The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Azure Cosmos DB 服務等級協定 (SLA) 相關聯的計量圖表會顯示相較於實際效能的 SLA 值。Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. 此計量套件可讓您以更透明的方式監視監視 SLA。This suite of metrics makes monitoring your SLAs transparent.

若要檢閱計量和 SLA:To review metrics and SLAs:

  1. 在您的 Cosmos DB 帳戶導覽功能表中,選取 [計量] 。Select Metrics in your Cosmos DB account's navigation menu.

  2. 選取一個索引標籤 (例如 [延遲] ),並在右側選取時間範圍。Select a tab such as Latency, and select a timeframe on the right. 比較圖表中的實際SLA 的資料行。Compare the Actual and SLA lines on the charts.

    Azure Cosmos DB 計量套件

  3. 檢閱其他索引標籤中的計量。Review the metrics on the other tabs.

清除資源Clean up resources

完成您的 Web 應用程式和 Azure Cosmos DB 帳戶之後,您可以將建立的 Azure 資源刪除,以免產生更多費用。When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. 若要刪除資源:To delete the resources:

  1. 在 Azure 入口網站中,選取最左邊的 [資源群組] 。In the Azure portal, select Resource groups on the far left. 若已摺疊左側功能表,請選取展開按鈕加以展開。If the left menu is collapsed, select Expand button to expand it.

  2. 選取您在本快速入門中建立的資源群組。Select the resource group you created for this quickstart.

    Azure 入口網站中的計量

  3. 在新視窗中,選取 [刪除資源群組] 。In the new window, select Delete resource group.

    Azure 入口網站中的計量

  4. 在下個視窗中輸入要刪除的資源群組名稱,然後選取 [刪除] 。In the next window, enter the name of the resource group to delete, and then select Delete.

後續步驟Next steps

在本快速入門中,您已了解如何建立 Cosmos 帳戶、建立集合,以及執行主控台應用程式。In this quickstart, you've learned how to create a Cosmos account, create a collection and run a console app. 您現在可以將其他資料匯入到 Cosmos 資料庫。You can now import additional data to your Cosmos database.