Come usare la libreria client apache Cordova per app per dispositivi mobili di Azure
Informazioni generali
Questa guida illustra come eseguire scenari comuni usando il plug-in Apache Cordova più recente per app per dispositivi mobili di Azure. Se non si ha esperienza con app per dispositivi mobili di Azure, completare prima di tutto Avvio rapido di App per dispositivi mobili di Azure per creare un back-end, creare una tabella e scaricare un progetto Apache Cordova predefinito. In questa guida viene illustrato il plug-in Apache Cordova sul lato client.
Piattaforme supportate
Questo SDK supporta Apache Cordova v6.0.0 e versioni successive nei dispositivi iOS, Android e Windows. Il supporto della piattaforma è il seguente:
- API Android 19-24 (KitKat fino a Nougat).
- iOS versioni 8.0 e successive.
- Windows Phone 8.1.
- Piattaforma UWP (Universal Windows Platform).
Configurazione e prerequisiti
Questa guida presuppone che sia stato creato un back-end con una tabella. In questa guida si presuppone che la tabella abbia lo stesso schema delle tabelle di tali esercitazioni. Questa guida presuppone anche che sia stato aggiunto il plug-in Apache Cordova al codice. In caso contrario, è possibile aggiungere il plug-in Apache Cordova al progetto nella riga di comando:
cordova plugin add cordova-plugin-ms-azure-mobile-apps
Per altre informazioni sulla creazione di la prima app Apache Cordova, vedere la relativa documentazione.
Configurazione di un'app Ionic v2
Per configurare correttamente un progetto DiIon v2, creare prima di tutto un'app di base e aggiungere il plug-in Cordova:
ionic start projectName --v2
cd projectName
ionic plugin add cordova-plugin-ms-azure-mobile-apps
Aggiungere le righe seguenti a app.component.ts per creare l'oggetto client:
declare var WindowsAzure: any;
var client = new WindowsAzure.MobileServiceClient("https://yoursite.azurewebsites.net");
È ora possibile compilare ed eseguire il progetto nel browser:
ionic platform add browser
ionic run browser
Il plug-in Cordova per app mobili di Azure supporta sia le app Ionic v1 che v2. Solo le app DiIon v2 richiedono la dichiarazione aggiuntiva per l'oggetto WindowsAzure.
Creare una connessione client
Creare una connessione client creando un oggetto WindowsAzure.MobileServiceClient. Sostituire appUrl con l'URL dell'app per dispositivi mobili.
var client = WindowsAzure.MobileServiceClient(appUrl);
Utilizzare le tabelle
Per accedere o aggiornare i dati, creare un riferimento alla tabella back-end. Sostituire tableName con il nome della tabella
var table = client.getTable(tableName);
Dopo aver ottenuto un riferimento alla tabella, è possibile lavorare ulteriormente con la tabella:
-
interrogare una tabella
- filtro dei dati
- Scorrere tra i dati
- l'ordinamento dei dati
- inserimento di dati
- Modifica dei dati
- Eliminazione dei dati
Procedura: Eseguire query su un riferimento a una tabella
Dopo aver creato un riferimento alla tabella, è possibile usarlo per eseguire query sui dati nel server. Le query vengono eseguite in un linguaggio simile a LINQ. Per restituire tutti i dati dalla tabella, usare il codice seguente:
/**
* 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 funzione *success* viene chiamata con i risultati. Non usare for (var i in results) nella funzione di operazione riuscita, perché eseguirà l'iterazione delle informazioni incluse nei risultati quando vengono usate altre funzioni di query , ad esempio .includeTotalCount().
Per altre informazioni sulla sintassi query, vedere la [documentazione dell'oggetto query].
Filtro dei dati nel server
È possibile usare una clausola where nel riferimento alla tabella:
table
.where({ userId: user.userId, complete: false })
.read()
.then(success, failure);
È anche possibile usare una funzione che filtra l'oggetto. In questo caso, la variabile this viene assegnata all'oggetto corrente filtrato. Il codice seguente è funzionalmente equivalente all'esempio precedente:
function filterByUserId(currentUserId) {
return this.userId === currentUserId && this.complete === false;
}
table
.where(filterByUserId, user.userId)
.read()
.then(success, failure);
Scorrere i dati
Utilizzare i metodi take() e skip(). Ad esempio, se si vuole suddividere la tabella in record di 100 righe:
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
}
}
}
Il metodo .includeTotalCount() viene utilizzato per aggiungere un campo totalCount all'oggetto risultati. Il campo totalCount viene compilato con il numero totale di record che verrebbero restituiti se non viene utilizzato alcun paging.
È quindi possibile usare la variabile pages e alcuni pulsanti dell'interfaccia utente per fornire un elenco di pagine; usare loadPage() per caricare i nuovi record per ogni pagina. Implementare la memorizzazione nella cache per velocizzare l'accesso ai record già caricati.
Procedura: Restituire dati ordinati
Usare i metodi di interrogazione .orderBy() o .orderByDescending():
table
.orderBy('name')
.read()
.then(success, failure);
Per altre informazioni sull'oggetto Query, vedere la [documentazione dell'oggetto Query].
Procedura: Inserire dati
Creare un oggetto JavaScript con la data appropriata e chiamare table.insert() in modo asincrono:
var newItem = {
name: 'My Name',
signupDate: new Date()
};
table
.insert(newItem)
.done(function (insertedItem) {
var id = insertedItem.id;
}, failure);
Al termine dell'inserimento, l'elemento inserito viene restituito con i campi aggiuntivi necessari per le operazioni di sincronizzazione. Aggiornare la propria cache con queste informazioni per gli aggiornamenti successivi.
App per dispositivi mobili di Azure Node.js Server SDK supporta lo schema dinamico a scopo di sviluppo. Lo schema dinamico consente di aggiungere colonne alla tabella specificandole in un'operazione di inserimento o aggiornamento. È consigliabile disattivare lo schema dinamico prima di spostare l'applicazione nell'ambiente di produzione.
Procedura: Modificare i dati
Analogamente al metodo .insert(), è necessario creare un oggetto Update e quindi chiamare .update(). L'oggetto update deve contenere l'ID del record da aggiornare. L'ID viene ottenuto durante la lettura del record o quando si chiama .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);
Procedura: Eliminare dati
Per eliminare un record, chiamare il metodo .del(). Passare l'ID in un riferimento a un oggetto:
table
.del({ id: '7163bc7a-70b2-4dde-98e9-8818969611bd' })
.done(function () {
// Record is now deleted - update your cache
}, failure);
Procedura: Autenticare gli utenti
Servizio app di Azure supporta l'autenticazione e l'autorizzazione degli utenti di app usando diversi provider di identità esterni: Facebook, Google, Account Microsoft e Twitter. È possibile impostare le autorizzazioni per le tabelle per limitare l'accesso per operazioni specifiche solo agli utenti autenticati. È anche possibile usare l'identità degli utenti autenticati per implementare le regole di autorizzazione negli script del server. Per altre informazioni, vedere l'esercitazione Introduzione all'autenticazione.
Quando si usa l'autenticazione in un'app Apache Cordova, i plug-in Cordova seguenti devono essere disponibili:
Sono supportati due flussi di autenticazione: un flusso server e un flusso client. Il flusso del server offre l'esperienza di autenticazione più semplice, perché si basa sull'interfaccia di autenticazione Web del provider. Il flusso client consente un'integrazione più approfondita con funzionalità specifiche del dispositivo, ad esempio Single Sign-On, in quanto si basa su SDK specifici del provider specifici del dispositivo.
Procedura: Eseguire l'autenticazione con un provider (Flusso del server)
Per fare in modo che app per dispositivi mobili gestisca il processo di autenticazione nell'app, devi registrare l'app con il provider di identità. Nel servizio app di Azure è quindi necessario configurare l'ID applicazione e il segreto forniti dal provider. Per ulteriori informazioni, consulta il tutorial Aggiungi autenticazione alla tua app.
Dopo aver registrato il provider di identità, invocare il metodo .login() con il nome del provider. Ad esempio, per accedere con Facebook usare il codice seguente:
client.login("facebook").done(function (results) {
alert("You are now signed in as: " + results.userId);
}, function (err) {
alert("Error: " + err);
});
I valori validi per il provider sono "aad", "facebook", "google", "microsoftaccount" e "twitter".
Nota
Google Authentication non funziona attualmente tramite Server Flow. Per eseguire l'autenticazione con Google, è necessario usare un metodo di flusso client.
In questo caso, il servizio app di Azure gestisce il flusso di autenticazione OAuth 2.0. Visualizza la pagina di accesso del provider selezionato e genera un token di autenticazione del Servizio App dopo l'accesso con il provider di identità. La funzione di accesso, al termine, restituisce un oggetto JSON che espone rispettivamente l'ID utente e il token di autenticazione del servizio app nei campi userId e authenticationToken. Questo token può essere memorizzato nella cache e riutilizzato fino alla scadenza.
Procedura: Eseguire l'autenticazione con un provider (Flusso del client)
L'app può anche contattare il provider di identità in modo indipendente e quindi fornire il token restituito al servizio app per l'autenticazione. Questo flusso client consente di offrire un'esperienza di accesso Single Sign-In per gli utenti o recuperare dati utente aggiuntivi dal provider di identità.
Esempio di base di autenticazione social
Questo esempio usa l'SDK client Facebook per l'autenticazione:
client.login(
"facebook",
{"access_token": token})
.done(function (results) {
alert("You are now signed in as: " + results.userId);
}, function (err) {
alert("Error: " + err);
});
In questo esempio si presuppone che il token fornito dal rispettivo SDK del provider sia archiviato nella variabile del token.
Procedura: Ottenere informazioni sull'utente autenticato
Le informazioni di autenticazione possono essere recuperate dall'endpoint /.auth/me usando una chiamata HTTP con qualsiasi libreria AJAX. Assicurarsi di impostare l'intestazione X-ZUMO-AUTH sul token di autenticazione. Il token di autenticazione viene archiviato in client.currentUser.mobileServiceAuthenticationToken. Ad esempio, per usare l'API di recupero:
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 è disponibile come un pacchetto npm o per il download nei browser da CDNJS. È anche possibile usare jQuery o un'altra API AJAX per recuperare le informazioni. I dati sono ricevuti come oggetto JSON.
Procedura: Configurare il servizio app per dispositivi mobili per gli URL di reindirizzamento esterni.
Diversi tipi di applicazioni Apache Cordova usano una funzionalità di loopback per gestire i flussi dell'interfaccia utente OAuth. I flussi dell'interfaccia utente OAuth in localhost causano problemi perché il servizio di autenticazione è in grado di utilizzare il tuo servizio solo per impostazione predefinita. Esempi di flussi di interfaccia utente OAuth problematici includono:
- Emulatore di Ripple.
- Ricaricamento in tempo reale con Ionic.
- Esecuzione del back-end mobile in locale
- Esecuzione del back-end per dispositivi mobili in un servizio app di Azure diverso da quello che fornisce l'autenticazione.
Seguire queste istruzioni per aggiungere le impostazioni locali alla configurazione:
Accedere al portale di Azure
Selezionare Tutte le risorse o Servizi app quindi fare clic sul nome dell'app per dispositivi mobili.
Fare clic su strumenti
Fare clic su Esplora risorse nel menu OBSERVE, quindi scegliere Vai. Verrà visualizzata una nuova finestra o una nuova scheda.
Espandi i nodi config e authsettings per il tuo sito nel riquadro di navigazione a sinistra.
Fai clic su Modifica
Cercare l'elemento "allowedExternalRedirectUrls". Può essere impostato su Null o su una matrice di valori. Modificare il valore con il valore seguente:
"allowedExternalRedirectUrls": [ "https://localhost:3000", "https://localhost:3000" ],Sostituire gli URL con gli URL del tuo servizio. Gli esempi includono
https://localhost:3000(per il servizio di esempio Node.js) ohttps://localhost:4400(per il servizio Ripple). Tuttavia, questi URL sono esempi: la situazione, inclusa per i servizi menzionati negli esempi, può essere diversa.Fare clic sul pulsante lettura/scrittura nell'angolo superiore destro della schermata.
Fare clic sul pulsante verde PUT.
Le impostazioni vengono salvate a questo punto. Non chiudere la finestra del browser fino al termine del salvataggio delle impostazioni. Aggiungere anche questi URL di loopback alle impostazioni CORS per il servizio app:
- Accedere al portale di Azure
- Selezionare Tutte le risorse o Servizi app quindi fare clic sul nome dell'app per dispositivi mobili.
- La schermata Impostazioni si apre automaticamente. In caso contrario, fare clic su Tutte le impostazioni.
- Fare clic su CORS nel menu API.
- Immettere l'URL da aggiungere nella casella specificata e premere INVIO.
- Immettere URL aggiuntivi in base alle esigenze.
- Fare clic su Salva per salvare le impostazioni.
Per rendere effettive le nuove impostazioni sono necessari circa 10-15 secondi.
Procedura: Eseguire la registrazione per le notifiche push
Installare il phonegap-plugin-push per gestire le notifiche push. Questo plug-in può essere aggiunto facilmente usando il comando cordova plugin add nella riga di comando o tramite il programma di installazione del plug-in Git all'interno di Visual Studio. Il codice seguente nell'app Apache Cordova registra il dispositivo per le notifiche 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
});
Usare l'SDK di Hub di notifica per inviare notifiche push dal server. Non inviare mai notifiche push direttamente dai client. Questa operazione può essere usata per attivare un attacco Denial of Service contro Hub di notifica o PNS. Il PNS potrebbe vietare il traffico in seguito a tali attacchi.
Altre informazioni
Per informazioni dettagliate sull'API, vedere la documentazione dell'API .