How to Use the JavaScript client library for Azure Mobile Apps

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

Omówienie

Ten przewodnik zawiera instrukcje dotyczące wykonywania typowych scenariuszy przy użyciu najnowszego zestawu SDK języka JavaScript dla usługi Azure Mobile Apps. Jeśli dopiero zaczynasz korzystać z usługi Azure Mobile Apps, najpierw ukończ przewodnik Szybki start usługi Azure Mobile Apps , aby utworzyć zaplecze i utworzyć tabelę. W tym przewodniku skupimy się na korzystaniu z zaplecza mobilnego w aplikacjach internetowych HTML/JavaScript.

Obsługiwane platformy

Ograniczamy obsługę przeglądarki do bieżących i ostatnich wersji głównych przeglądarek: Google Chrome, Microsoft Edge, Microsoft Internet Explorer i Mozilla Firefox. Oczekujemy, że zestaw SDK będzie działać z dowolną stosunkowo nowoczesną przeglądarką.

Pakiet jest dystrybuowany jako uniwersalny moduł JavaScript, dlatego obsługuje formaty globalne, AMD i CommonJS.

Konfigurowanie 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.

Instalowanie zestawu SDK języka JavaScript usługi Azure Mobile Apps można wykonać za pomocą npm polecenia :

npm install azure-mobile-apps-client --save

Biblioteka może być również używana jako moduł ES2015 w środowiskach CommonJS, takich jak Browserify i Webpack oraz jako biblioteka AMD. Na przykład:

// For ECMAScript 5.1 CommonJS
var WindowsAzure = require('azure-mobile-apps-client');
// For ES2015 modules
import * as WindowsAzure from 'azure-mobile-apps-client';

Możesz również użyć wstępnie utworzonej wersji zestawu SDK, pobierając bezpośrednio z naszej sieci CDN:

<script src="https://zumo.blob.core.windows.net/sdk/azure-mobile-apps-client.min.js"></script>

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ą:

• Odpytywanie tabeli
  • Filtrowanie danych
  • Stronicowanie danych
  • Sortowanie danych
• Wstawianie danych
• Modyfikowanie danych
• Usuwanie danych

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

Instrukcje: uwierzytelnianie użytkowników

Azure App Service obsługuje uwierzytelnianie i autoryzowanie użytkowników aplikacji przy użyciu różnych dostawców tożsamości zewnętrznych: Facebook, Google, Microsoft Account i Twitter. Możesz ustawić uprawnienia do tabel, aby ograniczyć dostęp do określonych operacji tylko uwierzytelnionych użytkowników. Można 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 .

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 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ć 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ę w serwisie 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ę z dostawcą 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.

Instrukcje: konfigurowanie App Service mobilnych dla zewnętrznych adresów URL przekierowania.

Kilka typów aplikacji JavaScript używa funkcji sprzężenia zwrotnego do obsługi przepływów interfejsu użytkownika OAuth. Te funkcje obejmują:

• Lokalne uruchamianie usługi
• Używanie ponownego ładowania na żywo za pomocą platformy Ionic
• Przekierowywanie do App Service na potrzeby uwierzytelniania.

Uruchamianie lokalnie może powodować problemy, ponieważ domyślnie App Service uwierzytelnianie jest skonfigurowane tylko tak, aby zezwalało na dostęp z zaplecza aplikacji mobilnej. Wykonaj następujące kroki, aby zmienić ustawienia App Service w celu włączenia uwierzytelniania podczas lokalnego uruchamiania serwera:

1. Zaloguj się do witryny Azure Portal.

2. Przejdź do zaplecza aplikacji mobilnej.

3. Wybierz pozycję Eksplorator zasobów w menu NARZĘDZIA PROGRAMISTYCZNE .

4. Kliknij pozycję Przejdź , aby otworzyć eksplorator zasobów zaplecza aplikacji mobilnej na nowej karcie lub w nowym oknie.

5. Rozwiń węzełauthsettingskonfiguracji> dla aplikacji.

6. Kliknij przycisk Edytuj , aby włączyć edytowanie zasobu.

7. Znajdź element allowedExternalRedirectUrls , który powinien mieć wartość null. Dodaj adresy URL w tablicy:

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

   Zastąp adresy URL w tablicy adresami URL usługi, które w tym przykładzie dotyczy https://localhost:3000 lokalnej usługi Node.js przykładowej. Można również użyć https://localhost:4400 dla usługi Ripple lub innego adresu URL, w zależności od sposobu konfigurowania aplikacji.

8. W górnej części strony kliknij pozycję Odczyt/zapis, a następnie kliknij pozycję PUT , aby zapisać aktualizacje.

Należy również dodać te same adresy URL sprzężenia zwrotnego do ustawień listy dozwolonych mechanizmu CORS:

1. Wróć do Azure Portal.
2. Przejdź do zaplecza aplikacji mobilnej.
3. Kliknij pozycję CORS w menu interfejsu API .
4. Wprowadź każdy adres URL w pustym polu tekstowym Dozwolone źródła . Zostanie utworzone nowe pole tekstowe.
5. Kliknij pozycję ZAPISZ.

Po zaktualizowaniu zaplecza będzie można używać nowych adresów URL sprzężenia zwrotnego w aplikacji.