Краткое руководство. Создание приложения API для таблиц с помощью Node.js и Azure Cosmos DB
Область применения: Таблица
В этом кратком руководстве вы создадите учетную запись Azure Cosmos DB для таблицы и используйте Обозреватель данных и приложение 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.
2. Создание таблицы
Затем необходимо создать таблицу в учетной записи Azure Cosmos DB для использования приложения. В отличие от традиционной базы данных, свойства (столбцы) в таблице указывать не требуется — нужно указать только имя таблицы. Свойства (столбцы) будут создаваться при загрузке данных в таблицу автоматически по мере необходимости.
В портал Azure выполните следующие действия, чтобы создать таблицу в учетной записи Azure Cosmos DB.
3. Получение строка подключения Azure Cosmos DB
Чтобы получить доступ к таблицам в Azure Cosmos DB, приложению потребуется таблица строка подключения для учетной записи хранения CosmosDB. Строку подключения можно получить с помощью портала Azure, Azure CLI или Azure PowerShell.
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, для добавления столбцов, как в традиционной базе данных.
Эта модель обеспечивает гибкость работы приложения с источниками данных, которые могут добавлять или изменять то, какие данные должны быть записаны со временем или в каких случаях различные входные данные предоставляют разные сведения приложению. В примере приложения можно смоделировать метеостанцию, которая отправляет не только базовые данные о погоде, но и ряд дополнительных значений. Когда объект с этими новыми свойствами сохраняется в таблице в первый раз, соответствующие свойства (столбцы) автоматически добавляются в таблицу.
Чтобы вставить или upsert такой объект с помощью API для таблицы, сопоставить свойства расширяемого объекта с TableEntity
объектом и использовать createEntity
upsertEntity
методы в serviceClient
объекте соответствующим образом.
В примере приложения функция 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 для таблицы.