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

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

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 表服务交互，需要创建表客户端的实例 - 例如，TableServiceClient 或 TableClient。 请参阅 示例，了解如何创建 TableServiceClient，了解有关身份验证的详细信息。

注意：Azure Active Directory（AAD）仅支持 Azure 存储帐户。

• 使用共享密钥 服务客户端
• 具有共享访问签名的服务客户端
• 使用 TokenCredential 服务客户端
• 使用共享密钥的表客户端
• 具有共享访问签名的表客户端
• 使用 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 缩放应用程序提供服务的结构化数据的 TB
• 存储不需要复杂联接、外键或存储过程的数据集，并且可以取消规范化以便快速访问
• 使用聚集索引快速查询数据
• 使用 OData 协议筛选器表达式访问数据

例子

• 导入包
• 创建表服务客户端
  • 列出帐户 中的表
  • 创建新表
• 创建表客户端
  • 表 中的“列出实体”
  • 创建新实体并将其添加到表

导入包

若要使用客户端，请在文件中导入包：

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

或者，选择性地仅导入所需的类型：

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

创建表服务客户端

TableServiceClient 需要表服务和访问凭据的 URL。 它还可以选择接受 options 参数中的某些设置。

使用 AzureNamedKeyCredential TableServiceClient

可以通过将帐户名称和帐户密钥作为参数来实例化具有 AzureNamedKeyCredential 的 TableServiceClient。 （可以从 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
);

使用 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

此外，还可以使用共享访问签名（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 实例列出帐户中的表。 此函数返回可以使用 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 采用表名称作为参数

使用 AzureNamedKeyCredentialTableClient

可以通过将帐户名称和帐户密钥作为参数来实例化具有 AzureNamedKeyCredential 的 TableClient。 （可以从 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);

使用 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

可以使用共享访问签名（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)
);

使用 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 实例在表中创建新实体。 此函数采用实体作为参数插入。 实体必须包含 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 Tables 客户端 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 机器人会自动确定是否需要提供 CLA 并适当修饰 PR（例如标签、注释）。 只需按照机器人提供的说明进行操作。 只需使用 CLA 在所有存储库中执行此操作一次。

该项目已采用 Microsoft开源行为准则。 有关详细信息，请参阅 行为准则常见问题解答 或与 opencode@microsoft.com 联系，了解任何其他问题或意见。

若要参与此库，请阅读 贡献指南 了解有关如何生成和测试代码的详细信息。