適用於 JavaScript 的 Azure 數據表用戶端連結庫 - 13.3.0 版

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

使用用戶端連結庫來：

• 建立/刪除數據表
• 查詢/建立/讀取/更新/刪除實體

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

• 周全域散發。
• 全球專用輸送量。
• 第99個百分位數的單位數毫秒延遲。
• 保證高可用性。
• 自動進行次要索引編製。
• Azure 數據表用戶端連結庫可以順暢地以 Azure 數據表記憶體或 Azure Cosmos DB 數據表服務端點為目標，而不需要變更程式代碼。

主要連結：

• 原始程式碼
• 套件 （NPM）
• API 參考檔
• 產品檔
• 範例

開始

先決條件

目前支持的環境：

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

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

安裝 @azure/data-tables 套件

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

npm install @azure/data-tables

驗證 TableServiceClient

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

注意：Azure Active Directory （AAD） 僅支援 Azure 記憶體帳戶。

• 使用共用金鑰 服務用戶端
• 具有共用存取簽章的服務用戶端
• 使用 TokenCredential （AAD） 服務用戶端
• 具有共用金鑰的數據表用戶端
• 具有共用存取簽章的數據表用戶端
• 使用 TokenCredential 資料表用戶端 （AAD）

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

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

JavaScript 套件組合

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

CORS

如果您需要為瀏覽器進行開發，您必須為記憶體帳戶設定 跨原始資源分享 （CORS） 規則。 移至 Azure 入口網站和 Azure 記憶體總管，尋找您的記憶體帳戶，為 Blob/佇列/檔案/資料表服務建立新的 CORS 規則。

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

• 允許的來源： *
• 允許的動詞：DELETE、GET、HEAD、MERGE、POST、OPTIONS、PUT
• 允許的標頭： *
• 公開的標頭： *
• 年齡上限（秒）：86400

重要概念

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

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

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

• Entity - 實體類似於數據列。 實體具有主鍵和一組屬性。 屬性是名稱、具型別值組，類似於數據行。

資料表服務的常見用法包括：

• 儲存能夠為 Web 規模應用程式提供服務的結構化資料BS
• 儲存不需要複雜聯結、外鍵或預存程序的數據集，而且可以還原正規化以快速存取
• 使用叢集索引快速查詢數據
• 使用 OData 通訊協定篩選表達式存取數據

例子

• 匯入套件
• 建立數據表服務用戶端
  • 帳戶中的清單數據表
  • 建立新的數據表
• 建立數據表用戶端
  • 列出數據表中的實體
  • 建立新的實體，並將它新增至數據表

匯入套件

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

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

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

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

建立數據表服務用戶端

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

使用 AzureNamedKeyCredential TableServiceClient

您可以藉由將 account-name 和 account-key 作為自變數，以 AzureNamedKeyCredential 具現化 TableServiceClient。 （帳戶名稱和帳戶密鑰可以從 Azure 入口網站取得。[僅適用於NODE.JS運行時間]

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
);

搭配 TokenCredential TableServiceClient （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
);

使用SAS令牌 TableServiceClient

此外，您可以使用共用存取簽章來具現化 TableServiceClient（SAS）。 您可以從 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 實例，列出帳戶內的數據表。 此函式會傳回您可以使用 for-await-of 取用的 PageableAsyncIterator

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 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();

建立數據表用戶端

TableClient 的建立方式與 TableServiceClient 類似，TableClient 採用數據表名稱做為參數的差異

具有 AzureNamedKeyCredential 的 TableClient

您可以藉由將 account-name 和 account-key 作為自變數，以 AzureNamedKeyCredential 具現化 TableClient。 （帳戶名稱和帳戶密鑰可以從 Azure 入口網站取得。[僅適用於NODE.JS運行時間]

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);

使用 TokenCredentialTableClient （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
);

使用SAS令牌 TableClient

您可以使用共用存取簽章來具現化 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)
);

搭配 TokenCredential TableClient （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
);

列出數據表中的實體

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

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 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();

建立新的實體，並將其新增至數據表

您可以透過呼叫 createEntity 函式的 TableClient 實例，在數據表中建立新的 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 也適用於 Azure 記憶體和資料表 API 相容的伺服器模擬器 Azurite。 如需如何開始使用，請參閱 （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，而不需使用連接字串快捷方式。 不過，如果 Azurite 在 http 端點中執行，則必須手動設定 allowInsecureConnection。

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開放原始碼。 如需詳細資訊，請參閱 《行為規範》常見問題 或連絡 opencode@microsoft.com，以取得任何其他問題或意見。

如果您想要參與此連結庫，請閱讀 參與指南，以深入瞭解如何建置和測試程序代碼。