Клиентская библиотека Azure Tables для JavaScript — версия 13.3.1

2025-06-02

таблицах Azure — это облачная служба, которая хранит структурированные данные NoSQL, предоставляя хранилище ключей и атрибутов без схемы. Хранилище таблиц обеспечивает разработчикам гибкость и масштабируемость со всеми лучшими частями облака Azure.

Использование клиентской библиотеки для:

Создание и удаление таблиц
Запрос/ создание, чтение, обновление и удаление сущностей

Azure Cosmos DB предоставляет API таблиц для приложений, написанных для хранилища таблиц Azure и требующих таких возможностей класса "Премиум":

Готовое глобальное распределение.
Выделенная пропускная способность по всему миру.
Задержка в миллисекундах с одной цифрой на 99-м процентилье.
Гарантированная высокий уровень доступности.
Автоматическая вторичная индексация.
Клиентская библиотека таблиц Azure может легко использовать хранилище таблиц Azure или конечные точки службы таблиц Azure Cosmos DB без изменений кода.

Ключевые ссылки:

исходный код
пакета (NPM)
Справочная документация по API
документации по продукту
примеры

Начало работы

Необходимые условия

В настоящее время поддерживаются среды:

Версии LTS Node.js
Последние версии Safari, Chrome, Edge и Firefox

Для использования этого пакета необходимо иметь подписки Azure и учетную запись хранения или базу данных Azure CosmosDB.

Установка пакета `@azure/data-tables`

Предпочтительный способ установки клиентской библиотеки таблиц Azure для JavaScript — использовать диспетчер пакетов npm. Введите следующее в окно терминала:

npm install @azure/data-tables

Проверка подлинности `TableServiceClient`

Таблицы Azure поддерживают несколько способов проверки подлинности. Чтобы взаимодействовать со службой таблиц Azure, необходимо создать экземпляр клиента таблиц — TableServiceClient или TableClient, например. Дополнительные сведения о проверке подлинности см. в примерах для создания TableServiceClient.

Примечание. Azure Active Directory (AAD) поддерживается только для учетных записей хранения Azure.

клиент службы с общим ключом
клиент службы с подписанными URL-адресами
клиент службы с TokenCredential (AAD)
клиент таблицы с общим ключом
клиент таблицы с подписанными URL-адресами
клиент таблицы с TokenCredential (AAD)

Следующие функции, интерфейсы, классы или функции доступны только в Node.js

Авторизация общего ключа на основе имени учетной записи и ключа учетной записи
- AzureNamedKeyCredential
- Строка подключения учетной записи.

Пакет JavaScript

Чтобы использовать эту клиентную библиотеку в браузере, сначала необходимо использовать пакет. Дополнительные сведения о том, как это сделать, см. в нашей документации по .

CORS (Совместное использование ресурсов разных источников)

Необходимо настроить правила совместного использования ресурсов (CORS) для учетной записи хранения, если необходимо разработать для браузеров. Перейдите на портал Azure и обозреватель службы хранилища Azure, найдите свою учетную запись хранения, создайте новые правила CORS для больших двоичных объектов, очередей, файлов и таблиц.

Например, можно создать следующие параметры CORS для отладки. Но настройте параметры тщательно в соответствии с вашими требованиями в рабочей среде.

Допустимые источники: *
Разрешенные команды: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Разрешенные заголовки: *
Открытые заголовки: *
Максимальный возраст (в секундах): 86400

Основные понятия

TableServiceClient — клиент, который предоставляет функции для взаимодействия на уровне службы таблиц, таких как создание, перечисление и удаление таблиц
TableClient — клиент, предоставляющий функции для взаимодействия на уровне сущности, например создания, перечисления и удаления сущностей в таблице.
Table . Таблицы хранят данные в виде коллекций сущностей.
Entity — сущности похожи на строки. Сущность имеет первичный ключ и набор свойств. Свойство — это пара "имя", "типизированное значение", аналогичное столбцу.

Распространенные варианты использования службы таблиц включают:

Хранение TOB-объектов структурированных данных, способных обслуживать веб-масштабируемые приложения
Хранение наборов данных, которые не требуют сложных соединений, внешних ключей или хранимых процедур и могут быть удалены для быстрого доступа.
Быстрый запрос данных с помощью кластеризованного индекса
Доступ к данным с помощью выражений фильтра протокола OData

Примеры

Импорт пакета
Создание клиента службы таблиц
- таблицы списка в учетной записи
- Создание новой таблицы
Создание клиента таблицы
- Перечисление сущностей в таблице
- Создать сущность и добавить ее в таблицу

Импорт пакета

Чтобы использовать клиенты, импортируйте пакет в файл:

import * as azureTables from "@azure/data-tables";

Кроме того, выборочно импортируйте только необходимые типы:

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

Создание клиента службы таблиц

Для TableServiceClient требуется URL-адрес службы таблиц и учетные данные доступа. Он также при необходимости принимает некоторые параметры в параметре options.

`TableServiceClient` с AzureNamedKeyCredential

Вы можете создать экземпляр TableServiceClient с AzureNamedKeyCredential, передав имя учетной записи и ключ учетной записи в качестве аргументов. (Имя учетной записи и ключ учетной записи можно получить на портале Azure.) [ДОСТУПНО ТОЛЬКО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS]

import { AzureNamedKeyCredential, TableServiceClient } from "@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 AD в службе хранилища Azure см. в Azure.Identity README

import { DefaultAzureCredential } from "@azure/identity";
import { TableServiceClient } from "@azure/data-tables";

const credential = new DefaultAzureCredential();
const account = "<account name>";

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

`TableServiceClient` с маркером SAS

Кроме того, можно создать экземпляр TableServiceClient с подписанными URL-адресами (SAS). Маркер SAS можно получить на портале Azure.

import { TableServiceClient, AzureSASCredential } from "@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),
);

Вывод списка таблиц в учетной записи

Таблицы в учетной записи можно перечислить с помощью экземпляра TableServiceClient, вызывающего функцию listTables. Эта функция возвращает PageableAsyncIterator, которую можно использовать с помощью for-await-of

import { DefaultAzureCredential } from "@azure/identity";
import { TableServiceClient } from "@azure/data-tables";

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

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

let i = 0;
const tables = serviceClient.listTables();
for await (const table of tables) {
  console.log(`Table${++i}: ${table.name}`);
}

Создание новой таблицы

Таблицу можно создать с помощью экземпляра TableServiceClient, вызывающего функцию createTable. Эта функция принимает имя таблицы для создания в качестве параметра. Обратите внимание, что createTable не вызовет ошибку, если таблица уже существует.

import { DefaultAzureCredential } from "@azure/identity";
import { TableServiceClient } from "@azure/data-tables";

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

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

const tableName = "newtable";
// If the table 'newTable' already exists, createTable doesn't throw
await serviceClient.createTable(tableName);

Ниже приведен пример, демонстрирующий, как проверить, существует ли таблица при попытке создать ее:

import { DefaultAzureCredential } from "@azure/identity";
import { TableServiceClient } from "@azure/data-tables";

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

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

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

Создание клиента таблицы

TableClient создается так же, как и TableServiceClient с разницей, что TableClient принимает имя таблицы в качестве параметра.

`TableClient` с `AzureNamedKeyCredential`

Вы можете создать экземпляр TableClient с AzureNamedKeyCredential, передав имя учетной записи и ключ учетной записи в качестве аргументов. (Имя учетной записи и ключ учетной записи можно получить на портале Azure.) [ДОСТУПНО ТОЛЬКО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS]

import { AzureNamedKeyCredential, TableClient } from "@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)

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

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 с подписанными URL-адресами (SAS). Маркер SAS можно получить на портале Azure.

import { TableClient, AzureSASCredential } from "@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, вызывающего функцию listEntities. Эта функция возвращает PageableAsyncIterator, которую можно использовать с помощью for-await-of

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

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

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

let i = 0;
const entities = client.listEntities();
for await (const entity of entities) {
  console.log(`Entity${++i}: PartitionKey: ${entity.partitionKey} RowKey: ${entity.rowKey}`);
}

Создание сущности и добавление ее в таблицу

Вы можете создать новую сущность в таблице с помощью TableClient экземпляра, вызывающего функцию createEntity. Эта функция принимает сущность для вставки в качестве параметра. Сущность должна содержать partitionKey и rowKey.

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

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

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

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

Эмулятор Azurite и хранилища

Клиентский пакет SDK для таблиц Azure также работает с Azurite, совместимым с API службы хранилища Azure и таблиц, совместимым с эмулятором сервера. См. раздел (репозиторий Azurite) о том, как приступить к работе с ним.

Подключение к Azurite с помощью ярлыка строки подключения

Самый простой способ подключения к Azurite из приложения — настроить строку подключения, которая ссылается на ярлык UseDevelopmentStorage=true. Ярлык эквивалентен полной строке подключения для эмулятора, которая указывает имя учетной записи, ключ учетной записи и конечные точки эмулятора для каждой из служб службы хранилища Azure: (см. дополнительные). С помощью этого ярлыка клиентский пакет SDK для таблиц Azure настраивает строку подключения по умолчанию и allowInsecureConnection в параметрах клиента.

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

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

Подключение к Azurite без ярлыка строки подключения

Вы можете подключиться к azurite вручную, не используя ярлык строки подключения, указав URL-адрес службы и AzureNamedKeyCredential или настраиваемую строку подключения. Однако 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 },
);

Устранение неполадок

Общее

При взаимодействии со службой таблиц с помощью пакета SDK javascript/Typescript ошибки, возвращаемые службой, соответствуют тем же кодам состояния HTTP, возвращенным для запросов REST API: коды ошибок службы таблиц хранилища

Лесозаготовка

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения путем вызова setLogLevel в @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Способствует

Этот проект приветствует взносы и предложения. Большинство вкладов требуют, чтобы вы согласились с соглашением о лицензии участника (CLA), заявив, что у вас есть право, и на самом деле, предоставьте нам права на использование вашего вклада. Дополнительные сведения см. в https://cla.microsoft.com.

При отправке запроса на вытягивание бот CLA автоматически определяет, нужно ли предоставить соглашение об уровне обслуживания и украсить pr соответствующим образом (например, метка, комментарий). Просто следуйте инструкциям, предоставленным ботом. Это необходимо сделать только один раз во всех репозиториях с помощью нашего CLA.

Этот проект принял Microsoft Open Source Code of Conduct. Дополнительные сведения см. в кодекса поведения или с дополнительными вопросами или комментариями.

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по вкладу, чтобы узнать больше о том, как создавать и тестировать код.