快速入門:使用 Node.js 連線至 Azure Cosmos DB SQL API 帳戶並從中查詢資料

適用於: SQL API

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

逐步解說影片

如需本文內容的完整逐步解說,請觀看這段影片。

必要條件

建立 Azure Cosmos 帳戶

在此快速入門中,您可以使用免費試用 Azure Cosmos DB 選項來建立 Azure Cosmos 帳戶。

  1. 瀏覽至免費試用 Azure Cosmos DB 頁面。

  2. 選擇 [SQL] API 帳戶,然後選取 [建立]。 使用您的 Microsoft 帳戶登入 。

  3. 登入成功之後,您的 Azure Cosmos 帳戶應該已就緒。 選取 [在 Azure 入口網站中開啟],以開啟新建立的帳戶。

「免費試用 Azure Cosmos DB」選項不需要 Azure 訂用帳戶,您可以使用 Azure Cosmos 帳戶 30 天。 如果想使用 Azure Cosmos 帳戶較長的時間,您應該在 Azure 訂用帳戶內建立帳戶

新增容器

您現在可以在 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 複製 Node.js 應用程式、設定連接字串,然後加以執行。

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

    git clone https://github.com/Azure-Samples/azure-cosmos-db-sql-api-nodejs-getting-started.git
    

檢閱程式碼

此為選用步驟。 若您想要了解如何在程式碼中建立 Azure Cosmos 資料庫資源,您可以檢閱下列程式碼片段。 或者也可以直接跳至更新您的連接字串

如果您熟悉舊版 SQL JavaScript SDK,則可能已習慣看到「集合」和「文件」等字詞。 因為 Azure Cosmos DB 支援多個 API 模型2.0+ 版的 JavaScript SDK 會使用「容器」這個泛用字詞,此字詞可能是用來說明容器內容的集合、圖表或資料表和「項目」。

Cosmos DB JavaScript SDK 稱為 "@azure/cosmos",可以從 npm 安裝...

npm install @azure/cosmos

下列程式碼片段全部取自 app.js 檔案。

  • CosmosClient 是從 @azure/cosmos npm 套件匯入。

    const CosmosClient = require("@azure/cosmos").CosmosClient;
    
  • 已初始化新的 CosmosClient 物件。

    const client = new CosmosClient({ endpoint, key });
    
  • 選取「工作」資料庫。

    const database = client.database(databaseId);
    
  • 選取「項目」容器/集合。

    const container = database.container(containerId);
    
  • 選取「項目」容器中的所有項目。

    // query to return all items
    const querySpec = {
      query: "SELECT * from c"
    };
    
    const { resources: items } = await container.items
      .query(querySpec)
      .fetchAll();
    
  • 建立新的項目

    const { resource: createdItem } = await container.items.create(newItem);
    
  • 更新項目

    const { id, category } = createdItem;
    
    createdItem.isComplete = true;
    const { resource: updatedItem } = await container
      .item(id, category)
      .replace(createdItem);
    
  • 刪除項目

    const { resource: result } = await container.item(id, category).delete();
    

注意

在「更新」和「刪除」兩種方法中,都必須藉由呼叫 container.item() 從資料庫中選取項目。 傳入的兩個參數是項目的識別碼和項目的分割區索引鍵。 在此案例中,分割區索引鍵是「類別」欄位的值。

更新您的連接字串

現在請回到 Azure 入口網站,以取得 Azure Cosmos 帳戶的連接字串詳細資料。 將連接字串複製到應用程式中,使其可連線至您的資料庫。

  1. 在您於 Azure 入口網站的 Azure Cosmos DB 帳戶中,從左側瀏覽區選取 [金鑰],然後選取 [讀寫金鑰]。 在下一個步驟中,使用畫面右側的複製按鈕,將 URI 和主要金鑰複製到 app.js 檔案。

    View and copy an access key in the Azure portal, Keys blade

  2. 開啟 config.js 檔案。

  3. 從入口網站複製您的 URI 值 (使用 [複製] 按鈕),並使其成為 config.js 中的端點金鑰值。

    endpoint: "<Your Azure Cosmos account URI>"

  4. 然後,從入口網站複製您的主要金鑰值,並使其成為 config.js 中的 config.key 值。 您現已更新應用程式,使其具有與 Azure Cosmos DB 通訊所需的所有資訊。

    key: "<Your Azure Cosmos account key>"

執行應用程式

  1. 在終端機中執行 npm install 以安裝 "@azure/cosmos" npm 套件

  2. 在終端機中執行 node app.js 來啟動您的節點應用程式。

  3. 您稍早在本快速入門中建立的兩個項目都會列出。已建立新項目。 該項目上的「isComplete」旗標會更新為「true」,最後系統會刪除該項目。

您可以繼續在此範例應用程式中實驗,或返回資料總管、修改和處理您的資料。

在 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 帳戶、如何使用 [資料總管] 建立容器,以及如何執行 Node.js 應用程式。 您現在可以將其他資料匯入 Azure Cosmos DB 帳戶中。

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