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

Статья
12/19/2022

Заметка

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

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

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

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

API Android 19+.
iOS версии 8.0 и более поздних версий.

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

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

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

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

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

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

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

Чтобы правильно настроить проект Ionic версии 2, сначала создайте базовое приложение и добавьте подключаемый модуль 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 версии 1, так и версии 2. Только приложения Ionic версии 2 требуют дополнительного объявления для объекта WindowsAzure.

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

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

var client = WindowsAzure.MobileServiceClient(appUrl);

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

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

var table = client.getTable(tableName);

После получения ссылки на таблицу можно продолжить работу с таблицей:

запрос таблицы
вставка данных
изменение данных
удалении данных

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

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

/**
 * 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()).

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

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

Для ссылки на таблицу можно использовать предложение 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 в объект результатов. Поле totalCount заполняется общим количеством записей, которые будут возвращены, если не используется разбиение по страницам.

Затем можно использовать переменную страниц и некоторые кнопки пользовательского интерфейса для предоставления списка страниц; используйте loadPage() для загрузки новых записей для каждой страницы. Реализуйте кэширование для ускорения доступа к записям, которые уже загружены.

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

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

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

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

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

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

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

Как и в методе .insert(), необходимо создать объект Update, а затем вызвать .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:

Заметка

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

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

Эмулятор Рябь.
Live Reload with Ionic.
Локальное выполнение серверной части мобильного устройства
Запуск серверной части мобильного устройства в другой службе приложений Azure, отличной от той, которая предоставляет проверку подлинности.

Выполните следующие инструкции, чтобы добавить локальные параметры в конфигурацию:

Войдите на портал Azure
Выберите Все ресурсы или Службы приложений выберите имя мобильного приложения.
Щелкните Сервис
Щелкните обозревателя ресурсов в меню OBSERVE, а затем щелкните Перейти. Откроется новое окно или вкладка.
Разверните конфигурацию узлах сайта в области навигации слева.
Щелкните Изменить
Найдите элемент allowedExternalRedirectUrls. Для него может быть задано значение NULL или массив значений. Измените значение на следующее значение:
```
"allowedExternalRedirectUrls": [
    "http://localhost:3000",
    "https://localhost:3000"
],
```
Замените URL-адреса URL-адресами службы. Примеры включают http://localhost:3000 (для службы Node.js образца) или http://localhost:4400 (для службы Ripple). Однако эти URL-адреса являются примерами— ваша ситуация, в том числе для служб, упомянутых в примерах, может отличаться.
Нажмите кнопку чтение и запись в правом верхнем углу экрана.
Нажмите зеленую кнопку PUT.

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

Войдите на портал Azure
Выберите Все ресурсы или Службы приложений выберите имя мобильного приложения.
Откроется колонка "Параметры" автоматически. Если это не так, щелкните все параметры.
Щелкните CORS в меню API.
Введите URL-адрес, который вы хотите добавить в поле, и нажмите клавишу ВВОД.
Введите дополнительные URL-адреса по мере необходимости.
Щелкните Сохранить, чтобы сохранить параметры.

Чтобы новые параметры вступают в силу, потребуется примерно 10–15 секунд.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Дополнительные ресурсы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Базовый пример социальной проверки подлинности

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

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

Дополнительные ресурсы