Come usare la libreria client Apache Cordova per App per dispositivi mobili di AzureHow to use Apache Cordova client library for Azure Mobile Apps

Questa guida descrive come eseguire scenari comuni usando il più recente plug-in Apache Cordova per le app per dispositivi mobili di Azure.This guide teaches you to perform common scenarios using the latest [Apache Cordova Plugin for Azure Mobile Apps]. Se non si ha familiarità con le app per dispositivi mobili di Azure, completare prima di tutto l' esercitazione introduttiva sulle app per dispositivi mobili di Azure per creare un back-end e una tabella e per scaricare un progetto Apache Cordova predefinito.If you are new to Azure Mobile Apps, first complete [Azure Mobile Apps Quick Start] to create a backend, create a table, and download a pre-built Apache Cordova project. In questa guida si esaminerà il plug-in Apache Cordova.In this guide, we focus on the client-side Apache Cordova Plugin.

Piattaforme supportateSupported platforms

Questo SDK supporta Apache Cordova v6.0.0 e versioni successive sui dispositivi iOS, Android e Windows.This SDK supports Apache Cordova v6.0.0 and later on iOS, Android, and Windows devices. Il supporto della piattaforma è il seguente:The platform support is as follows:

  • API Android 19-24 (KitKat tramite Nougat).Android API 19-24 (KitKat through Nougat).
  • iOS versioni 8.0 e successive.iOS versions 8.0 and later.
  • Windows Phone 8.1Windows Phone 8.1.
  • Piattaforma UWP (Universal Windows Platform).Universal Windows Platform.

Installazione e prerequisitiSetup and prerequisites

In questa guida si presuppone che siano stati creati un backend e una tabella.This guide assumes that you have created a backend with a table. In questa guida si presuppone che la tabella abbia lo stesso schema delle tabelle presenti in tali esercitazioni.This guide assumes that the table has the same schema as the tables in those tutorials. Si presuppone anche che il plug-in Apache Cordova sia stato aggiunto al codice.This guide also assumes that you have added the Apache Cordova Plugin to your code. In caso contrario, è possibile aggiungere il plug-in Apache Cordova al progetto nella riga di comando:If you have not done so, you may add the Apache Cordova plugin to your project on the command line:

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

Per altre informazioni sulla creazione della prima app Apache Cordova, vedere la relativa documentazione.For more information on creating [your first Apache Cordova app], see their documentation.

Configurazione di un'app Ionic v2Setting up an Ionic v2 app

Per configurare correttamente un progetto Ionic v2, innanzitutto creare un'applicazione di base e aggiungere il plug-in Cordova:To properly configure an Ionic v2 project, first create a basic app and add the Cordova plugin:

ionic start projectName --v2
cd projectName
ionic plugin add cordova-plugin-ms-azure-mobile-apps

Aggiungere le seguenti righe a app.component.ts per creare l'oggetto client:Add the following lines to app.component.ts to create the client object:

declare var WindowsAzure: any;
var client = new WindowsAzure.MobileServiceClient("https://yoursite.azurewebsites.net");

È ora possibile compilare ed eseguire il progetto nel browser:You can now build and run the project in the browser:

ionic platform add browser
ionic run browser

Il plug-in Cordova di App per dispositivi mobili di Azure supporta le app Ionic sia v1 che v2.The Azure Mobile Apps Cordova plugin supports both Ionic v1 and v2 apps. Solo le app Ionic v2 richiedono la dichiarazione aggiuntiva per l'oggetto WindowsAzure.Only the Ionic v2 apps require the additional declaration for the WindowsAzure object.

Creare una connessione clientCreate a client connection

Creare una connessione client creando un oggetto WindowsAzure.MobileServiceClient .Create a client connection by creating a WindowsAzure.MobileServiceClient object. Sostituire appUrl con l'URL dell'app per dispositivi mobili.Replace appUrl with the URL to your Mobile App.

var client = WindowsAzure.MobileServiceClient(appUrl);

Usare le tabelleWork with tables

Per l'accesso o l'aggiornamento dei dati, creare un riferimento alla tabella di back-end.To access or update data, create a reference to the backend table. Sostituire tableName con il nome della tabellaReplace tableName with the name of your table

var table = client.getTable(tableName);

Dopo aver creato un riferimento a tabella, saranno disponibili le operazioni seguenti:Once you have a table reference, you can work further with your table:

Procedura: Eseguire query su un riferimento a tabellaHow to: Query a table reference

Dopo aver creato un riferimento a tabella, è possibile usarlo per eseguire una query sui dati nel server.Once you have a table reference, you can use it to query for data on the server. Le query vengono eseguite in un linguaggio "simile a LINQ".Queries are made in a "LINQ-like" language. Per restituire tutti i dati dalla tabella, usare il codice seguente:To return all data from the table, use the following code:

/**
 * 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 l'oggetto results.The success function is called with the results. Non usare for (var i in results) nella funzione success, perché ripete le informazioni incluse nei risultati quando si usano altre funzioni di query, ad esempio .includeTotalCount().Do not use for (var i in results) in the success function as that will iterate over information that is included in the results when other query functions (such as .includeTotalCount()) are used.

Per altre informazioni sulla sintassi delle query, vedere la [documentazione relativa all'oggetto Query].For more information on the Query syntax, see the [Query object documentation].

Filtro dei dati nel serverFiltering data on the server

È possibile usare una clausola where nel riferimento a tabella:You can use a where clause on the table reference:

table
    .where({ userId: user.userId, complete: false })
    .read()
    .then(success, failure);

È anche possibile usare una funzione che filtra l'oggetto.You can also use a function that filters the object. In questo caso la variabile this viene assegnata all'oggetto che si sta filtrando.In this case, the this variable is assigned to the current object being filtered. A livello funzionale, il codice seguente è equivalente al precedente:The following code is functionally equivalent to the prior example:

function filterByUserId(currentUserId) {
    return this.userId === currentUserId && this.complete === false;
}

table
    .where(filterByUserId, user.userId)
    .read()
    .then(success, failure);

Paging dei datiPaging through data

Usare i metodi take() e skip().Utilize the take() and skip() methods. Ad esempio, se si vuole dividere la tabella in record di 100 righe:For example, if you wish to split the table into 100-row records:

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 usato per aggiungere un campo totalCount all'oggetto results.The .includeTotalCount() method is used to add a totalCount field to the results object. Se non si usa il paging, il campo totalCount viene compilato con il numero totale di record restituiti.The totalCount field is filled with the total number of records that would be returned if no paging is used.

Si potrà quindi 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.You can then use the pages variable and some UI buttons to provide a page list; use loadPage() to load the new records for each page. Implementare il caching per velocizzare l'accesso ai record già caricati.Implement caching to speed access to records that have already been loaded.

Procedura: Restituire i dati ordinatiHow to: Return sorted data

Usare i metodi di query .orderBy() o .orderByDescending():Use the .orderBy() or .orderByDescending() query methods:

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

Per altre informazioni sull'oggetto delle query, vedere la [documentazione relativa all'oggetto Query].For more information on the Query object, see the [Query object documentation].

Procedura: Inserire datiHow to: Insert data

Creare un oggetto JavaScript con la data appropriata e chiamare table.insert() in modo asincrono:Create a JavaScript object with the appropriate date and call table.insert() asynchronously:

var newItem = {
    name: 'My Name',
    signupDate: new Date()
};

table
    .insert(newItem)
    .done(function (insertedItem) {
        var id = insertedItem.id;
    }, failure);

Una volta completato l'inserimento, viene restituito l'elemento inserito con i campi aggiuntivi necessari per le operazioni di sincronizzazione.On successful insertion, the inserted item is returned with the additional fields that are required for sync operations. Aggiornare la cache con queste informazioni per gli aggiornamenti successivi.Update your own cache with this information for later updates.

Node. js Server SDK per le app per dispositivi mobili supporta lo schema dinamico per scopi di sviluppo.The Azure Mobile Apps Node.js Server SDK supports dynamic schema for development purposes. Lo Schema dinamico consente di aggiungere colonne alla tabella specificandole in un'operazione di inserimento o aggiornamento.Dynamic Schema allows you to add columns to the table by specifying them in an insert or update operation. È consigliabile disattivare lo schema dinamico prima di trasferire l'applicazione in produzione.We recommend that you turn off dynamic schema before moving your application to production.

Procedura: Modificare datiHow to: Modify data

In modo analogo al metodo .insert(), è consigliabile creare un oggetto Update e quindi chiamare .update().Similar to the .insert() method, you should create an Update object and then call .update(). L'oggetto update deve contenere l'ID del record da aggiornare, che si ottiene durante la lettura del record o quando si chiama .insert().The update object must contain the ID of the record to be updated - the ID is obtained when reading the record or when calling .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 datiHow to: Delete data

Per eliminare un record, chiamare il metodo .del().To delete a record, call the .del() method. Passare l'ID in un riferimento all'oggetto:Pass the ID in an object reference:

table
    .del({ id: '7163bc7a-70b2-4dde-98e9-8818969611bd' })
    .done(function () {
        // Record is now deleted - update your cache
    }, failure);

Procedura: Autenticare gli utentiHow to: Authenticate users

Il servizio app di Azure supporta l'autenticazione e l'autorizzazione degli utenti di app usando diversi provider di identità esterni, a esempio Facebook, Google, account Microsoft e Twitter.Azure App Service supports authenticating and authorizing app users using various external identity providers: Facebook, Google, Microsoft Account, and Twitter. È possibile impostare le autorizzazioni per le tabelle per limitare l'accesso per operazioni specifiche solo agli utenti autenticati.You can set permissions on tables to restrict access for specific operations to only authenticated users. È inoltre possibile utilizzare l'identità degli utenti autenticati per implementare regole di autorizzazione negli script del server.You can also use the identity of authenticated users to implement authorization rules in server scripts. Per ulteriori informazioni, vedere l'esercitazione Introduzione all'autenticazione .For more information, see the [Get started with authentication] tutorial.

Quando si usa l'autenticazione in un'app Apache Cordova, devono essere disponibili i plug-in Cordova seguenti:When using authentication in an Apache Cordova app, the following Cordova plugins must be available:

Sono supportati due flussi di autenticazione, ovvero un flusso server e un flusso client.Two authentication flows are supported: a server flow and a client flow. Il flusso server è il processo di autenticazione più semplice, poiché si basa sull'interfaccia di autenticazione Web del provider.The server flow provides the simplest authentication experience, as it relies on the provider's web authentication interface. Il flusso client assicura una maggiore integrazione con funzionalità specifiche del dispositivo, ad esempio Single-Sign-On, poiché si basa su SDK specifici del provider e del dispositivo.The client flow allows for deeper integration with device-specific capabilities such as single-sign-on as it relies on provider-specific device-specific SDKs.

Procedura: Eseguire l'autenticazione con un provider (flusso server)How to: Authenticate with a provider (Server Flow)

Per consentire alle app per dispositivi mobili di gestire il processo di autenticazione nella propria app, è necessario effettuare la registrazione dell'app con il provider di identità.To have Mobile Apps manage the authentication process in your app, you must register your app with your identity provider. Nel proprio servizio app di Azure è quindi necessario configurare l'ID e il segreto dell'applicazione forniti dal provider.Then in your Azure App Service, you need to configure the application ID and secret provided by your provider. Per altre informazioni, vedere l'esercitazione Aggiungere l'autenticazione all'app di Servizi mobili.For more information, see the tutorial Add authentication to your app.

Dopo aver effettuato la registrazione del provider di identità, chiamare il metodo .login() con il nome del provider.Once you have registered your identity provider, call the .login() method with the name of your provider. Per accedere ad esempio con Facebook, utilizzare il codice seguente:For example, to login with Facebook use the following code:

client.login("facebook").done(function (results) {
     alert("You are now logged in as: " + results.userId);
}, function (err) {
     alert("Error: " + err);
});

I valori validi per il provider sono "aad", "facebook", "google", "microsoftaccount" e "twitter".The valid values for the provider are 'aad', 'facebook', 'google', 'microsoftaccount', and 'twitter'.

Nota

L'autenticazione di Google attualmente non funziona tramite Flusso server.Google Authentication does not currently work via Server Flow. Per eseguire l'autenticazione con Google, è necessario usare un metodo di flusso client.To authenticate with Google, you must use a client-flow method.

In questo caso, il Servizio app di Azure gestisce il flusso di autenticazione OAuth 2.0.In this case, Azure App Service manages the OAuth 2.0 authentication flow. Viene visualizzata la pagina di accesso al provider selezionato e viene generato un token di autenticazione del Servizio app dopo aver eseguito correttamente l'accesso con il provider di identità.It displays the login page of the selected provider and generates an App Service authentication token after successful login with the identity provider. La funzione login, una volta completata, restituisce un oggetto JSON che espone l'ID utente e il token di autenticazione del servizio app rispettivamente nei campi userId e authenticationToken.The login function, when complete, returns a JSON object that exposes both the user ID and App Service authentication token in the userId and authenticationToken fields, respectively. È possibile memorizzare questo token nella cache e riutilizzarlo fino alla scadenza.This token can be cached and reused until it expires.

Procedura: Eseguire l'autenticazione con un provider (flusso client)How to: Authenticate with a provider (Client Flow)

L'app può anche contattare il provider di identità in modo indipendente e quindi fornire il token restituito al servizio app per l'autenticazione.Your app can also independently contact the identity provider and then provide the returned token to your App Service for authentication. Mediante il flusso client è possibile consentire agli utenti di effettuare l'accesso un'unica volta o recuperare dal provider di identità dati utente aggiuntivi.This client flow enables you to provide a single sign-in experience for users or to retrieve additional user data from the identity provider.

Esempio di base di autenticazione tramite social networkSocial Authentication basic example

Questo esempio utilizza il client SDK di Facebook per l'autenticazione:This example uses Facebook client SDK for authentication:

client.login(
     "facebook",
     {"access_token": token})
.done(function (results) {
     alert("You are now logged in as: " + results.userId);
}, function (err) {
     alert("Error: " + err);
});

In questo esempio si presuppone che il token fornito dall'SDK del rispettivo provider sia archiviato nella variabile token.This example assumes that the token provided by the respective provider SDK is stored in the token variable.

Esempio di account MicrosoftMicrosoft Account example

Nell'esempio seguente viene utilizzato Live SDK, che supporta Single-Sign-On per le app di Windows Store tramite un account Microsoft:The following example uses the Live SDK, which supports single-sign-on for Windows Store apps by using Microsoft Account:

WL.login({ scope: "wl.basic"}).then(function (result) {
      client.login(
            "microsoftaccount",
            {"authenticationToken": result.session.authentication_token})
      .done(function(results){
            alert("You are now logged in as: " + results.userId);
      },
      function(error){
            alert("Error: " + err);
      });
});

Questo esempio ottiene un token da Live Connect, che viene fornito al servizio app chiamando la funzione login.This example gets a token from Live Connect, which is supplied to your App Service by calling the login function.

Procedura: Ottenere informazioni relative all'utente autenticatoHow to: Obtain information about the authenticated user

Le informazioni di autenticazione possono essere recuperate dall'endpoint /.auth/me usando una chiamata HTTP con una libreria AJAX qualsiasi.The authentication information can be retrieved from the /.auth/me endpoint using an HTTP call with any AJAX library. Assicurarsi di impostare l'intestazione X-ZUMO-AUTH sul token di autenticazione.Ensure you set the X-ZUMO-AUTH header to your authentication token. Il token di autenticazione è memorizzato in client.currentUser.mobileServiceAuthenticationToken.The authentication token is stored in client.currentUser.mobileServiceAuthenticationToken. Ad esempio, per usare l'API fetch:For example, to use the fetch 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
    });

L'operazione di recupero è disponibile come pacchetto npm oppure può essere scaricato tramite il browser da CDNJS.Fetch is available as an npm package or for browser download from CDNJS. È anche possibile usare jQuery o un'altra API AJAX per recuperare le informazioni.You could also use jQuery or another AJAX API to fetch the information. I dati saranno ricevuti come oggetto JSON.Data is received as a JSON object.

Procedura: Configurare il servizio App per dispositivi mobili per URL di reindirizzamento esterni.How to: Configure your Mobile App Service for external redirect URLs.

Molti tipi di applicazioni Apache Cordova usano una funzionalità di loopback per gestire i flussi dell’interfaccia utente di OAuth.Several types of Apache Cordova applications use a loopback capability to handle OAuth UI flows. I flussi dell'interfaccia utente di OAuth sull'host locale causa problemi in quanto il servizio di autenticazione sa usare il servizio solo con le impostazioni predefinite.OAuth UI flows on localhost cause problems since the authentication service only knows how to utilize your service by default. Alcuni esempi di flussi dell'interfaccia utente di OAuth problematici sono:Examples of problematic OAuth UI flows include:

  • L'emulatore Ripple.The Ripple emulator.
  • Live Reload con Ionic.Live Reload with Ionic.
  • L'esecuzione del back-end per dispositivi mobili in localeRunning the mobile backend locally
  • L'esecuzione del back-end per dispositivi mobili in un Servizio app di Azure diverso rispetto a quello che fornisce l'autenticazione.Running the mobile backend in a different Azure App Service than the one providing authentication.

Per aggiungere le proprie impostazioni locali alla configurazione seguire questa procedura:Follow these instructions to add your local settings to the configuration:

  1. Accedere al portale di AzureLog in to the [Azure portal]
  2. Selezionare Tutte le risorse o Servizi app e quindi fare clic sul nome dell'app per dispositivi mobili.Select All resources or App Services then click the name of your Mobile App.
  3. Fare clic su StrumentiClick Tools
  4. Fare clic su Esplora risorse nel menu OSSERVAZIONE, quindi fare clic su Vai.Click Resource explorer in the OBSERVE menu, then click Go. Si apre una nuova finestra o una nuova scheda.A new window or tab opens.
  5. Espandere i nodi config, authsettings del sito nel riquadro di spostamento a sinistra.Expand the config, authsettings nodes for your site in the left-hand navigation.
  6. Fare clic su ModificaClick Edit
  7. Cercare l’elemento "allowedExternalRedirectUrls".Look for the "allowedExternalRedirectUrls" element. Può essere impostato su null o su una matrice di valori.It may be set to null or an array of values. Modificare il valore nel valore seguente:Change the value to the following value:

      "allowedExternalRedirectUrls": [
          "http://localhost:3000",
          "https://localhost:3000"
      ],
    

    Sostituire gli URL con quelli del servizio.Replace the URLs with the URLs of your service. Ad esempio includere "http://localhost:3000" (per il servizio di esempio Node.js) o "http://localhost:4400" (per il servizio Ripple).Examples include "http://localhost:3000" (for the Node.js sample service), or "http://localhost:4400" (for the Ripple service). Questi URL sono solo esempi e la situazione reale per i servizi dell'esempio potrebbe essere diversa.However, these URLs are examples - your situation, including for the services mentioned in the examples, may be different.

  8. Fare clic sul pulsante Lettura/scrittura nell'angolo in alto a destra della schermata.Click the Read/Write button in the top-right corner of the screen.
  9. Fare clic sul pulsante verde PUT .Click the green PUT button.

A questo punto le impostazioni vengono salvate.The settings are saved at this point. Non chiudere la finestra del browser finché non è terminato il salvataggio delle impostazioni.Do not close the browser window until the settings have finished saving. Aggiungere gli URL di loopback anche alle impostazioni CORS del servizio app:Also add these loopback URLs to the CORS settings for your App Service:

  1. Accedere al portale di AzureLog in to the [Azure portal]
  2. Selezionare Tutte le risorse o Servizi app e quindi fare clic sul nome dell'app per dispositivi mobili.Select All resources or App Services then click the name of your Mobile App.
  3. Il pannello Impostazioni si apre automaticamente.The Settings blade opens automatically. In caso contrario fare clic su Tutte le impostazioni.If it doesn't, click All Settings.
  4. Fare clic su CORS nel menu API.Click CORS under the API menu.
  5. Immettere l'URL che si desidera aggiungere nella casella apposita e prema INVIO.Enter the URL that you wish to add in the box provided and press Enter.
  6. Immettere gli altri URL in base alle esigenze.Enter additional URLs as needed.
  7. Fare clic su Salva per salvare le impostazioni.Click Save to save the settings.

Le nuove impostazioni saranno operative in 10-15 secondi.It takes approximately 10-15 seconds for the new settings to take effect.

Procedura: Registrarsi per le notifiche pushHow to: Register for push notifications

Installare phonegap-plugin-push per gestire le notifiche push.Install the phonegap-plugin-push to handle push notifications. Questo plug-in può essere facilmente aggiunto usando il comando cordova plugin add nella riga di comando o tramite il programma di installazione del plug-in Git in Visual Studio.This plugin can be easily added using the cordova plugin add command on the command line, or via the Git plugin installer within Visual Studio. Il codice seguente nell'app Apache Cordova registra il dispositivo per le notifiche push:The following code in your Apache Cordova app registers your device for push notifications:

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 Notification Hubs SDK per inviare notifiche push dal server.Use the Notification Hubs SDK to send push notifications from the server. Non inviare mai le notifiche push direttamente dai client.Never send push notifications directly from clients. Questa operazione può essere usata per attivare un attacco denial-of-service agli Hub di notifica o al servizio PNS.Doing so could be used to trigger a denial of service attack against Notification Hubs or the PNS. Il servizio PNS potrebbe escludere il traffico come conseguenza di questi attacchi.The PNS could ban your traffic as a result of such attacks.

Altre informazioniMore information

È possibile trovare informazioni dettagliate sulle API nella documentazione sulle API.You can find detailed API details in our API documentation.