Клиентская библиотека таблиц Azure для JavaScript версии 13.2.2

Статья
04/10/2023

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

Используйте клиентские библиотеки, чтобы:

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

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

Комплексные возможности глобального распределения.
выделенная пропускная способность в любой точке мира;
задержка меньше 10 миллисекунд на уровне 99-го процентиля;
гарантированно высокий уровень доступности;
автоматическое вторичное индексирование.
Клиентская библиотека таблиц Azure может легко ориентироваться либо на хранилище таблиц Azure, либо на конечные точки службы таблиц Azure Cosmos DB без изменений кода.

Основные ссылки:

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

Предварительные требования

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

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

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

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

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

npm install @azure/data-tables

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

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

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

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

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

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

Пакет JavaScript

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

CORS

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

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

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

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

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

Наиболее частые способы использования службы таблицы включают следующие.

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

Примеры

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

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

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

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

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

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

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

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

`TableServiceClient` с AzureNamedKeyCredential

Можно создать TableServiceClient экземпляр с , AzureNamedKeyCredential передав в качестве аргументов имя учетной записи и ключ учетной записи. (Имя учетной записи и ключ учетной записи можно получить на портале 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
);

`TableServiceClient` с TokenCredential (AAD)

Таблицы Azure обеспечивают интеграцию с Azure Active Directory (Azure AD) для проверки подлинности на основе удостоверений запросов к службе таблиц при нацелии на конечную точку хранилища. С помощью Azure AD можно использовать управление доступом на основе ролей (RBAC), чтобы предоставить пользователям, группам или приложениям доступ к ресурсам таблиц Azure.

Чтобы получить доступ к ресурсу таблицы с TokenCredentialпомощью , удостоверение, прошедшее проверку подлинности, должно иметь роль "Участник данных таблицы хранилища" или "Читатель данных таблицы хранилища".

@azure/identity С помощью пакета можно легко авторизовать запросы как в среде разработки, так и в рабочей среде. Дополнительные сведения об интеграции Azure AD в службе хранилища Azure см. в файле сведений об 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

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

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

Перечисление таблиц в учетной записи

Вы можете перечислить таблицы в учетной записи с помощью экземпляра, вызывающего TableServiceClient функцию listTables . Эта функция возвращает объект , 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();

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

Таблицу можно создать с помощью экземпляра, вызывающего TableServiceClient функцию createTable . Эта функция принимает имя создаваемой таблицы в качестве параметра. Обратите внимание, что 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 принимает имя таблицы в качестве параметра.

`TableClient` с `AzureNamedKeyCredential`

Вы можете создать TableClient экземпляр с AzureNamedKeyCredential , передав имя учетной записи и ключ учетной записи в качестве аргументов. (Имя учетной записи и ключ учетной записи можно получить на портале 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);

`TableClient` с `TokenCredential` (Azure Active Directory)

Таблицы Azure обеспечивают интеграцию с Azure Active Directory (Azure AD) для проверки подлинности на основе удостоверений запросов к службе таблиц при нацелии на конечную точку хранилища. С помощью Azure AD можно использовать управление доступом на основе ролей (RBAC), чтобы предоставить доступ к ресурсам таблицы Azure пользователям, группам или приложениям.

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

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 пользователям, группам или приложениям.

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 . Эта функция принимает сущность для вставки в качестве параметра. Сущность должна содержать 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 и эмулятор хранения

Клиентский пакет 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:

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

setLogLevel("info");

Дальнейшие действия

В ближайшее время появится еще несколько примеров кода Issue No 10531

Участие

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

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

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.

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

Просмотры

Клиентская библиотека таблиц Azure для JavaScript версии 13.2.2

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

Предварительные требования

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

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

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

Пакет JavaScript

CORS

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

Примеры

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

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

`TableServiceClient` с AzureNamedKeyCredential

`TableServiceClient` с TokenCredential (AAD)

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

Перечисление таблиц в учетной записи

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

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

`TableClient` с `AzureNamedKeyCredential`

`TableClient` с `TokenCredential` (Azure Active Directory)

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

`TableClient` с TokenCredential (AAD)

Перечисление сущностей в таблице

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

Azurite и эмулятор хранения

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

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

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

Общие сведения

Ведение журнала

Дальнейшие действия

Участие

Обратная связь

Дополнительные ресурсы

Клиентская библиотека таблиц Azure для JavaScript версии 13.2.2

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

Предварительные требования

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

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

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

Пакет JavaScript

CORS

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

Примеры

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

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

TableServiceClient с AzureNamedKeyCredential

TableServiceClient с TokenCredential (AAD)

TableServiceClient с маркером SAS

Перечисление таблиц в учетной записи

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

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

TableClient с AzureNamedKeyCredential

TableClient с TokenCredential (Azure Active Directory)

TableClient с маркером SAS

TableClient с TokenCredential (AAD)

Перечисление сущностей в таблице

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

Azurite и эмулятор хранения

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

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

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

Общие сведения

Ведение журнала

Дальнейшие действия

Участие

Обратная связь

Дополнительные ресурсы

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

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

`TableServiceClient` с AzureNamedKeyCredential

`TableServiceClient` с TokenCredential (AAD)

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

`TableClient` с `AzureNamedKeyCredential`

`TableClient` с `TokenCredential` (Azure Active Directory)

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

`TableClient` с TokenCredential (AAD)