共用方式為

快速入門：使用 Node.js 與 Azure Cosmos DB 建置資料表 API 應用程式

  • 發行項

適用於： 桌子

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

必要條件

範例應用程式

本教學課程的應用程式範例可從存放庫 https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js 複製或下載。 入門和已完成的應用程式都包含在樣本存放庫中。

git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js

應用程式範例會以氣象資料為例來示範資料表 API 的功能。 代表氣象觀察的物件會使用資料表 API 來儲存和取出，其中包括儲存具有其他屬性的物件以藉此示範資料表 API 的無架構功能。

已完成應用程式的螢幕快照，其中顯示使用適用於數據表的 API 儲存在 Azure Cosmos DB 資料表中的數據。

1 - 建立 Azure Cosmos DB 帳戶

您必須先建立 Azure Cosmos DB 資料表 API 帳戶，其中會包含您應用程式中所使用的資料表。 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 來完成此操作。

登入 Azure 入口網站，並遵循下列步驟來建立 Azure Cosmos DB 帳戶。

指示 Screenshot
在 Azure 入口網站中:
  1. 在 Azure 入口網站頂端的搜尋列中，輸入「cosmos db」。
  2. 在出現在搜尋列下方的功能表上，選取 [服務] 下標示為 [Azure Cosmos DB] 的項目。
 此螢幕快照顯示如何使用頂端工具列中的搜尋方塊，在 Azure 中尋找 Azure Cosmos DB 帳戶。
在 [Azure Cosmos DB] 頁面上，選取 [+ 建立]。 顯示 Azure 中 Azure Cosmos DB 帳戶頁面上 [建立] 按鈕位置的螢幕快照。
在 [選取 API 選項] 頁面上，選擇 [Azure 資料表] 選項。 螢幕快照，顯示 [Azure 數據表] 選項作為選取的正確選項。
在 [建立 Azure Cosmos DB 帳戶 - Azure 資料表] 頁面上，以如下方式填寫表單。
  1. 選取 [資源群組] 下的 [新建] 連結，以為名為 rg-msdocs-tables-sdk-demo 的儲存體帳戶建立全新資源群組。
  2. 將您的儲存體帳戶取名為 cosmos-msdocs-tables-sdk-demo-XYZ，其中 XYZ 為任意三個隨機字元，藉此建立出唯一的帳戶名稱。 Azure Cosmos DB 帳戶名稱的長度必須介於 3 到 44 個字元之間，且只能包含小寫字母、數字或連字號 (-) 字元。
  3. 選取儲存體帳戶的區域。
  4. 選取 [標準] 效能。
  5. 在 [容量模式] 下，為此範例選取 [已佈建輸送量]。
  6. 針對此範例，請選取 [套用免費階層折扣] 下的 [套用]。
  7. 選取畫面底部的 [檢閱 + 建立] 按鈕，然後在摘要畫面上選取 [建立] 以建立 Azure Cosmos DB 帳戶。 此程序可能需要幾分鐘的時間。
 顯示如何在 Azure Cosmos DB 帳戶建立頁面上填寫字段的螢幕快照。

2 - 建立資料表

接下來，您必須在 Azure Cosmos DB 帳戶內建立資料表以供應用程式使用。 與傳統資料庫不同的是，您只需要指定資料表的名稱，而無須指定資料表中的屬性 (資料行)。 當資料載入至資料表時，系統會視需要自動建立屬性 (資料行)。

在 Azure 入口網站中完成下列步驟，以在您的 Azure Cosmos DB 帳戶內建立資料表。

指示 Screenshot
在 Azure 入口網站中，瀏覽至 Azure Cosmos DB 帳戶的概觀頁面。 您可以在頂端的搜尋列中鍵入 Azure Cosmos DB 帳戶的名稱 (cosmos-msdocs-tables-sdk-demo-XYZ)，並在資源標題下方查看，以巡覽至您 Azure Cosmos DB 帳戶的概觀頁面。選取 Azure Cosmos DB 帳戶的名稱以前往概觀頁面。 螢幕快照，顯示如何使用頂端工具列中的搜尋方塊來尋找您的 Azure Cosmos DB 帳戶。
在概觀頁面上，選取 [+ 新增資料表]。 [新增資料表] 對話方塊會從頁面右側滑出。 顯示 [新增數據表] 按鈕位置的螢幕快照。
在 [新增資料表] 對話方塊中，以如下方式填寫表單。
  1. 在資料表識別碼中輸入名稱 WeatherData。 這是資料表的名稱。
  2. 在此範例中，選取 [資料表輸送量 (自動調整)] 下的 [手動]。
  3. 在預估 RU/秒中使用預設值 400。
  4. 選取 [確定] 按鈕以建立資料表。
 顯示如何為 Azure Cosmos DB 資料表新增數據表對話框的螢幕快照。

3 - 取得 Azure Cosmos DB 連接字串

您的應用程式需要有 CosmosDB 儲存體帳戶的資料表連接字串，才能存取您在 Azure Cosmos DB 中的資料表。 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 來擷取連接字串。

指示 Screenshot
在 [Azure Cosmos DB 帳戶] 頁面的左側，在 [設定] 標題下找出名為 [連接字串] 的功能表項目，然後將其選取。 系統會將您帶往一個頁面，您可以在其中擷取 Azure Cosmos DB 帳戶的連接字串。 顯示 Azure Cosmos DB 頁面上 連接字串 連結位置的螢幕快照。
複製要在應用程式中使用的「主要連接字串」值。 螢幕快照，顯示應用程式中要選取和使用 連接字串。

4 - 安裝適用於 JS 的 Azure 資料表 SDK

若要從 nodejs 應用程式存取 Azure Cosmos DB for Table，請安裝 Azure Data Tables SDK 套件。

  npm install @azure/data-tables

5 - 在 env.js 檔案中設定資料表用戶端

從 Azure 入口網站中複製 Azure Cosmos DB 或儲存體帳戶連接字串，並使用複製的連接字串建立 TableServiceClient 物件。 切換為資料夾 1-strater-app 或 2-completed-app。 然後，在 configure/env.js 檔案中新增對應環境變數的值。

const env = {
  connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
  tableName: "WeatherData",
};

Azure SDK 會使用用戶端物件來與 Azure 進行通訊，並藉此對 Azure 執行不同的作業。 TableClient 類別是用來與 Azure Cosmos DB for Table 通訊的類別。 應用程式通常會為每個資料表建立單一 serviceClient 物件，以便在整個應用程式中使用。

const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
  env.connectionString,
  env.tableName
);

6 - 實作 Azure Cosmos DB 資料表作業

範例應用程式的所有 Azure Cosmos DB 資料表作業都會在位於 [服務] 目錄下 tableClient.js 檔案的 serviceClient 物件中實作。

const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
  env.connectionString,
  env.tableName
);

從資料表取得資料列

serviceClient 物件中包含一個名為 listEntities 的方法，可讓您從資料表中選取資料列。 在此範例中，因為未將任何參數傳遞至方法，所以會從資料表中選取所有資料列。

const allRowsEntities = serviceClient.listEntities();

篩選從資料表傳回的資料列

若要篩選從資料表傳回的資料列，您可以將 OData 樣式篩選字串傳遞至 listEntities 方法。 例如，如果您想要取得在 2021 年 7 月 1 日午夜與 2021 年 7 月 2 日午夜 (含) 之間芝加哥的所有氣象讀數，您會傳入下列篩選字串。

PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00' and RowKey le '2021-07-02 12:00'

您可以在 OData 網站的篩選系統查詢選項區段中，檢視所有 OData 篩選運算子。

將 request.args 參數傳遞至 serviceClient 類別中的 listEntities 方法時，其會為每個非 null 的屬性值建立一個篩選字串。 然後其會將所有值與「and」子句聯結在一起，以建立出合併的篩選字串。 這個合併的篩選字串會傳遞至 serviceClient 物件上的 listEntities 方法，且僅會傳回符合篩選字串的資料列。 您可以在程式碼中使用類似的方法，藉此視您應用程式的需要來建構適當的篩選字串。

const filterEntities = async function (option) {
  /*
    You can query data according to existing fields
    option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
    minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
  */
  const filterEntitiesArray = [];
  const filters = [];
  if (option.partitionKey) {
    filters.push(`PartitionKey eq '${option.partitionKey}'`);
  }
  if (option.rowKeyDateTimeStart) {
    filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
  }
  if (option.rowKeyDateTimeEnd) {
    filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
  }
  if (option.minTemperature !== null) {
    filters.push(`Temperature ge ${option.minTemperature}`);
  }
  if (option.maxTemperature !== null) {
    filters.push(`Temperature le ${option.maxTemperature}`);
  }
  if (option.minPrecipitation !== null) {
    filters.push(`Precipitation ge ${option.minPrecipitation}`);
  }
  if (option.maxPrecipitation !== null) {
    filters.push(`Precipitation le ${option.maxPrecipitation}`);
  }
  const res = serviceClient.listEntities({
    queryOptions: {
      filter: filters.join(" and "),
    },
  });
  for await (const entity of res) {
    filterEntitiesArray.push(entity);
  }

  return filterEntitiesArray;
};

使用 TableEntity 物件插入資料

要將資料新增至資料表，最簡單的方法是使用 TableEntity 物件。 在此範例中，資料會從輸入模型物件對應至 TableEntity 物件。 輸入物件上代表氣象站名稱和觀察日期/時間的屬性會分別對應至 PartitionKey 和 RowKey 屬性，形成資料表中該資料列的唯一索引鍵。 然後，輸入模型物件上的其他屬性會對應到 TableEntity 物件上的字典屬性。 最後，在 serviceClient 物件上使用 createEntity 方法，將資料插入資料表中。

修改範例應用程式中的 insertEntity 函式以包含下列程式碼。

const insertEntity = async function (entity) {

  await serviceClient.createEntity(entity);

};

使用 TableEntity 物件來 upsert 資料

如果您嘗試使用已經存在於該資料表中的分割區索引鍵/資料列索引鍵組合，來將資料列插入資料表中，您將會收到錯誤訊息。 基於這個理由，在將資料列加入資料表時，通常最好使用 upsertEntity 來取代 createEntity 方法。 如果指定的分割區索引鍵/資料列索引鍵組合已存在於資料表中，upsertEntity 方法便會更新現有的資料列。 否則，便會將資料列新增至資料表中。

const upsertEntity = async function (entity) {

  await serviceClient.upsertEntity(entity, "Merge");

};

使用變數屬性插入或 upsert 資料

使用 Azure Cosmos DB for Table 的其中一項優點，就是如果載入資料表的物件包含任何新屬性，則這些屬性會自動新增至資料表，而值則會儲存在 Azure Cosmos DB 中。 您不需像在傳統資料庫中一樣，執行 ALTER TABLE 等 DDL 陳述式來新增資料行。

若之後因資料來源而需要新增或修改所需擷取的資料，或是當不同的輸入端為應用程式提供不同的資料時，這種模型可讓您的應用程式更有彈性。 在範例應用程式中，我們所模擬的氣象站不只能傳送基本的氣象資料，還有一些額外的值。 當具有這些新屬性的物件第一次儲存到資料表中時，對應的屬性 (資料行) 也會自動新增至資料表中。

若要使用資料表 API 插入或 upsert 這類物件，請將可展開物件的屬性對應至 TableEntity 物件，並適當地在 serviceClient 物件上使用 createEntity 或 upsertEntity 方法。

在範例應用程式中，upsertEntity 函式也可以使用變數屬性來實作插入或 upsert 資料的函式

const insertEntity = async function (entity) {
  await serviceClient.createEntity(entity);
};

const upsertEntity = async function (entity) {
  await serviceClient.upsertEntity(entity, "Merge");
};

更新實體

在 serviceClient 物件上呼叫 updateEntity 方法，即可更新實體。

在樣本應用程式中，這個物件會傳遞至 serviceClient 物件中的 upsertEntity 方法。 其會更新該實體物件，並使用 upsertEntity 方法來將更新儲存至資料庫。

const updateEntity = async function (entity) {
  await serviceClient.updateEntity(entity, "Replace");
};

7 - 執行程式碼

執行應用程式範例以與 Azure Cosmos DB for Table 互動。 您第一次執行應用程式時不會看到任何資料，因為資料表是空的。 使用應用程式頂端的任意按鈕來將資料新增至資料表。

應用程式的螢幕快照，其中顯示用來使用數據表 API 將資料插入 Azure Cosmos DB 的按鈕位置。

選取 [使用資料表實體插入] 按鈕後會開啟一個對話方塊，可讓您使用 TableEntity 物件來插入或 upsert 新的資料列。

應用程式的螢幕快照，其中顯示用來使用 TableEntity 物件插入數據的對話方塊。

選取 [使用可展開的資料插入] 按鈕後會顯示一個對話方塊，讓您使用自訂屬性插入物件，示範 Azure Cosmos DB for Table 如何在需要時自動將屬性 (資料行) 新增至資料表。 使用 [新增自訂欄位] 按鈕來新增一個或多個新的屬性，並示範這項功能。

應用程式的螢幕快照，其中顯示用來使用具有自定義欄位的物件插入數據的對話方塊。

使用 [插入範例資料] 按鈕，將部分範例資料載入您的 Azure Cosmos DB 資料表中。

應用程式的螢幕快照，其中顯示範例數據插入按鈕的位置。

選取頂端功能表中的 [篩選結果] 項目以移至 [篩選結果] 頁面。 在此頁面上，填寫篩選準則以示範如何建立篩選子句並將其傳遞至 Azure Cosmos DB for Table。

應用程式的螢幕快照，其中顯示篩選結果頁面，並醒目提示用來巡覽至頁面的功能表項。

清除資源

在您完成應用程式範例後，您應該從 Azure 帳戶中移除與此文章相關的所有 Azure 資源。 您可以藉由刪除資源群組來完成這項作業。

您可以執行下列動作來使用 Azure 入口網站刪除資源群組。

指示 Screenshot
若要移至資源群組，請在搜尋列中輸入該資源群組的名稱。 然後，在 [資源群組] 索引標籤上，選取該資源群組的名稱。 顯示如何搜尋資源群組的螢幕快照。
從資源群組頁面頂端的工具列中，選取 [刪除資源群組]。 顯示 [刪除資源群組] 按鈕位置的螢幕快照。
畫面右側會出現一個對話方塊，要求您確認是否要刪除資源群組。
  1. 依指示在文字輸入框中輸入資源群組的完整名稱以確認刪除。
  2. 選取頁面底部的 [刪除] 按鈕。
 顯示刪除資源群組之確認對話框的螢幕快照。

下一步

在本快速入門中，您已了解如何建立 Azure Cosmos DB 帳戶、如何使用資料總管來建立資料表，以及如何執行應用程式。 現在，您可以使用資料表 API 來查詢您的資料。

使用 API for Table 查詢 Azure Cosmos DB