Så här använder du Apache Cordova-klientbiblioteket för Azure Mobile Apps

Översikt

I den här guiden lär du dig att utföra vanliga scenarier med hjälp av det senaste Apache Cordova-plugin-programmet för Azure Mobile Apps. Om du är nybörjare på Azure Mobile Apps slutför du först Snabbstart för Azure Mobile Apps för att skapa en serverdel, skapa en tabell och ladda ned ett färdigt Apache Cordova-projekt. I den här guiden fokuserar vi på Apache Cordova-plugin-programmet på klientsidan.

Plattformar som stöds

Denna SDK stöder Apache Cordova v6.0.0 och senare på iOS-, Android- och Windows-enheter. Plattformsstödet är följande:

• Android API 19-24 (KitKat via Nougat).
• iOS-versionerna 8.0 och senare.
• Windows Phone 8.1.
• Universell Windows-plattform.

Installation och krav

Den här guiden förutsätter att du har skapat en serverdel med en tabell. Den här guiden förutsätter att tabellen har samma schema som tabellerna i dessa självstudier. Den här guiden förutsätter också att du har lagt till Apache Cordova-plugin-programmet i koden. Om du inte har gjort det kan du lägga till Apache Cordova-plugin-programmet i projektet på kommandoraden:

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

Mer information om hur du skapar din första Apache Cordova-appfinns i dokumentationen.

Konfigurera en Ionic v2-applikation

Om du vill konfigurera ett Ionic v2-projekt korrekt skapar du först en grundläggande app och lägger till Cordova-plugin-programmet:

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

Lägg till följande rader i app.component.ts för att skapa klientobjektet:

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

Nu kan du skapa och köra projektet i webbläsaren:

ionic platform add browser
ionic run browser

Plugin-programmet Azure Mobile Apps Cordova stöder både Ionic v1- och v2-appar. Endast Ionic v2-apparna kräver ytterligare deklaration för WindowsAzure objektet.

Skapa en klientanslutning

Skapa en klientanslutning genom att skapa ett WindowsAzure.MobileServiceClient objekt. Ersätt appUrl med URL:en till mobilappen.

var client = WindowsAzure.MobileServiceClient(appUrl);

Arbeta med tabeller

Om du vill komma åt eller uppdatera data skapar du en referens till serverdelstabellen. Ersätt tableName med namnet på tabellen

var table = client.getTable(tableName);

När du har en tabellreferens kan du arbeta vidare med tabellen:

• fråga en tabell
  • Filtrering av data
  • Bläddra genom data
  • sorteringsdata
• infoga data
• Ändra data
• ta bort data

Anvisningar: Fråga en tabellreferens

När du har en tabellreferens kan du använda den för att fråga efter data på servern. Frågor görs på ett "LINQ-liknande" språk. Om du vill returnera alla data från tabellen använder du följande kod:

/**
 * 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);

Funktion för framgång anropas med resultaten. Använd inte for (var i in results) i success-funktionen eftersom det itererar över information som ingår i resultatet när andra frågefunktioner (till exempel .includeTotalCount()) används.

Mer information om frågesyntaxen finns i [Dokumentation om frågeobjekt].

Filtrera data på servern

Du kan använda en where-sats i tabellreferensen:

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

Du kan också använda en funktion som filtrerar objektet. I det här fallet tilldelas variabeln this till det aktuella objekt som filtreras. Följande kod är funktionellt likvärdig med föregående exempel:

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

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

Bläddra genom data

Använd metoderna take() och skip(). Om du till exempel vill dela upp tabellen i poster på 100 rader:

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
        }
    }
}

Metoden .includeTotalCount() används för att lägga till ett totalCount-fält i resultatobjektet. Fältet totalCount fylls med det totala antalet poster som skulle ha returnerats om ingen paginering används.

Du kan sedan använda sidvariabeln och vissa användargränssnittsknappar för att tillhandahålla en sidlista. använd loadPage() för att läsa in de nya posterna för varje sida. Implementera cachelagring för att påskynda åtkomsten till poster som redan har lästs in.

Anvisningar: Returnera sorterade data

Använd frågemetoderna .orderBy() eller .orderByDescending():

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

Mer information om frågeobjektet finns i [Dokumentation om frågeobjekt].

Anvisningar: Infoga data

Skapa ett JavaScript-objekt med rätt datum och anropa table.insert() asynkront:

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

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

Vid lyckad infogning returneras det infogade objektet med de ytterligare fält som krävs för synkroniseringsåtgärder. Uppdatera din egen cache med den här informationen för senare uppdateringar.

Azure Mobile Apps Node.js Server SDK stöder dynamiskt schema i utvecklingssyfte. Med dynamiskt schema kan du lägga till kolumner i tabellen genom att ange dem i en infognings- eller uppdateringsåtgärd. Vi rekommenderar att du inaktiverar dynamiskt schema innan du flyttar programmet till produktion.

Gör så här: Ändra data

Precis som med metoden .insert() bör du skapa ett Update-objekt och sedan anropa .update(). Uppdateringsobjektet måste innehålla ID:t för posten som ska uppdateras – ID:t hämtas när posten läses eller när .insert()anropas.

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);

Gör så här: Ta bort data

Om du vill ta bort en post anropar du metoden .del(). Skicka ID:t i en objektreferens:

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

Anvisningar: Autentisera användare

Azure App Service stöder autentisering och auktorisering av appanvändare med hjälp av olika externa identitetsprovidrar: Facebook, Google, Microsoft-konto och Twitter. Du kan ange behörigheter för tabeller för att begränsa åtkomsten för specifika åtgärder till endast autentiserade användare. Du kan också använda identiteten för autentiserade användare för att implementera auktoriseringsregler i serverskript. Mer information finns i självstudiekursen Komma igång med autentisering.

När du använder autentisering i en Apache Cordova-app måste följande Cordova-plugin-program vara tillgängliga:

• cordova-plugin-device
• cordova-plugin-inappbrowser

Två autentiseringsflöden stöds: ett serverflöde och ett klientflöde. Serverflödet ger den enklaste autentiseringsupplevelsen eftersom det förlitar sig på leverantörens webbautentiseringsgränssnitt. Klientflödet möjliggör djupare integrering med enhetsspecifika funktioner, till exempel enkel inloggning eftersom det förlitar sig på providerspecifika enhetsspecifika SDK:er.

Anvisningar: Autentisera med en provider (serverflöde)

Om du vill att Mobile Apps ska hantera autentiseringsprocessen i din app måste du registrera din app hos din identitetsprovider. I Azure App Service måste du sedan konfigurera program-ID:t och hemligheten som tillhandahålls av leverantören. Mer information finns i självstudien Lägg till autentisering i din app.

När du har registrerat din identitetsprovider anropar du metoden .login() med namnet på din leverantör. Om du till exempel vill logga in med Facebook använder du följande kod:

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

De giltiga värdena för providern är "aad", "facebook", "google", "microsoftaccount" och "twitter".

I det här fallet hanterar Azure App Service OAuth 2.0-autentiseringsflödet. Den visar inloggningssidan för den valda providern och genererar en App Service-autentiseringstoken efter lyckad inloggning med identitetsprovidern. När inloggningsfunktionen är klar returnerar den ett JSON-objekt som exponerar både användar-ID och App Service-autentiseringstoken i fälten userId respektive authenticationToken. Den här token kan cachelagras och återanvändas tills den upphör att gälla.

Gör så här: Autentisera med en provider (klientflöde)

Din app kan också självständigt kontakta identitetsprovidern och sedan ange den returnerade token till Din App Service för autentisering. Med det här klientflödet kan du tillhandahålla en enkel inloggningsupplevelse för användare eller hämta ytterligare användardata från identitetsprovidern.

Grundläggande exempel på social autentisering

I det här exemplet används Facebook-klient-SDK för autentisering:

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

Det här exemplet förutsätter att token som tillhandahålls av respektive provider-SDK lagras i tokenvariabeln.

Anvisningar: Hämta information om den autentiserade användaren

Autentiseringsinformationen /.auth/me kan hämtas från slutpunkten med hjälp av ett HTTP-anrop med valfritt AJAX-bibliotek. Se till att du anger X-ZUMO-AUTH-huvudet till din autentiseringstoken. Autentiseringstoken lagras i client.currentUser.mobileServiceAuthenticationToken. Om du till exempel vill använda hämtnings-API:et:

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
    });

Hämta är tillgängligt som ett npm-paket eller för webbläsarnedladdning från CDNJS. Du kan också använda jQuery eller ett annat AJAX-API för att hämta informationen. Data tas emot som ett JSON-objekt.

Anvisningar: Konfigurera mobile app-tjänsten för externa omdirigerings-URL:er.

Flera typer av Apache Cordova-program använder en loopback-funktion för att hantera OAuth-UI-flöden. OAuth UI-flöden på localhost orsakar problem eftersom autentiseringstjänsten bara vet hur du använder tjänsten som standard. Exempel på problematiska OAuth-användargränssnittsflöden är:

• Ripple-emulatorn.
• Live Reload med Ionic.
• Köra det mobila backendet lokalt
• Köra den mobila serverdelen i en annan Azure App Service än den som tillhandahåller autentisering.

Följ de här anvisningarna för att lägga till dina lokala inställningar i konfigurationen:

1. Logga in på Azure-portalen

2. Välj Alla resurser eller App Services och klicka sedan på namnet på din mobilapp.

3. Klicka på Verktyg

4. Klicka på Resursutforskaren på MENYN OBSERVERA och klicka sedan på Gå. Ett nytt fönster eller en ny flik öppnas.

5. Expandera config, authsettings nodera för din webbplats i den vänstra navigeringen.

6. Klicka på Redigera

7. Leta efter elementet "allowedExternalRedirectUrls". Den kan vara inställd på null eller en matris med värden. Ändra värdet till följande värde:

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

   Ersätt URL:erna med URL:erna för din tjänst. Exempel är https://localhost:3000 (för Node.js exempeltjänst) eller https://localhost:4400 (för Ripple-tjänsten). Dessa URL:er är dock exempel – din situation, även för de tjänster som nämns i exemplen, kan vara annorlunda.

8. Klicka på knappen läs-/skriv- i det övre högra hörnet på skärmen.

9. Klicka på den gröna knappen PUT.

Inställningarna sparas nu. Stäng inte webbläsarfönstret förrän inställningarna har sparats. Lägg också till dessa loopback-URL:er i CORS-inställningarna för din App Service:

1. Logga in på Azure-portalen
2. Välj Alla resurser eller App Services och klicka sedan på namnet på din mobilapp.
3. Bladet Inställningar öppnas automatiskt. Om den inte gör det klickar du på Alla inställningar.
4. Klicka på CORS- under API-menyn.
5. Ange den URL som du vill lägga till i rutan och tryck på Retur.
6. Ange ytterligare URL:er efter behov.
7. Klicka på Spara för att spara inställningarna.

Det tar cirka 10–15 sekunder innan de nya inställningarna börjar gälla.

Gör så här: Registrera dig för push-meddelanden

Installera phonegap-plugin-push för att hantera push-meddelanden . Det här plugin-programmet kan enkelt läggas till med kommandot cordova plugin add på kommandoraden eller via installationsprogrammet för Git-plugin-programmet i Visual Studio. Följande kod i Apache Cordova-appen registrerar enheten för push-meddelanden:

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
});

Använd Notification Hubs SDK för att skicka push-meddelanden från servern. Skicka aldrig push-meddelanden direkt från klienter. Detta kan användas för att utlösa en överbelastningsattack mot Notification Hubs eller PNS. PNS kan förbjuda din trafik till följd av sådana attacker.

Mer information

Du hittar detaljerad API-information i vår API-dokumentation.