Verwenden der Apache Cordova-Clientbibliothek für Azure Mobile Apps

Artikel
06/25/2019

Übersicht

Dieser Artikel beschreibt gängige Szenarien für die Verwendung des neuesten Apache Cordova-Plug-Ins für Azure Mobile Apps. Wenn Sie mit Azure Mobile Apps noch nicht vertraut sind, führen Sie zunächst den Schnellstart von Azure Mobile Apps durch, um ein Back-End und eine Tabelle zu erstellen und ein vorgefertigtes Apache Cordova-Projekt herunterzuladen. In dieser Anleitung konzentrieren wir uns auf das clientseitige Apache Cordova-Plug-In.

Unterstützte Plattformen

Dieses SDK unterstützt Apache Cordova v6.0.0 und höher auf iOS-, Android- und Windows-Geräten. Folgende Plattformen werden unterstützt:

Android API 19–24 (KitKat bis Nougat)
iOS-Version 8.0 und höher.
Windows Phone 8.1
Universelle Windows-Plattform

Einrichtung und Voraussetzungen

Dieses Lernprogramm setzt voraus, dass Sie ein Back-End mit einer Tabelle erstellt haben. In dieser Anleitung wird davon ausgegangen, dass die Tabelle das gleiche Schema wie die Tabellen in diesen Lernprogrammen aufweist. In dieser Anleitung wird davon ausgegangen, dass Sie Ihrem Code das Apache Cordova-Plug-In hinzugefügt haben. Falls noch nicht geschehen, können Sie das Apache Cordova-Plug-In über die Befehlszeile Ihrem Projekt hinzufügen:

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

Weitere Informationen zum Erstellen Ihrer ersten Apache Cordova-Appfinden Sie in der dazugehörigen Dokumentation.

Einrichten einer Ionic v2-App

Erstellen Sie für die ordnungsgemäße Konfiguration eines Ionic v2-Projekts zunächst eine allgemeine App, und fügen Sie anschließend das Cordova-Plug-In hinzu:

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

Fügen Sie app.component.ts die folgenden Zeilen hinzu, um das Clientobjekt zu erstellen:

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

Nun können Sie das Projekt im Browser erstellen und ausführen:

ionic platform add browser
ionic run browser

Das Azure Mobile Apps-Cordova-Plug-In unterstützt Ionic v1- und v2-Apps. Nur bei Ionic v2-Apps ist die zusätzliche Deklaration für das WindowsAzure-Objekt erforderlich.

Erstellen einer Clientverbindung

Stellen Sie eine Clientverbindung her, indem Sie ein WindowsAzure.MobileServiceClient -Objekt erstellen. Ersetzen Sie appUrl durch die URL zu Ihrer mobilen App.

var client = WindowsAzure.MobileServiceClient(appUrl);

Arbeiten mit Tabellen

Zum Zugreifen auf oder Aktualisieren von Daten erstellen Sie einen Verweis auf die Back-End-Tabelle. Ersetzen Sie tableName durch den Namen Ihrer Tabelle.

var table = client.getTable(tableName);

Sobald Sie einen Tabellenverweis haben, können Sie mit der Tabelle:

Eine Tabelle abfragen
Daten einfügen
Ändern von Daten
Löschen von Daten

Vorgehensweise: Abfragen von Tabellenverweisen

Sobald Sie über einen Tabellenverweis verfügen, können Sie diesen zum Abfragen von Daten auf dem Server verwenden. Abfragen erfolgen in einer „LINQ-ähnlichen“ Sprache. Verwenden Sie den folgenden Code, um alle Daten aus der Tabelle zurückzugeben:

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

Die „success“-Funktion mit den Ergebnissen wird aufgerufen. Verwenden Sie for (var i in results) nicht in der „success“-Funktion, da dies zum Durchlaufen von Informationen in den Ergebnissen führt, wenn andere Abfragefunktionen verwendet werden (wie z.B. .includeTotalCount()).

Weitere Informationen zur Abfragesyntax finden Sie in der [Dokumentation zum Query-Objekt].

Filtern von Daten auf dem Server

Sie können für den Tabellenverweis eine where Klausel verwenden:

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

Sie können auch eine Funktion nutzen, die das Objekt filtert. In diesem Fall wird die Variable this dem aktuell gefilterten Objekt zugewiesen. Der folgende Code hat die gleiche Funktion wie das vorherige Beispiel:

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

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

Aufteilung von Daten auf Seiten

Verwenden Sie die Methoden take() und skip(). Angenommen, die Tabelle soll in Datensätze mit 100 Zeilen aufgeteilt werden:

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

Die Methode .includeTotalCount() wird verwendet, um ein totalCount-Feld dem „results“-Objekt hinzuzufügen. Das „totalCount“-Feld wird mit der Gesamtanzahl von Datensätzen aufgefüllt, die zurückgegeben wird, wenn keine Seitenverwaltung verwendet wird.

Sie können dann die pages-Variable und einige Schaltflächen auf der Benutzeroberfläche verwenden, um eine Seitenliste bereitzustellen. Verwenden Sie loadPage() zum Laden der neuen Datensätze für jede Seite. Implementieren Sie eine Zwischenspeicherung, um den Zugriff auf bereits geladene Datensätze zu beschleunigen.

Vorgehensweise: Zurückgeben sortierter Daten

Verwenden Sie die Abfragemethode .orderBy() oder .orderByDescending():

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

Weitere Informationen zum Query-Objekt finden Sie in der [Dokumentation zum Query-Objekt].

Vorgehensweise: Einfügen von Daten

Erstellen Sie ein JavaScript-Objekt mit dem entsprechenden Datum, und rufen Sie table.insert() asynchron auf:

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

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

Bei erfolgreichem Einfügen wird das eingefügte Element mit den zusätzlichen Feldern zurückgegeben, die für Synchronisierungsvorgänge erforderlich sind. Aktualisieren Sie Ihren Cache für spätere Updates mit diesen Informationen.

Das Node.js-Server SDK für Azure Mobile Apps unterstützt ein dynamisches Schema für die Entwicklung. Dadurch können Sie der Tabelle Spalten durch Angabe in einem Einfüge- oder Aktualisierungsvorgang hinzufügen. Es wird empfohlen, das dynamische Schema zu deaktivieren, bevor die Anwendung in die Produktion verlagert wird.

Vorgehensweise: Ändern von Daten

Ähnlich wie bei der .insert()-Methode müssen Sie zuerst ein Update-Objekt erstellen und dann .update() aufrufen. Das Update-Objekt muss die ID des Datensatzes enthalten, der aktualisiert werden soll. Die ID wird beim Lesen des Datensatzes oder Aufrufen von .insert() abgerufen.

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

Vorgehensweise: Löschen von Daten

Rufen Sie die .del()-Methode auf, um einen Datensatz zu löschen. Übergeben Sie die ID in einen Objektverweis:

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

Vorgehensweise: Authentifizieren von Benutzern

App Service unterstützt die Authentifizierung und Autorisierung von App-Benutzern mithilfe verschiedener externer Identitätsanbieter: Facebook, Google, Microsoft-Konto und Twitter. Sie können Berechtigungen für Tabellen vergeben, um den Zugriff auf bestimmte Operationen auf authentifizierte Benutzer zu beschränken. Außerdem können Sie die Identität authentifizierter Benutzer verwenden, um Autorisierungsregeln in Serverskripts zu implementieren. Weitere Informationen finden Sie im Lernprogramm Erste Schritte mit der Authentifizierung .

Bei Verwendung der Authentifizierung in einer Apache Cordova-App müssen die folgenden Cordova-Plug-Ins verfügbar sein:

Insgesamt werden zwei Authentifizierungsflüsse unterstützt: ein Serverfluss und ein Clientfluss. Der Serverfluss bietet die einfachste Authentifizierungsform, da in diesem Fall die Authentifizierungs-Webschnittstelle des Anbieters verwendet wird. Der Clientfluss ermöglicht eine tiefere Integration mit gerätespezifischen Fähigkeiten wie z. B. einmalige Anmeldung, da in diesem Fall anbieterspezifische und gerätespezifische SDKs verwendet werden.

Vorgehensweise: Authentifizieren mithilfe eines Anbieters (Serverfluss)

Sie müssen Ihre Mobile Apps bei Ihrem Identitätsanbieter registrieren, um Mobile Services die Verwaltung des Authentifizierungsprozesses in Ihrer App zu ermöglichen. Anschließend müssen Sie in Ihrem Azure App Service die Anwendungs-ID und den geheimen Schlüssel Ihres Anbieters konfigurieren. Weitere Informationen finden Sie im Lernprogramm Authentifizierung zu Ihrer App hinzufügen.

Rufen Sie nach der Registrierung bei Ihrem Identitätsanbieter die .login()-Methode mit dem Namen Ihres Anbieters auf. Verwenden Sie also beispielsweise für die Facebook-Anmeldung den folgenden Code:

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

Gültige Anbieterwerte sind „aad“, „facebook“, „google“, „microsoftaccount“ und „twitter“.

Hinweis

Die Authentifizierung über Google ist zurzeit nicht per Serverfluss möglich. Für die Authentifizierung über Google muss eine Clientflussmethode verwendet werden.

In diesem Fall verwaltet Azure App Service den OAuth 2.0-Authentifizierungsfluss. Dabei wird die Anmeldeseite des ausgewählten Anbieters angezeigt und nach erfolgreicher Anmeldung beim Identitätsanbieter ein App Service-Authentifizierungstoken generiert. Die Anmeldefunktion gibt nach Abschluss ein JSON-Objekt zurück, das sowohl die Benutzer-ID als auch das App Service-Authentifizierungstoken in den Feldern „userId“ bzw. „authenticationToken“ verfügbar macht. Dieses Token kann zwischengespeichert und wiederverwendet werden, bis es abläuft.

Vorgehensweise: Authentifizieren mithilfe eines Anbieters (Clientfluss)

Ihre Anwendung kann den Identitätsanbieter auch unabhängig kontaktieren und das zurückgegebene Token zur Authentifizierung Ihrem App Service vorlegen. Mit diesem Clientfluss können Sie die einmalige Anmeldung für Ihre Benutzer implementieren oder zusätzliche Benutzerdaten vom Identitätsanbieter abrufen.

Dieses Beispiel verwendet die Client-SDK von Facebook für die Authentifizierung:

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

Dieses Beispiel geht davon aus, dass das vom jeweiligen Anbieter gelieferte Token in der token-Variable gespeichert wird.

Vorgehensweise: Abrufen von Informationen zum authentifizierten Benutzer

Die Authentifizierungsinformationen können mithilfe eines HTTP-Aufrufs mit einer beliebigen AJAX-Bibliothek vom /.auth/me-Endpunkt abgerufen werden. Stellen Sie sicher, dass der X-ZUMO-AUTH -Header auf Ihr Authentifizierungstoken festgelegt ist. Das Authentifizierungstoken wird in client.currentUser.mobileServiceAuthenticationTokengespeichert. Geben Sie beispielsweise Folgendes ein, um die API abzurufen:

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

Der Abruf ist als npm-Paket oder als Browserdownload über CDNJS verfügbar. Sie können auch JQuery oder eine andere AJAX-API zum Abrufen der Informationen verwenden. Daten werden als JSON-Objekt empfangen.

Vorgehensweise: Konfigurieren Ihres Mobile App Service für externe Umleitungs-URLs

Mehrere Apache Cordova-Anwendungen verwenden eine Loopback-Funktion, um Abläufe in der OAuth-Benutzeroberfläche zu verarbeiten. Abläufe in der OAuth-Benutzeroberfläche auf localhost führen zu Problemen, da der Authentifizierungsdienst nur weiß, wie Ihr Dienst standardmäßig zu verwenden ist. Folgende Abläufe in der OAuth-Benutzeroberfläche können problematisch sein:

Der Ripple-Emulator.
Live Reload mit Ionic.
Lokale Ausführung des mobilen Back-Ends
Ausführen des mobilen Back-Ends in einer anderen Azure App Service-Instanz als derjenigen, die die Authentifizierung bereitstellt.

Um die Konfiguration Ihrer lokalen Einstellungen hinzuzufügen, gehen Sie wie folgt vor:

Melden Sie sich beim Azure portal
Wählen Sie Alle Ressourcen oder App Services aus, und klicken Sie dann auf den Namen Ihrer mobilen App.
Klicken Sie auf Tools
Klicken Sie im Menü ÜBERWACHEN auf Ressourcen-Explorer, und klicken Sie dann auf Start. Es wird ein neues Fenster oder eine neue Registerkarte geöffnet.
Erweitern Sie im linken Navigationsbereich die Knoten Konfiguration und Authentifizierungseinstellungen für Ihre Website.
Klicken Sie auf Bearbeiten
Suchen Sie nach dem Element allowedExternalRedirectUrls. Das Element ist möglicherweise auf Null oder ein Wertearray festgelegt. Ändern Sie den Wert folgendermaßen:
```
  "allowedExternalRedirectUrls": [
      "https://localhost:3000",
      "https://localhost:3000"
  ],
```
Ersetzen Sie die URLs mit den URLs Ihres Diensts. Beispiele hierfür sind https://localhost:3000 (für den Node.js-Beispieldienst) oder https://localhost:4400 (für den Ripple-Dienst). Diese URLs sind jedoch nur Beispiele – Ihre Situation kann auch für die Dienste, die im Beispiel dargestellt sind, ganz anders sein.
Klicken Sie in der oberen rechten Ecke des Bildschirms auf die Schaltfläche Lesen/Schreiben .
Klicken Sie auf die grüne Schaltfläche PUT .

An diesem Punkt werden die Einstellungen gespeichert. Schließen Sie das Browserfenster nicht, ehe die Einstellungen gespeichert wurden. Sie müssen auch die Loopback-URLs zu den CORS-Einstellungen für Ihre App Service-Instanz hinzufügen:

Melden Sie sich beim Azure portal
Wählen Sie Alle Ressourcen oder App Services aus, und klicken Sie dann auf den Namen Ihrer mobilen App.
Das Blatt „Einstellungen“ wird automatisch geöffnet. Wenn dies nicht der Fall ist, klicken Sie auf Alle Einstellungen.
Klicken Sie im API-Menü auf CORS .
Geben Sie in das bereitgestellte Feld die URL ein, die Sie hinzufügen möchten, und drücken Sie die EINGABETASTE.
Geben Sie ggf. zusätzliche URLs ein.
Klicken Sie auf Speichern , um die Einstellungen zu speichern.

Es dauert ungefähr 10-15 Sekunden, bis die neuen Einstellungen wirksam sind.

Gewusst wie: Registrieren für Pushbenachrichtigungen

Installieren Sie das Plug-In phonegap-plug-in-push zum Verarbeiten von Pushbenachrichtigungen. Dieses Plug-In kann problemlos mithilfe des cordova plugin add -Befehls über die Befehlszeile oder den Git-Installer für Plug-Ins in Visual Studio hinzugefügt werden. Der folgende Code in der Apache Cordova-App registriert Ihr Gerät für Pushbenachrichtigungen:

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

Verwenden Sie das Notification Hubs SDK zum Senden von Pushbenachrichtigungen vom Server. Senden Sie Pushbenachrichtigungen niemals direkt von Clients. Diese Vorgehensweise könnte dazu missbraucht werden, einen Denial-of-Service-Angriff auf Notification Hubs oder den Pushbenachrichtigungsdienst auszulösen. Als Folge solcher Angriffe könnte der Pushbenachrichtigungsdienst Ihren Datenverkehr sperren.

Weitere Informationen

Ausführliche Informationen zur API finden Sie in unserer API-Dokumentation.