Cara menggunakan pustaka klien Apache Cordova untuk Azure Mobile Apps
Gambaran Umum
Panduan ini mengajarkan Anda untuk melakukan skenario umum menggunakan Plugin Apache Cordova terbaru untuk Azure Mobile Apps. Jika Anda baru mengenal Azure Mobile Apps, selesaikan dulu Mulai Cepat Aplikasi Ponsel Azure untuk membuat backend, membuat tabel, dan mengunduh proyek Apache Cordova yang sudah dibuat sebelumnya. Dalam panduan ini, kami berfokus pada Plugin Apache Cordova sisi klien.
Platform yang didukung
SDK ini mendukung Apache Cordova v6.0.0 dan yang lebih baru di perangkat iOS, Android, dan Windows. Dukungan platform adalah sebagai berikut:
- Android API 19-24 (KitKat melalui Nougat).
- iOS versi 8.0 dan versi lebih baru.
- Windows Phone 8.1.
- Platform Windows Universal.
Penyiapan dan prasyarat
Panduan ini mengasumsikan bahwa Anda telah membuat backend dengan tabel. Panduan ini mengasumsikan bahwa tabel memiliki skema yang sama dengan tabel dalam tutorial tersebut. Panduan ini juga mengasumsikan bahwa Anda telah menambahkan Plugin Apache Cordova ke kode Anda. Jika Anda belum melakukannya, Anda dapat menambahkan plugin Apache Cordova ke proyek Anda di baris perintah:
cordova plugin add cordova-plugin-ms-azure-mobile-apps
Untuk informasi selengkapnya tentang membuat Aplikasi Apache Cordova pertama Anda, lihat dokumentasinya.
Menyiapkan aplikasi Ionic v2
Untuk mengonfigurasi proyek Ionic v2 dengan benar, pertama-tama buat aplikasi dasar dan tambahkan plugin Cordova:
ionic start projectName --v2
cd projectName
ionic plugin add cordova-plugin-ms-azure-mobile-apps
Tambahkan baris berikut ke app.component.ts untuk membuat objek klien:
declare var WindowsAzure: any;
var client = new WindowsAzure.MobileServiceClient("https://yoursite.azurewebsites.net");
Anda sekarang dapat membuat dan menjalankan proyek di browser:
ionic platform add browser
ionic run browser
Plugin Azure Mobile Apps Cordova mendukung aplikasi Ionic v1 dan v2. Hanya aplikasi Ionic v2 yang memerlukan deklarasi tambahan untuk WindowsAzure objek.
Membuat koneksi klien
Buat koneksi klien dengan membuat objek WindowsAzure.MobileServiceClient. Ganti appUrl dengan URL ke Aplikasi Seluler Anda.
var client = WindowsAzure.MobileServiceClient(appUrl);
Bekerja dengan tabel
Untuk mengakses atau memperbarui data, buat referensi ke tabel backend. Ganti tableName dengan nama tabel Anda
var table = client.getTable(tableName);
Setelah Anda memiliki referensi tabel, Anda dapat bekerja lebih lanjut dengan tabel Anda:
Cara: Kueri referensi tabel
Setelah memiliki referensi tabel, Anda dapat menggunakannya untuk meminta data di server. Kueri dibuat dalam bahasa "seperti LINQ". Untuk mengembalikan semua data dari tabel, gunakan kode berikut:
/**
* 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);
Fungsi sukses disebut dengan hasilnya. Jangan gunakan for (var i in results) dalam fungsi sukses karena akan berulang atas informasi yang termasuk dalam hasil ketika fungsi kueri lain (seperti .includeTotalCount()) digunakan.
Untuk informasi selengkapnya tentang sintaks Kueri, lihat [Dokumentasi objek kueri].
Memfilter data di server
Anda dapat menggunakan klausul where pada referensi tabel:
table
.where({ userId: user.userId, complete: false })
.read()
.then(success, failure);
Anda juga dapat menggunakan fungsi yang memfilter objek. Dalam hal ini, variabel this ditetapkan ke objek saat ini yang sedang difilter. Kode berikut secara fungsional setara dengan contoh sebelumnya:
function filterByUserId(currentUserId) {
return this.userId === currentUserId && this.complete === false;
}
table
.where(filterByUserId, user.userId)
.read()
.then(success, failure);
Paging melalui data
Gunakan metode take() dan skip(). Misalnya, jika Anda ingin membagi tabel menjadi catatan 100 baris:
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
}
}
}
Metode .includeTotalCount() digunakan untuk menambahkan bidang totalCount ke objek hasil. Bidang totalCount diisi dengan jumlah total catatan yang akan dikembalikan jika tidak ada paging yang digunakan.
Kemudian, Anda dapat menggunakan variabel halaman dan beberapa tombol UI untuk menyediakan daftar halaman; gunakan loadPage() untuk memuat catatan baru untuk setiap halaman. Terapkan penembolokan untuk mempercepat akses ke catatan yang telah dimuat.
Cara: Mengembalikan data yang diurutkan
Gunakan metode kueri .orderBy() atau .orderByDescending():
table
.orderBy('name')
.read()
.then(success, failure);
Untuk informasi selengkapnya tentang objek Kueri, lihat [Mengkueri dokumentasi objek].
Cara: Menyisipkan data
Buat objek JavaScript dengan tanggal yang sesuai dan panggil table.insert() secara asinkron:
var newItem = {
name: 'My Name',
signupDate: new Date()
};
table
.insert(newItem)
.done(function (insertedItem) {
var id = insertedItem.id;
}, failure);
Pada penyisipan yang berhasil, item yang dimasukkan dikembalikan dengan bidang tambahan yang diperlukan untuk operasi sinkronisasi. Perbarui cache Anda sendiri dengan informasi ini untuk pembaruan nanti.
Azure Mobile Apps Node.js Server SDK mendukung skema dinamis untuk tujuan pengembangan. Skema Dinamis memungkinkan Anda menambahkan kolom ke tabel dengan menentukannya dalam operasi sisipkan atau perbarui. Sebaiknya matikan skema dinamis sebelum memindahkan aplikasi ke produksi.
Cara: Memodifikasi data
Mirip dengan metode .insert(), Anda harus membuat objek Pembaruan dan kemudian memanggil .update(). Objek pembaruan harus berisi ID catatan yang akan diperbarui - ID diperoleh saat membaca catatan atau saat menelepon .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);
Cara: Hapus data
Untuk menghapus rekaman, hubungi metode .del(). Lewati ID dalam referensi objek:
table
.del({ id: '7163bc7a-70b2-4dde-98e9-8818969611bd' })
.done(function () {
// Record is now deleted - update your cache
}, failure);
Cara: Mengautentikasi pengguna
Azure App Service mendukung pengautentikasian dan otorisasi pengguna aplikasi menggunakan berbagai penyedia identitas eksternal: Facebook, Google, Akun Microsoft, dan Twitter. Anda dapat mengatur izin pada tabel untuk membatasi akses untuk operasi tertentu hanya untuk pengguna yang diautentikasi. Anda juga dapat menggunakan identitas pengguna yang diautentikasi untuk menerapkan aturan otorisasi dalam skrip server. Untuk informasi selengkapnya, lihat tutorial Memulai autentikasi.
Saat menggunakan autentikasi di aplikasi Apache Cordova, plugin Cordova berikut harus tersedia:
Dua alur autentikasi didukung: alur server dan alur klien. Aliran server memberikan pengalaman autentikasi yang paling sederhana, karena bergantung pada antarmuka autentikasi web penyedia. Alur klien memungkinkan integrasi yang lebih dalam dengan kemampuan khusus perangkat seperti akses menyeluruh karena bergantung pada SDK khusus perangkat khusus penyedia.
Cara: Autentikasi dengan penyedia (Server Flow)
Agar Aplikasi Ponsel mengelola proses autentikasi di aplikasi, Anda harus mendaftarkan aplikasi ke penyedia identitas Anda. Kemudian di Azure App Service, Anda perlu mengonfigurasi ID aplikasi dan rahasia yang disediakan oleh penyedia Anda. Untuk informasi selengkapnya, lihat tutorial Menambahkan autentikasi ke aplikasi Anda.
Setelah Anda mendaftarkan penyedia identitas Anda, panggil metode .login() dengan nama penyedia Anda. Misalnya, untuk masuk dengan Facebook gunakan kode berikut:
client.login("facebook").done(function (results) {
alert("You are now signed in as: " + results.userId);
}, function (err) {
alert("Error: " + err);
});
Nilai yang valid untuk penyedia adalah 'aad', 'facebook', 'google', 'microsoftaccount', dan 'twitter'.
Catatan
Autentikasi Google saat ini tidak berfungsi melalui server Flow. Untuk mengautentikasi dengan Google, Anda harus menggunakan metode alur klien.
Dalam hal ini, Azure App Service mengelola alur autentikasi OAuth 2.0. Ini menampilkan halaman masuk dari penyedia yang dipilih dan menghasilkan token autentikasi App Service setelah berhasil masuk dengan penyedia identitas. Fungsi masuk, setelah selesai, mengembalikan objek JSON yang mengekspos ID pengguna dan token autentikasi App Service di bidang userId dan authenticationToken, masing-masing. Token ini dapat di-cache dan digunakan kembali sampai kedaluwarsa.
Cara: Autentikasi dengan penyedia (Client Flow)
Aplikasi Anda juga dapat secara independen menghubungi penyedia identitas dan kemudian memberikan token yang dikembalikan ke App Service Anda untuk autentikasi. Alur klien ini memungkinkan Anda untuk memberikan pengalaman masuk tunggal bagi pengguna atau untuk mengambil data pengguna tambahan dari penyedia identitas.
Contoh dasar Autentikasi Sosial
Contoh ini menggunakan SDK klien Facebook untuk autentikasi:
client.login(
"facebook",
{"access_token": token})
.done(function (results) {
alert("You are now signed in as: " + results.userId);
}, function (err) {
alert("Error: " + err);
});
Contoh ini mengasumsikan bahwa token yang disediakan oleh SDK penyedia masing-masing disimpan dalam variabel token.
Cara: Mendapatkan informasi tentang pengguna yang diautentikasi
Informasi autentikasi dapat diambil dari /.auth/me titik akhir menggunakan panggilan HTTP dengan pustaka AJAX apa pun. Pastikan Anda mengatur header X-ZUMO-AUTH ke token autentikasi Anda. Token autentikasi disimpan dalam client.currentUser.mobileServiceAuthenticationToken. Misalnya, untuk menggunakan API ambil:
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 tersedia sebagai paket npm atau untuk unduhan browser dari CDNJS. Anda juga dapat menggunakan jQuery atau API AJAX lain untuk mengambil informasi. Data diterima sebagai objek JSON.
Cara: Konfigurasikan App Service Seluler Anda untuk URL pengalihan eksternal.
Beberapa jenis aplikasi Apache Cordova menggunakan kemampuan loopback untuk menangani alur UI OAuth. Alur OAuth UI di localhost menyebabkan masalah karena layanan autentikasi hanya tahu cara memanfaatkan layanan Anda secara default. Contoh alur UI OAuth yang bermasalah meliputi:
- Emulator Ripple.
- Live Reload dengan Ionic.
- Menjalankan backend seluler secara lokal
- Menjalankan backend seluler di Azure App Service yang berbeda dari yang menyediakan autentikasi.
Ikuti petunjuk ini untuk menambahkan pengaturan lokal Anda ke konfigurasi:
Masuk ke portal Microsoft Azure
Pilih Semua sumber daya atau App Service lalu klik nama Aplikasi Ponsel Anda.
Klik Alat
Klik Penjelajah sumber daya di menu AMATI, lalu klik Buka. Jendela atau tab baru terbuka.
Perluas node konfigurasi dan authsettings untuk situs Anda di navigasi kiri.
Klik Edit
Cari elemen "allowedExternalRedirectUrls". Ini dapat diatur ke null atau array nilai. Ubah nilai ke nilai berikut:
"allowedExternalRedirectUrls": [ "https://localhost:3000", "https://localhost:3000" ],Ganti URL dengan URL layanan Anda. Contohnya termasuk
https://localhost:3000(untuk layanan sampel Node.js), atauhttps://localhost:4400(untuk layanan Ripple). Namun, URL ini adalah contoh - situasi Anda, termasuk untuk layanan yang disebutkan dalam contoh, mungkin berbeda.Klik tombol Baca/Tulis di pojok kanan atas layar.
Klik tombol PUT hijau.
Pengaturan disimpan pada saat ini. Jangan tutup jendela browser sampai pengaturan selesai disimpan. Tambahkan juga URL loopback ini ke pengaturan CORS untuk App Service Anda:
- Masuk ke portal Microsoft Azure
- Pilih Semua sumber daya atau App Service lalu klik nama Aplikasi Ponsel Anda.
- Bilah Pengaturan terbuka secara otomatis. Jika tidak, klik Semua Pengaturan.
- Klik CORS di bawah menu API.
- Masukkan URL yang ingin Anda tambahkan dalam kotak yang disediakan dan tekan Enter.
- Masukkan URL tambahan sesuai kebutuhan.
- Klik Simpan untuk menyimpan pengaturan.
Dibutuhkan sekitar 10-15 detik agar pengaturan baru berlaku.
Cara: Daftar untuk pemberitahuan push
Instal phonegap-plugin-push untuk menangani notifikasi push. Plugin ini dapat dengan mudah ditambahkan menggunakan cordova plugin add perintah pada baris perintah, atau melalui penginstal plugin Git dalam Visual Studio. Kode berikut di aplikasi Apache Cordova Anda mendaftarkan perangkat Anda untuk pemberitahuan 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
});
Gunakan SDK Hub Notifikasi untuk mengirim pemberitahuan push dari server. Jangan pernah mengirim pemberitahuan push langsung dari klien. Melakukan hal itu dapat digunakan untuk memicu serangan penolakan layanan terhadap Notification Hubs atau PNS. PNS dapat melarang lalu lintas Anda sebagai akibat dari serangan tersebut.
Informasi selengkapnya
Anda dapat menemukan detail API terperinci di dokumentasi API kami.