Använda Apache Cordova-klientbiblioteket för Azure Mobile Apps

Artikel
06/25/2019

Översikt

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-24 (KitKat till Nolådat).
iOS version 8.0 och senare.
Windows Phone 8.1.
Universell Windows-plattform.

Konfiguration och förutsättningar

Den här guiden förutsätter att du har skapat en backend 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 din kod. 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-app finns 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-apparna kräver den ytterligare 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 tabell
Infoga data
Ändra data
Ta bort data

Anvisning: 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.

Anvisning: 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].

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

När infogningen har fungerat returneras den infogade posten med de ytterligare 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.

Anvisning: Ä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);

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

Gör så här för att: 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 Kom 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:

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.

Gör så här för att: 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

Google-autentisering fungerar för närvarande inte via Server Flow. Om du vill autentisera med Google 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 en 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.

Gör så här för att: 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. Det här klientflödet gör det möjligt för dig att tillhandahålla enkel inloggning för användare eller hämta ytterligare användardata från identitetsprovidern.

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.

Gör så här för att: Få mer information om den autentiserade användaren

Autentiseringsinformationen kan hämtas från /.auth/me-slutpunkten med hjälp av HTTP-anrop med ett AJAX-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. Du kan även använda jQuery eller en annan AJAX API för att hämta informationen. Data tas emot som ett JSON-objekt.

Gör så här: Konfigurera mobiler App Service 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:

Ripple-emulatorn.
Läs in live igen med Ionic.
Köra den mobila backend lokalt
Köra den mobila server backend i en annan Azure App Service än den som tillhandahåller autentisering.

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

Logga in på Azure-portalen
Välj Alla resurserApp Services klicka sedan på namnet på din mobilapp.
Klicka på Verktyg
Klicka på Resursutforskaren på OBSERVE-menyn och klicka sedan på Gå. Ett nytt fönster eller en ny flik öppnas.
Expandera noderna config, authsettings för din plats i det vänstra navigeringsfönstret.
Klicka på Redigera
Leta efter elementet "allowedExternalRedirectUrls". Den kan anges till 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, inklusive för de tjänster som nämns i exemplen, kan vara annorlunda.
Klicka på knappen Läsa /skriva i det övre högra hörnet på skärmen.
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:

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

Det tar cirka 10–15 sekunder för de nya inställningarna att 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 cordova plugin add kommandot på kommandoraden eller via installationsprogrammet för Git-plugin-programmet Visual Studio. Följande kod i Apache Cordova-appen registrerar din enhet 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 DoS-attack mot Notification Hubs eller PNS. PNS kan förbjuda din trafik på grund av sådana attacker.

Mer information

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