Comment utiliser le plug-in Apache Cordova pour Azure Mobile Apps
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 :
- API Android 19+.
- iOS 8.0 et versions ultérieures.
Avertissement
Cet article décrit les informations relatives à la version de la bibliothèque v4.2.0, qui est supprimée. Aucune autre mise à jour n’est apportée à cette bibliothèque, y compris les mises à jour pour les problèmes de sécurité. Envisagez de passer à un client .NET tel que .NET MAUI pour une prise en charge continue.
Configuration et prérequis
Ce guide part du principe que vous avez créé un serveur principal avec une table. Les exemples utilisent la table TodoItem issue des guides de démarrage rapide. Pour ajouter le plug-in Azure Mobile Apps à votre projet, utilisez la commande suivante :
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 :
Interrogation d’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.
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].
Insertion 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.
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);
Supprimer les 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);
Authentifier des 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 :
Remarque
Des changements de sécurité récents dans iOS et Android peuvent rendre indisponible l’authentification du flux serveur. Dans ce cas, vous devez utiliser un flux client.
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.
l’authentification auprès d’un fournisseur (flux 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 ».
Remarque
En raison de problèmes de sécurité, certains fournisseurs d’authentification risquent de ne pas utiliser un flux serveur. Dans ce cas, vous devez utiliser une méthode de flux 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.
l’authentification auprès d’un fournisseur (flux 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. Ce flux client permet de proposer une expérience de connexion unique aux utilisateurs ou de récupérer des données utilisateur supplémentaires 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. Les détails requis par chaque fournisseur sont légèrement différents. Consultez la documentation relative à l’authentification et à l’autorisation Azure App Service pour déterminer la forme exacte de la charge utile.
l’obtention des informations sur l’utilisateur authentifié
Les informations d’authentification peuvent être récupérées à partir du point de terminaison /.auth/me à l’aide d’un appel HTTP avec une bibliothèque HTTP/REST. 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. 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": [ "http://localhost:3000", "https://localhost:3000" ],Remplacez les URL par les URL de votre service. Par exemple,
http://localhost:3000(pour l’exemple de service Node.js) ouhttp://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 d’autres URL si nécessaire.
- Cliquez sur Enregistrer pour enregistrer les paramètres.
L’application des nouveaux paramètres prend environ 10 à 15 secondes.
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour