快速入門:建置 JAVA 應用程式來管理 Azure Cosmos DB SQL API 資料

適用於: SQL API

在本快速入門中,您會從 Azure 入口網站以及藉由使用從 GitHub 複製的 Java 應用程式,來建立和管理 Azure Cosmos DB SQL API 帳戶。 首先,您必須使用 Azure 入口網站建立 Azure Cosmos DB SQL API 帳戶、使用 SQL Java SDK 建立 Java 應用程式,然後使用 Java 應用程式將資源新增至您的 Cosmos DB 帳戶。 Azure Cosmos DB 是多模型的資料庫服務,可讓您快速建立及查詢具有全域散發和水平調整功能的文件、資料表、索引鍵/值及圖形資料庫。

重要

本快速入門僅適用於 Azure Cosmos DB Java SDK v4。 如需詳細資訊,請檢視 Azure Cosmos DB Java SDK v4 版本資訊Maven 存放庫、Azure Cosmos DB Java SDK v4 效能秘訣和 Azure Cosmos DB Java SDK v4 疑難排解指南。 如果您目前使用的版本比 v4 舊,請參閱遷移至 Azure Cosmos DB Java SDK v4 指南,以取得升級至 v4 的協助。

必要條件

簡介注意事項

Cosmos DB 帳戶的結構。 不論是 API 還是程式設計語言,Cosmos DB「帳戶」會包含零個以上的「資料庫」、「資料庫」(DB) 會包含零個以上的「容器」,「容器」則會包含零個以上的項目,如下圖所示:

Azure Cosmos account entities

您可以在這裡了解更多有關資料庫、容器和項目的詳細資訊。有些重要的屬性是在容器層級定義,包括「佈建的輸送量」和「分割區索引鍵」。

佈建的輸送量會以具有貨幣價格的要求單位 (RU) 來進行測量,在決定帳戶的營運成本時,RU 會是一大因素。 佈建的輸送量可依每一容器的細微性或每一資料庫的細微性來加以選取,不過一般來說,最好是指定容器層級的輸送量。 您可以在這裡進一步了解輸送量佈建。

隨著 Cosmos DB 容器中不斷插入項目,資料庫也可藉由新增更多儲存體和計算來處理要求,以水平方式跟著成長。 儲存體和計算容量會以離散單位 (稱為「分割區」) 來新增,而且您必須在文件中選擇一個欄位來作為分割區索引鍵,以將每個文件對應至分割區。 分割區的管理方式是為每個分割區指派分割區索引鍵值範圍中大致相等的配量;因此,建議您選擇相對隨機或平均分佈的分割區索引鍵。 否則,某些分割區會看到高出許多的要求 (「熱分割區」),其他分割區則會看到少了許多的要求 (「冷分割區」),我們應該避免這種情況。 您可以在這裡深入了解分割。

建立資料庫帳戶

您必須先使用 Azure Cosmos DB 建立 SQL API 帳戶,才可以建立文件資料庫。

  1. 從 Azure 入口網站功能表或[首頁] 頁面,選取 [建立資源]。

  2. 在 [新增] 頁面上,搜尋並選取 [Azure Cosmos DB]。

  3. 在 [選取 API 選項] 頁面上,選取 [核心 (SQL) - 建議] 區段中的 [建立] 選項。 Azure Cosmos DB 提供五個 API:Core(SQL) 和 MongoDB (適用於文件資料)、Gremlin (適用於圖形資料)、Azure 資料表及 Cassandra。 目前,您必須為每個 API 建立個別個帳戶。 進一步了解 SQL API

  4. 在 [建立 Azure Cosmos DB 帳戶] 頁面中,輸入新 Azure Cosmos 帳戶的基本設定。

    設定 描述
    訂用帳戶 訂閱名稱 選取要用於此 Azure Cosmos 帳戶的 Azure 訂用帳戶。
    資源群組 資源群組名稱 選取資源群組,或選取 [新建],然後輸入新資源群組的唯一名稱。
    帳戶名稱 唯一的名稱 輸入名稱來識別您的 Azure Cosmos 帳戶。 因為 documents.azure.com 會附加到您所提供的名稱以建立 URI,請使用唯一名稱。

    名稱只能包含小寫字母、數字及連字號 (-) 字元。 其長度必須介於 3 到 44 個字元之間。
    Location 最接近使用者的區域 選取用來裝載 Azure Cosmos DB 帳戶的地理位置。 使用最接近使用者的位置,讓他們能以最快速度存取資料。
    容量模式 佈建輸送量或無伺服器 選取 [佈建的輸送量],以佈建的輸送量模式建立帳戶。 選取 [無伺服器],以無伺服器模式建立帳戶。
    申請 Azure Cosmos DB 免費階層折扣 適用不適用 使用 Azure Cosmos DB 免費層,您將可在帳戶中免費取得前 1000 RU/秒和 25 GB 的儲存體。 深入了解免費層

    注意

    每個 Azure 訂用帳戶最多可以有一個免費層的 Azure Cosmos DB 帳戶,而且必須在建立帳戶時選擇加入。 如果您看不到套用免費層折扣的選項,這表示訂用帳戶中的另一個帳戶已透過免費層啟用。

    The new account page for Azure Cosmos DB

  5. 在 [全域散發] 索引標籤中,設定下列詳細資料。 您可以保留預設值以用於本快速入門:

    設定 說明
    異地備援 停用 藉由將您的區域與配對區域進行配對,在您的帳戶上啟用或停用全域散發。 您可以在稍後將更多區域新增至您的帳戶。
    多區域寫入 停用 多重區域寫入功能可讓您利用在全球為資料庫及容器佈建的輸送量。

    注意

    如果您選取 [無伺服器] 作為容量模式,則無法使用下列選項:

    • 申請免費層折扣
    • 異地備援
    • 多區域寫入
  6. (選用) 您可以在下列索引標籤中設定其他詳細資料:

    • 網路 - 設定從虛擬網路存取
    • 備份原則 - 設定定期連續備份原則。
    • 加密 - 使用服務管理的金鑰或客戶自控金鑰
    • 標籤 - 標籤為成對的名稱和值,可讓您將相同的標籤套用至多個資源與資源群組,以便為資源分類及檢視合併的帳單。
  7. 選取 [檢閱 + 建立]。

  8. 檢閱帳戶設定,然後選取 [建立]。 建立帳戶需要幾分鐘的時間。 等候入口網站頁面顯示 [您的部署已完成] 訊息。

    The Azure portal Notifications pane

  9. 選取 [移至資源] 以移至 Azure Cosmos DB 帳戶頁面。

    The Azure Cosmos DB account page

新增容器

您現在可以在 Azure 入口網站中使用 [資料總管] 工具,建立資料庫和容器。

  1. 選取 [資料總管]>[新增容器]。

    [新增容器] 區域會顯示在最右邊,您可能需要向右捲動才能看到它。

    The Azure portal Data Explorer, Add Container pane

  2. 在 [新增容器] 頁面上,輸入新容器的設定。

    設定 建議的值 描述
    資料庫識別碼 ToDoList 輸入 Tasks 作為新資料庫的名稱。 資料庫名稱必須包含從 1 到 255 個字元,且不能包含 /, \\, #, ? 或尾端空格。 核取 [共用容器間的輸送量] 選項,它可讓您在資料庫上的所有容器內共用佈建到資料庫的輸送量。 此選項也有助於節省成本。
    資料庫輸送量 您可以佈建 [自動調整] 或 [手動] 輸送量。 手動輸送量可讓您自行調整 RU/秒,而自動調整輸送量可讓系統根據使用量來調整 RU/秒。 針對此範例,請選取 [手動]。

    讓輸送量保持在每秒 400 個要求單位 (RU/秒)。 如果您想要降低延遲,稍後可以使用容量計算機來評估所需的 RU/秒,以擴大輸送量。

    注意:在無伺服器帳戶中建立新容器時,無法使用此設定。
    容器識別碼 項目 輸入 Items 作為新容器的名稱。 容器識別碼與資料庫名稱具有相同的字元需求。
    分割區索引鍵 /類別 本文中所述的範例使用 /category 作為分割區索引鍵。

    請勿在此範例中新增唯一索引鍵或開啟分析存放區。 唯一索引鍵可讓您藉由確保每個分割索引鍵有一或多個唯一值,來對資料庫新增一層資料完整性。 如需詳細資訊,請參閱 Azure Cosmos DB 中的唯一索引鍵。分析存放區可用於大規模分析操作資料,而不會對交易式工作負載產生影響。

    選取 [確定]。 [資料總管] 會顯示新的資料庫和容器。

新增範例資料

您現在可以使用 [資料總管] 將資料新增至您的新容器。

  1. 在 [資料總管] 中,展開 Tasks 資料庫,然後展開 Items 容器。 選取 [項目],然後選取 [新增項目]

    Create new documents in Data Explorer in the Azure portal

  2. 現在將文件新增至具有下列結構的容器。

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. 將 json 新增至 [文件] 索引標籤後,選取 [儲存]

    Copy in json data and select Save in Data Explorer in the Azure portal

  4. 多建立並儲存一份文件,以便在其中插入 id 屬性的唯一值,並適當變更其他屬性。 新文件可擁有您想要的任何結構,因為 Azure Cosmos DB 不會對您的資料強加任何結構描述。

查詢資料

您可以在 [資料總管] 中,使用查詢來擷取和篩選您的資料。

  1. 在 [資料總管] 中的 [項目] 索引標籤頂端,檢閱預設查詢 SELECT * FROM c。 此查詢會依照識別碼順序擷取並顯示容器中的所有文件。

    Default query in Data Explorer is SELECT * FROM c

  2. 若要變更查詢,請選取 [編輯篩選條件],以 ORDER BY c._ts DESC 取代預設查詢,然後選取 [套用篩選條件]。

    Change the default query by adding ORDER BY c._ts DESC and clicking Apply Filter

    經過修改的查詢會根據文件的時間戳記,依遞減順序顯示文件,因此現會最先列出您的第二份文件。

    Changed query to ORDER BY c._ts DESC and clicking Apply Filter

若您熟悉 SQL 語法,則可在查詢述詞方塊中輸入任何支援的 SQL 查詢。 您也可以使用 [資料總管] 來建立伺服器端商務邏輯的預存程序、UDF 和觸發程序。

[資料總管] 可讓您透過 Azure 入口網站輕鬆存取 API 中所有可用的內建程式設計資料存取功能。 您也可以使用入口網站來調整輸送量、取得金鑰和連接字串,以及檢閱 Azure Cosmos DB 帳戶的計量和 SLA。

複製範例應用程式

現在讓我們切換為使用程式碼。 我們將從 GitHub 複製 SQL API 應用程式、設定連接字串,然後加以執行。 您會看到,以程式設計方式來處理資料有多麼的容易。

執行下列命令來複製範例存放庫。 此命令會在您的電腦上建立範例應用程式副本。

git clone https://github.com/Azure-Samples/azure-cosmos-java-getting-started.git

檢閱程式碼

此為選用步驟。 若您想要瞭解如何在程式碼中建立資料庫資源,則可檢閱下列程式碼片段。 或是,您可以直接跳到執行應用程式

使用同步 API 管理資料庫資源

  • CosmosClient 初始化。 CosmosClient 提供適用於 Azure Cosmos 資料庫服務的用戶端邏輯表示法。 此用戶端會用於設定和執行針對服務的要求。

    client = new CosmosClientBuilder()
        .endpoint(AccountSettings.HOST)
        .key(AccountSettings.MASTER_KEY)
        //  Setting the preferred location to Cosmos DB Account region
        //  West US is just an example. User should set preferred location to the Cosmos DB region closest to the application
        .preferredRegions(Collections.singletonList("West US"))
        .consistencyLevel(ConsistencyLevel.EVENTUAL)
        .buildClient();
    
    
  • CosmosDatabase 建立。

    CosmosDatabaseResponse cosmosDatabaseResponse = client.createDatabaseIfNotExists(databaseName);
    database = client.getDatabase(cosmosDatabaseResponse.getProperties().getId());
    
  • CosmosContainer 建立。

    CosmosContainerProperties containerProperties =
        new CosmosContainerProperties(containerName, "/lastName");
    
    //  Create container with 400 RU/s
    CosmosContainerResponse cosmosContainerResponse =
        database.createContainerIfNotExists(containerProperties, ThroughputProperties.createManualThroughput(400));
    container = database.getContainer(cosmosContainerResponse.getProperties().getId());
    
  • 使用 createItem 方法建立項目。

    //  Create item using container that we created using sync client
    
    //  Use lastName as partitionKey for cosmos item
    //  Using appropriate partition key improves the performance of database operations
    CosmosItemRequestOptions cosmosItemRequestOptions = new CosmosItemRequestOptions();
    CosmosItemResponse<Family> item = container.createItem(family, new PartitionKey(family.getLastName()), cosmosItemRequestOptions);
    
  • 端點讀取是使用 readItem 方法來執行。

    try {
        CosmosItemResponse<Family> item = container.readItem(family.getId(), new PartitionKey(family.getLastName()), Family.class);
        double requestCharge = item.getRequestCharge();
        Duration requestLatency = item.getDuration();
        logger.info("Item successfully read with id {} with a charge of {} and within duration {}",
            item.getItem().getId(), requestCharge, requestLatency);
    } catch (CosmosException e) {
        logger.error("Read Item failed with", e);
    }
    
  • 使用 queryItems 方法,透過 JSON 執行 SQL 查詢。

    // Set some common query options
    CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions();
    //queryOptions.setEnableCrossPartitionQuery(true); //No longer necessary in SDK v4
    //  Set query metrics enabled to get metrics around query executions
    queryOptions.setQueryMetricsEnabled(true);
    
    CosmosPagedIterable<Family> familiesPagedIterable = container.queryItems(
        "SELECT * FROM Family WHERE Family.lastName IN ('Andersen', 'Wakefield', 'Johnson')", queryOptions, Family.class);
    
    familiesPagedIterable.iterableByPage(10).forEach(cosmosItemPropertiesFeedResponse -> {
        logger.info("Got a page of query result with {} items(s) and request charge of {}",
                cosmosItemPropertiesFeedResponse.getResults().size(), cosmosItemPropertiesFeedResponse.getRequestCharge());
    
        logger.info("Item Ids {}", cosmosItemPropertiesFeedResponse
            .getResults()
            .stream()
            .map(Family::getId)
            .collect(Collectors.toList()));
    });
    

執行應用程式

現在,返回 Azure 入口網站以取得連接字串資訊,然後使用端點資訊啟動應用程式。 這可讓您的應用程式與託管資料庫進行通訊。

  1. 在 git 終端機視窗中,cd 至範例程式碼資料夾。

    cd azure-cosmos-java-getting-started
    
  2. 在 git 終端機視窗中,使用下列命令來安裝必要的 Java 套件。

    mvn package
    
  3. 在 git 終端機視窗中,使用下列命令啟動 Java 應用程式 (將 SYNCASYNCMODE 取代為 syncasync (取決於您想要執行的範例程式碼),將 YOUR_COSMOS_DB_HOSTNAME 取代為入口網站中加上引號的 URI 值,並將 YOUR_COSMOS_DB_MASTER_KEY 取代為入口網站中加上引號的主要金鑰)

    mvn exec:java@SYNCASYNCMODE -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEY
    
    

    終端機視窗會顯示已建立 FamilyDB 資料庫的通知。

  4. 此應用程式會建立名稱為 AzureSampleFamilyDB 的資料庫

  5. 此應用程式會建立名稱為 FamilyContainer 的容器

  6. 此應用程式會使用物件識別碼和分割索引鍵值 (在我們的範例中為 lastName) 來執行端點讀取。

  7. 此應用程式會查詢項目,以擷取姓氏屬於 ('Andersen', 'Wakefield', 'Johnson') 的所有家族

  8. 應用程式並不會刪除已建立的資源。 切換回入口網站,從您的帳戶中清除資源, 以免產生費用。

在 Azure 入口網站中檢閱 SLA

Azure 入口網站會監視您的 Cosmos DB 帳戶輸送量、儲存體、可用性、延遲和一致性。 與 Azure Cosmos DB 服務等級協定 (SLA) 相關聯的計量圖表會顯示相較於實際效能的 SLA 值。 此計量套件可讓您以更透明的方式監視監視 SLA。

若要檢閱計量和 SLA:

  1. 在您的 Cosmos DB 帳戶導覽功能表中,選取 [計量]

  2. 選取一個索引標籤 (例如 [延遲]),並在右側選取時間範圍。 比較圖表中的實際SLA 的資料行。

    Azure Cosmos DB metrics suite

  3. 檢閱其他索引標籤中的計量。

清除資源

完成您的應用程式和 Azure Cosmos DB 帳戶之後,您可以將建立的 Azure 資源刪除,以免產生更多費用。 若要刪除資源:

  1. 在 Azure 入口網站的 [搜尋] 列中,搜尋並選取 [資源群組]

  2. 在該清單中,選取您在本快速入門中建立的資源群組。

    Select the resource group to delete

  3. 在 [資源群組] 的 [概觀] 頁面中,選取 [刪除資源群組]

    Delete the resource group

  4. 在下個視窗中輸入要刪除的資源群組名稱,然後選取 [刪除]

後續步驟

在本快速入門中,您已了解如何使用 [資料總管] 來建立 Azure Cosmos DB SQL API 帳戶、文件資料庫和容器,以及如何執行 Java 應用程式來以程式設計方式執行同樣的作業。 您現在可以將其他資料匯入 Azure Cosmos DB 帳戶中。

正在嘗試為遷移至 Azure Cosmos DB 進行容量規劃嗎? 您可以使用現有資料庫叢集的相關資訊進行容量規劃。