快速入門:使用 Node.js 與 Azure Cosmos DB 建置資料表 API 應用程式
適用於: 桌子
在本快速入門中,您會建立 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 帳戶。
2 - 建立資料表
接下來,您必須在 Azure Cosmos DB 帳戶內建立資料表以供應用程式使用。 與傳統資料庫不同的是,您只需要指定資料表的名稱,而無須指定資料表中的屬性 (資料行)。 當資料載入至資料表時,系統會視需要自動建立屬性 (資料行)。
在 Azure 入口網站中完成下列步驟,以在您的 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 來查詢您的資料。