Comment utiliser la bibliothèque cliente Apache Cordova pour Azure Mobile Apps
Vue d’ensemble
Ce guide indique le déroulement de scénarios courants dans le cadre de l’utilisation du dernier plug-in Apache Cordova pour Azure Mobile Apps. Si vous ne connaissez pas Azure Mobile Apps, consultez d’abord la section Démarrage rapide d’Azure Mobile Apps pour créer un serveur principal, créer une table et télécharger un projet Apache Cordova prédéfini. Dans ce guide, nous nous concentrons sur le plug-in Apache Cordova côté client.
Plateformes prises en charge
Ce kit de développement logiciel (SDK) prend en charge Apache Cordova 6.0.0 et version ultérieure sur les appareils iOS, Android et Windows. La prise en charge de la plate-forme est la suivante :
- Android API 19-24 (KitKat à Nougat).
- iOS 8.0 et versions ultérieures.
- Windows Phone 8.1.
- Plateforme Windows universelle.
Configuration et prérequis
Ce guide part du principe que vous avez créé un serveur principal avec une table. Ce guide suppose que la table a le même schéma que les tables dans ces didacticiels. Ce guide suppose également que vous avez ajouté le plug-in Apache Cordova à votre code. Si ce n’est pas le cas, vous pouvez l’ajouter à votre projet depuis la ligne de commande :
cordova plugin add cordova-plugin-ms-azure-mobile-apps
Pour plus d’informations sur la création de votre première application Apache Cordova, consultez la documentation officielle.
Configuration d’une application Ionic v2
Pour configurer correctement un projet Ionic v2, créez d’abord une application de base et ajoutez le plug-in Cordova :
ionic start projectName --v2
cd projectName
ionic plugin add cordova-plugin-ms-azure-mobile-apps
Ajoutez les lignes suivantes à app.component.ts pour créer l’objet client :
declare var WindowsAzure: any;
var client = new WindowsAzure.MobileServiceClient("https://yoursite.azurewebsites.net");
Vous pouvez maintenant générer et exécuter le projet dans le navigateur :
ionic platform add browser
ionic run browser
Le plug-in Azure Mobile Apps Cordova prend en charge les applications Ionic v1 et v2. Seules les applications Ionic v2 nécessitent la déclaration supplémentaire pour l’objet WindowsAzure.
Créer une connexion cliente
Créez une connexion cliente en créant un objet WindowsAzure.MobileServiceClient . Remplacez appUrl par l’URL de votre application mobile.
var client = WindowsAzure.MobileServiceClient(appUrl);
Utiliser des tables
Pour accéder aux données ou les mettre à jour, créez une référence à la table principale. Remplacez tableName par le nom de votre table.
var table = client.getTable(tableName);
Une fois que vous disposez d’une référence de table, vous pouvez continuer à utiliser votre table :
Comment : interroger une référence de table
Une fois que vous disposez d’une référence de table, vous pouvez l’utiliser pour rechercher des données sur le serveur. Les requêtes sont effectuées dans un langage de type LINQ. Pour retourner toutes les données de la table, utilisez le code suivant :
/**
* 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);
La fonction success est appelée avec les résultats. Ne recourez pas à for (var i in results) dans la fonction success, car cette action entraîne une itération sur les informations contenues dans les résultats quand d’autres fonctions de requête (telles que .includeTotalCount()) sont utilisées.
Pour plus d’informations sur la syntaxe de requête, consultez la [documentation de l’objet Query].
Filtrage des données sur le serveur
Vous pouvez utiliser une clause where sur la référence de table :
table
.where({ userId: user.userId, complete: false })
.read()
.then(success, failure);
Vous pouvez également utiliser une fonction qui filtre l’objet. Dans ce cas, la variable this est affectée à l’objet en cours de filtrage. Le code suivant est équivalent à l’exemple précédent sur le plan fonctionnel :
function filterByUserId(currentUserId) {
return this.userId === currentUserId && this.complete === false;
}
table
.where(filterByUserId, user.userId)
.read()
.then(success, failure);
Pagination des données
Utilisez les méthodes take() et skip(). Par exemple, si vous souhaitez fractionner la table en enregistrements de 100 lignes :
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
}
}
}
La méthode .includeTotalCount() est utilisée pour ajouter un champ totalCount à l’objet results. Le champ totalCount est rempli avec le nombre total d’enregistrements qui est retourné si aucune pagination n’est utilisée.
Vous pouvez ensuite utiliser la variable pages et des boutons d’interface utilisateur pour fournir une liste de pages ; utilisez loadPage() pour charger les nouveaux enregistrements pour chaque page. Implémentez la mise en cache pour accélérer l’accès aux enregistrements qui ont déjà été chargés.
Procédure : renvoi de données triées
Utilisez les méthodes de requête .orderBy() ou .orderByDescending() :
table
.orderBy('name')
.read()
.then(success, failure);
Pour plus d’informations sur l’objet Query, consultez la [documentation de l’objet Query].
Comment : insérer des données
Créez un objet JavaScript avec la date appropriée et appelez table.insert() de façon asynchrone :
var newItem = {
name: 'My Name',
signupDate: new Date()
};
table
.insert(newItem)
.done(function (insertedItem) {
var id = insertedItem.id;
}, failure);
Une fois l’insertion correctement effectuée, l’élément inséré est retourné avec les champs supplémentaires qui sont nécessaires pour les opérations de synchronisation. Mettez à jour votre propre cache avec ces informations en vue des mises à jour ultérieures.
Le Kit de développement logiciel (SDK) de serveur Node.js Azure Mobile Apps prend en charge le schéma dynamique à des fins de développement. Le schéma dynamique vous permet d’ajouter des colonnes à la table en les spécifiant dans une opération d’insertion ou de mise à jour. Nous vous recommandons de désactiver le schéma dynamique avant de déplacer votre application vers un environnement de production.
Comment : modifier des données
Comme dans le cas de la méthode .insert(), vous devez créer un objet de mise à jour, puis appeler .update(). L’objet de mise à jour doit contenir l’ID de l’enregistrement à mettre à jour, obtenu au moment de la lecture de l’enregistrement ou de l’appel de .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);
Comment : supprimer des données
Pour supprimer un enregistrement, appelez la méthode .del(). Transmettez l’ID d’une référence d’objet :
table
.del({ id: '7163bc7a-70b2-4dde-98e9-8818969611bd' })
.done(function () {
// Record is now deleted - update your cache
}, failure);
Procédure : authentifier les utilisateurs
Azure App Service prend en charge l’authentification et l’autorisation des utilisateurs d’applications par le biais de divers fournisseurs d’identité externes : Facebook, Google, compte Microsoft et Twitter. Vous pouvez définir des autorisations sur les tables pour limiter l'accès à certaines opérations aux seuls utilisateurs authentifiés. Vous pouvez également utiliser l’identité des utilisateurs authentifiés pour implémenter des règles d’autorisation dans les scripts serveur. Pour plus d'informations, consultez la page Prise en main de l'authentification .
Quand vous utilisez l’authentification dans une application Apache Cordova, les plug-ins Cordova suivants doivent être réunis :
Deux flux d’authentification sont pris en charge : un flux serveur et un flux client. Le flux serveur fournit l'authentification la plus simple, car il repose sur l'interface d'authentification Web du fournisseur. Le flux client permet une intégration approfondie avec les fonctionnalités propres aux appareils, telles que l'authentification unique, car il repose sur des Kits de développement logiciel (SDK) propres aux appareils et aux fournisseurs.
Procédure : s’authentifier auprès d’un fournisseur (Flow serveur)
Pour que Mobile Apps gère le processus d’authentification dans votre application, vous devez inscrire votre application auprès de votre fournisseur d’identité. Ensuite, dans Azure App Service, vous devez configurer l’ID d’application et le secret fournis par votre fournisseur. Pour plus d'informations, consultez le didacticiel Ajout de l'authentification à votre application.
Une fois que vous avez inscrit votre fournisseur d'identité, appelez la méthode .login() avec le nom de votre fournisseur. Par exemple, pour vous connecter avec Facebook, utilisez le code suivant :
client.login("facebook").done(function (results) {
alert("You are now signed in as: " + results.userId);
}, function (err) {
alert("Error: " + err);
});
Les valeurs valides pour le fournisseur sont « aad », « facebook », « google », « microsoftaccount » et « twitter ».
Notes
L’authentification Google ne fonctionne pour le moment pas via le flux serveur. Pour s’authentifier auprès de Google, vous devez utiliser une méthode gérée par le client.
Dans ce cas, Azure App Service gère le flux d’authentification OAuth 2.0. Il affiche la page de connexion du fournisseur sélectionné et génère un jeton d’authentification App Service après avoir établi une connexion avec le fournisseur d’identité. La fonction de connexion, quand elle est utilisée, renvoie un objet JSON qui expose l’ID utilisateur et le jeton d’authentification App Service dans les champs userId et authenticationToken, respectivement. Ce jeton peut être mis en cache et réutilisé jusqu'à ce qu'il arrive à expiration.
Procédure : s’authentifier auprès d’un fournisseur (Flow client)
Votre application peut également contacter le fournisseur d’identité de manière indépendante, puis fournir le jeton renvoyé à App Service à des fins d’authentification. Le flux client permet de proposer l'authentification unique aux utilisateurs ou de récupérer d'autres données utilisateur auprès du fournisseur d'identité.
Exemple de base de l’authentification sociale
Cet exemple utilise le SDK client Facebook pour l'authentification :
client.login(
"facebook",
{"access_token": token})
.done(function (results) {
alert("You are now signed in as: " + results.userId);
}, function (err) {
alert("Error: " + err);
});
Cet exemple part du principe que le jeton fourni par le Kit de développement logiciel (SDK) propre au fournisseur est stocké dans une variable token.
Procédure : obtention des informations sur l’utilisateur authentifié
Les informations d’authentification peuvent être récupérées du point de terminaison /.auth/me à l’aide d’un appel HTTP avec une bibliothèque AJAX. Veillez à définir l’en-tête X-ZUMO-AUTH sur votre jeton d’authentification. Le jeton d'authentification est stocké dans client.currentUser.mobileServiceAuthenticationToken. Par exemple, pour utiliser l’API d’extraction :
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
});
L’extraction est disponible sous forme de package npm ou de téléchargement par navigateur à partir de CDNJS. Vous pouvez également utiliser jQuery ou une autre API AJAX pour extraire les informations. Les données sont reçues sous la forme d’un objet JSON.
Configurer votre Mobile App Service pour les URL de redirection externes.
Plusieurs types d’applications Apache Cordova utilisent une fonctionnalité de bouclage pour gérer les flux d’interface utilisateur OAuth. Les flux d’interface utilisateur OAuth posent des problèmes car le service d’authentification sait uniquement comment utiliser votre service par défaut. Voici quelques exemples de problèmes causés par les flux d’interface utilisateur OAuth :
- L’émulateur Ripple.
- Live recharger avec Ionic.
- Exécution locale du backend mobile
- Exécution du backend mobile dans une autre instance Azure App Service que celle fournissant l’authentification.
Suivez ces instructions pour ajouter vos paramètres régionaux à la configuration :
Connectez-vous au portail Azure
Sélectionnez Toutes les ressources ou App Services, puis cliquez sur le nom de votre application mobile.
Cliquez sur Outils
Cliquez sur Explorateur de ressources dans le menu OBSERVER, puis cliquez sur Atteindre. Une nouvelle fenêtre ou un nouvel onglet s’ouvre.
Développez les nœuds config et authsettings pour votre site dans le volet de navigation de gauche.
Cliquez sur Modifier
Recherchez l’élément "allowedExternalRedirectUrls". Il peut être défini sur null ou sur un tableau de valeurs. Remplacez la valeur par la valeur suivante :
"allowedExternalRedirectUrls": [ "https://localhost:3000", "https://localhost:3000" ],Remplacez les URL par les URL de votre service. Par exemple,
https://localhost:3000(pour l’exemple de service Node.js) ouhttps://localhost:4400(pour le service Ripple). Il s’agit seulement d’exemples d’URL. Votre situation, y compris pour les services mentionnés dans les exemples, peut être différente.Cliquez sur le bouton Lecture/Écriture dans le coin supérieur droit de l’écran.
Cliquez sur le bouton vert PUT .
Les paramètres sont alors enregistrés. Ne fermez pas la fenêtre du navigateur avant la fin de l’enregistrement des paramètres. Ajoutez également ces URL de bouclage aux paramètres de CORS pour votre App Service :
- Connectez-vous au portail Azure
- Sélectionnez Toutes les ressources ou App Services, puis cliquez sur le nom de votre application mobile.
- Le panneau Paramètres s’ouvre automatiquement. Si ce n’est pas le cas, cliquez sur Tous les paramètres.
- Cliquez sur CORS sous le menu de l’API.
- Entrez l’URL à ajouter dans la zone correspondante et appuyez sur Entrée.
- Entrez des URL supplémentaires, si nécessaire.
- Cliquez sur Enregistrer pour enregistrer les paramètres.
L’application des nouveaux paramètres prend environ 10 à 15 secondes.
Procédure : inscription aux notifications push
Installez le plug-in phonegap-plugin-push pour gérer les notifications Push. Vous pouvez ajouter ce plugin facilement en exécutant la commande cordova plugin add sur la ligne de commande, ou par le biais du programme d’installation de plug-in Git dans Visual Studio. Le code suivant dans votre application Apache Cordova inscrit votre appareil aux notifications 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
});
Utilisez le Kit de développement logiciel (SDK) Notification Hubs pour envoyer des notifications Push à partir du serveur. N’envoyez jamais de notifications Push directement depuis les clients. Cela risquerait de déclencher une attaque par déni de service au niveau des concentrateurs de notification ou de PNS. Le PNS pourrait bannir votre trafic en réponse à ces attaques.
Informations complémentaires
Vous pouvez trouver des informations sur les API dans notre documentation sur les API.