Jak používat modul plug-in Apache Cordova pro Azure Mobile Apps

  • Článek

V této příručce se naučíte provádět běžné scénáře pomocí nejnovějšího modulu plug-in Apache Cordova pro Azure Mobile Apps. Pokud s Azure Mobile Apps teprve začínáte, nejprve dokončete rychlý start Azure Mobile Apps a vytvořte back-end, vytvořte tabulku a stáhněte si předem vytvořený projekt Apache Cordova. V této příručce se zaměříme na modul plug-in Apache Cordova na straně klienta.

Podporované platformy

Tato sada SDK podporuje Apache Cordova verze 6.0.0 a novější na zařízeních s iOSem, Androidem a Windows. Podpora platformy je následující:

  • Android API 19+.
  • iOS verze 8.0 a novější

Upozorňující

Tento článek popisuje informace o verzi knihovny v4.2.0, která je vyřazena. V této knihovně nebudou provedeny žádné další aktualizace, včetně aktualizací problémů se zabezpečením. Pokud chcete pokračovat v podpoře, zvažte přechod na klienta .NET, jako je .NET MAUI .

Nastavení a požadavky

Tato příručka předpokládá, že jste vytvořili back-end s tabulkou. Příklady používají TodoItem tabulku z rychlých startů. Pokud chcete do projektu přidat modul plug-in Azure Mobile Apps, použijte následující příkaz:

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

Další informace o vytvoření první aplikace Apache Cordova najdete v dokumentaci.

Nastavení aplikace Ionic v2

Pokud chcete správně nakonfigurovat projekt Ionic v2, nejprve vytvořte základní aplikaci a přidejte modul plug-in Cordova:

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

Přidejte následující řádky pro app.component.ts vytvoření objektu klienta:

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

Teď můžete sestavit a spustit projekt v prohlížeči:

ionic platform add browser
ionic run browser

Modul plug-in Cordova pro Azure Mobile Apps podporuje aplikace Ionic v1 i v2. Pouze aplikace Ionic v2 vyžadují pro objekt extra deklaraci WindowsAzure .

Vytvoření připojení klienta

Vytvořte připojení klienta tak, že vytvoříte objekt WindowsAzure.MobileServiceClient. Nahraďte appUrl adresou URL vaší mobilní aplikace.

var client = WindowsAzure.MobileServiceClient(appUrl);

Práce s tabulkami

Pro přístup k datům a jejich aktualizaci vytvořte odkaz na back-endovou tabulku. Nahraďte tableName názvem vaší tabulky.

var table = client.getTable(tableName);

Jakmile budete mít odkaz na tabulku, můžete s ní dále pracovat:

Dotazování na odkaz na tabulku

Jakmile budete mít odkaz na tabulku, můžete jej použít k dotazování na data na serveru. Dotazy se sestavují v jazyce podobném jazyku LINQ. Pokud chcete vrátit všechna data z tabulky, použijte následující kód:

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

S výsledky se zavolá funkce success. Nepoužívejte ve funkci success smyčku for (var i in results) – ta provádí iterace nad informacemi zahrnutými ve výsledcích při použití dalších funkcí dotazování (například .includeTotalCount()).

Další informace o syntaxi dotazu najdete v dokumentaci k objektu dotazu.

Filtrování dat na serveru

Můžete použít klauzuli where na odkaz na tabulku:

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

Můžete také použít funkci, která filtruje objekt. V takovém případě se právě filtrovanému objektu přiřadí proměnná this. Následující kód je funkčně srovnatelný s předchozím příkladem:

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

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

Procházení dat po stránkách

Použijte metody take() a skip(). Pokud například chcete rozdělit tabulku na záznamy po stovkách řádků:

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() slouží k přidání pole totalCount do objektu výsledků. Pole totalCount obsahuje celkový počet záznamů, které by se vrátily, kdyby nebylo použité stránkování.

Následně můžete pomocí proměnné pages a několika tlačítek uživatelského rozhraní zobrazit seznam stránek. K načtení nových záznamů pro jednotlivé stránky použijte metodu loadPage(). Pro rychlý přístup k již načteným záznamům implementujte ukládání do mezipaměti.

Vrácení seřazených dat

Použijte metody dotazu .orderBy() nebo .orderByDescending():

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

Další informace o objektu dotazu najdete v [Dokumentaci k objektu dotazu].

Vložení dat

Vytvořte objekt JavaScriptu s vhodným datem a asynchronně zavolejte metodu table.insert():

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

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

Po úspěšném vložení se vložená položka vrátí s dalšími poli, která jsou nutná pro operace synchronizace. Aktualizujte tyto informace ve vlastní mezipaměti pro pozdější aktualizace.

Sada Node.js Server SDK ve funkci Azure Mobile Apps podporuje dynamické schéma pro účely vývoje. Dynamické schéma umožňuje přidávat do tabulky sloupce tak, že je zadáte v operaci insert nebo update. Před nasazením aplikace do ostrého provozu doporučujeme dynamické schéma vypnout.

Úprava dat

Podobně jako u metody .insert() byste měli vytvořit objekt aktualizace a pak zavolat metodu .update(). Objekt aktualizace musí obsahovat ID záznamu, který se má aktualizovat – ID získáte při čtení záznamu nebo zavoláním 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);

Odstranění dat

Pokud chcete odstranit záznam, zavolejte metodu .del(). V odkazu na objekt předejte ID:

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

Ověření uživatelů

služba Aplikace Azure podporuje ověřování a autorizaci uživatelů aplikací pomocí různých externích zprostředkovatelů identity: Facebook, Google, účet Microsoft a Twitter. U tabulek můžete nastavit oprávnění k omezení přístupu pro konkrétní operace pouze ověřeným uživatelům. Identitu ověřených uživatelů můžete použít také k implementaci autorizačních pravidel ve skriptech serveru. Další informace najdete v kurzu Začínáme s ověřováním .

Při použití ověřování v aplikaci Apache Cordova musí být k dispozici následující moduly plug-in Cordova:

Poznámka:

Nedávné změny zabezpečení v iOSu a Androidu můžou způsobit nedostupnost ověřování toku serveru. V těchto případech musíte použít tok klienta.

Podporují se dva toky ověřování: tok serveru a tok klienta. Tok serveru poskytuje nejjednodušší možnosti ověřování, protože závisí na webovém ověřovacím rozhraní poskytovatele. Tok klienta umožňuje hlubší integraci s funkcemi specifickými pro zařízení, jako je jednotné přihlašování, protože spoléhá na sady SDK specifické pro konkrétního poskytovatele.

Ověřování pomocí zprostředkovatele (Tok serveru)

Pokud chcete, aby funkce Mobile Apps spravovala proces ověřování ve vaší aplikaci, je třeba aplikaci zaregistrovat u vašeho zprostředkovatele identity. Potom je nutné ve službě Azure App Service nakonfigurovat ID aplikace a tajný klíč, který vám poskytne zprostředkovatel. Další informace najdete v kurzu Přidání ověřování do aplikace.

Jakmile budete zaregistrováni u zprostředkovatele identity, zavolejte metodu .login() s názvem vašeho zprostředkovatele. Pokud se například chcete přihlásit pomocí Facebooku, použijte následující kód:

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

Platné hodnoty pro zprostředkovatele jsou „aad“, „facebook“, „google“, „microsoftaccount“ a „twitter“.

Poznámka:

Kvůli obavám z hlediska zabezpečení nemusí někteří poskytovatelé ověřování pracovat s tokem serveru. V těchto případech musíte použít metodu toku klienta.

V tomto případě služba Azure App Service spravuje tok ověřování OAuth 2.0. Zobrazí přihlašovací stránku vybraného zprostředkovatele a po úspěšném přihlášení pomocí zprostředkovatele identity vygeneruje ověřovací token služby App Service. Funkce login po dokončení vrátí objekt JSON, který vystaví ID uživatele a ověřovací token služby App Service v polích userId a authenticationToken. Tento token se může uložit do mezipaměti a znovu požívat do vypršení platnosti.

Ověřování pomocí zprostředkovatele (tok klienta)

Vaše aplikace také může nezávisle kontaktovat zprostředkovatele identity a následně poskytnout navrácený token službě App Service k ověření. Tento tok klienta umožňuje poskytovat uživatelům jednotné přihlašování nebo načítat další uživatelská data z poskytovatele identity.

Základní příklad sociálního ověřování

Tento příklad používá k ověřování klientskou sadu SDK Facebooku:

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

Tento příklad předpokládá, že token poskytnutý příslušnou sadou SDK zprostředkovatele je uložený v proměnné token. Podrobnosti vyžadované jednotlivými poskytovateli se mírně liší. Přesné znění datové části najdete v dokumentaci k ověřování a autorizaci služby Aplikace Azure.

Získání informací o ověřeném uživateli

Ověřovací informace je možné načíst z koncového /.auth/me bodu pomocí volání HTTP s libovolnou knihovnou HTTP/REST. Ujistěte se, že jste hlavičku X-ZUMO-AUTH nastavili na váš ověřovací token. Ověřovací token je uložen v client.currentUser.mobileServiceAuthenticationToken. Například pokud chcete použít rozhraní Fetch API:

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

Fetch je k dispozici jako balíček npm nebo ke stažení přes prohlížeč na webu CDNJS. Přijatá data jsou ve formátu objektu JSON.

Nakonfigurujte službu Mobile App Service pro adresy URL externího přesměrování.

Několik typů aplikací Apache Cordova používá funkci zpětné smyčky pro zpracování toků uživatelského rozhraní OAuth. Toky uživatelského rozhraní OAuth na místním hostiteli způsobují problémy, protože ověřovací služba ve výchozím nastavení ví, jak službu využívat. Mezi problematické toky uživatelského rozhraní OAuth patří:

  • Emulátor Ripple.
  • Live Reload with Ionic.
  • Místní spuštění mobilního back-endu
  • Spuštění mobilního back-endu v jiné službě Aplikace Azure, než je služba poskytující ověřování.

Podle těchto pokynů přidejte do konfigurace místní nastavení:

  1. Přihlaste se k portálu Azure Portal.

  2. Vyberte Všechny prostředky nebo App Services a klikněte na název mobilní aplikace.

  3. Klikněte na Nástroje.

  4. V nabídce POZOR klikněte na Průzkumníka prostředků a potom klikněte na Přejít. Otevře se nové okno nebo karta.

  5. V levém navigačním panelu rozbalte konfiguraci a uzly ověřování pro váš web.

  6. Klikněte na Edit (Upravit).

  7. Vyhledejte element allowedExternalRedirectUrls. Může být nastavena na hodnotu null nebo pole hodnot. Změňte hodnotu na následující hodnotu:

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

    Nahraďte adresy URL adresami URL vaší služby. Mezi příklady patří http://localhost:3000 (pro ukázkovou službu Node.js) nebo http://localhost:4400 (pro službu Ripple). Tyto adresy URL jsou však příklady – vaše situace, včetně služeb uvedených v příkladech, se může lišit.

  8. Klikněte na tlačítko Číst/Zapisovat v pravém horním rohu obrazovky.

  9. Klikněte na zelené tlačítko PUT .

Nastavení se v tomto okamžiku uloží. Nezavírejte okno prohlížeče, dokud nastavení nedokončí uložení. Přidejte také tyto adresy URL zpětné smyčky do nastavení CORS pro vaši službu App Service:

  1. Přihlaste se k portálu Azure Portal.
  2. Vyberte Všechny prostředky nebo App Services a klikněte na název mobilní aplikace.
  3. Automaticky se otevře okno Nastavení. Pokud ne, klikněte na Všechny Nastavení.
  4. V nabídce rozhraní API klikněte na CORS .
  5. Zadejte adresu URL, kterou chcete přidat do zadaného pole, a stiskněte Enter.
  6. Podle potřeby zadejte další adresy URL.
  7. Kliknutím na Uložit nastavení uložte.

Než se nová nastavení projeví, trvá přibližně 10 až 15 sekund.