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

• Android
• Cordova
• JavaScript
• iOS
• Управляемый клиент (Windows, Xamarin)

Обзор

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

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

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

• API Android 19–24 (от KitKat до Nougat);
• iOS 8.0 и более поздних версий;
• Windows Phone 8.1;
• Универсальная платформа Windows.

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

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

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

Поддерживается два потока аутентификации: серверный и клиентский. Серверный поток обеспечивает самый простой способ проверки подлинности, так как он использует веб-интерфейс проверки подлинности. Клиентский поток обеспечивает более тесную интеграцию с возможностями устройства, такими как единый вход, так как использует пакеты 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.

Примечание

Сейчас проверка подлинности Google не выполняется через серверный поток. Для проверки подлинности с помощью Google необходимо использовать метод клиентского потока.

В этом случае служба приложений 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.

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

Сведения о проверке подлинности можно получить из конечной точки /.auth/me, выполнив вызов HTTP с помощью любой библиотеки AJAX. Обязательно настройте заголовок 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. Для получения информации можно также использовать jQuery или другой API AJAX. Данные получаются в виде объекта JSON.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Практическое руководство. Регистрация для получения push-уведомлений

Для обработки push-уведомлений установите phonegap-plugin-push . Этот подключаемый модуль можно легко добавить, введя команду cordova plugin add в командной строке или воспользовавшись установщиком подключаемых модулей Git в Visual Studio. Следующий код в приложении Apache Cordova регистрирует устройство для получения push-уведомлений.

var pushOptions = {
    android: {
        senderId: '<from-gcm-console>'
    },
    ios: {
        alert: true,
        badge: true,
        sound: true
    },
    windows: {
    }
};
pushHandler = PushNotification.init(pushOptions);

pushHandler.on('registration', function (data) {
    registrationId = data.registrationId;
    // For cross-platform, you can use the device plugin to determine the device
    // Best is to use device.platform
    var name = 'gcm'; // For android - default
    if (device.platform.toLowerCase() === 'ios')
        name = 'apns';
    if (device.platform.toLowerCase().substring(0, 3) === 'win')
        name = 'wns';
    client.push.register(name, registrationId);
});

pushHandler.on('notification', function (data) {
    // data is an object and is whatever is sent by the PNS - check the format
    // for your particular PNS
});

pushHandler.on('error', function (error) {
    // Handle errors
});

Для отправки push-уведомления с сервера используется пакет SDK для центров уведомлений. Никогда не следует отправлять push-уведомления непосредственно из клиентов. Это может быть использовано для атак типа "отказ в обслуживании" на центры уведомлений или PNS. PNS может заблокировать ваш трафик в результате таких атак.

Дополнительные сведения

Дополнительные сведения об API можно найти в нашей документация по API.