快速入門：使用 Node.js 與 Azure Cosmos DB 建置資料表 API 應用程式
適用於：
Table
在本快速入門中，您會建立 Azure Cosmos DB for Table 帳戶，並使用資料總管和從 GitHub 複製的 Node.js 應用程式來建立資料表和實體。 Azure Cosmos DB 是多模型的資料庫服務，可讓您快速建立及查詢具有全域散發和水平調整功能的文件、資料表、索引鍵/值及圖形資料庫。
必要條件
- 具有有效訂用帳戶的 Azure 帳戶。 免費建立一個。
- Node.js 0.10.29+。
- Git。
範例應用程式
本教學課程的應用程式範例可從存放庫 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 的無架構功能。
1 - 建立 Azure Cosmos DB 帳戶
您必須先建立 Azure Cosmos DB 資料表 API 帳戶，其中會包含您應用程式中所使用的資料表。 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 來完成此操作。
登入 Azure 入口網站，並遵循下列步驟來建立 Azure Cosmos DB 帳戶。
| 指示 | Screenshot |
|---|---|
在 Azure 入口網站中:
|
|
| 在 [Azure Cosmos DB] 頁面上，選取 [+ 建立]。 | 
|
| 在 [選取 API 選項] 頁面上，選擇 [Azure 資料表] 選項。 | 
|
在 [建立 Azure Cosmos DB 帳戶 - Azure 資料表] 頁面上，以如下方式填寫表單。
|
|
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 帳戶的名稱以前往概觀頁面。 | 
|
| 在概觀頁面上，選取 [+ 新增資料表]。 [新增資料表] 對話方塊會從頁面右側滑出。 | 
|
在 [新增資料表] 對話方塊中，以如下方式填寫表單。
|
|
3 - 取得 Azure Cosmos DB 連接字串
您的應用程式需要有 CosmosDB 儲存體帳戶的資料表連接字串，才能存取您在 Azure Cosmos DB 中的資料表。 您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 來擷取連接字串。
| 指示 | Screenshot |
|---|---|
| 在 [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 互動。 您第一次執行應用程式時不會看到任何資料，因為資料表是空的。 使用應用程式頂端的任意按鈕來將資料新增至資料表。
選取 [使用資料表實體插入] 按鈕後會開啟一個對話方塊，可讓您使用 TableEntity 物件來插入或 upsert 新的資料列。
選取 [使用可展開的資料插入] 按鈕後會顯示一個對話方塊，讓您使用自訂屬性插入物件，示範 Azure Cosmos DB for Table 如何在需要時自動將屬性 (資料行) 新增至資料表。 使用 [新增自訂欄位] 按鈕來新增一個或多個新的屬性，並示範這項功能。
使用 [插入範例資料] 按鈕，將部分範例資料載入您的 Azure Cosmos DB 資料表中。
選取頂端功能表中的 [篩選結果] 項目以移至 [篩選結果] 頁面。 在此頁面上，填寫篩選準則以示範如何建立篩選子句並將其傳遞至 Azure Cosmos DB for Table。
清除資源
在您完成應用程式範例後，您應該從 Azure 帳戶中移除與此文章相關的所有 Azure 資源。 您可以藉由刪除資源群組來完成這項作業。
您可以執行下列動作來使用 Azure 入口網站刪除資源群組。
| 指示 | Screenshot |
|---|---|
| 若要移至資源群組，請在搜尋列中輸入該資源群組的名稱。 然後，在 [資源群組] 索引標籤上，選取該資源群組的名稱。 | 
|
| 從資源群組頁面頂端的工具列中，選取 [刪除資源群組]。 | 
|
畫面右側會出現一個對話方塊，要求您確認是否要刪除資源群組。
|
|
下一步
在本快速入門中，您已了解如何建立 Azure Cosmos DB 帳戶、如何使用資料總管來建立資料表，以及如何執行應用程式。 現在，您可以使用資料表 API 來查詢您的資料。