Использование подключаемого модуля Apache Cordova для мобильных приложений Azure

В данном руководстве показано, как реализовать типичные сценарии с использованием последней версии подключаемого модуля Apache Cordova для мобильных приложений Azure. Если вы не знакомы с мобильными приложениями Azure, изучите статью Быстрый запуск мобильного приложения Azure , чтобы создать серверную часть и таблицу, а также скачать предварительно собранный проект Apache Cordova. В данном руководстве мы сосредоточимся на клиентской части подключаемого модуля Apache Cordova.

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

Этот пакет SDK поддерживает Apache Cordova 6.0.0 и более поздних версий на устройствах iOS, Android и устройствах с Windows. Ниже перечислены возможности, поддерживаемые платформой:

• API 19 и более поздних версий для Android;
• iOS 8.0 и более поздних версий;

Предупреждение

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

Настройка и необходимые компоненты

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

cordova plugin add cordova-plugin-ms-azure-mobile-apps

Дополнительные сведения о создании первого приложения Apache Cordova см. в соответствующей документации.

Настройка приложения Ionic v2

Чтобы правильно настроить проект Ionic v2, создать простое приложение и добавить подключаемый модуль Cordova, сделайте следующее.

ionic start projectName --v2
cd projectName
ionic plugin add cordova-plugin-ms-azure-mobile-apps

Добавьте следующие строки в app.component.ts, чтобы создать клиентский объект:

declare var WindowsAzure: any;
var client = new WindowsAzure.MobileServiceClient("https://yoursite.azurewebsites.net");

Теперь можно создать и запустить проект в браузере.

ionic platform add browser
ionic run browser

Подключаемый модуль Cordova для мобильных приложений Azure поддерживает обе версии приложения Ionic — v1 и v2. Но в приложениях Ionic v2 требуется дополнительное объявление для объекта WindowsAzure.

Создание подключения клиента

Создайте подключение клиента, создав объект WindowsAzure.MobileServiceClient . Замените appUrl URL-адресом в своем мобильном приложении.

var client = WindowsAzure.MobileServiceClient(appUrl);

Работа с таблицами

Для доступа к данным или их обновления создайте ссылку на таблицу серверной части. Замените tableName на имя таблицы.

var table = client.getTable(tableName);

Имея ссылку на таблицу, можно работать с этой таблицей:

• Запрос к таблице
  • Фильтрация данных
  • Разбиение данных по страницам
  • Сортировка данных
• Вставка данных
• Изменение данных
• Удаление данных

Запрос ссылки на таблицу

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

/**
 * Process the results that are received by a call to table.read()
 *
 * @param {Object} results the results as a pseudo-array
 * @param {int} results.length the length of the results array
 * @param {Object} results[] the individual results
 */
function success(results) {
   var numItemsRead = results.length;

   for (var i = 0 ; i < results.length ; i++) {
       var row = results[i];
       // Each row is an object - the properties are the columns
   }
}

function failure(error) {
    throw new Error('Error loading data: ', error);
}

table
    .read()
    .then(success, failure);

Выполненная функция вызывается с результатами. Не используйте в этой функции свойство for (var i in results) — оно вызывает перебор данных, включаемых в результаты применения других функций запросов (таких как .includeTotalCount()).

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

Фильтрация данных на сервере

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

table
    .where({ userId: user.userId, complete: false })
    .read()
    .then(success, failure);

Также можно использовать функцию фильтрации объектов. В этом случае переменная this присваивается текущему объекту фильтрации. Представленный ниже код функционально эквивалентен предыдущему примеру:

function filterByUserId(currentUserId) {
    return this.userId === currentUserId && this.complete === false;
}

table
    .where(filterByUserId, user.userId)
    .read()
    .then(success, failure);

Разбиение данных по страницам

Используйте методы take() и skip(). Например, если вы хотите разбить на строки таблицу, содержащую 100 записей:

var totalCount = 0, pages = 0;

// Step 1 - get the total number of records
table.includeTotalCount().take(0).read(function (results) {
    totalCount = results.totalCount;
    pages = Math.floor(totalCount/100) + 1;
    loadPage(0);
}, failure);

function loadPage(pageNum) {
    let skip = pageNum * 100;
    table.skip(skip).take(100).read(function (results) {
        for (var i = 0 ; i < results.length ; i++) {
            var row = results[i];
            // Process each row
        }
    }
}

Метод .includeTotalCount() добавляет в объект результатов поле totalCount. В этом поле указывается общее количество записей, которое будет возвращено, если данные не разбиты на страницы.

После этого можно настроить список страниц, используя переменную pages и определенные кнопки пользовательского интерфейса, и загрузить новые данные на каждой странице с помощью метода loadPage(). Чтобы ускорить доступ к уже загруженным записям, добавьте кэширование.

Возврат отсортированных данных

Используйте методы запроса .orderBy() или .orderByDescending():

table
    .orderBy('name')
    .read()
    .then(success, failure);

Дополнительные сведения об объекте запроса см. в [документации по объектам запросов].

Вставка данных

Создайте объект JavaScript с соответствующей датой и асинхронно вызовите метод table.insert():

var newItem = {
    name: 'My Name',
    signupDate: new Date()
};

table
    .insert(newItem)
    .done(function (insertedItem) {
        var id = insertedItem.id;
    }, failure);

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

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

Изменение данных

Как и при использовании метода .insert(), в этом случае следует создать объект обновления и вызвать метод .update(). Объект обновления должен содержать идентификатор обновляемой записи, получаемый при ее чтении или при вызове метода .insert().

var updateItem = {
    id: '7163bc7a-70b2-4dde-98e9-8818969611bd',
    name: 'My New Name'
};

table
    .update(updateItem)
    .done(function (updatedItem) {
        // You can now update your cached copy
    }, failure);

Удаление данных

Для удаления записи вызовите метод .del(). В ссылке на объект укажите идентификатор:

table
    .del({ id: '7163bc7a-70b2-4dde-98e9-8818969611bd' })
    .done(function () {
        // Record is now deleted - update your cache
    }, failure);

Аутентификация пользователей

Служба приложений Azure поддерживает аутентификацию и авторизацию пользователей с помощью различных внешних поставщиков удостоверений: Facebook, Google, учетная запись Майкрософт и Twitter. Можно задать разрешения таблиц, чтобы предоставить доступ к определенным операциям только пользователям, прошедшим проверку подлинности. Удостоверения пользователей, прошедших проверку подлинности, также можно применять для реализации правил авторизации в серверных скриптах. Дополнительные сведения см. в учебнике Приступая к работе с проверкой подлинности.

Если в приложении Apache Cordova используется проверка подлинности, должны быть доступны следующие подключаемые модули Cordova:

• cordova-plugin-device
• cordova-plugin-inappbrowser

Примечание.

Последние изменения для системы безопасности в iOS и Android могут привести к недоступности проверки подлинности на сервере. В таких случаях необходимо использовать клиентский поток.

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

Проверка подлинности с помощью поставщика (серверный поток)

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

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

client.login("facebook").done(function (results) {
     alert("You are now signed in as: " + results.userId);
}, function (err) {
     alert("Error: " + err);
});

Допустимые для поставщика значения: aad, facebook, google, microsoftaccount и twitter.

Примечание.

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

В этом случае служба приложений Azure управляет потоком проверки подлинности согласно протоколу OAuth 2.0. Она отображает страницу входа выбранного поставщика и создает маркер проверки подлинности службы приложений после успешного входа с помощью поставщика удостоверений. Функция login после завершения работы возвращает объект JSON, который содержит и идентификатор пользователя, и маркер проверки подлинности службы приложений в полях userId и authenticationToken соответственно. Этот маркер можно поместить в кэш и повторно использовать, пока не истечет срок его действия.

Проверка подлинности с помощью поставщика (клиентский поток)

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

Простой пример проверки подлинности на основе учетной записи социальной сети

В этом примере используется пакет SDK для клиента Facebook для проверки подлинности:

client.login("facebook", {"access_token": token})
.done(function (results) {
     alert("You are now signed in as: " + results.userId);
}, function (err) {
     alert("Error: " + err);
});

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

Получение сведений о пользователе, прошедшем аутентификацию

Сведения о проверке подлинности можно получить из конечной точки /.auth/me, выполнив вызов HTTP с помощью любой библиотеки HTTP/REST. Обязательно настройте заголовок X-ZUMO-AUTH для маркера аутентификации. Маркер аутентификации хранится в client.currentUser.mobileServiceAuthenticationToken. Например, чтобы использовать API выборки:

var url = client.applicationUrl + '/.auth/me';
var headers = new Headers();
headers.append('X-ZUMO-AUTH', client.currentUser.mobileServiceAuthenticationToken);
fetch(url, { headers: headers })
    .then(function (data) {
        return data.json()
    }).then(function (user) {
        // The user object contains the claims for the authenticated user
    });

Компонент выборки предоставляется в виде пакета NPM или для скачивания браузером из CDNJS. Данные получаются в виде объекта JSON.

Настройка службы мобильных приложений для внешних URL-адресов перенаправления

Для обработки потоков пользовательского интерфейса OAuth некоторые типы приложений Apache Cordova используют функцию замыкания на себя. Потоки пользовательского интерфейса OAuth в localhost приводят к возникновению проблем, так как службе аутентификации известно только, как использовать вашу службу по умолчанию. Ниже перечислены примеры проблемных потоков пользовательского интерфейса OAuth:

• эмулятор Ripple;
• динамическая перезагрузка с Ionic.
• Локальное выполнение серверной части мобильной службы
• Возможно выполнение серверной части мобильной службы в службе приложений Azure, отличной от той, которая обеспечивает аутентификацию.

Чтобы добавить локальные параметры в конфигурацию, выполните приведенные ниже указания.

1. Войдите на портал Azure

2. Выберите Все ресурсы или Службы приложений, а затем щелкните имя своего мобильного приложения.

3. Щелкните Инструменты

4. В меню "Наблюдение" щелкните Обозреватель ресурсов, затем щелкните Перейти. Откроется новое окно или вкладка.

5. В левой области навигации разверните узлы config, authsettings для сайта.

6. Щелкните Изменить

7. Найдите элемент "allowedExternalRedirectUrls". Ему может быть присвоено значение NULL или массив значений. Измените его значение на следующее:

   "allowedExternalRedirectUrls": [
       "http://localhost:3000",
       "https://localhost:3000"
   ],
   

   Замените URL-адреса на URL-адреса службы. Примеры: http://localhost:3000 (для примера службы Node.js) или http://localhost:4400 (для службы Ripple). Это только примеры URL-адресов. Ваша ситуация, включая упомянутые в приведенных примерах службы, может быть совершенно другой.

8. В правом верхнем углу экрана нажмите кнопку Чтение и запись .

9. Нажмите зеленую кнопку PUT .

Параметры будут сохранены. Не закрывайте окно браузера, пока не завершится сохранение параметров. Кроме того, добавьте указанные URL-адреса замыкания на себя в параметры CORS своей службы приложений.

1. Войдите на портал Azure
2. Выберите Все ресурсы или Службы приложений, а затем щелкните имя своего мобильного приложения.
3. Автоматически откроется колонка "Параметры". В противном случае щелкните Все параметры.
4. В меню API щелкните CORS .
5. Введите URL-адрес, который вы хотите добавить, и нажмите клавишу ВВОД.
6. При необходимости введите дополнительные URL-адреса.
7. Нажмите кнопку Сохранить , чтобы сохранить параметры.

Новые параметры вступят в действие приблизительно через 10–15 секунд.