Comment utiliser le plug-in Apache Cordova pour Azure Mobile Apps
Note
Ce produit est mis hors service. Pour un remplacement des projets utilisant .NET 8 ou version ultérieure, consultez la bibliothèque Datasync Community Toolkit.
Ce guide vous apprend à effectuer des scénarios courants à l’aide du dernier plug-in Apache Cordova Apache Cordova pour Azure Mobile Apps. Si vous débutez avec Azure Mobile Apps, commencez par terminer démarrage rapide Azure Mobile Apps pour créer un back-end, 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 SDK prend en charge Apache Cordova v6.0.0 et versions ultérieures sur les appareils iOS, Android et Windows. La prise en charge de la plateforme est la suivante :
- API Android 19+.
- iOS versions 8.0 et 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 conditions préalables
Ce guide part du principe que vous avez créé un back-end avec une table. Les exemples utilisent la table TodoItem à partir des démarrages rapides. 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 leur documentation.
Configuration d’une application Ionic v2
Pour configurer correctement un projet Ionic v2, commencez par créer 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 Cordova Azure Mobile Apps 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 back-end. 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 travailler plus loin avec votre table :
-
interroger une table
- filtrage des données
- pagination via le de données
- tri des données
- Insertion de données
- modification des de données
- suppression de données
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 « LINQ-like ». 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 de réussite est appelée avec les résultats. N’utilisez pas for (var i in results) dans la fonction de réussite, car cela itérera sur les informations incluses dans les résultats lorsque 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 de requête .
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 actuel filtré. Le code suivant est fonctionnellement équivalent à l’exemple précédent :
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 de résultats. Le champ totalCount est rempli avec le nombre total d’enregistrements retournés si aucune pagination n’est utilisée.
Vous pouvez ensuite utiliser la variable de pages et certains 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.
Retourner des 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 sur l’objet Query].
Insérer des données
Créez un objet JavaScript avec la date appropriée et appelez table.insert() de manière asynchrone :
var newItem = {
name: 'My Name',
signupDate: new Date()
};
table
.insert(newItem)
.done(function (insertedItem) {
var id = insertedItem.id;
}, failure);
Lors de l’insertion réussie, l’élément inséré est retourné avec des champs supplémentaires requis pour les opérations de synchronisation. Mettez à jour votre propre cache avec ces informations pour les mises à jour ultérieures.
Le SDK Azure Mobile Apps Node.js Server 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 en production.
Modifier des données
Comme pour la méthode .insert(), vous devez créer un objet Update, puis appeler .update(). L’objet de mise à jour doit contenir l’ID de l’enregistrement à mettre à jour : l’ID est obtenu lors de la lecture de l’enregistrement ou lors 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 des données
Pour supprimer un enregistrement, appelez la méthode .del(). Transmettez l’ID dans 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 les utilisateurs
Azure App Service prend en charge l’authentification et l’autorisation des utilisateurs d’applications à l’aide de différents fournisseurs d’identité externes : Facebook, Google, Compte Microsoft et Twitter. Vous pouvez définir des autorisations sur des tables pour restreindre l’accès pour des opérations spécifiques aux utilisateurs authentifiés uniquement. Vous pouvez également utiliser l’identité des utilisateurs authentifiés pour implémenter des règles d’autorisation dans des scripts de serveur. Pour plus d’informations, consultez le didacticiel Bien démarrer avec l’authentification.
Lorsque vous utilisez l’authentification dans une application Apache Cordova, les plug-ins Cordova suivants doivent être disponibles :
- cordova-plugin-device
- cordova-plugin-inappbrowser
Note
Les modifications de sécurité récentes dans iOS et Android peuvent rendre l’authentification de flux de serveur indisponible. Dans ces cas, vous devez utiliser un flux client.
Deux flux d’authentification sont pris en charge : un flux de serveur et un flux client. Le flux de serveur offre l’expérience d’authentification la plus simple, car il s’appuie sur l’interface d’authentification web du fournisseur. Le flux client permet une intégration plus approfondie avec des fonctionnalités spécifiques à l’appareil, telles que l’authentification unique, car il s’appuie sur des kits SDK spécifiques à un appareil spécifiques au fournisseur.
S’authentifier auprès d’un fournisseur (flux de 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 votre Azure App Service, vous devez configurer l’ID d’application et le secret fournis par votre fournisseur. Pour plus d’informations, consultez le didacticiel Ajouter 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 ».
Note
En raison de problèmes de sécurité, certains fournisseurs d’authentification peuvent ne pas fonctionner avec un flux de serveur. Vous devez utiliser une méthode de flux client dans ces cas.
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 la connexion réussie avec le fournisseur d’identité. La fonction de connexion, une fois terminée, retourne un objet JSON qui expose respectivement l’ID utilisateur et le jeton d’authentification App Service dans les champs userId et authenticationToken. Ce jeton peut être mis en cache et réutilisé jusqu’à son expiration.
S’authentifier auprès d’un fournisseur (flux client)
Votre application peut également contacter indépendamment le fournisseur d’identité, puis fournir le jeton retourné à votre App Service pour l’authentification. Ce flux client vous permet de fournir une expérience de connexion unique pour les utilisateurs ou de récupérer des données utilisateur supplémentaires à partir du fournisseur d’identité.
Exemple de base de l’authentification sociale
Cet exemple utilise le Kit de développement logiciel (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) du fournisseur respectif est stocké dans la variable de jeton. Les détails requis par chaque fournisseur sont légèrement différents. Consultez la documentation l’authentification et l’autorisation Azure App Service pour déterminer la forme exacte de la charge utile.
Obtenir 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 n’importe quelle 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 fetch :
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
});
Fetch est disponible en tant que un package npm ou pour le téléchargement du navigateur à partir de CDNJS. Les données sont reçues en tant qu’objet JSON.
Configurez votre Mobile App Service pour les URL de redirection externe.
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 sur localhost provoquent des problèmes, car le service d’authentification sait uniquement comment utiliser votre service par défaut. Voici quelques exemples de flux d’interface utilisateur OAuth problématiques :
- L’émulateur d’Ondulation.
- Rechargement en direct avec Ionic.
- Exécution locale du back-end mobile
- Exécution du back-end mobile dans un autre service Azure App Service que celui qui fournit l’authentification.
Suivez ces instructions pour ajouter vos paramètres locaux à la configuration :
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 Accéder à. Une nouvelle fenêtre ou onglet s’ouvre.
Développez la configuration , les authentifications nœuds de votre site dans la navigation de gauche.
Cliquez sur Modifier
Recherchez l’élément « allowedExternalRedirectUrls ». Elle peut être définie 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. Les exemples incluent
http://localhost:3000(pour l’exemple de service Node.js) ouhttp://localhost:4400(pour le service Ondulation). Toutefois, ces URL sont des exemples : 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 enregistrés à ce stade. Ne fermez pas la fenêtre du navigateur tant que les paramètres n’ont pas terminé l’enregistrement. Ajoutez également ces URL de bouclage aux paramètres CORS de 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 API.
- Entrez l’URL que vous souhaitez ajouter dans la zone fournie, puis appuyez sur Entrée.
- Entrez d’autres URL en fonction des besoins.
- Cliquez sur Enregistrer pour enregistrer les paramètres.
Il faut environ 10 à 15 secondes pour que les nouveaux paramètres prennent effet.