Jak używać biblioteki klienta platformy Apache Cordova dla usługi Azure Mobile Apps

• Android
• Cordova
• JavaScript
• iOS
• zarządzane (Windows/Xamarin)

Przegląd

Ten przewodnik zawiera instrukcje dotyczące wykonywania typowych scenariuszy przy użyciu najnowszej wtyczki Apache Cordova dla usługi Azure Mobile Apps. Jeśli dopiero zaczynasz korzystać z usługi Azure Mobile Apps, najpierw ukończ szybki start usługi Azure Mobile Apps, aby utworzyć zaplecze, utworzyć tabelę i pobrać wstępnie utworzony projekt apache Cordova. W tym przewodniku skoncentrujemy się na wtyczki Apache Cordova po stronie klienta.

Obsługiwane platformy

Ten zestaw SDK obsługuje oprogramowanie Apache Cordova w wersji 6.0.0 lub nowszej na urządzeniach z systemami iOS, Android i Windows. Obsługa platformy jest następująca:

• Android API 19-24 (KitKat przez Nougat).
• System iOS w wersji 8.0 lub nowszej.
• Windows Phone 8.1.
• platforma uniwersalna systemu Windows.

Konfiguracja i wymagania wstępne

W tym przewodniku założono, że utworzono zaplecze z tabelą. W tym przewodniku założono, że tabela ma ten sam schemat co tabele w tych samouczkach. W tym przewodniku założono również, że do kodu dodano wtyczkę Apache Cordova. Jeśli nie zostało to zrobione, możesz dodać wtyczkę Apache Cordova do projektu w wierszu polecenia:

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

Aby uzyskać więcej informacji na temat tworzenia pierwszej aplikacji platformy Apache Cordova, zobacz ich dokumentację.

Konfigurowanie aplikacji Ionic w wersji 2

Aby prawidłowo skonfigurować projekt Ionic v2, najpierw utwórz podstawową aplikację i dodaj wtyczkę Cordova:

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

Dodaj następujące wiersze, aby app.component.ts utworzyć obiekt klienta:

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

Teraz możesz skompilować i uruchomić projekt w przeglądarce:

ionic platform add browser
ionic run browser

Wtyczka Cordova usługi Azure Mobile Apps obsługuje zarówno aplikacje Ionic v1, jak i v2. Tylko aplikacje Ionic w wersji 2 wymagają dodatkowej WindowsAzure deklaracji dla obiektu.

Tworzenie połączenia klienta

Utwórz połączenie klienta, tworząc obiekt WindowsAzure.MobileServiceClient. Zastąp appUrl adresem URL aplikacji mobilnej.

var client = WindowsAzure.MobileServiceClient(appUrl);

Praca z tabelami

Aby uzyskać dostęp do danych lub zaktualizować je, utwórz odwołanie do tabeli zaplecza. Zastąp tableName nazwą tabeli

var table = client.getTable(tableName);

Po utworzeniu odwołania do tabeli możesz kontynuować pracę z tabelą:

• wykonywanie zapytań względem tabeli
  • filtrowanie danych
  • Przeglądanie danych strona po stronie
  • Sortowanie danych
• wstawianie danych
• modyfikowanie danych
• usuwanie danych

Jak zapytać o odwołanie do tabeli

Po utworzeniu odwołania do tabeli możesz użyć jej do wykonywania zapytań dotyczących danych na serwerze. Zapytania są tworzone w języku "przypominającym LINQ". Aby zwrócić wszystkie dane z tabeli, użyj następującego kodu:

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

Funkcja success jest wywoływana z wynikami. Nie używaj for (var i in results) w funkcji powodzenia, ponieważ będzie iterować informacje zawarte w wynikach, gdy są używane inne funkcje zapytania (takie jak .includeTotalCount()).

Aby uzyskać więcej informacji na temat składni zapytania, zobacz dokumentację obiektu [Query].

Filtrowanie danych na serwerze

Możesz użyć klauzuli where w odniesieniu do tabeli:

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

Można również użyć funkcji, która filtruje obiekt. W takim przypadku zmienna this jest przypisywana do filtrowanego bieżącego obiektu. Poniższy kod jest funkcjonalnie odpowiednikiem poprzedniego przykładu:

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

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

Stronicowanie danych

Skorzystaj z metod take() i skip(). Jeśli na przykład chcesz podzielić tabelę na rekordy po 100 wierszy:

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

Metoda .includeTotalCount() służy do dodawania pola totalCount do obiektu results. Pole totalCount jest wypełnione całkowitą liczbą rekordów, które zostaną zwrócone, jeśli stronicowanie nie jest stosowane.

Następnie możesz użyć zmiennej pages i niektórych przycisków interfejsu użytkownika, aby podać listę stron; użyj loadPage(), aby załadować nowe rekordy dla każdej strony. Zaimplementuj buforowanie, aby przyspieszyć dostęp do rekordów, które zostały już załadowane.

Instrukcje: Zwracanie posortowanych danych

Użyj metod zapytań .orderBy() lub .orderByDescending():

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

Aby uzyskać więcej informacji na temat obiektu Query, zobacz dokumentację obiektu [Query object].

Instrukcje: Wstawianie danych

Utwórz obiekt JavaScript z odpowiednią datą i wywołaj table.insert() asynchronicznie:

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

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

Po pomyślnym wstawieniu wstawiony element jest zwracany z dodatkowymi polami wymaganymi do operacji synchronizacji. Zaktualizuj własną pamięć podręczną, korzystając z tych informacji, aby uzyskać późniejsze aktualizacje.

Zestaw SDK usługi Azure Mobile Apps Node.js Server obsługuje schemat dynamiczny na potrzeby programowania. Schemat dynamiczny umożliwia dodawanie kolumn do tabeli przez określenie ich w operacji wstawiania lub aktualizacji. Zalecamy wyłączenie schematu dynamicznego przed przeniesieniem aplikacji do środowiska produkcyjnego.

Instrukcje: modyfikowanie danych

Podobnie jak w przypadku metody .insert(), należy utworzyć obiekt Update, a następnie wywołać metodę .update(). Obiekt aktualizacji musi zawierać identyfikator rekordu do zaktualizowania — identyfikator jest uzyskiwany podczas odczytywania rekordu lub podczas wywoływania .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);

Instrukcje: usuwanie danych

Aby usunąć rekord, wywołaj metodę .del(). Przekaż identyfikator w odwołaniu do obiektu:

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

Instrukcje: uwierzytelnianie użytkowników

Usługa Azure App Service obsługuje uwierzytelnianie i autoryzowanie użytkowników aplikacji przy użyciu różnych zewnętrznych dostawców tożsamości: Facebook, Google, Konto Microsoft i Twitter. Możesz ustawić uprawnienia do tabel, aby ograniczyć dostęp do określonych operacji tylko dla uwierzytelnionych użytkowników. Możesz również użyć tożsamości uwierzytelnionych użytkowników do zaimplementowania reguł autoryzacji w skryptach serwera. Aby uzyskać więcej informacji, zobacz samouczek Wprowadzenie do uwierzytelniania.

W przypadku korzystania z uwierzytelniania w aplikacji Apache Cordova następujące wtyczki Cordova muszą być dostępne:

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

Obsługiwane są dwa przepływy uwierzytelniania: przepływ serwera i przepływ klienta. Przepływ serwera zapewnia najprostsze doświadczenie uwierzytelniania, ponieważ opiera się na interfejsie internetowym uwierzytelniania dostawcy. Przepływ klienta umożliwia głębszą integrację z funkcjami specyficznymi dla urządzenia, takimi jak logowanie jednokrotne, ponieważ opiera się na zestawach SDK specyficznych dla dostawcy.

Instrukcje: uwierzytelnianie za pomocą dostawcy (przepływ serwera)

Aby usługa Mobile Apps zarządzała procesem uwierzytelniania w aplikacji, musisz zarejestrować aplikację u dostawcy tożsamości. Następnie w usłudze Azure App Service należy skonfigurować identyfikator aplikacji i wpis tajny dostarczony przez dostawcę. Aby uzyskać więcej informacji, zobacz samouczek Dodawanie uwierzytelniania do aplikacji.

Po zarejestrowaniu dostawcy tożsamości wywołaj metodę .login() z nazwą dostawcy. Aby na przykład zalogować się za pomocą serwisu Facebook, użyj następującego kodu:

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

Prawidłowe wartości dostawcy to "aad", "facebook", "google", "microsoftaccount" i "twitter".

Uwaga

Uwierzytelnianie Google nie działa obecnie za pośrednictwem trybu serwera. Aby uwierzytelnić się w usłudze Google, należy użyć metody przepływu klienta.

W takim przypadku usługa Azure App Service zarządza przepływem uwierzytelniania OAuth 2.0. Wyświetla stronę logowania wybranego dostawcy i generuje token uwierzytelniania usługi App Service po pomyślnym zalogowaniu się u dostawcy tożsamości. Po zakończeniu funkcja logowania zwraca obiekt JSON, który uwidacznia odpowiednio identyfikator użytkownika i token uwierzytelniania usługi App Service w polach userId i authenticationToken. Ten token można buforować i ponownie używać do momentu jego wygaśnięcia.

Instrukcje: uwierzytelnianie za pomocą dostawcy (przepływ klienta)

Aplikacja może również niezależnie skontaktować się z dostawcą tożsamości, a następnie podać zwrócony token do usługi App Service na potrzeby uwierzytelniania. Ten przepływ klienta umożliwia udostępnienie użytkownikom logowania jednokrotnego lub pobranie dodatkowych danych użytkownika od dostawcy tożsamości.

Podstawowy przykład uwierzytelniania społecznościowego

W tym przykładzie użyto zestawu SDK klienta usługi Facebook do uwierzytelniania:

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

W tym przykładzie przyjęto założenie, że token dostarczony przez odpowiedni zestaw SDK dostawcy jest przechowywany w zmiennej tokenu.

Instrukcje: uzyskiwanie informacji o uwierzytelnianych użytkownikach

Informacje uwierzytelniania można pobrać z punktu końcowego /.auth/me przy użyciu wywołania HTTP z dowolną biblioteką AJAX. Upewnij się, że dla nagłówka X-ZUMO-AUTH ustawiono token uwierzytelniania. Token uwierzytelniania jest przechowywany w client.currentUser.mobileServiceAuthenticationToken. Na przykład, aby użyć interfejsu API fetch:

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

Pobieranie jest dostępne jako pakiet npm lub do przeglądarek poprzez CDNJS. Możesz również użyć zestawu jQuery lub innego interfejsu API AJAX, aby pobrać informacje. Dane są odbierane jako obiekt JSON.

Instrukcje: konfigurowanie usługi Mobile App Service pod kątem zewnętrznych adresów URL przekierowania.

Kilka typów aplikacji Apache Cordova wykorzystuje funkcję sprzężenia zwrotnego do obsługi przepływów interfejsu użytkownika OAuth. Przepływy interfejsu użytkownika OAuth na hoście lokalnym powodują problemy, ponieważ usługa uwierzytelniania domyślnie potrafi korzystać tylko z twojej usługi. Przykłady problematycznych przepływów interfejsu użytkownika protokołu OAuth obejmują:

• Emulator Ripple.
• Automatyczne przeładowanie przy użyciu Ionic.
• Lokalne uruchamianie zaplecza mobilnego
• Uruchamianie zaplecza mobilnego w innej usłudze Azure App Service niż ta, która zapewnia uwierzytelnianie.

Postępuj zgodnie z tymi instrukcjami, aby dodać ustawienia lokalne do konfiguracji:

1. Zaloguj się do witryny Azure Portal.

2. Wybierz pozycję Wszystkie zasoby lub App Services a następnie kliknij nazwę aplikacji mobilnej.

3. Kliknij Tools

4. Kliknij pozycję Eksplorator zasobów w menu OBSERWOWANIE, a następnie kliknij pozycję Przejdź. Zostanie otwarte nowe okno lub karta.

5. Rozwiń węzły config i authsettings dla swojej witryny w lewym panelu nawigacyjnym.

6. Kliknij , aby edytować

7. Wyszukaj element "allowedExternalRedirectUrls". Może być ustawiona na wartość null lub tablicę wartości. Zmień wartość na następującą wartość:

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

   Zastąp adresy URL adresami URL usługi. Przykłady obejmują https://localhost:3000 (dla przykładowej usługi Node.js) lub https://localhost:4400 (dla usługi Ripple). Jednak te adresy URL są przykładami — sytuacja, w tym dla usług wymienionych w przykładach, może się różnić.

8. Kliknij przycisk odczyt/zapis w prawym górnym rogu ekranu.

9. Kliknij zielony przycisk PUT.

Ustawienia są zapisywane w tym momencie. Nie zamykaj okna przeglądarki, dopóki ustawienia nie zakończą zapisywania. Dodaj również te adresy URL sprzężenia zwrotnego do ustawień mechanizmu CORS dla usługi App Service:

1. Zaloguj się do witryny Azure Portal.
2. Wybierz pozycję Wszystkie zasoby lub App Services a następnie kliknij nazwę aplikacji mobilnej.
3. Zostanie otwarty blok Ustawienia automatycznie. Jeśli tak nie jest, kliknij pozycję Wszystkie ustawienia.
4. Kliknij CORS w menu API.
5. Wprowadź adres URL, który chcesz dodać w podanym polu i naciśnij Enter.
6. Wprowadź dodatkowe adresy URL zgodnie z potrzebami.
7. Kliknij przycisk Zapisz, aby zapisać ustawienia.

Zastosowanie nowych ustawień trwa około 10–15 sekund.

Jak zarejestrować się w celu otrzymywania powiadomień push

Zainstaluj wtyczkę phonegap-plugin-push, aby obsługiwać powiadomienia push. Tę wtyczkę można łatwo dodać przy użyciu cordova plugin add polecenia w wierszu polecenia lub za pośrednictwem instalatora wtyczki Git w programie Visual Studio. Poniższy kod w aplikacji Apache Cordova rejestruje urządzenie w celu otrzymywania powiadomień push:

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

Użyj zestawu SDK usługi Notification Hubs, aby wysyłać push powiadomienia z serwera. Nigdy nie wysyłaj powiadomień push bezpośrednio z poziomu klientów. Może to służyć do wyzwalania ataku typu "odmowa usługi" na usługi Notification Hubs lub pnS. PNS może blokować ruch w wyniku takich ataków.

Więcej informacji

Szczegółowe informacje o interfejsie API można znaleźć w naszej dokumentacji interfejsu API.