共用方式為

適用于 JavaScript 的 Azure 資料表用戶端程式庫 - 13.2.2 版

  • 發行項

Azure 資料表 是一種雲端式服務，可儲存結構化的 NoSQL 資料，並提供無架構設計的索引鍵/屬性存放區。 資料表儲存體可為開發人員提供 Azure 雲端所有最佳部分的彈性和延展性。

使用用戶端程式庫可以：

  • 建立/刪除資料表
  • 查詢/建立/讀取/更新/刪除實體

Azure Cosmos DB 針對針對 Azure 資料表儲存體所撰寫的應用程式，以及需要進階功能的應用程式提供資料表 API，例如：

  • 周全的全域發佈。
  • 全球專用的輸送量。
  • 99 百分位數的單一數字毫秒延遲。
  • 保證高可用性。
  • 自動次要索引。
  • Azure 資料表用戶端程式庫可以順暢地以 Azure 資料表儲存體或 Azure Cosmos DB 資料表服務端點為目標，而不需要變更程式碼。

重要連結：

開始使用

Prerequisites

目前支援的環境：

  • Node.js 的 LTS 版本
  • 最新版 Safari、Chrome、Edge 和 Firefox

您必須擁有 Azure 訂 用 帳戶和儲存體帳戶 或 Azure CosmosDB 資料庫 ，才能使用此套件。

安裝 @azure/data-tables 套件

安裝適用于 JavaScript 的 Azure Tables 用戶端程式庫的慣用方式是使用 npm 套件管理員。 在終端機視窗中輸入下列內容：

npm install @azure/data-tables

驗證 TableServiceClient

Azure 資料表支援數種方式進行驗證。 若要與 Azure 資料表服務互動，您必須建立 Tables 用戶端的實例， TableServiceClient 例如 TableClient 。 請參閱建立 TableServiceClient 的範例，以深入瞭解驗證。

注意：Azure Active Directory (AAD) 僅支援 Azure 儲存體帳戶。

下列功能、介面、類別或函式僅適用于 Node.js

  • 根據帳戶名稱和帳戶金鑰的共用金鑰授權
    • AzureNamedKeyCredential
    • 帳戶連接字串。

JavaScript 套件組合

若要在瀏覽器中使用此用戶端程式庫，您必須先使用套件組合器。 如需如何執行這項操作的詳細資訊，請參閱我們的 統合檔。

CORS

如果您需要針對瀏覽器進行開發，您必須為儲存體帳戶設定 跨原始來源資源分享 (CORS) 規則。 移至Azure 入口網站和Azure 儲存體總管，尋找您的儲存體帳戶，為 blob/queue/file/table 服務建立新的 CORS 規則， (s) 。

例如，您可以建立下列 CORS 設定以進行偵錯。 但請根據生產環境中的需求，仔細自訂設定。

  • 允許的來源： *
  • 允許的動詞：DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
  • 允許的標頭： *
  • 公開標頭：*
  • 最長 (秒) ：86400

重要概念

  • TableServiceClient - 提供函式以在資料表服務層級互動的用戶端，例如建立、列出和刪除資料表

  • TableClient - 提供函式在實體層級互動的用戶端，例如在資料表內建立、列出和刪除實體。

  • Table - 資料表會將資料儲存為實體集合。

  • Entity - 實體類似于資料列。 實體包含主索引鍵和一組屬性。 屬性是名稱與具類型值組，類似資料行。

資料表服務的一般用途包括：

  • 儲存好幾 TB 的結構化資料，足以供應 Web 規模的應用程式所需
  • 儲存不需要複雜聯結、外鍵或預存程式的資料集，而且可以取消正規化以快速存取
  • 使用叢集索引來快速查詢資料
  • 使用 OData 通訊協定篩選運算式存取資料

範例

匯入封裝

若要使用用戶端，請在您的檔案中匯入套件：

const AzureTables = require("@azure/data-tables");

或者，選擇性地只匯入您需要的類型：

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

建立表格服務用戶端

TableServiceClient需要資料表服務的 URL 和存取認證。 它也選擇性地接受 參數中的 options 某些設定。

TableServiceClient 搭配 AzureNamedKeyCredential

您可以傳遞 account-name 和 account-key 作為引數，以具現化 TableServiceClientAzureNamedKeyCredential 。 (您可以從 azure 入口網站取得帳戶名稱和帳戶金鑰。) [僅適用于 NODE.JS RUNTIME]

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

TableServiceClient 使用 TokenCredential (AAD)

Azure 資料表提供與 Azure Active Directory (Azure) AD 的整合，以在以儲存體端點為目標時，針對資料表服務的要求進行身分識別型驗證。 透過 Azure AD，您可以使用角色型存取控制 (RBAC) ，將 Azure 資料表資源的存取權授與使用者、群組或應用程式。

若要使用 TokenCredential 存取資料表資源，已驗證的身分識別應該具有「儲存體資料表資料參與者」或「儲存體資料表資料讀取者」角色。

@azure/identity透過套件，您可以在開發和生產環境中順暢地授權要求。 若要深入瞭解 Azure 儲存體中的 Azure AD 整合，請參閱 Azure.Identity 讀我檔案

const { TableServiceClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";

const clientWithAAD = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

TableServiceClient 使用 SAS 權杖

此外，您也可以使用共用存取簽章 (SAS) 具現化 TableServiceClient 。 您可以從 Azure 入口網站取得 SAS 權杖。

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

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const serviceClientWithSAS = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  new AzureSASCredential(sas)
);

列出帳戶中的資料表

您可以透過呼叫 函 listTables 式的 TableServiceClient 實例，列出帳戶內的資料表。 此函式會傳 PageableAsyncIterator 回您可以使用 的 for-await-of

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  let tablesIter = serviceClient.listTables();
  let i = 1;
  for await (const table of tablesIter) {
    console.log(`Table${i}: ${table.name}`);
    i++;
    // Output:
    // Table1: testTable1
    // Table1: testTable2
    // Table1: testTable3
    // Table1: testTable4
    // Table1: testTable5
  }
}

main();

建立新的資料表

您可以透過呼叫 函式的 createTable 實例建立 TableServiceClient 資料表。 此函式會採用要建立的資料表名稱做為參數。 請注意， createTable 當資料表已經存在時，不會擲回錯誤。

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tableName = `newtable`;
  // If the table 'newTable' already exists, createTable doesn't throw
  await serviceClient.createTable(tableName);
}

main();

以下是示範如何在嘗試建立資料表時測試資料表是否存在的範例：

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tableName = `newtable${new Date().getTime()}`;
  await serviceClient.createTable(tableName, {
    onResponse: (response) => {
      if (response.status === 409) {
        console.log(`Table ${tableName} already exists`);
      }
    }
  });
}

main();

建立資料表用戶端

會以類似 的方式 TableServiceClient 建立 ， TableClient 其差異 TableClient 會採用資料表名稱做為參數

AzureNamedKeyCredential 的 TableClient

您可以傳遞 account-name 和 account-key 作為引數，以具現化 TableClientAzureNamedKeyCredential 。 (可以從 azure 入口網站取得帳戶名稱和帳戶金鑰。) [只能在 NODE.JS RUNTIME 中使用]

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

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

// Use AzureNamedKeyCredential with storage account and account key
// AzureNamedKeyCredential is only available in Node.js runtime, not in browsers
const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

TableClient (TokenCredential Azure Active Directory)

Azure 資料表提供與 Azure Active Directory (Azure AD) 的整合，以在以儲存體端點為目標時，對資料表服務的要求進行身分識別式驗證。 透過 Azure AD，您可以使用角色型存取控制 (RBAC) ，將 Azure 資料表資源的存取權授與使用者、群組或應用程式。

若要使用 TokenCredential 存取資料表資源，已驗證的身分識別應該具有「儲存體資料表資料參與者」或「儲存體資料表資料讀取者」角色。

@azure/identity透過套件，您可以在開發和生產環境中順暢地授權要求。 若要深入瞭解 Azure 儲存體中的 Azure AD 整合，請參閱 Azure.Identity 讀我檔案

const { TableClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";
const tableName = "<tableName>";

const clientWithAAD = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  credential
);

TableClient 使用 SAS 權杖

您可以使用共用存取簽章來具 TableClient 現化 ， (SAS) 。 您可以從 Azure 入口網站取得 SAS 權杖。

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

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const tableName = "<tableName>";

const clientWithSAS = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  new AzureSASCredential(sas)
);

TableClient 使用 TokenCredential (AAD)

Azure 資料表提供與 Azure Active Directory (Azure AD) 的整合，以在以儲存體端點為目標時，對資料表服務的要求進行身分識別式驗證。 透過 Azure AD，您可以使用角色型存取控制 (RBAC) ，將 Azure 資料表資源的存取權授與使用者、群組或應用程式。

若要使用 TokenCredential 存取資料表資源，已驗證的身分識別應該具有「儲存體資料表資料參與者」或「儲存體資料表資料讀取者」角色。

@azure/identity透過套件，您可以在開發和生產環境中順暢地授權要求。 若要深入瞭解 Azure 儲存體中的 Azure AD 整合，請參閱 Azure.Identity 讀我檔案

const { TableClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";
const tableName = "<tableName>";

const clientWithAAD = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  credential
);

列出資料表中的實體

您可以透過 TableClient 呼叫 函式的 listEntities 實例，列出資料表內的實體。 此函式會傳 PageableAsyncIterator 回您可以使用 的 for-await-of

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

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

async function main() {
  let entitiesIter = client.listEntities();
  let i = 1;
  for await (const entity of entitiesIter) {
    console.log(`Entity${i}: PartitionKey: ${entity.partitionKey} RowKey: ${entity.rowKey}`);
    i++;
    // Output:
    // Entity1: PartitionKey: P1 RowKey: R1
    // Entity2: PartitionKey: P2 RowKey: R2
    // Entity3: PartitionKey: P3 RowKey: R3
    // Entity4: PartitionKey: P4 RowKey: R4
  }
}

main();

建立新的實體，並將其新增至資料表

您可以透過 TableClient 呼叫 createEntity 函式的 實例，在資料表中建立新的 Entity。 此函式會採用實體來插入做為參數。 實體必須包含 partitionKey 和 rowKey 。

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

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

async function main() {
  const testEntity = {
    partitionKey: "P1",
    rowKey: "R1",
    foo: "foo",
    bar: 123
  };
  await client.createEntity(testEntity);
}

main();

Azurite 和儲存體模擬器

Azure 資料表用戶端 SDK 也適用于 Azurite，這是 Azure 儲存體和資料表 API 相容的伺服器模擬器。 請參閱 (Azurite 存放庫) 瞭解如何開始使用。

使用連接字串快捷方式連接到 Azurite

從您的應用程式連線到 Azurite 的最簡單方式是設定參考快捷方式 UseDevelopmentStorage=true 的連接字串。 快捷方式相當於模擬器的完整連接字串，它會指定每個 Azure 儲存體服務的帳戶名稱、帳戶金鑰和模擬器端點： (查看更多) 。 使用此快捷方式，Azure 資料表用戶端 SDK 會在用戶端選項中設定預設連接字串和 allowInsecureConnection 。

import { TableClient } from "@azure/data-tables";

const connectionString = "UseDevelopmentStorage=true";
const client = TableClient.fromConnectionString(connectionString, "myTable");

在沒有連接字串快捷方式的情況下連接到 Azurite

您可以藉由指定服務 URL 和 AzureNamedKeyCredential 或自訂連接字串，手動連線到 azurite，而不使用連接字串快捷方式。 不過， allowInsecureConnection 在端點中 http 執行 Azurite 時，必須手動設定。

import { TableClient, AzureNamedKeyCredential } from "@azure/data-tables";

const client = new TableClient(
  "<Azurite-http-table-endpoint>",
  "myTable",
  new AzureNamedKeyCredential("<Azurite-account-name>", "<Azurite-account-key>"),
  { allowInsecureConnection: true }
);

疑難排解

一般

當您使用 JAVAscript/Typescript SDK 與資料表服務互動時，服務傳回的錯誤會對應至針對 REST API 要求傳回的相同 HTTP 狀態碼： 儲存體資料表服務錯誤碼

記錄

啟用記錄有助於找出失敗的相關實用資訊。 若要查看 HTTP 的要求和回應記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。 或者，您可以在 @azure/logger 中呼叫 setLogLevel，以在執行階段啟用記錄：

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

後續步驟

即將推出更多程式碼範例問題#10531

參與

此專案歡迎參與和提供建議。 大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。 如需詳細資料，請前往 https://cla.microsoft.com 。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。 如需詳細資訊，請參閱管理辦法常見問題集，如有任何其他問題或意見請連絡 opencode@microsoft.com。

如果您希望向此程式庫投稿，請參閱投稿指南，深入瞭解如何組建與測試程式碼。

曝光數