Использование пакета SDK Node.js для мобильных приложений Azure

Статья
05/05/2021

Заметка

Этот продукт отставлен. Сведения о замене проектов с помощью .NET 8 или более поздней версии см. вбиблиотеке Community Toolkit Datasync.

В этой статье содержатся подробные сведения и примеры работы с серверной частью NodeJS для мобильных приложений Azure.

Знакомство

Мобильные приложения Azure предоставляют возможность добавления веб-API доступа к данным, оптимизированного для мобильных устройств, в веб-приложение. Пакет SDK для мобильных приложений Azure предоставляется для ASP.NET Framework и веб-приложений Node.js. Пакет SDK предоставляет следующие операции:

Операции таблицы (чтение, вставка, обновление, удаление) для доступа к данным
Пользовательские операции API

Обе операции обеспечивают проверку подлинности для всех поставщиков удостоверений, которые позволяет служба приложений Azure. К таким поставщикам относятся поставщики удостоверений социальных сетей, такие как Facebook, Twitter, Google и Майкрософт, а также идентификатор Microsoft Entra для корпоративного удостоверения.

Поддерживаемые платформы

Пакет SDK для мобильных приложений Azure Node.js поддерживает узел 6.x и более поздние версии и был протестирован до узла 12.x. Другие версии Node могут работать, но не поддерживаются.

Пакет SDK для мобильных приложений Azure Node.js поддерживает два драйвера базы данных:

Драйвер node-mssql поддерживает базу данных SQL Azure и локальные экземпляры SQL Server.
Драйвер sqlite3 поддерживает базы данных SQLite только в одном экземпляре.

Создание основной внутренней части узла с помощью командной строки

Все мобильные приложения Azure Node.js серверной части начинаются как приложение Express. Express — это самая популярная платформа веб-служб, доступная для Node.js. Вы можете создать базовое приложение Express следующим образом:

В окне команды или PowerShell создайте каталог для проекта:
```
$ mkdir basicapp
```
Выполните npm init, чтобы инициализировать структуру пакета:
```
$ cd basicapp
$ npm init
```
Команда npm init задает набор вопросов для инициализации проекта. См. пример выходных данных:
Установите библиотеки express и azure-mobile-apps из репозитория npm:
```
npm install --save express azure-mobile-apps
```

Создайте файл app.js для реализации базового мобильного сервера:

var express = require('express'),
    azureMobileApps = require('azure-mobile-apps');

var app = express(),
    mobile = azureMobileApps();

// Define a TodoItem table.
mobile.tables.add('TodoItem');

// Add the Mobile API so it is accessible as a Web API.
app.use(mobile);

// Start listening on HTTP.
app.listen(process.env.PORT || 3000);

Это приложение создает веб-API, оптимизированный для мобильных устройств, с одной конечной точкой (/tables/TodoItem), которая предоставляет доступ к базовому хранилищу данных SQL без проверки подлинности с помощью динамической схемы. Он подходит для выполнения следующих кратких руководств по клиентской библиотеке:

Код для этого базового приложения можно найти в области примеров наGitHub.

Включение домашней страницы для приложения

Многие приложения — это сочетание веб-приложений и мобильных приложений. Платформу Express можно использовать для объединения двух аспектов. Однако иногда может потребоваться реализовать только мобильный интерфейс. Полезно предоставить домашнюю страницу, чтобы убедиться, что служба приложений работает и работает. Вы можете предоставить собственную домашнюю страницу или включить временную домашнюю страницу. Чтобы включить временную домашнюю страницу, используйте следующий код для создания экземпляра мобильных приложений Azure:

var mobile = azureMobileApps({ homePage: true });

Если этот параметр доступен только при локальной разработке, можно добавить этот параметр в файл конфигурации azureMobile.js:

module.exports = {
    homePage: true,
};

При необходимости можно добавить другие параметры в файл azureMobile.js.

Операции с таблицами

Пакет SDK для сервера azure-mobile-apps Node.js предоставляет механизмы предоставления таблиц данных, хранящихся в базе данных SQL Azure в качестве веб-API. Он предоставляет пять операций:

Операция	Описание
`GET /tables/tablename`	Получение всех записей в таблице.
`GET /tables/tablename/:id`	Получите определенную запись в таблице.
`POST /tables/tablename`	Создайте запись в таблице.
`PATCH /tables/tablename/:id`	Обновите запись в таблице.
`DELETE /tables/tablename/:id`	Удалите запись в таблице.

Этот веб-API поддерживает OData версии 3 и расширяет схему таблицы для поддержки автономной синхронизации данных.

Определение таблиц с помощью динамической схемы

Прежде чем использовать таблицу, ее необходимо определить. Таблицы можно определить с помощью статической схемы (где вы определяете столбцы схемы) или динамически (где пакет SDK управляет схемой на основе входящих запросов). Кроме того, вы можете управлять конкретными аспектами веб-API, добавив код JavaScript в определение.

Рекомендуется определить каждую таблицу в файле JavaScript в каталоге tables, а затем использовать метод tables.import() для импорта таблиц. Расширяя пример базового приложения, можно настроить файл app.js:

var express = require('express'),
    azureMobileApps = require('azure-mobile-apps');

var app = express(),
    mobile = azureMobileApps();

// Define the database schema that is exposed.
mobile.tables.import('./tables');

// Provide initialization of any tables that are statically defined.
mobile.tables.initialize().then(function () {
    // Add the Mobile API so it is accessible as a Web API.
    app.use(mobile);

    // Start listening on HTTP.
    app.listen(process.env.PORT || 3000);
});

Определите таблицу в ./table/TodoItem.js:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Additional configuration for the table goes here.

module.exports = table;

Таблицы используют динамическую схему по умолчанию.

Определение таблиц с помощью статической схемы

Можно явно определить столбцы для предоставления через веб-API. Пакет SDK azure-mobile-apps Node.js автоматически добавляет дополнительные столбцы, необходимые для автономной синхронизации данных, в указанный список. Например, клиентским приложениям быстрого запуска требуется таблица с двумя столбцами: text (строка) и complete (логическое значение). Таблицу можно определить в файле JavaScript определения таблицы (расположен в каталоге tables) следующим образом:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};

// Turn off the dynamic schema.
table.dynamicSchema = false;

module.exports = table;

Если таблицы определены статически, необходимо также вызвать метод tables.initialize(), чтобы создать схему базы данных при запуске. Метод возвращает обещания , чтобы веб-служба не обслуживала запросы до инициализации базы данных.

Использование SQL Server Express в качестве хранилища данных разработки на локальном компьютере

Пакет SDK для мобильных приложений Azure Node.js предоставляет три варианта обслуживания данных из поля:

Используйте драйвер памяти для предоставления непрекращающегося хранилища примеров.
Используйте драйвер mssql для предоставления хранилища данных SQL Server Express для разработки.
Используйте драйвер mssql для предоставления хранилища данных базы данных SQL Azure для рабочей среды.

Пакет Node.js мобильных приложений Azure использует пакет Node.js mssql mssql для установления и использования подключения к базе данных SQL Server Express и БАЗЫ данных SQL. Для этого пакета требуется включить TCP-подключения в экземпляре SQL Server Express.

Кончик

Драйвер памяти не предоставляет полный набор средств для тестирования. Если вы хотите протестировать серверную часть локально, рекомендуется использовать хранилище данных SQL Server Express и драйвер mssql.

Скачайте и установите microsoft SQL Server 2019 Developer.
Запустите Configuration Manager:
- Разверните узел конфигурации сети SQL Server в меню дерева.
- Выберите протоколы для имени экземпляра.
- Щелкните правой кнопкой мыши TCP/IP и выберите Включить. Нажмите кнопку ОК во всплывающем диалоговом окне.
- Выберите служб SQL Server в меню дерева.
- Щелкните правой кнопкой мыши SQL Server (имя экземпляра) и выберите Перезапустить.
- Закройте Configuration Manager.

Вам также потребуется создать имя пользователя и пароль, которые мобильные приложения Azure могут использовать для подключения к базе данных. Убедитесь, что у создаваемого пользователя есть роль сервера dbcreator. Дополнительные сведения о настройке пользователей см. в документации SQL Server

Обязательно запишите выбранное имя пользователя и пароль. В зависимости от требований к базе данных может потребоваться назначить дополнительные роли сервера или разрешения.

Приложение Node.js считывает переменную среды SQLCONNSTR_MS_TableConnectionString для строки подключения для этой базы данных. Эту переменную можно задать в вашей среде. Например, с помощью PowerShell можно задать эту переменную среды:

$env:SQLCONNSTR_MS_TableConnectionString = "Server=127.0.0.1; Database=mytestdatabase; User Id=azuremobile; Password=T3stPa55word;"

Доступ к базе данных через TCP/IP-подключение. Укажите имя пользователя и пароль для подключения.

Настройка проекта для локальной разработки

Мобильные приложения Azure считывают файл JavaScript с именем azureMobile.js из локальной файловой системы. Не используйте этот файл для настройки пакета SDK для мобильных приложений Azure в рабочей среде. Вместо этого используйте параметры приложения на портале Azure.

Файл azureMobile.js должен экспортировать объект конфигурации. Наиболее распространенными параметрами являются:

Параметры базы данных
Параметры ведения журнала диагностики
Альтернативные параметры CORS

В этом примере azureMobile.js файл реализует предыдущие параметры базы данных:

module.exports = {
    cors: {
        origins: [ 'localhost' ]
    },
    data: {
        provider: 'mssql',
        server: '127.0.0.1',
        database: 'mytestdatabase',
        user: 'azuremobile',
        password: 'T3stPa55word'
    },
    logging: {
        level: 'verbose'
    }
};

Рекомендуется добавить azureMobile.js в файл .gitignore (или другой файл управления исходным кодом), чтобы предотвратить хранение паролей в облаке.

Настройка параметров приложения для мобильного приложения

Большинство параметров в файле azureMobile.js имеют эквивалентный параметр приложения на портале Azure. Используйте следующий список, чтобы настроить приложение в параметрах приложения :

Параметр приложения	параметр azureMobile.js	Описание	Допустимые значения
MS_MobileAppName	имя	Имя приложения	струна
MS_MobileLoggingLevel	logging.level	Минимальный уровень журналов сообщений для журнала	error, warning, info, verbose, debug, silly
MS_DebugMode	отлаживать	Включает или отключает режим отладки	true, false
MS_TableSchema	data.schema	Имя схемы по умолчанию для таблиц SQL	string (по умолчанию: dbo)
MS_DynamicSchema	data.dynamicSchema	Включает или отключает режим отладки	true, false
MS_DisableVersionHeader	версия (задано значение undefined)	Отключает заголовок X-ZUMO-Server-Version	true, false
MS_SkipVersionCheck	skipversioncheck	Отключает проверку версии КЛИЕНТСКОго API	true, false

Для изменения большинства параметров приложения требуется перезапуск службы.

Использование SQL Azure в качестве рабочего хранилища данных

Использование Базы данных SQL Azure в качестве хранилища данных идентично всем типам приложений Службы приложений Azure. Если это еще не сделано, выполните следующие действия, чтобы создать серверную часть службы приложений Azure. Создайте экземпляр SQL Azure, а затем задайте для параметра приложения SQLCONNSTR_MS_TableConnectionString строку подключения для экземпляра SQL Azure, который вы хотите использовать. Убедитесь, что серверная часть службы приложений Azure может взаимодействовать с экземпляром SQL Azure.

Требовать проверку подлинности для доступа к таблицам

Если вы хотите использовать проверку подлинности службы приложений с конечной точкой tables, сначала необходимо настроить проверку подлинности службы приложений на портале Azure. Дополнительные сведения см. в руководстве по настройке поставщика удостоверений, который вы планируете использовать:

настройка проверки подлинности Microsoft Entra
Настройка проверки подлинности Facebook
Настройка проверки подлинности Google
Настройка проверки подлинности Майкрософт
Настройка проверки подлинности Twitter

Каждая таблица имеет свойство доступа, которое можно использовать для управления доступом к таблице. В следующем примере показана статическая таблица с обязательной проверкой подлинности.

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};

// Turn off the dynamic schema.
table.dynamicSchema = false;

// Require authentication to access the table.
table.access = 'authenticated';

module.exports = table;

Свойство access может принимать одно из трех значений:

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

Если свойство доступа не определено, разрешен доступ без проверки подлинности.

Использование утверждений проверки подлинности с таблицами

При настройке проверки подлинности можно настроить различные утверждения, запрашиваемые при настройке проверки подлинности. Эти утверждения обычно недоступны через объект context.user. Однако их можно получить с помощью метода context.user.getIdentity(). Метод getIdentity() возвращает обещание, разрешающее объекту. Объект ключом является метод проверки подлинности (facebook, google, twitter, microsoftaccountили aad).

Заметка

При использовании проверки подлинности Майкрософт с помощью идентификатора Microsoft Entra метод проверки подлинности aad, а не microsoftaccount.

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

var azureMobileApps = require('azure-mobile-apps');

// Create a new table definition.
var table = azureMobileApps.table();

table.columns = {
    "emailAddress": "string",
    "text": "string",
    "complete": "boolean"
};
table.dynamicSchema = false;
table.access = 'authenticated';

/**
* Limit the context query to those records with the authenticated user email address
* @param {Context} context the operation context
* @returns {Promise} context execution Promise
*/
function queryContextForEmail(context) {
    return context.user.getIdentity().then((data) => {
        context.query.where({ emailAddress: data.aad.claims.emailaddress });
        return context.execute();
    });
}

/**
* Adds the email address from the claims to the context item - used for
* insert operations
* @param {Context} context the operation context
* @returns {Promise} context execution Promise
*/
function addEmailToContext(context) {
    return context.user.getIdentity().then((data) => {
        context.item.emailAddress = data.aad.claims.emailaddress;
        return context.execute();
    });
}

// Configure specific code when the client does a request.
// READ: only return records that belong to the authenticated user.
table.read(queryContextForEmail);

// CREATE: add or overwrite the userId based on the authenticated user.
table.insert(addEmailToContext);

// UPDATE: only allow updating of records that belong to the authenticated user.
table.update(queryContextForEmail);

// DELETE: only allow deletion of records that belong to the authenticated user.
table.delete(queryContextForEmail);

module.exports = table;

Чтобы узнать, какие утверждения доступны, используйте веб-браузер для просмотра /.auth/me конечной точки сайта.

Отключение доступа к определенным операциям таблицы

Помимо отображения в таблице, свойство доступа можно использовать для управления отдельными операциями. Существует четыре операции:

read — это операция RESTful GET в таблице.
insert — это операция RESTful POST в таблице.
update — это операция RESTful PATCH в таблице.
delete — это операция RESTful DELETE в таблице.

Например, может потребоваться предоставить таблицу без проверки подлинности только для чтения:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Read-only table. Only allow READ operations.
table.read.access = 'anonymous';
table.insert.access = 'disabled';
table.update.access = 'disabled';
table.delete.access = 'disabled';

module.exports = table;

Настройка запроса, используемого с операциями таблицы

Обычное требование для операций с таблицами заключается в предоставлении ограниченного представления данных. Например, можно указать таблицу, помеченную идентификатором пользователя, прошедшим проверку подлинности, так что вы можете только читать или обновлять собственные записи. Следующее определение таблицы предоставляет эту функцию:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define a static schema for the table.
table.columns = {
    "userId": "string",
    "text": "string",
    "complete": "boolean"
};
table.dynamicSchema = false;

// Require authentication for this table.
table.access = 'authenticated';

// Ensure that only records for the authenticated user are retrieved.
table.read(function (context) {
    context.query.where({ userId: context.user.id });
    return context.execute();
});

// When adding records, add or overwrite the userId with the authenticated user.
table.insert(function (context) {
    context.item.userId = context.user.id;
    return context.execute();
});

module.exports = table;

Операции, которые обычно выполняют запрос, имеют свойство запроса, которое можно настроить с помощью предложения where. Свойство запроса — это объект QueryJS, используемый для преобразования запроса OData в то, что серверная часть данных может обрабатывать. Для простых случаев равенства (например, предыдущих), можно использовать карту. Кроме того, можно добавить определенные предложения SQL:

context.query.where('myfield eq ?', 'value');

Настройка обратимого удаления в таблице

Обратимое удаление фактически не удаляет записи. Вместо этого он помечает их как удаленные в базе данных, установив для удаленного столбца значение true. Пакет SDK для мобильных приложений Azure автоматически удаляет обратимо удаленные записи из результатов, если пакет SDK для мобильных клиентов не использует includeDeleted(). Чтобы настроить таблицу для обратимого удаления, задайте свойство softDelete в файле определения таблицы:

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};

// Turn off the dynamic schema.
table.dynamicSchema = false;

// Turn on soft delete.
table.softDelete = true;

// Require authentication to access the table.
table.access = 'authenticated';

module.exports = table;

Создайте механизм для окончательного удаления записей, таких как клиентское приложение, веб-задание, функция Azure или пользовательский API.

Заполнение базы данных данными

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

var azureMobileApps = require('azure-mobile-apps');

var table = azureMobileApps.table();

// Define the columns within the table.
table.columns = {
    "text": "string",
    "complete": "boolean"
};
table.seed = [
    { text: 'Example 1', complete: false },
    { text: 'Example 2', complete: true }
];

// Turn off the dynamic schema.
table.dynamicSchema = false;

// Require authentication to access the table.
table.access = 'authenticated';

module.exports = table;

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

Мы рекомендуем явно вызвать метод tables.initialize(), чтобы создать таблицу при запуске службы.

Включение поддержки Swagger

Мобильные приложения Azure поддерживают встроенные Swagger. Чтобы включить поддержку Swagger, сначала установите swagger-ui в качестве зависимостей:

npm install --save swagger-ui

Затем можно включить поддержку Swagger в конструкторе мобильных приложений Azure:

var mobile = azureMobileApps({ swagger: true });

Возможно, вы хотите включить поддержку Swagger только в выпусках разработки. Вы можете включить поддержку Swagger в разработке с помощью параметра приложения NODE_ENV:

var mobile = azureMobileApps({ swagger: process.env.NODE_ENV !== 'production' });

Конечная точка swagger находится в http://.azurewebsites.net/swagger сайта. Пользовательский интерфейс Swagger можно получить через конечную точку /swagger/ui. Если вы решили требовать проверку подлинности во всем приложении, Swagger выдает ошибку. Для получения наилучших результатов выберите разрешение неавтоентизованных запросов в параметрах проверки подлинности и авторизации службы приложений Azure, а затем управляйте проверкой подлинности с помощью свойства table.access.

Вы также можете добавить параметр Swagger в файл azureMobile.js, если требуется только поддержка Swagger для локальной разработки.

Пользовательские API

Помимо API доступа к данным через конечную точку /tables мобильные приложения Azure могут предоставлять пользовательское покрытие API. Пользовательские API определяются аналогичным образом с определениями таблиц и могут получить доступ ко всем тем же объектам, включая проверку подлинности.

Определение пользовательского API

Пользовательские API определяются точно так же, как и API таблиц:

Создайте каталог api.
Создайте файл JavaScript определения API в каталоге api.
Используйте метод импорта для импорта каталога api.

Ниже приведено определение прототипа API на основе примера базового приложения, который мы использовали ранее:

var express = require('express'),
    azureMobileApps = require('azure-mobile-apps');

var app = express(),
    mobile = azureMobileApps();

// Import the custom API.
mobile.api.import('./api');

// Add the Mobile API so it is accessible as a Web API.
app.use(mobile);

// Start listening on HTTP
app.listen(process.env.PORT || 3000);

Давайте рассмотрим пример API, который возвращает дату сервера с помощью метода Date.now(). Ниже приведен файл api/date.js:

var api = {
    get: function (req, res, next) {
        var date = { currentTime: Date.now() };
        res.status(200).type('application/json').send(date);
    });
};

module.exports = api;

Каждый параметр является одним из стандартных команд RESTful: GET, POST, PATCH или DELETE. Метод является стандартной ПО промежуточного слоя ExpressJS, которая отправляет необходимые выходные данные.

Требовать проверку подлинности для доступа к пользовательскому API

Пакет SDK для мобильных приложений Azure реализует проверку подлинности одинаково для конечной точки tables и пользовательских API. Чтобы добавить проверку подлинности в API, разработанный в предыдущем разделе, добавьте свойство access:

var api = {
    get: function (req, res, next) {
        var date = { currentTime: Date.now() };
        res.status(200).type('application/json').send(date);
    });
};
// All methods must be authenticated.
api.access = 'authenticated';

module.exports = api;

Можно также указать проверку подлинности для определенных операций:

var api = {
    get: function (req, res, next) {
        var date = { currentTime: Date.now() };
        res.status(200).type('application/json').send(date);
    }
};
// The GET methods must be authenticated.
api.get.access = 'authenticated';

module.exports = api;

Тот же маркер, используемый для конечной точки tables, должен использоваться для пользовательских API, требующих проверки подлинности.

Обработка отправки больших файлов

Пакет SDK для мобильных приложений Azure использует по промежуточному по промежуточному слоям средства анализа текста, для принятия и декодировки содержимого текста в отправке. Чтобы принять более крупные отправки файлов, можно предварительно настроить средство синтаксического анализа текста:

var express = require('express'),
    bodyParser = require('body-parser'),
    azureMobileApps = require('azure-mobile-apps');

var app = express(),
    mobile = azureMobileApps();

// Set up large body content handling.
app.use(bodyParser.json({ limit: '50mb' }));
app.use(bodyParser.urlencoded({ limit: '50mb', extended: true }));

// Import the custom API.
mobile.api.import('./api');

// Add the Mobile API so it is accessible as a Web API.
app.use(mobile);

// Start listening on HTTP.
app.listen(process.env.PORT || 3000);

Файл закодирован до передачи в кодировке base-64. Эта кодировка увеличивает размер фактической отправки (и размер, который необходимо учитывать).

Выполнение пользовательских инструкций SQL

Пакет SDK для мобильных приложений Azure позволяет получить доступ ко всему контексту через объект запроса. Вы можете легко выполнить параметризованные инструкции SQL для определенного поставщика данных:

var api = {
    get: function (request, response, next) {
        // Check for parameters. If not there, pass on to a later API call.
        if (typeof request.params.completed === 'undefined')
            return next();

        // Define the query. Anything that the mssql
        // driver can handle is allowed.
        var query = {
            sql: 'UPDATE TodoItem SET complete=@completed',
            parameters: [{
                completed: request.params.completed
            }]
        };

        // Execute the query. The context for Azure Mobile Apps is available through
        // request.azureMobile. The data object contains the configured data provider.
        request.azureMobile.data.execute(query)
        .then(function (results) {
            response.json(results);
        });
    }
};

api.get.access = 'authenticated';
module.exports = api;

Отладка

Отладка, диагностика и устранение неполадок мобильных приложений Azure

Служба приложений Azure предоставляет несколько методов отладки и устранения неполадок для Node.js приложений. Чтобы приступить к устранению неполадок Node.js серверной части мобильных приложений Azure, ознакомьтесь со следующими статьями:

Node.js приложения имеют доступ к широкому спектру средств журналов диагностики. В настоящее время пакет SDK для мобильных приложений Azure Node.js использует [Winston] для ведения журнала диагностики. Ведение журнала автоматически включено при включении режима отладки или настройке параметра приложения MS_DebugMode значение true на портале Azure. Созданные журналы отображаются в журналах диагностики на портале Azure.

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