你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 JavaScript 的 Azure 表客户端库 - 版本 13.2.2

Azure 表 是一种基于云的服务，用于存储结构化的 NoSQL 数据，提供具有无架构设计的密钥/属性存储。 表存储为开发人员提供了 Azure 云中所有最佳部件的灵活性和可伸缩性。

使用客户端库可以执行以下操作：

• 创建/删除表
• 查询/创建/读取/更新/删除实体

Azure Cosmos DB 为为 Azure 表存储编写的需要高级功能的应用程序提供表 API，例如：

• 统包式全局分发。
• 全球范围内专用的吞吐量。
• 99% 的情况下低至个位数的毫秒级延迟。
• 保证高可用性。
• 自动编制辅助索引。
• Azure 表客户端库可以无缝面向 Azure 表存储或 Azure Cosmos DB 表服务终结点，无需更改代码。

关键链接：

• 源代码
• 包 (NPM)
• API 参考文档
• 产品文档
• 示例

入门

先决条件

当前支持的环境：

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

必须具有 Azure 订阅 和 存储帐户 或 Azure CosmosDB 数据库 才能使用此包。

安装 @azure/data-tables 包

安装适用于 JavaScript 的 Azure 表客户端库的首选方法是使用 npm 包管理器。 在终端窗口中键入以下内容：

npm install @azure/data-tables

对 进行身份验证 TableServiceClient

Azure 表支持多种方式进行身份验证。 若要与 Azure 表服务交互，需要创建 Tables 客户端的实例， TableServiceClient 或者 TableClient 例如。 若要详细了解身份验证，TableServiceClient请参阅创建 的示例。

注意：仅 Azure 存储帐户支持 Azure Active Directory (AAD) 。

• 使用共享密钥的服务客户端
• 具有共享访问签名的服务客户端
• 具有 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 - 实体类似于行。 一个实体具有一个主键和一组属性。 属性与列类似，是一个名称/类型化值对。

表服务的常见用途包括：

• 存储 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 作为参数传递来实例化 TableServiceClient 。AzureNamedKeyCredential (可以从 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();

创建表客户端

TableClient的创建方式与 的创建方式类似，TableServiceClient区别在于TableClient采用表名作为参数

带 AzureNamedKeyCredential 的 TableClient

可以通过将 account-name 和 account-key 作为参数传递来实例化 TableClient 。AzureNamedKeyCredential (可从 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 令牌

可以使用共享访问签名 (SAS) 实例化 TableClient 。 可以从 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();

创建新实体并将其添加到表

可以通过调用 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 还适用于 Azurite，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 需要手动设置，以防 Azurite 在终结点中 http 运行。

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 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。

若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。