如何使用 Azure 資料表記憶體或 Azure Cosmos DB for Table from Node.js

發行項
02/06/2024

適用於： Table

提示

本文的內容適用於 Azure 資料表記憶體和適用於資料表的 Azure Cosmos DB。 Table 的 API 是數據表記憶體的進階供應專案，可提供輸送量優化的數據表、全域散發和自動次要索引。

本文說明如何建立數據表、儲存數據，以及對上述數據執行 CRUD 作業。這些範例是以Node.js撰寫。

建立 Azure 服務帳戶

您可以使用 Azure 資料表記憶體或 Azure Cosmos DB 來處理資料表。若要深入瞭解這兩個服務中的數據表供應專案之間的差異，請參閱 API for Table 概觀。您必須為要使用的服務建立帳戶。下列各節說明如何建立 Azure 數據表記憶體和 Azure Cosmos DB 帳戶，不過您只能使用其中一個帳戶。

建立 Azure 儲存體帳戶

建立 Azure 記憶體帳戶最簡單的方式是使用 Azure 入口網站。若要深入了解，請參閱建立儲存體帳戶。

您也可以使用 Azure PowerShell 或 Azure CLI 來建立 Azure 記憶體帳戶。

如果您目前不想建立記憶體帳戶，您也可以使用 Azure 儲存體模擬器在本機環境中執行及測試程序代碼。如需詳細資訊，請參閱使用 Azure 儲存體模擬器進行開發和測試。

建立適用於數據表帳戶的 Azure Cosmos DB

如需建立適用於數據表帳戶的 Azure Cosmos DB 的指示，請參閱建立資料庫帳戶。

設定您的應用程式以存取資料表儲存體

若要使用 Azure 儲存體或 Azure Cosmos DB，您需要 azure Tables SDK for Node.js，其中包含一組與儲存體 REST 服務通訊的便利連結庫。

使用 Node 封裝管理員（NPM）安裝套件

使用命令行介面，例如 PowerShell （Windows）、 終端機 （Mac）或 Bash （Unix），並流覽至您建立應用程式的資料夾。
在指令視窗中輸入下列內容：

   npm install @azure/data-tables

您可以手動執行 ls 命令，以確認 已建立node_modules 資料夾。在該資料夾內，您會發現 @azure/資料表 套件，其中包含您需要存取數據表的連結庫。

匯入套件

將下列程式代碼新增至應用程式中server.js檔案頂端：

const { TableServiceClient, TableClient, AzureNamedKeyCredential, odata } = require("@azure/data-tables");

連線至 Azure 數據表服務

您可以連線到 Azure 記憶體帳戶或適用於資料表帳戶的 Azure Cosmos DB。根據您使用的帳戶類型取得共用金鑰或連接字串。

從共用金鑰建立資料表服務用戶端

Azure 模組會讀取環境變數AZURE_ACCOUNT和AZURE_ACCESS_KEY和AZURE_TABLES_ENDPOINT，以取得連線到 Azure 儲存體帳戶或 Azure Cosmos DB 所需的資訊。如果未設定這些環境變數，您必須在呼叫 TableServiceClient時指定帳戶資訊。例如，下列程式代碼會 TableServiceClient 建立物件：

const endpoint = "<table-endpoint-uri>";
const credential = new AzureNamedKeyCredential(
  "<account-name>",
  "<account-key>"
);

const tableService = new TableServiceClient(
  endpoint,
  credential
);

從連接字串建立數據表服務用戶端

若要新增 Azure Cosmos DB 或儲存體帳戶連線，請建立 TableServiceClient 物件並指定您的帳戶名稱、主鍵和端點。您可以在 Azure Cosmos DB 帳戶或儲存體帳戶的 Azure 入口網站中，從 設定> 連線 ion String 複製這些值。例如：

const tableService = TableServiceClient.fromConnectionString("<connection-string>");

建立表格

的呼叫 createTable 會建立具有指定名稱的新數據表，如果它不存在的話。如果 'mytable' 不存在，下列範例會建立名為 'mytable' 的新數據表：

await tableService.createTable('<table-name>');

建立數據表用戶端

若要與數據表互動，您應該使用用來建立的相同認證來建立 TableClientTableServiceClient物件。 TableClient也需要目標數據表的名稱。

const tableClient = new TableClient(
  endpoint,
  '<table-name>',
  credential
);

將實體新增至資料表

若要新增實體，請先建立定義實體屬性的物件。所有實體都必須包含 partitionKey 和 rowKey，這是實體的唯一標識碼。

partitionKey - 決定實體儲存所在的分割區。
rowKey - 唯一識別數據分割內的實體。

partitionKey 和rowKey都必須是字串值。

以下是定義實體的範例。 dueDate 定義為的型別Date。指定類型是選擇性的，如果未指定，則會推斷類型。

const task = {
  partitionKey: "hometasks",
  rowKey: "1",
  description: "take out the trash",
  dueDate: new Date(2015, 6, 20)
};

注意

每個記錄也有一個 Timestamp 欄位，當插入或更新實體時，Azure 會設定此欄位。

若要將實體新增至數據表，請將實體對象傳遞至 createEntity 方法。

let result = await tableClient.createEntity(task);
    // Entity create

如果作業成功， result 則包含 ETag 和作業的相關信息。

範例回應：

{ 
  clientRequestId: '94d8e2aa-5e02-47e7-830c-258e050c4c63',
  requestId: '08963b85-1002-001b-6d8c-12ae5d000000',
  version: '2019-02-02',
  date: 2022-01-26T08:12:32.000Z,
  etag: `W/"datetime'2022-01-26T08%3A12%3A33.0180348Z'"`,
  preferenceApplied: 'return-no-content',
  'cache-control': 'no-cache',
  'content-length': '0'
}

更新實體

和 upsertEntity 方法的不同模式updateEntity

合併：藉由更新實體的屬性而不取代現有的實體，以更新實體。
取代：藉由取代整個實體，更新現有的實體。

下列範例示範如何使用 upsertEntity來更新實體：

// Entity doesn't exist in table, so calling upsertEntity will simply insert the entity.
let result = await tableClient.upsertEntity(task, "Replace");

如果正在更新的實體不存在，則更新作業會失敗;因此，如果您想要儲存實體，而不論實體是否存在，請使用 upsertEntity。

result成功更新作業的包含已更新實體的 Etag。

使用實體群組

有時候，在批次中一起提交多個作業是合理的，以確保伺服器不可部分完成的處理。若要達成此目的，請建立作業數位，並將它傳遞至 submitTransaction 上的 TableClient方法。

下列範例示範如何在批次中提交兩個實體：

const task1 = {
  partitionKey: "hometasks",
  rowKey: "1",
  description: "Take out the trash",
  dueDate: new Date(2015, 6, 20)
};
const task2 = {
  partitionKey: "hometasks",
  rowKey: "2",
  description: "Wash the dishes",
  dueDate: new Date(2015, 6, 20)
};

const tableActions = [
  ["create", task1],
  ["create", task2]
];

let result = await tableClient.submitTransaction(tableActions);
    // Batch completed

針對成功的批次作業， result 包含批次中每個作業的資訊。

依索引鍵擷取實體

若要根據 PartitionKey 和 RowKey 傳回特定實體，請使用 getEntity 方法。

let result = await tableClient.getEntity("hometasks", "1")
  .catch((error) => {
    // handle any errors
  });
  // result contains the entity

完成此作業之後， result 會包含實體。

查詢一組實體

下列範例會建置查詢，以傳回前五個專案的 PartitionKey 為 'hometasks'，並列出數據表中的所有實體。

const topN = 5;
const partitionKey = "hometasks";

const entities = tableClient.listEntities({
  queryOptions: { filter: odata`PartitionKey eq ${partitionKey}` }
});

let topEntities = [];
const iterator = entities.byPage({ maxPageSize: topN });

for await (const page of iterator) {
  topEntities = page;
  break;
}

// Top entities: 5
console.log(`Top entities: ${topEntities.length}`);

// List all the entities in the table
for await (const entity of entities) {
console.log(entity);
}

查詢實體屬性的子集

數據表的查詢只能從實體擷取幾個欄位。這可減少頻寬，並可改善查詢效能，特別是針對大型實體。 使用 select 子句，並傳遞要傳回的功能變數名稱。例如，下列查詢只會 傳回 description 和 dueDate 字段。

const topN = 5;
const partitionKey = "hometasks";

const entities = tableClient.listEntities({
  queryOptions: { filter: odata`PartitionKey eq ${partitionKey}`,
                  select: ["description", "dueDate"]  }
});

let topEntities = [];
const iterator = entities.byPage({ maxPageSize: topN });

for await (const page of iterator) {
  topEntities = page;
  break;
}

刪除實體

您可以使用實體的數據分割和數據列索引鍵來刪除實體。在此範例中 ，task1 物件包含 要刪除之實體的rowKey 和 partitionKey 值。然後，對象會傳遞至 deleteEntity 方法。

const tableClient = new TableClient(
  tablesEndpoint,
  tableName,
  new AzureNamedKeyCredential("<accountName>", "<accountKey>")
);

await tableClient.deleteEntity("hometasks", "1");
    // Entity deleted

注意

請考慮在刪除專案時使用ETag，以確保專案尚未由另一個進程修改。如需使用ETag 的資訊，請參閱更新實體。

刪除資料表

下列程式代碼會從記憶體帳戶刪除數據表。

await tableClient.deleteTable(mytable);
        // Table deleted

使用接續令牌

當您查詢數據表以取得大量結果時，請尋找接續令牌。您的查詢可能會有大量數據可供您瞭解，如果您未建置來辨識接續令牌存在時，可能無法辨識。

查詢 實體期間傳回的結果 物件會在這類令牌存在時設定 continuationToken 屬性。接著，您可以在執行查詢時使用此專案，以繼續跨分割區和數據表實體移動。

查詢時，您可以在查詢物件實例與回調函式之間提供 continuationToken 參數：

let iterator = tableClient.listEntities().byPage({ maxPageSize: 2 });
let interestingPage;

const page = await tableClient
   .listEntities()
   .byPage({ maxPageSize: 2, continuationToken: interestingPage })
   .next();

 if (!page.done) {
   for (const entity of page.value) {
     console.log(entity.rowKey);
   }
 }

使用共用存取簽章

共用存取簽章（SAS）是一種安全的方式，可提供對數據表的細微存取，而不需要提供儲存體帳戶名稱或密鑰。 SAS 通常用來提供數據的有限存取權，例如允許行動應用程式查詢記錄。

雲端式服務之類的受信任應用程式會使用 TableClient 的 generateTableSas 來產生 SAS，並將它提供給不受信任的或半信任的應用程式，例如行動應用程式。 SAS 是使用原則所產生，其描述 SAS 有效期間的開始和結束日期，以及授與 SAS 持有者的存取層級。

下列範例會產生新的共用存取原則，以允許 SAS 持有者查詢資料表（'r'）。

const tablePermissions = {
    query: true
// Allows querying entities
};

// Create the table SAS token
const tableSAS = generateTableSas('mytable', cred, {
  expiresOn: new Date("2022-12-12"),
  permissions: tablePermissions
});

用戶端應用程式接著會使用SAS搭配 AzureSASCredential 來執行數據表的作業。下列範例會連線到數據表並執行查詢。如需 tableSAS 的格式，請參閱使用共用存取簽章（SAS）將有限的存取權授與 Azure 儲存體資源一文。

// Note in the following command, tablesUrl is in the format: `https://<your_storage_account_name>.table.core.windows.net` and the tableSAS is in the format: `sv=2018-03-28&si=saspolicy&tn=mytable&sig=9aCzs76n0E7y5BpEi2GvsSv433BZa22leDOZXX%2BXXIU%3D`;

const tableService = new TableServiceClient(tablesUrl, new AzureSASCredential(tableSAS));
const partitionKey = "hometasks";

const entities = tableService.listTables({
  queryOptions: { filter: odata`PartitionKey eq ${partitionKey}` }
});

由於 SAS 只產生查詢存取權，因此如果您嘗試插入、更新或刪除實體，則會傳回錯誤。

存取控制清單

您也可以使用存取控制清單（ACL）來設定 SAS 的存取原則。如果您想要允許多個用戶端存取數據表，但為每個用戶端提供不同的存取原則，這會很有用。

ACL 是使用存取原則陣列來實作，且標識碼與每個原則相關聯。下列範例會定義兩個原則，一個用於 'user1'，另一個用於 'user2'：

var sharedAccessPolicy = [{
  id:"user1",
  accessPolicy:{
    permission: "r" ,
    Start: startsOn,
    Expiry: expiresOn,
  }},
  {
  id:"user2",
  accessPolicy:{
    permissions: "a",
    Start: startsOn,
    Expiry: expiresOn,
  }},
]

下列範例會取得 hometasks 數據表目前的 ACL，然後使用 setAccessPolicy 加入新的原則。此方法允許：

tableClient.getAccessPolicy();
tableClient.setAccessPolicy(sharedAccessPolicy);

設定 ACL 之後，您就可以根據原則的標識碼建立 SAS。下列範例會為 'user2' 建立新的 SAS：

tableSAS = generateTableSas("hometasks",cred,{identifier:'user2'});

下一步

如需詳細資訊，請參閱下列資源。

Microsoft Azure 儲存體總管是一個免費的獨立應用程式，可讓您在 Windows、MacOS 和 Linux 上以視覺化方式處理 Azure 儲存體資料。
GitHub 上適用於 Node.js 存放庫的 Azure Data Tables SDK。
在 Azure 中建立 Node.js Web 應用程式
建置Node.js應用程式並將其部署至 Azure 雲端服務（使用 Windows PowerShell）