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

I den här guiden lär du dig att utföra vanliga scenarier med det senaste Apache Cordova-plugin-programmet för Azure Mobile Apps. Om azure Mobile Apps är nytt för dig måste du först slutföra Azure Mobile Apps Snabbstart för att skapa en backend, skapa en tabell och ladda ned ett förbyggt Apache Cordova-projekt. I den här guiden fokuserar vi på Apache Cordova-pluginprogrammet på klientsidan.

Plattformar som stöds

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

  • Android API 19+.
  • iOS version 8.0 och senare.

Installation och krav

Den här guiden förutsätter att du har skapat en backend med en tabell. I exemplen TodoItem används tabellen från snabbstarterna. Använd följande kommando för Mobile Apps lägga till plugin-programmet Azure Mobile Apps i projektet:

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

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

Konfigurera en Ionic v2-app

För att konfigurera ett Ionic v2-projekt måste du först skapa en grundläggande app och lägga 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-appar kräver den extra deklarationen för WindowsAzure objektet.

Skapa en klientanslutning

Skapa en klientanslutning genom att skapa ett WindowsAzure.MobileServiceClient-objekt. Ersätt appUrl med URL-adressen till din mobilapp.

var client = WindowsAzure.MobileServiceClient(appUrl);

Arbeta med tabeller

För att få åtkomst till 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 mer med din tabell:

Fråga en tabellreferens

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

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

Klarfunktionen anropas med resultatet. Använd inte for (var i in results) i klarfunktionen eftersom det upprepas över informationen som ingår i resultatet när andra frågefunktioner (som .includeTotalCount()) används.

Mer information om frågesyntaxen finns i dokumentationen för frågeobjekt.

Filtrera data på servern

Du kan använda en where-sats på tabellreferensen:

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

Du kan även använda en funktion som filtrerar objektet. I det här fallet tilldelas variabeln this till det aktuella objektet som filtreras. Följande kod har samma funktioner som i 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 igenom data

Utnyttja metoderna take() och skip(). Om du till exempel vill dela upp tabellen i 100-radsposter:

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 till resultatobjekten. Fältet totalCount fylls i med det totala antalet poster som skulle returneras om ingen sidindelning används.

Du kan sedan använda sidvariablerna och vissa UI-knappar för att få en sidlista. Läs in de nya posterna för varje sida med hjälp av loadPage(). Implementera cachelagring för att påskynda åtkomst till poster som redan har lästs in.

Returnera sorterade data

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

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

Mer information om frågeobjektet finns i [dokumentationen för frågeobjekt].

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 extra fält som krävs för synkroniseringsåtgärder. Uppdatera ditt eget cacheminne med den här informationen för senare uppdateringar.

Azure Mobile Apps Node.js Server SDK har funktioner för dynamiskt schema i utvecklingssyften. 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 stänger av dynamiskt schema innan du flyttar programmet till produktionen.

Ändra data

Precis som för metoden .insert() ska du skapa ett objekt för uppdateringen och sedan anropa .update(). Uppdateringsobjektet måste innehålla ID:t för posten som ska uppdateras – ID:t hämtas vid läsning av posten 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);

Ta bort data

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

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

Autentisera användare

Azure App Service stöder autentisering och auktorisering av appanvändare med hjälp av olika externa identitetsproviders: 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älvstudien 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:

Anteckning

De senaste säkerhetsändringarna i iOS och Android kan göra att serverflödesautentisering inte är tillgänglig. I dessa fall måste du använda ett klientflöde.

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

Autentisera med en provider (Server Flow)

För att använda Mobile Apps för att hantera autentiseringsprocessen i din app måste du registrera din app med din identitetsprovider. Sedan måste du konfigurera program-ID och -hemligheten som du fått av din provider i Azure App Service. Mer information finns i självstudierna Lägg till autentisering till din app.

När du har registrerat din identitetsprovider anropar du .login()-metoden med namnet på din provider. 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);
});

Giltiga värden för providern är 'aad', 'facebook', 'google', 'microsoftaccount' och 'twitter'.

Anteckning

Av säkerhetsskäl kanske vissa autentiseringsproviders inte fungerar med ett serverflöde. I dessa fall måste du använda en klientflödesmetod.

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 färdig returnerar den ett JSON-objekt som både visar 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.

Autentisera med en provider (Client Flow)

Din app kan även oberoende kontakta identitetsprovidern och sedan tillhandahålla den returnerade token till App Service för autentisering. Med det här klientflödet kan du tillhandahålla en enkel inloggning för användare eller hämta extra användardata från identitetsprovidern.

Grundläggande exempel på social autentisering

I det här exemplet används Facebook-klientens 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 den token som tillhandahålls av respektive provider-SDK lagras i token-variabeln. Informationen som krävs av varje leverantör skiljer sig något åt. Läs dokumentationen Azure App Service autentisering och auktorisering för att fastställa den exakta formen av nyttolasten.

Hämta information om den autentiserade användaren

Autentiseringsinformationen kan hämtas från slutpunkten med /.auth/me hjälp av ett HTTP-anrop med val annat HTTP/REST-bibliotek. Se till att du ställer in X-ZUMO-AUTH-rubriken till din autentiseringstoken. Autentiseringstoken lagras i client.currentUser.mobileServiceAuthenticationToken. För att till exempel använda 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
    });

Fetch är tillgängligt som ett npm-paket eller som nedladdning via en webbläsare från CDNJS. Data tas emot som ett JSON-objekt.

Konfigurera Mobile-App Service 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 tjänsten ska användas som standard. Exempel på problematiska OAuth UI-flöden är:

  • Ripple-emulatorn.
  • Läs in live igen med Ionic.
  • Köra den mobila backend lokalt
  • Köra den mobila serverd 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 Portal

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

  3. Klicka på Verktyg

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

  5. Expandera noderna config, authsettings för din plats i det vänstra navigeringsfönstret.

  6. Klicka på Redigera

  7. Leta efter elementet "allowedExternalRedirectUrls". Det kan anges till null eller en matris med värden. Ändra värdet till följande värde:

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

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

  8. Klicka på knappen Läsa/skriva i det övre högra hörnet på skärmen.

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

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

  1. Logga in på Azure Portal
  2. Välj Alla resurser eller App Services 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 fler URL:er efter behov.
  7. Spara inställningarna genom att klicka på Spara.

Det tar cirka 10–15 sekunder för de nya inställningarna att gälla.