Azure Mobile Apps için Apache Cordova eklentisini kullanma

Bu kılavuz, Azure Mobile Apps için en son Apache Cordova Eklentisini kullanarak yaygın senaryolar gerçekleştirmeyi öğretir. Azure Mobile Apps'i kullanmaya yeni başladıysanız, önce arka uç oluşturmak, tablo oluşturmak ve önceden oluşturulmuş bir Apache Cordova projesi indirmek için Azure Mobile Apps Hızlı Başlangıç'ı tamamlayın. Bu kılavuzda istemci tarafı Apache Cordova Eklentisine odaklanacağız.

Desteklenen platformlar

Bu SDK, iOS, Android ve Windows cihazlarında Apache Cordova v6.0.0 ve üzerini destekler. Platform desteği aşağıdaki gibidir:

• Android API 19+.
• iOS sürüm 8.0 ve üzeri.

Kurulum ve önkoşullar

Bu kılavuzda, tablo içeren bir arka uç oluşturduğunuz varsayılır. Örneklerde hızlı başlangıçlardan TodoItem itibaren tablo kullanılır. Azure Mobile Apps eklentisini projenize eklemek için aşağıdaki komutu kullanın:

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

İlk Apache Cordova uygulamanızı oluşturma hakkında daha fazla bilgi için belgelerine bakın.

Ionic v2 uygulaması ayarlama

Bir Ionic v2 projesini düzgün yapılandırmak için önce temel bir uygulama oluşturun ve Cordova eklentisini ekleyin:

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

İstemci nesnesini oluşturmak için app.component.ts aşağıdaki satırları ekleyin:

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

Artık projeyi tarayıcıda derleyebilir ve çalıştırabilirsiniz:

ionic platform add browser
ionic run browser

Azure Mobile Apps Cordova eklentisi hem Ionic v1 hem de v2 uygulamalarını destekler. Yalnızca Ionic v2 uygulamaları nesne için WindowsAzure ek bildirim gerektirir.

İstemci bağlantısı oluşturma

Bir WindowsAzure.MobileServiceClient nesnesi oluşturarak istemci bağlantısı oluşturun. appUrl ifadesini Mobile Uygulamanızın URL’si ile değiştirin.

var client = WindowsAzure.MobileServiceClient(appUrl);

Tablolarla çalışma

Verilere erişmek veya verileri güncelleştirmek için arka uç tablosuna başvuru oluşturun. tableName ifadesini tablonuzun adıyla değiştirin

var table = client.getTable(tableName);

Bir tablo başvurusu oluşturduktan sonra tablonuzla başka işlemler yapabilirsiniz:

• Tablo sorgulama
  • Verileri filtreleme
  • Verileri sayfalama
  • Verileri sıralama
• Veri ekleme
• Verileri değiştirme
• Veri silme

Tablo başvurusunu sorgulama

Bir tablo başvurusu oluşturduktan sonra sunucudaki verileri sorgulamak için kullanabilirsiniz. Sorgular "LINQ benzeri" bir dilde yapılır. Tablodan tüm verileri döndürmek için aşağıdaki kodu kullanın:

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

Sonuçlarla birlikte başarı işlevi çağrılır. Başarı işlevinde for (var i in results) öğesini kullanmayın, aksi takdirde diğer sorgu işlevleri (.includeTotalCount() gibi) kullanıldığında sonuçlara eklenen bilgilerin üzerine yinelenir.

Sorgu söz dizimi hakkında daha fazla bilgi için Sorgu nesnesi belgelerine bakın.

Sunucu üzerindeki verileri filtreleme

Tablo başvurusunda bir where yan tümcesi kullanabilirsiniz:

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

Ayrıca, nesneyi filtreleyen bir işlev de kullanabilirsiniz. Bu durumda, this değişkeni filtre uygulanan geçerli nesneye atanır. Aşağıdaki kod önceki örnek ile işlevsel olarak eşdeğerdir:

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

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

Verileri sayfalama

take() ve skip() yöntemlerini kullanın. Örneğin, tabloyu 100 satırlı kayıtlara bölmek istiyorsanız:

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

Sonuç nesnesine bir totalCount alanı eklemek için .includeTotalCount() yöntemi kullanılır. Sayfalama kullanılmazsa döndürülecek toplam kayıt sayısı TotalCount alanına doldurulur.

Bir sayfa listesi sağlamak için pages değişkenini ve bazı kullanıcı arabirimi düğmelerini kullanabilirsiniz; her sayfanın yeni kayıtlarını yüklemek için loadPage() seçeneğini kullanın. Daha önce yüklenmiş kayıtlara hızlı erişim için önbelleğe almayı uygulayın.

Sıralanmış verileri döndürme

.orderBy() veya .orderByDescending() sorgu yöntemlerini kullanın:

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

Query nesnesi hakkında daha fazla bilgi için [Query nesnesi belgelerine] bakın.

Veri ekleme

Uygun tarihle bir JavaScript nesnesi oluşturun ve table.insert() öğesini zaman uyumsuz olarak çağırın:

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

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

Ekleme başarılı olduğunda, eklenen öğe eşitleme işlemleri için gereken ek alanlarla birlikte döndürülür. Sonraki güncelleştirmeler için önbelleğinizi bu bilgilerle güncelleştirin.

Azure Mobile Apps Node.js Sunucu SDK’sı, geliştirme için dinamik şemayı destekler. Dinamik Şema, bir insert veya update işleminde sütun belirterek tabloya sütun eklemenize olanak tanır. Uygulamanızı üretime taşımadan önce dinamik şemanın kapatılması önerilir.

Verileri değiştirme

.insert() yöntemine benzer şekilde, bir Update nesnesi oluşturup .update() öğesini çağırmanız gerekir. Update nesnesi, güncelleştirilecek kaydın kimliğini içermelidir; bu kimlik, kayıt okunurken veya .insert() çağrılırken elde edilir.

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

Veri silme

Bir kaydı silmek için .del() yöntemini çağırın. Kimliği bir nesne başvurusuna geçirin:

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

Kullanıcıların kimliğini doğrulama

Azure Uygulaması Hizmeti çeşitli dış kimlik sağlayıcılarını kullanarak uygulama kullanıcılarının kimliğini doğrulamayı ve yetkilendirmeyi destekler: Facebook, Google, Microsoft Hesabı ve Twitter. Belirli işlemlere erişimi yalnızca kimliği doğrulanmış kullanıcılarla kısıtlamak için tablolarda izinleri ayarlayabilirsiniz. Sunucu betiklerinde yetkilendirme kuralları uygulamak için kimliği doğrulanmış kullanıcıların kimliğini de kullanabilirsiniz. Daha fazla bilgi için kimlik doğrulamasını kullanmaya başlama öğreticisine bakın.

Apache Cordova uygulamasında kimlik doğrulaması kullanılırken aşağıdaki Cordova eklentilerinin kullanılabilir olması gerekir:

• cordova-plugin-device
• cordova-plugin-inappbrowser

İki kimlik doğrulama akışı desteklenir: sunucu akışı ve istemci akışı. Sunucu akışı, sağlayıcının web kimlik doğrulaması arabirimini temel alan en basit kimlik doğrulama deneyimini sağlar. İstemci akışı, sağlayıcıya özgü cihaza özgü SDK'lara bağlı olduğundan çoklu oturum açma gibi cihaza özgü özelliklerle daha ayrıntılı tümleştirme sağlar.

Sağlayıcıyla kimlik doğrulaması (Sunucu Akışı)

Mobile Apps hizmetinin uygulamanızdaki kimlik doğrulama işlemini yönetmesi için kimlik sağlayıcınıza uygulamanızı kaydetmeniz gerekir. Ardından, Azure App Service'te sağlayıcınız tarafından verilen uygulama kimliği ile parolasını yapılandırmanız gerekir. Daha fazla bilgi için Uygulamanıza kimlik doğrulaması ekleme öğreticisine bakın.

Kimlik sağlayıcınızı kaydettikten sonra sağlayıcınızın adıyla .login() yöntemini çağırın. Örneğin, Facebook ile oturum açmak için aşağıdaki kodu kullanın:

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

'aad', 'facebook', 'google', 'microsoftaccount' ve 'twitter', sağlayıcı için geçerli değerlerdir.

Bu durumda, OAuth 2.0 kimlik doğrulama akışını Azure App Service yönetir. Seçili sağlayıcının oturum açma sayfasını görüntüler ve kimlik sağlayıcısıyla başarılı bir şekilde oturum açıldıktan sonra bir App Service kimlik doğrulama belirteci oluşturur. Oturum açma işlevi tamamlandığında, hem kullanıcı kimliğini hem de App Service kimlik doğrulama belirtecini sırasıyla userId ve authenticationToken alanlarında ortaya çıkaran bir JSON nesnesi döndürür. Bu belirteç önbelleğe alınabilir süresi sona erene kadar yeniden kullanılabilir.

Sağlayıcıyla kimlik doğrulama (İstemci Akışı)

Uygulamanız kimlik sağlayıcısı ile bağımsız olarak da iletişim kurabilir ve sonra döndürülen belirteci kimlik doğrulaması için App Service’e döndürebilir. Bu istemci akışı, kullanıcılar için tek bir oturum açma deneyimi sağlamanıza veya kimlik sağlayıcısından ek kullanıcı verileri almanıza olanak tanır.

Sosyal Kimlik Doğrulaması temel örneği

Bu örnekte kimlik doğrulaması için Facebook istemci SDK’sı kullanılır:

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

Bu örnek, ilgili sağlayıcı SDK’sı tarafından sağlanan belirtecin belirteç değişkenine depolandığını varsayar. Her sağlayıcının gerektirdiği ayrıntılar biraz farklıdır. Yükün tam biçimini belirlemek için Azure Uygulaması Hizmet Kimlik Doğrulaması ve Yetkilendirme belgelerine başvurun.

Kimliği doğrulanmış kullanıcı hakkında bilgi alma

Kimlik doğrulama bilgileri, herhangi bir HTTP/REST kitaplığı ile bir HTTP çağrısı kullanılarak uç noktadan alınabilir /.auth/me . X-ZUMO-AUTH üst bilgisini kimlik doğrulama belirtecinize ayarlandığınızdan emin olun. Kimlik doğrulama belirteci client.currentUser.mobileServiceAuthenticationToken içine depolanır. Örneğin, fetch API’sini kullanmak için:

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, bir npm paketi olarak mevcuttur veya CDNJS’den tarayıcı ile indirilebilir. Veriler bir JSON nesnesi olarak alınır.

Mobile App Service'inizi dış yeniden yönlendirme URL'leri için yapılandırın.

Birkaç tür Apache Cordova uygulaması, OAuth UI akışlarını işlemek için bir geri döngü özelliği kullanır. Localhost'ta OAuth kullanıcı arabirimi akışları sorunlara neden olur çünkü kimlik doğrulama hizmeti yalnızca hizmetinizi varsayılan olarak nasıl kullanacağınızı bilir. Sorunlu OAuth UI akışlarına örnek olarak şunlar verilebilir:

• Ripple öykünücüsü.
• Ionic ile Canlı Yeniden Yükleme.
• Mobil arka ucu yerel olarak çalıştırma
• Mobil arka ucu kimlik doğrulaması sağlayandan farklı bir Azure Uygulaması Hizmetinde çalıştırma.

Yapılandırmaya yerel ayarlarınızı eklemek için şu yönergeleri izleyin:

1. Azure portalı’nda oturum açın

2. Tüm kaynaklar veya Uygulama Hizmetleri'ni seçip Mobil Uygulamanızın adına tıklayın.

3. Araçlar'a tıklayın

4. GÖZLEM menüsünde Kaynak gezgini'ne ve ardından Git'e tıklayın. Yeni bir pencere veya sekme açılır.

5. Sol gezinti bölmesinde sitenizin authsettings düğümleri olan yapılandırmayı genişletin.

6. Düzenle'ye tıklayın

7. "allowedExternalRedirectUrls" öğesini arayın. Null veya bir değer dizisi olarak ayarlanabilir. Değeri aşağıdaki değerle değiştirin:

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

   URL'leri hizmetinizin URL'leriyle değiştirin. Örnek olarak http://localhost:3000 (Node.js örnek hizmeti için) veya http://localhost:4400 (Ripple hizmeti için) verilebilir. Ancak, bu URL'ler örnektir; örneklerde belirtilen hizmetler de dahil olmak üzere durumunuz farklı olabilir.

8. Ekranın sağ üst köşesindeki Oku/Yaz düğmesine tıklayın.

9. Yeşil PUT düğmesine tıklayın.

Ayarlar bu noktada kaydedilir. Ayarlar kaydetmeyi bitirene kadar tarayıcı penceresini kapatmayın. Ayrıca bu geri döngü URL'lerini App Service'inizin CORS ayarlarına ekleyin:

1. Azure portalı’nda oturum açın
2. Tüm kaynaklar veya Uygulama Hizmetleri'ni seçip Mobil Uygulamanızın adına tıklayın.
3. Ayarlar dikey penceresi otomatik olarak açılır. Aksi takdirde Tüm Ayarlar'e tıklayın.
4. API menüsünün altında CORS'ye tıklayın.
5. Sağlanan kutuya eklemek istediğiniz URL'yi girin ve Enter tuşuna basın.
6. Gerektiğinde daha fazla URL girin.
7. Ayarları kaydetmek için Kaydet’e tıklayın.

Yeni ayarların etkili olması yaklaşık 10-15 saniye sürer.