Jak používat klientskou Apache Cordova pro Azure Mobile Apps
Přehled
Tato příručka vás naučí provádět běžné scénáře s využitím nejnovějšího modulu plug-in Apache Cordova pro Azure Mobile Apps. Pokud se službou Azure Mobile Apps novinka, nejprve dokončete azure Mobile Apps rychlé zprovoznění a vytvořte back-end, vytvořte tabulku a stáhněte předem Apache Cordova projekt. V této příručce se zaměříme na modul plug-in Apache Cordova straně klienta.
Podporované platformy
Tato sada SDK podporuje Apache Cordova v6.0.0 a novějších na zařízeních s iOSem, Androidem a Windows počítači. Podpora platformy je následující:
- Android API 19–24 (KitKat přes Nougat).
- iOS verze 8.0 a novější.
- Windows Phone 8.1.
- Univerzální platforma Windows.
Nastavení a požadavky
V této příručce se předpokládá, že jste vytvořili back-end s tabulkou. V této příručce se předpokládá, že tabulka má stejné schéma jako tabulky v těchto kurzech. Tato příručka také předpokládá, že jste do kódu Apache Cordova plug-in modulu plug-in. Pokud jste to ještě neudělali, můžete přidat modul plug-Apache Cordova plug-in do projektu na příkazovém řádku:
cordova plugin add cordova-plugin-ms-azure-mobile-apps
Další informace o vytvoření první aplikace Apache Cordova najdete v jejich 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 do pro app.component.ts vytvoření objektu klienta:
declare var WindowsAzure: any;
var client = new WindowsAzure.MobileServiceClient("https://yoursite.azurewebsites.net");
Teď můžete projekt sestavit a spustit v prohlížeči:
ionic platform add browser
ionic run browser
Modul plug-in Azure Mobile Apps Cordova podporuje aplikace Ionic v1 i v2. Další deklaraci objektu vyžadují pouze aplikace WindowsAzure Ionic v2.
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:
Postup: Dotazování odkazu 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);
Stránkování dat
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.
Postup: 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].
Postup: Vkládání 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 vrátí vložená položka i s dalšími poli požadovanými 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.
Postup: Ú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);
Postup: 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);
Postupy: Ověřování uživatelů
Azure App Service podporuje ověřování a ověřování uživatelů aplikací pomocí různých externích zprostředkovatelů identity: Facebook, Google, účet Microsoft a Twitter. Můžete nastavit oprávnění k tabulkám a omezit tak přístup pro konkrétní operace jenom na ověřené uživatele. 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 ověřování.
Při použití ověřování v Apache Cordova aplikace musí být k dispozici následující moduly plug-in Cordova:
Podporují se dva toky ověřování: tok serveru a tok klienta. Tok serveru poskytuje nejjednodušší prostředí ověřování, protože spoléhá na webové ověřovací rozhraní poskytovatele. Tok klienta umožňuje hlubší integraci s funkcemi specifickými pro zařízení, jako je jednotné přihlašování, protože závisí na zprostředkovatelích specifických sdk pro zařízení.
Postup: Ověřování pomocí zprostředkovatele (tok na straně 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 přes Facebook, 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
Ověřování Google přes tok na straně serveru aktuálně nefunguje. K ověřování Google je třeba použít metodu toku na straně 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 vygeneruje ověřovací token App Service po úspěšném přihlášení pomocí zprostředkovatele identity. 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.
Postup: Ověřování pomocí zprostředkovatele (tok na straně 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 na straně klienta vám umožní poskytnout uživatelům jednotné přihlašování nebo od zprostředkovatele identity načíst další uživatelská data.
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.
Postup: Získání informací o ověřeném uživateli
Ověřovací informace můžete načíst z koncového bodu /.auth/me voláním HTTP pomocí libovolné knihovny AJAX. 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. K načtení informací můžete použít také jQuery nebo jiné rozhraní AJAX API. Přijatá data jsou ve formátu objektu JSON.
Postupy: Konfigurace adresy URL App Service pro mobilní zařízení.
Několik typů Apache Cordova aplikací používá funkci zpětné smyčky ke 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 ví, jak ve výchozím nastavení využívat vaši službu. Příklady problematických toků uživatelského rozhraní OAuth:
- Emulátor Ripple.
- Live Reload with Ionic (Znovu živé načtení pomocí Ionic).
- Místní spuštění mobilního back-endu
- Spuštění mobilního back-endu v jiném Azure App Service než ten, který poskytuje ověřování.
Podle těchto pokynů přidejte místní nastavení do konfigurace:
Přihlaste se k portálu Azure Portal.
Vyberte Všechny prostředkynebo App Services klikněte na název vaší mobilní aplikace.
Klikněte na Nástroje.
V nabídce SLEDOVAT klikněte na Průzkumník prostředků a pak klikněte na Přejít. Otevře se nové okno nebo karta.
V levémnavigačním panelu rozbalte uzly konfigurace a nastavení ověřování pro váš web.
Klikněte na Upravit.
Vyhledejte element allowedExternalRedirectUrls. Může být nastaven na hodnotu null nebo pole hodnot. Změňte hodnotu na následující hodnotu:
"allowedExternalRedirectUrls": [ "https://localhost:3000", "https://localhost:3000" ],Adresy URL nahraďte adresami URL vaší služby. Mezi příklady
https://localhost:3000patří (Node.js ukázkové služby)https://localhost:4400nebo (pro službu Ripple). Tyto adresy URL jsou ale příklady – vaše situace, včetně služeb uvedených v příkladech, se může lišit.Klikněte na tlačítko Čtení a zápis v pravém horním rohu obrazovky.
Klikněte na zelené tlačítko PUT .
Nastavení se uloží v tomto okamžiku. Nezadáte okno prohlížeče, dokud se nedokončí ukládání nastavení. Do nastavení CORS pro vaši aplikaci přidejte také tyto adresy URL zpětné App Service:
- Přihlaste se k portálu Azure Portal.
- Vyberte Všechny prostředkynebo App Services klikněte na název vaší mobilní aplikace.
- Okno Nastavení se automaticky otevře. Pokud ne, klikněte na Všechny Nastavení.
- V nabídce rozhraní API klikněte na CORS.
- Zadejte adresu URL, kterou chcete přidat do poskytnutého pole, a stiskněte Enter.
- Podle potřeby zadejte další adresy URL.
- Kliknutím na Uložit nastavení uložte.
Trvá přibližně 10 až 15 sekund, než se nové nastavení projeví.
Postupy: Registrace nabízených oznámení
Nainstalujte phonegap-plugin-push pro zpracování nabízených oznámení. Tento modul plug-in můžete snadno cordova plugin add přidat pomocí příkazu na příkazovém řádku nebo prostřednictvím instalačního programu modulu plug-in Git v rámci Visual Studio. Následující kód ve vaší aplikaci Apache Cordova zaregistruje vaše zařízení pro nabízená oznámení:
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
});
Pomocí sady Notification Hubs SDK můžete odesílat nabízená oznámení ze serveru. Nikdy neodesílejte nabízená oznámení přímo od klientů. To lze použít k aktivaci útoku dosaž í odepření služeb proti Notification Hubs nebo systému PNS. V důsledku takových útoků může PNS váš provoz zakázat.
Další informace
Podrobné podrobnosti o rozhraní API najdete v naší dokumentaci k rozhraní API.