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

Статья
11/19/2024

таблицах 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

Примеры

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

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

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

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 README

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

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

Таблицу можно создать с помощью экземпляра 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)

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)

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

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

Вы можете создать новую сущность в таблице с помощью 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");

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

Дополнительные примеры кода, поступающие в ближайшее время, проблема#10531

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

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

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

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

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

впечатлений

Поделиться через

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

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

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

Установка пакета `@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.3.0

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

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

Установка пакета @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)