De Apache Cordova-invoegtoepassing gebruiken voor Azure Mobile Apps

In deze handleiding leert u veelvoorkomende scenario's uit te voeren met behulp van de nieuwste Apache Cordova-invoegtoepassing voor Azure Mobile Apps. Als u geen toegang hebt tot Azure Mobile Apps, voltooit u eerst de quickstart van Azure Mobile Apps om een back-end te maken, maakt u een tabel en downloadt u een vooraf gebouwd Apache Cordova-project. In deze handleiding richten we ons op de Apache Cordova-invoegtoepassing aan de clientzijde.

Ondersteunde platforms

Deze SDK ondersteunt Apache Cordova v6.0.0 en hoger op iOS-, Android- en Windows-apparaten. De platformondersteuning is als volgt:

• Android-API 19+.
• iOS-versies 8.0 en hoger.

Installatie en vereisten

In deze handleiding wordt ervan uitgegaan dat u een back-end hebt gemaakt met een tabel. Voorbeelden maken gebruik van de TodoItem tabel uit de snelstartgidsen. Gebruik de volgende opdracht om de Azure Mobile Apps-invoegtoepassing toe te voegen aan uw project:

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

Raadpleeg de bijbehorende documentatie voor meer informatie over het maken van uw eerste Apache Cordova-app.

Een Ionic v2-app instellen

Als u een Ionic v2-project correct wilt configureren, maakt u eerst een basis-app en voegt u de Cordova-invoegtoepassing toe:

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

Voeg de volgende regels toe om het clientobject te app.component.ts maken:

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

U kunt nu het project bouwen en uitvoeren in de browser:

ionic platform add browser
ionic run browser

De Azure Mobile Apps Cordova-invoegtoepassing ondersteunt zowel Ionic v1- als v2-apps. Alleen de Ionic v2-apps vereisen de extra declaratie voor het WindowsAzure object.

Een clientverbinding maken

Maak een clientverbinding door een WindowsAzure.MobileServiceClient-object te maken. Vervang appUrl door de URL van uw mobiele app.

var client = WindowsAzure.MobileServiceClient(appUrl);

Werken met tabellen

Maak een verwijzing naar de back-endtabel als u gegevens wilt bekijken of bijwerken. Vervang tableName door de naam van uw tabel

var table = client.getTable(tableName);

Wanneer u een tabelverwijzing hebt, kunt u verder werken aan uw tabel:

• Een query uitvoeren op een tabel
  • Gegevens filteren
  • Door gegevens bladeren
  • Gegevens sorteren
• Gegevens invoegen
• Gegevens wijzigen
• Gegevens verwijderen

Een query uitvoeren op een tabelreferentie

Als u een tabelverwijzing hebt, kunt u deze gebruiken om een query uit te voeren op gegevens op de server. Query's worden gemaakt in een LINQ-achtige taal. Gebruik de volgende code om alle gegevens uit de tabel op te halen:

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

De functie voor geslaagde pogingen wordt aangeroepen met de resultaten. Gebruik for (var i in results) niet in de functie voor geslaagde pogingen, aangezien dit wordt herhaald voor informatie die is opgenomen in de resultaten wanneer andere queryfuncties (zoals .includeTotalCount()) worden gebruikt.

Zie de documentatie voor queryobjecten voor meer informatie over de querysyntaxis.

Gegevens filteren op de server

U kunt in de tabelverwijzing een where-clausule gebruiken:

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

U kunt ook een functie gebruiken die het object filtert. In dit geval wordt de this-variabele toegewezen aan het huidige object dat wordt gefilterd. De volgende code is functioneel equivalent aan het vorige voorbeeld:

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

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

Door gegevens bladeren

Gebruik de methode take() en skip(). Bijvoorbeeld als u de tabel wilt splitsen in records met 100 rijen:

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

De methode .includeTotalCount() wordt gebruikt om een totalCount-veld toe te voegen aan het resultaatobject. Het veld totalCount wordt gevuld met het totale aantal records dat zou worden geretourneerd als er geen paginering zou zijn gebruikt.

U kunt vervolgens de paginavariabelen en sommige UI-knoppen gebruiken om een paginalijst op te geven; gebruik loadPage() om de nieuwe records voor elke pagina te laden. Implementeer caching voor snellere toegang tot de records die al zijn geladen.

Gesorteerde gegevens retourneren

Gebruik de querymethode .orderBy() of .orderByDescending():

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

Zie de [Documentatie over queryobjecten] voor meer informatie over het queryobject.

Gegevens invoegen

Maak een JavaScript-object met de juiste datum en roep table.insert() asynchroon aan:

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

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

Bij een geslaagde invoeging wordt het ingevoegde item geretourneerd met extra velden die vereist zijn voor synchronisatiebewerkingen. Werk uw eigen cache bij met deze gegevens voor latere updates.

De Azure Mobile Apps Node.js Server SDK biedt ondersteuning voor dynamische schema's voor ontwikkelingsdoeleinden. Met een dynamisch schema kunt u kolommen toevoegen aan de tabel door deze op te geven in een Insert- of Update-bewerking. We raden u aan het dynamische schema uit te schakelen voordat u uw toepassing in productie neemt.

Gegevens wijzigen

Net als bij de methode .insert() moet u een Update-object maken en vervolgens .update() aanroepen. Het Update-object moet de id van het bij te werken record bevatten: de id wordt verkregen tijdens het lezen van het record of het aanroepen van .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);

Gegevens verwijderen

Roep de methode .del() aan als u een record wilt verwijderen. Geef de id door in een objectverwijzing:

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

Gebruikers verifiëren

Azure-app Service ondersteunt het verifiëren en autoriseren van app-gebruikers met behulp van verschillende externe id-providers: Facebook, Google, Microsoft-account en Twitter. U kunt machtigingen instellen voor tabellen om de toegang voor specifieke bewerkingen te beperken tot alleen geverifieerde gebruikers. U kunt ook de identiteit van geverifieerde gebruikers gebruiken om autorisatieregels in serverscripts te implementeren. Zie de zelfstudie Aan de slag met verificatie voor meer informatie.

Wanneer u verificatie gebruikt in een Apache Cordova-app, moeten de volgende Cordova-invoegtoepassingen beschikbaar zijn:

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

Er worden twee verificatiestromen ondersteund: een serverstroom en een clientstroom. De serverstroom biedt de eenvoudigste verificatie-ervaring, omdat deze afhankelijk is van de webverificatieinterface van de provider. De clientstroom biedt een diepere integratie met apparaatspecifieke mogelijkheden, zoals eenmalige aanmelding, omdat deze afhankelijk is van providerspecifieke apparaatspecifieke SDK's.

Verifiëren met een provider (serverstroom)

Als u het verificatieproces in uw app door Mobile Apps wilt laten beheren, moet u uw app registreren bij uw id-provider. Daarna moet u in uw Azure App Service de door uw provider verstrekte toepassings-id en geheim configureren. Zie de zelfstudie Verificatie toevoegen aan uw app voor meer informatie.

Wanneer u de id-provider hebt geregistreerd, roept u de methode .login() aan met de naam van uw provider. Als u zich bijvoorbeeld wilt aanmelden met Facebook, gebruikt u de volgende code:

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

De geldige waarden voor de provider zijn 'aad', 'facebook', 'google', 'microsoftaccount' en 'twitter'.

In dit geval beheert Azure App Service de OAuth 2.0-verificatiestroom. De aanmeldingspagina van de geselecteerde provider wordt weergegeven en er wordt een App Service-verificatietoken gegenereerd nadat de aanmelding is geslaagd bij de id-provider. De aanmeldingsfunctie retourneert na voltooiing een JSON-object dat zowel de gebruikers-id als het App Service-verificatietoken respectievelijk in de velden userId en authenticationToken weergeeft. Dit token kan worden opgeslagen in de cache en opnieuw worden gebruikt totdat het verloopt.

Verifiëren met een provider (Client Flow)

Uw app kan ook afzonderlijk contact opnemen met de id-provider en het geretourneerde token vervolgens aan uw App Service verstrekken voor verificatie. Met deze clientstroom kunt u eenmalige aanmelding bieden voor gebruikers of extra gebruikersgegevens ophalen van de id-provider.

Eenvoudig voorbeeld van sociale verificatie

In dit voorbeeld wordt de client-SDK van Facebook gebruikt voor verificatie:

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

In dit voorbeeld wordt ervan uitgegaan dat het token dat is opgegeven door de betreffende SDK-provider, is opgeslagen in de tokenvariabele. De gegevens die voor elke provider zijn vereist, verschillen enigszins. Raadpleeg de documentatie voor Azure-app serviceverificatie en autorisatie om de exacte vorm van de nettolading te bepalen.

Informatie verkrijgen over de geverifieerde gebruiker

De verificatiegegevens kunnen worden opgehaald uit het /.auth/me eindpunt met behulp van een HTTP-aanroep met elke HTTP/REST-bibliotheek. Zorg ervoor dat u de X-ZUMO-AUTH-header in uw verificatietoken instelt. Het verificatietoken wordt opgeslagen in client.currentUser.mobileServiceAuthenticationToken. Als u bijvoorbeeld de API 'Ophalen' gebruikt:

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

Ophalen is beschikbaar als npm-pakket, maar kan ook met een browser worden gedownload van CDNJS. Gegevens worden ontvangen als JSON-object.

Configureer uw Mobile App Service voor externe omleidings-URL's.

Verschillende typen Apache Cordova-toepassingen maken gebruik van een loopback-mogelijkheid om OAuth UI-stromen te verwerken. OAuth UI-stromen op localhost veroorzaken problemen omdat de verificatieservice alleen weet hoe uw service standaard moet worden gebruikt. Voorbeelden van problematische OAuth UI-stromen zijn:

• De Rimpelemulator.
• Live Reload met Ionic.
• De mobiele back-end lokaal uitvoeren
• Het uitvoeren van de mobiele back-end in een andere Azure-app Service dan de service die verificatie biedt.

Volg deze instructies om uw lokale instellingen toe te voegen aan de configuratie:

1. Meld u aan bij Azure Portal.

2. Selecteer Alle resources of App Services en klik vervolgens op de naam van uw mobiele app.

3. Klik op Extra

4. Klik op Resourceverkenner in het menu OBSERVE en klik vervolgens op Ga. Er wordt een nieuw venster of tabblad geopend.

5. Vouw de configuratie- en verificatieknooppunten voor uw site uit in de linkernavigatiebalk.

6. Klik op Bewerken

7. Zoek het element allowedExternalRedirectUrls. Deze kan worden ingesteld op null of een matrix met waarden. Wijzig de waarde in de volgende waarde:

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

   Vervang de URL's door de URL's van uw service. Voorbeelden zijn http://localhost:3000 (voor de Node.js-voorbeeldservice) of http://localhost:4400 (voor de Rimpelservice). Deze URL's zijn echter voorbeelden: uw situatie, waaronder voor de services die in de voorbeelden worden genoemd, kunnen afwijken.

8. Klik op de knop Lezen/schrijven in de rechterbovenhoek van het scherm.

9. Klik op de groene PUT-knop .

De instellingen worden op dit moment opgeslagen. Sluit het browservenster pas nadat de instellingen zijn opgeslagen. Voeg deze loopback-URL's ook toe aan de CORS-instellingen voor uw App Service:

1. Meld u aan bij Azure Portal.
2. Selecteer Alle resources of App Services en klik vervolgens op de naam van uw mobiele app.
3. De blade Instellingen wordt automatisch geopend. Als dit niet het probleem is, klikt u op Alle Instellingen.
4. Klik onder het API-menu op CORS .
5. Voer de URL in die u wilt toevoegen in het vak en druk op Enter.
6. Voer indien nodig meer URL's in.
7. Klik op Opslaan om de instellingen op te slaan.

Het duurt ongeveer 10-15 seconden voordat de nieuwe instellingen van kracht worden.