Jak używać biblioteki Apache Cordova klienta dla usługi Azure Mobile Apps
Omówienie
W tym przewodniku nauczysz się wykonywać typowe scenariusze przy użyciu najnowszej Apache Cordova Plugin for Azure Mobile Apps. Jeśli jesteś nowym użytkownikom usługi Azure Mobile Apps, najpierw ukończ tworzenie zaplecza w usłudze Azure Mobile Apps Szybki start , utwórz tabelę i pobierz wstępnie Apache Cordova projekt. W tym przewodniku skupimy się na wtyczce Apache Cordova klienta.
Obsługiwane platformy
Ten zestaw SDK obsługuje Apache Cordova w wersji 6.0.0 lub nowszej na urządzeniach z systemem iOS, Android Windows nowszych. Obsługa platformy jest następująca:
- Interfejs API systemu Android 19–24 (KitKat do Nougat).
- System iOS w wersji 8.0 lub nowszej.
- Windows Phone 8.1.
- platforma uniwersalna systemu Windows.
Konfigurowanie i wymagania wstępne
W tym przewodniku przyjęto założenie, że utworzono zaplecza z tabelą. W tym przewodniku przyjęto założenie, że tabela ma taki sam schemat jak tabele w tych samouczkach. W tym przewodniku przyjęto również założenie, że Apache Cordova wtyczki do kodu. Jeśli jeszcze tego nie zrobiono, 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 Apache Cordova aplikacji, 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 do , app.component.ts aby 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 Azure Mobile Apps Cordova obsługuje aplikacje Ionic v1 i v2. Tylko aplikacje Ionic w wersji 2 wymagają dodatkowej deklaracji dla WindowsAzure obiektu.
Tworzenie połączenia klienta
Utwórz połączenie klienta, tworząc obiekt WindowsAzure.MobileServiceClient. Zastąp ciąg appUrl adresem URL Twojej aplikacji Mobile App.
var client = WindowsAzure.MobileServiceClient(appUrl);
Praca z tabelami
Aby uzyskać dostęp do danych lub je zaktualizować, utwórz odwołanie do tabeli zaplecza. Zastąp ciąg tableName nazwą tabeli
var table = client.getTable(tableName);
Po utworzeniu odwołania do tabeli możesz kontynuować pracę z tabelą:
Instrukcje: odpytywanie odwołania do tabeli
Po utworzeniu odwołania do tabeli możesz przy jego użyciu wysłać zapytanie o dane 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 użyciem wyników. Nie umieszczaj w funkcji success pętli for (var i in results), ponieważ będzie ona przechodzić przez informacje zawarte w wynikach w czasie, gdy będą używane inne funkcje zapytań (takie jak .includeTotalCount()).
Aby dowiedzieć się więcej o składni zapytań, zobacz [dokumentację obiektu Query].
Filtrowanie danych na serwerze
W przypadku odwołania do tabeli możesz użyć klauzuli where:
table
.where({ userId: user.userId, complete: false })
.read()
.then(success, failure);
Ponadto możesz użyć funkcji filtrującej obiekt. W tym przykładzie zmienna this jest przypisana do obecnie filtrowanego obiektu. Poniższy kod jest funkcjonalnie równoważny z poprzednim przykładem:
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(). Na przykład jeśli chcesz podzielić tabelę na rekordy składające się ze 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() powoduje dodanie pola totalCount do obiektu results. Pole totalCount zostanie wypełnione łączną liczbą rekordów, które zostałyby zwrócone w przypadku braku stronicowania.
Następnie możesz udostępnić listę stron za pomocą zmiennej pages i przycisków interfejsu użytkownika. Aby załadować nowe rekordy na każdą stronę, użyj metody loadPage(). Zaimplementuj buforowanie, aby przyspieszyć dostęp do już załadowanych rekordów.
Instrukcje: zwracanie posortowanych danych
Użyj metody zapytania .orderBy() lub .orderByDescending():
table
.orderBy('name')
.read()
.then(success, failure);
Aby uzyskać informacje o obiekcie Query, zobacz [dokumentację obiektu Query].
Instrukcje: wstawianie danych
Utwórz obiekt JavaScript z odpowiednimi danymi i asynchronicznie wywołaj metodę table.insert():
var newItem = {
name: 'My Name',
signupDate: new Date()
};
table
.insert(newItem)
.done(function (insertedItem) {
var id = insertedItem.id;
}, failure);
Pomyślnie wstawiony element zostaje zwrócony z dodatkowymi polami, które są wymagane przez operacje synchronizacji. Zaktualizuj własną pamięć podręczną o te informacje na potrzeby późniejszych aktualizacji.
Zestaw Azure Mobile Apps Node.js Server SDK obsługuje schemat dynamiczny dla celów deweloperskich. Schemat dynamiczny umożliwia dodawanie kolumn do tabeli przez podanie ich w operacji wstawiania lub aktualizacji. Zalecamy wyłączenie schematu dynamicznego przed przeniesieniem aplikacji na etap produkcji.
Instrukcje: modyfikowanie danych
Podobnie jak w przypadku metody .insert() należy utworzyć obiekt aktualizacji, a następnie wywołać metodę .update(). Obiekt aktualizacji musi zawierać identyfikator rekordu do zaktualizowania — identyfikator ten uzyskuje się podczas odczytu rekordu bądź wywoływania metody .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);
Uwierzytelnianie użytkowników
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 do uwierzytelnionych użytkowników. Możesz również użyć tożsamości uwierzytelnionych użytkowników, aby zaimplementować reguły autoryzacji w skryptach serwera. Aby uzyskać więcej informacji, zobacz samouczek dotyczący Wprowadzenie z uwierzytelnianiem.
W przypadku korzystania z uwierzytelniania Apache Cordova aplikacji muszą być dostępne następujące wtyczki cordova:
Obsługiwane są dwa przepływy uwierzytelniania: przepływ serwera i przepływ klienta. Przepływ serwera zapewnia najprostsze środowisko uwierzytelniania, ponieważ opiera się na interfejsie uwierzytelniania internetowego dostawcy. Przepływ klienta umożliwia głębszą integrację z możliwościami specyficznym dla urządzenia, takimi jak logowanie pojedyncze, ponieważ opiera się na zestawach SDK specyficznych dla określonego dostawcy dla urządzeń.
Instrukcje: uwierzytelnianie za pomocą dostawcy (przepływ serwera)
Aby usługa Mobile Apps zarządzała procesem uwierzytelniania w aplikacji, musisz zarejestrować swoją aplikację u dostawcy tożsamości. Następnie w usłudze Azure App Service musisz skonfigurować identyfikator aplikacji oraz wpis tajny udostępniony przez dostawcę. Aby uzyskać więcej informacji, zapoznaj się z samouczkiem 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 dla dostawcy to „aad”, „facebook”, „google”, „microsoftaccount” oraz „twitter”.
Uwaga
Obecnie uwierzytelnianie za pomocą konta Google nie działa za pośrednictwem przepływu serwera. Aby uwierzytelnić się za pomocą konta Google, musisz użyć metody przepływu klienta.
W tym przypadku usługa Azure App Service zarządza przepływem uwierzytelniania OAuth 2.0. Wyświetla stronę logowania wybranego dostawcy i generuje token uwierzytelniania App Service po pomyślnym zalogowaniu się u dostawcy tożsamości. Po zakończeniu swojego działania funkcja logowania zwraca obiekt JSON, który udostępnia zarówno identyfikator użytkownika, jak i token uwierzytelniania usługi App Service, odpowiednio w polach userId oraz authenticationToken. Ten token można zapisać w pamięci podręcznej i ponownie go używać, dopóki nie wygaśnie.
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 udostępnić zwrócony token usłudze App Service na potrzeby uwierzytelniania. Ten przepływ klienta pozwala zapewnić środowisko logowania jednokrotnego dla użytkowników bądź pobrać dodatkowe dane użytkownika od dostawcy tożsamości.
Podstawowy przykład uwierzytelniania przy użyciu sieci społecznościowych
W tym przykładzie na potrzeby uwierzytelniania użyto zestawu SDK klienta usługi Facebook:
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 założono, że token udostępniony przez zestaw SDK danego dostawcy jest przechowywany w zmiennej token.
Instrukcje: pozyskiwanie informacji o uwierzytelnionym użytkowniku
Dane uwierzytelniania można pobrać z punktu końcowego /.auth/me przy użyciu wywołania HTTP z dowolną biblioteką AJAX. Pamiętaj, aby dla nagłówka X-ZUMO-AUTH ustawić swój token uwierzytelniania. Token uwierzytelniania jest przechowywany w elemencie 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
});
Interfejs Fetch jest dostępny jako pakiet npm. Ponadto można go pobrać w przeglądarce z witryny CDNJS. Do pobrania informacji można również użyć biblioteki jQuery lub innego interfejsu API AJAX. Dane są odbierane w postaci obiektu JSON.
How to: Configure your Mobile App Service for external redirect URL URL (Jak skonfigurować usługę Mobile App Service dla zewnętrznych adresów URL przekierowania.
Kilka typów aplikacji Apache Cordova używa funkcji sprzężenia zwrotnego do obsługi przepływów interfejsu użytkownika OAuth. Przepływy interfejsu użytkownika OAuth na localhost powodują problemy, ponieważ usługa uwierzytelniania domyślnie wie tylko, jak korzystać z usługi. Przykłady problematycznych przepływów interfejsu użytkownika OAuth:
- Emulator Ripple.
- Przeładuj ponownie na żywo za pomocą Ionic.
- Uruchamianie zaplecza mobilnego lokalnie
- Uruchamianie zaplecza mobilnego w innym Azure App Service niż to, które zapewnia uwierzytelnianie.
Postępuj zgodnie z tymi instrukcjami, aby dodać ustawienia lokalne do konfiguracji:
Zaloguj się do witryny Azure Portal.
Wybierz pozycję Wszystkie zasoby lub App Services a następnie kliknij nazwę aplikacji mobilnej.
Kliknij pozycję Narzędzia
Kliknij pozycję Eksplorator zasobów w menu OBSERVE, a następnie kliknij pozycję Przejdź. Zostanie otwarte nowe okno lub karta.
Rozwiń węzły konfiguracjiauthsettings dla lokacji w okienku nawigacji po lewej stronie.
Kliknij pozycję Edytuj.
Poszukaj elementu "allowedExternalRedirectUrls". Może być ustawiona na wartość null lub tablicę wartości. Zmień wartość na następującą:
"allowedExternalRedirectUrls": [ "https://localhost:3000", "https://localhost:3000" ],Zastąp adresy URL adresami URL usługi. Przykłady obejmują
https://localhost:3000(dla Node.js przykładowej usługi) lubhttps://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 być inna.Kliknij przycisk Odczyt/Zapis w prawym górnym rogu ekranu.
Kliknij zielony przycisk PUT .
Ustawienia są zapisywane w tym momencie. Nie zamykaj okna przeglądarki, dopóki ustawienia nie zostaną zakończone. Dodaj również następujące adresy URL sprzężenia zwrotnego do ustawień cors dla App Service:
- Zaloguj się do witryny Azure Portal.
- Wybierz pozycję Wszystkie zasoby lub App Services a następnie kliknij nazwę aplikacji mobilnej.
- Blok Ustawienia zostanie automatycznie otwarty. Jeśli tak się nie stanie, kliknij pozycję Wszystkie Ustawienia.
- Kliknij pozycję CORS w menu interfejsu API.
- Wprowadź adres URL, który chcesz dodać, w dostarczonym polu i naciśnij klawisz Enter.
- Wprowadź dodatkowe adresy URL zgodnie z potrzebami.
- Kliknij polecenie Zapisz, aby zapisać ustawienia.
Nowe ustawienia zostaną wprowadzone po około 10–15 sekundach.
Jak zarejestrować powiadomienia wypychane
Zainstaluj wtyczkę phonegap-plugin-push w celu obsługi powiadomień wypychanych. Tę wtyczkę można łatwo dodać za cordova plugin add pomocą polecenia w wierszu polecenia lub za pośrednictwem instalatora wtyczki Git w Visual Studio. Następujący kod w aplikacji Apache Cordova rejestruje urządzenie na powiadomienia wypychane:
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 NOTIFICATION HUBS SDK do wysyłania powiadomień wypychanych z serwera. Nigdy nie wysyłaj powiadomień wypychanych bezpośrednio od klientów. W ten sposób można wyzwolić atak typu "odmowa usługi" na Notification Hubs lub PNS. W wyniku takich ataków sieciowa może spowodować blokowania ruchu.
Więcej informacji
Szczegółowe informacje o interfejsie API można znaleźć w naszej dokumentacji interfejsu API.