Краткое руководство. Создание приложения API для таблиц с помощью Node.js и Azure Cosmos DB
ПРИМЕНИМО К:
Таблица
В этом кратком руководстве вы создадите учетную запись Azure Cosmos DB для таблиц и используете Data Explorer и приложение Node.js, клонированные из GitHub, для создания таблиц и сущностей. Azure Cosmos DB — это служба многомодельной базы данных, позволяющая быстро создавать и запрашивать документы, таблицы, пары "ключ-значение" и графовые базы данных, используя возможности глобального распределения и горизонтального масштабирования.
Предварительные требования
- Учетная запись Azure с активной подпиской. Создайте бесплатно.
- Node.js версии 0.10.29 и выше.
- Git.
Пример приложения
Пример приложения для этого учебника можно клонировать или скачать из репозитория https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js. В репозитории примеров имеется как начальное, так и готовое приложение.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
Пример приложения использует данные о погоде в качестве примера для демонстрации возможностей API для таблицы. Объекты, представляющие наблюдения за погодой, хранятся и извлекаются с помощью API для таблицы, включая хранение объектов с дополнительными свойствами для демонстрации бессхемных возможностей API для таблицы.
1\. Создание учетной записи Azure Cosmos DB
Сначала необходимо создать учетную запись API таблиц Azure Cosmos DB, которая будет содержать таблицы, используемые в приложении. Это можно сделать с помощью портала Azure, Azure CLI или Azure PowerShell.
Войдите в портал Azure и выполните следующие действия, чтобы создать учетную запись Azure Cosmos DB.
| Инструкции | Снимок экрана |
|---|---|
На портале Azure выполните следующие действия:
|
|
| На странице Azure Cosmos DB выберите +Создать. | 
|
| На странице Выберите вариант API параметр выберите вариант Таблица Azure. | 
|
На странице Создание учетной записи Azure Cosmos DB — таблица Azure заполните форму, как описано ниже.
|
|
2\. Создание таблицы
Затем необходимо создать таблицу в учетной записи Azure Cosmos DB для использования приложением. В отличие от традиционной базы данных, свойства (столбцы) в таблице указывать не требуется — нужно указать только имя таблицы. Свойства (столбцы) будут создаваться при загрузке данных в таблицу автоматически по мере необходимости.
В портал Azure выполните следующие действия, чтобы создать таблицу в учетной записи Azure Cosmos DB.
| Инструкции | Снимок экрана |
|---|---|
| На портале Azure перейдите к странице общих сведений об учетной записи Azure Cosmos DB. Вы можете перейти на страницу обзора учетной записи Azure Cosmos DB, введя имя (cosmos-msdocs-tables-sdk-demo-XYZ) учетной записи Azure Cosmos DB в верхней строке поиска и загляв под заголовком ресурсов. Выберите имя учетной записи Azure Cosmos DB, чтобы перейти на страницу обзора. | 
|
| На странице обзора выберите +Добавить таблицу. С правой стороны страницы появится диалоговое окно "Новая таблица". | 
|
В диалоговом окне Новая таблица укажите данные, как описано ниже.
|
|
3. Получение строки подключения Azure Cosmos DB
Чтобы получить доступ к таблицам в Azure Cosmos DB, приложению потребуется строка подключения к таблице для учетной записи хранения CosmosDB. Строку подключения можно получить с помощью портала Azure, Azure CLI или Azure PowerShell.
| Инструкции | Снимок экрана |
|---|---|
| В левой части страницы учетной записи Azure Cosmos DB под заголовком Параметры найдите элемент меню Строка подключения и выберите его. Вы перейдете на страницу, на которой сможете получить строку подключения для учетной записи Azure Cosmos DB. | 
|
| Скопируйте основную строку подключения для своего приложения. | 
|
4\. Установка пакета SDK таблиц данных Azure для JS
Чтобы получить доступ к Azure Cosmos DB для таблицы из приложения nodejs, установите пакет SDK для таблиц данных Azure .
npm install @azure/data-tables
5\. Настройка клиента таблицы в env.js file
Скопируйте строку подключения Azure Cosmos DB или учетной записи хранения из портал Azure и создайте объект TableServiceClient, используя скопированную строку подключения. Перейдите к папке 1-strater-app или 2-completed-app. Затем добавьте значение соответствующих переменных среды в файле configure/env.js.
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
Пакет SDK Azure взаимодействует с Azure с помощью клиентских объектов, используя их для выполнения различных операций в Azure. Класс TableClient — это класс, используемый для взаимодействия с Azure Cosmos DB для таблицы. Как правило, приложение создает для каждой таблицы отдельный объект serviceClient, который будет использоваться во всем приложении.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
6. Реализация операций с таблицами Azure Cosmos DB
Все операции с таблицами Azure Cosmos DB для примера приложения реализуются в объекте serviceClient , расположенном в файле в tableClient.jsкаталоге службы .
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
Получение строк из таблицы
Объект serviceClient содержит метод с именем listEntities, который позволяет выбирать строки из таблицы. В этом примере будут выбраны все строки из таблицы, так как параметры в метод не передаются.
const allRowsEntities = serviceClient.listEntities();
Фильтрация строк, возвращенных из таблицы
Для фильтрации строк, возвращаемых из таблицы, можно передать строку фильтра стиля OData в метод listEntities. Например, если требуется получить все показатели погоды в Чикаго с полуночи 1 июля до полуночи 2 июля 2021 года (включительно), передается следующая строка фильтра.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00' and RowKey le '2021-07-02 12:00'
Все операторы фильтра OData можно просмотреть на веб-сайте OData в разделе Системный параметр запроса фильтрации.
Когда параметр request.args передается в метод listEntities в классе serviceClient, он создает строку фильтра для каждого значения свойства, отличного от NULL. Затем он создает объединенную строку фильтра, объединяя все значения вместе с помощью предложения and. Эта объединенная строка фильтра передается в метод listEntities объекта serviceClient, в результате чего возвращаются только строки, соответствующие строке фильтра. Аналогичный метод можно использовать в коде для создания подходящих строк фильтра в соответствии с требованиями приложения.
const filterEntities = async function (option) {
/*
You can query data according to existing fields
option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
*/
const filterEntitiesArray = [];
const filters = [];
if (option.partitionKey) {
filters.push(`PartitionKey eq '${option.partitionKey}'`);
}
if (option.rowKeyDateTimeStart) {
filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
}
if (option.rowKeyDateTimeEnd) {
filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
}
if (option.minTemperature !== null) {
filters.push(`Temperature ge ${option.minTemperature}`);
}
if (option.maxTemperature !== null) {
filters.push(`Temperature le ${option.maxTemperature}`);
}
if (option.minPrecipitation !== null) {
filters.push(`Precipitation ge ${option.minPrecipitation}`);
}
if (option.maxPrecipitation !== null) {
filters.push(`Precipitation le ${option.maxPrecipitation}`);
}
const res = serviceClient.listEntities({
queryOptions: {
filter: filters.join(" and "),
},
});
for await (const entity of res) {
filterEntitiesArray.push(entity);
}
return filterEntitiesArray;
};
Вставка данных с помощью объекта TableEntity
Самый простой способ добавить данные в таблицу — использовать объект TableEntity. В этом примере данные сопоставляются из объекта входной модели с объектом TableEntity. Свойства входного объекта, представляющие имя, а также дату и время для метеостанции, сопоставляются со свойствами PartitionKey и RowKey, которые вместе образуют уникальный ключ для строки в таблице. Затем дополнительные свойства объекта входной модели сопоставляются со свойствами словаря в объекте TableEntity. Наконец, для вставки данных в таблицу используется метод createEntity объекта serviceClient.
Измените функцию insertEntity в примере приложения, чтобы она содержала следующий код.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
Выполнение операции upsert с данными с помощью объекта TableEntity
При попытке вставить в таблицу строку, сочетание ключа секции и ключа строки которой уже существует в этой таблице, будет выдано сообщение об ошибке. По этой причине при добавлении строк в таблицу зачастую предпочтительнее использовать метод upsertEntity вместо createEntity. Если в таблице уже существует заданное сочетание ключа секции и ключа строки, метод upsertEntity обновит существующую строку. В противном случае в таблицу будет добавлена строка.
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Выполнение операции вставки или upsert с данными с помощью свойств переменной
Одним из преимуществ использования Azure Cosmos DB для таблицы является то, что если объект, загружаемый в таблицу, содержит новые свойства, эти свойства автоматически добавляются в таблицу и значения, хранящиеся в Azure Cosmos DB. Нет необходимости выполнять операторы DDL, например ALTER TABLE, для добавления столбцов, как в традиционной базе данных.
Эта модель обеспечивает гибкость работы приложения с источниками данных, которые могут добавлять или изменять то, какие данные должны быть записаны со временем или в каких случаях различные входные данные предоставляют разные сведения приложению. В примере приложения можно смоделировать метеостанцию, которая отправляет не только базовые данные о погоде, но и ряд дополнительных значений. Когда объект с этими новыми свойствами сохраняется в таблице в первый раз, соответствующие свойства (столбцы) автоматически добавляются в таблицу.
Чтобы вставить или вставить такой объект с помощью API для таблицы, сопоставьте свойства расширяемого объекта с TableEntity объектом и используйте createEntity методы serviceClient или upsertEntity в объекте соответствующим образом.
В примере приложения функция upsertEntity также может реализовать функцию вставки или upsert данных с помощью свойств переменной
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Обновление сущности
Сущности можно обновить, вызвав метод updateEntity объекта serviceClient.
В примере приложения этот объект передается в метод upsertEntity объекта serviceClient. Он обновляет объект сущности и использует метод upsertEntity, чтобы сохранить обновления в базе данных.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7\. Выполнение кода
Запустите пример приложения для взаимодействия с Azure Cosmos DB для таблицы. При первом запуске приложения данные не отображаются, так как таблица пуста. Используйте любую из кнопок в верхней части приложения, чтобы добавить данные в таблицу.
При нажатии кнопки Вставить с помощью сущности таблицы открывается диалоговое окно, в котором можно выполнить операцию вставки или upsert для новой строки с помощью объекта TableEntity.
При нажатии кнопки Вставить с помощью расширяемых данных открывается диалоговое окно, позволяющее вставить объект с пользовательскими свойствами, демонстрируя, как Azure Cosmos DB для таблицы автоматически добавляет свойства (столбцы) в таблицу при необходимости. Чтобы добавить одно или несколько новых свойств и продемонстрировать эту возможность, воспользуйтесь кнопкой Добавить настраиваемое поле.
Используйте кнопку Вставить образцы данных , чтобы загрузить некоторые примеры данных в таблицу Azure Cosmos DB.
В верхнем меню выберите пункт Фильтрация результатов для отображения страницы "Фильтрация результатов". На этой странице заполните критерии фильтра, чтобы продемонстрировать, как можно создать предложение фильтра и передать его в Azure Cosmos DB для таблицы.
Очистка ресурсов
Завершив работу с примером приложения, необходимо удалить все ресурсы Azure, связанные с этой статьей, из учетной записи Azure. Это можно сделать, удалив группу ресурсов.
Группу ресурсов можно удалить на портале Azure, выполнив следующие действия.
| Инструкции | Снимок экрана |
|---|---|
| Чтобы перейти в группу ресурсов, в строке поиска введите ее имя. На вкладке Группы ресурсов выберите имя нужной группы. | 
|
| Выберите Удалить группу ресурсов на панели инструментов в верхней части страницы группы ресурсов. | 
|
В правой части экрана появится диалоговое окно с запросом подтвердить удаление группы ресурсов.
|
|
Дальнейшие действия
Из этого краткого руководства вы узнали, как создать учетную запись Azure Cosmos DB и таблицу с помощью обозревателя данных, а также как запустить приложение. Теперь вы можете запрашивать данные с помощью API для таблицы.