快速入門：使用 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 進行容量規劃嗎？ 您可以使用現有資料庫叢集的相關資訊進行容量規劃。

將資料匯入到 Azure Cosmos DB