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

Den här guiden lär 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 måste du först slutföra 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+.
  • iOS-versionerna 8.0 och senare.

Varning

Den här artikeln beskriver information för biblioteksversionen v4.2.0, som har dragits tillbaka. Inga ytterligare uppdateringar kommer att göras i det här biblioteket, inklusive uppdateringar för säkerhetsproblem. Överväg att flytta till en .NET-klient, till exempel .NET MAUI för fortsatt support.

Konfiguration och förutsättningar

Den här guiden förutsätter att du har skapat en serverdel med en tabell. Exempel använder tabellen TodoItem från snabbstarterna. Om du vill lägga till Azure Mobile Apps-plugin-programmet i projektet använder du följande kommando:

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

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

Konfigurera en Ionic v2-app

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 för att app.component.ts 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 den extra deklarationen WindowsAzure för 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);

Växla genom 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 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ä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:

Kommentar

De senaste säkerhetsändringarna i iOS och Android kan göra serverflödesautentiseringen otillgä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å 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.

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'.

Kommentar

På grund av säkerhetsproblem kanske vissa autentiseringsprovidrar inte fungerar med ett serverflöde. Du måste använda en klientflödesmetod i dessa fall.

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 (klientflöde)

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 inloggningsupplevelse 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 provider skiljer sig något åt. Läs dokumentationen om autentisering och auktorisering i Azure App Service för att fastställa den exakta formen av nyttolasten.

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 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 du använder tjänsten som standard. Exempel på problematiska OAuth-användargränssnittsflöden är:

  • Ripple-emulatorn.
  • Live Reload med Ionic.
  • Köra den mobila serverdelen 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å . Ett nytt fönster eller en ny flik öppnas.

  5. Expandera konfigurationen, authsettings-noderna för webbplatsen i det vänstra navigeringsfältet.

  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": [
        "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, ä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 PUT-knappen .

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 fler URL:er efter behov.
  7. Spara inställningarna genom att klicka på Spara.

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