Bu belgede, Google Veri API'si ("GData") sorguları göndermek ve döndürülen yanıtları yorumlamak için .NET istemci kitaplığının nasıl kullanılacağı açıklanmaktadır.
Google, GData özellikli hizmetlerle etkileşim kurmak için çeşitli programlama dillerinde bir dizi istemci kitaplığı sağlar. Bu kitaplıkları kullanarak GData istekleri oluşturabilir, bunları bir hizmete gönderebilir ve yanıt alabilirsiniz.
Bu belgede, istemci kitaplığının C# sürümünün yaygın kullanımına ilişkin bir dizi örnek ve ardından GData istemcileri yazma hakkında diğer bilgiler yer almaktadır. Bu belgenin sonunda, NDoc biçiminde C# istemci kitaplığına ait referans belgelerinin bağlantısı yer almaktadır.
Bu istemci kitaplığını kullanmak için .NET 1.1 çalışma zamanına ihtiyacınız vardır ve tüm yamaları güncel tutmanız gerekir.
.NET istemci kitaplığını indirin.
Bu kılavuzdaki örneklerde Google Takvim API'si ele alınmaktadır ancak bu kılavuz, Takvim API'sinin kullanımıyla ilgili doğru veya güncel bir kılavuz değildir. .NET istemci kitaplığını belirli bir hizmetin Veri API'siyle kullanma hakkında bilgi edinmek için hizmete özel dokümanlara bakın. Örneğin, Takvim ile çalışıyorsanız Calendar Data API Geliştirici Kılavuzu'nu okuyun.
İçindekiler
Kitle
Bu belge, GData hizmetleriyle etkileşim kurabilen istemci uygulamaları yazmak isteyen C# programcıları için hazırlanmıştır.
Bu belgede, Google Veri API'leri protokolünün temel kavramlarını bildiğiniz varsayılmaktadır. Ayrıca C# ile programlamayı bildiğiniz de varsayılır.
Veri modeline genel bakış
C# istemci kitaplığı, Google Veri API'leri tarafından kullanılan öğelere ve veri türlerine karşılık gelen bir dizi sınıf sağlar. Örneğin, <atom:feed> öğesine karşılık gelen bir Feed sınıfı vardır. Bu sınıf, giriş oluşturma, çeşitli alt öğelerin değerlerini alma ve ayarlama gibi yöntemlere sahiptir. <atom:entry> öğesine karşılık gelen bir Entry sınıfı da vardır. Google Veri API'lerinde tanımlanan her öğenin kendi sınıfı yoktur. Ayrıntılar için referans belgelerine bakın.
Kitaplık, Atom içeriğini otomatik olarak ayrıştırabilir ve Atom öğelerinin değerlerini uygun nesnelere yerleştirebilir. Örneğin, getFeed yöntemi bir feed alır, ayrıştırır ve sonuç değerleriyle bir Feed nesnesi döndürür.
Bir feed'i veya girişi bir hizmete göndermek için Feed veya Entry nesnesi oluşturur, ardından nesneyi otomatik olarak XML'ye çevirmek ve göndermek için bir kitaplık yöntemi (ör. insert yöntemi) çağırırsınız.
Tercih ederseniz XML'yi kendiniz ayrıştırabilir ve/veya oluşturabilirsiniz. Bunu yapmanın en kolay yolu uygun bir üçüncü taraf kitaplığı kullanmaktır.
Google Data API'nin XML söz dizimi genişletilebilir olduğu gibi, ilgili nesne modeli de genişletilebilir. Örneğin, istemci kitaplığı Google Veri ad alanında tanımlanan öğelere karşılık gelen sınıflar sağlar.
Eğitim ve örnekler
Aşağıdaki örneklerde, C# istemci kitaplığı kullanılarak çeşitli GData isteklerinin nasıl gönderileceği gösterilmektedir.
Bu örnekler, daha somut hale getirmek için belirli bir hizmetle (Google Takvim) nasıl etkileşimde bulunulacağını gösterir. Bu örnekleri diğer hizmetlerde kullanabilmeniz için Takvim'in diğer Google hizmetlerinden farklı olduğu yerleri vurgulayacağız. Takvim hakkında daha fazla bilgi için Google Calendar Data API belgelerine bakın.
İstemcinizi oluşturma ve çalıştırma
Bu belgedeki örnekleri derlemek için aşağıdaki using ifadesini kullanmanız gerekir:
using Google.GData.Client;
Feed isteğinde bulunma
Google Calendar Data API dokümanında açıklandığı gibi, Calendar'a aşağıdaki HTTP isteğini göndererek bir Calendar feed'i isteyebilirsiniz:
GET http://www.google.com/calendar/feeds/userID/private/full
Elbette userID yerine kullanıcının e-posta adresini girmeniz gerekir. Ayrıntılar için Takvim dokümanına bakın. Bunun yerine, Takvim ile etkileşim kurmak için özel varsayılan URL'yi (Takvim dokümanında açıklandığı gibi) kullanabilirsiniz. Ancak bu dokümanda, kullanıcı kimliğini içeren özel tam özet akışı URL'si kullanılacaktır.
Ayrıca uygun kimlik doğrulama bilgilerini de sağlamanız gerekir. Burada kullandığımız kimlik doğrulama sisteminin ("Yüklü Uygulamalar İçin Google Kimlik Doğrulaması" olarak bilinir) yalnızca masaüstü istemcileri gibi yüklü istemci uygulamalarında kullanıma uygun olduğunu, web uygulamalarında kullanıma uygun olmadığını unutmayın. Kimlik doğrulama hakkında daha fazla bilgi için Google Hesabı Kimlik Doğrulaması belgesine bakın.
E-posta adresi "jo@gmail.com" ve şifresi "mypassword" olan bir kullanıcı için C# istemci kitaplığını kullanarak Takvim feed'i istemek üzere aşağıdaki kodu kullanın:
// Create a query and service object:
FeedQuery query = new FeedQuery();
Service service = new Service("cl", "exampleCo-exampleApp-1"));
// Set your credentials:
service.setUserCredentials("jo@gmail.com", "mypassword");
// Create the query object:
query.Uri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");
// Tell the service to query:
AtomFeed calFeed = service.Query(query);Service sınıfı, bir GData hizmetine istemci bağlantısını (kimlik doğrulama ile) temsil eder. İstemci kitaplığını kullanarak bir hizmete sorgu göndermeyle ilgili genel prosedür aşağıdaki adımlardan oluşur:
- Uygun URL'yi edinin veya oluşturun.
- Bir hizmete veri gönderiyorsanız (örneğin, yeni bir giriş ekliyorsanız) ham verileri istemci kitaplığı sınıflarını kullanarak nesnelere dönüştürün. (Bu adım, bu örnekte yaptığımız gibi yalnızca feed isteğinde bulunuyorsanız geçerli değildir.)
- Hizmet adını (ör. Takvim için
"cl") ve uygulamanızın adını (companyName-applicationName-versionIDbiçiminde) ayarlayarak yeni birServiceörneği oluşturun. - Uygun kimlik bilgilerini ayarlayın.
- İsteği göndermek ve sonuçları almak için bir yöntemi çağırın.
service.setUserCredentials yöntemi, service.Credentials özelliğini standart bir .NET NetworkCredentials nesnesiyle ayarlar.
Kimlik bilgileri, istemcinizin sorguyu gönderdiği kullanıcının kimliği ve şifresi olarak ayarlanır. Bu belgedeki örneklerde "Yüklü Uygulamalar İçin Kimlik Doğrulama" kimlik doğrulama sistemi kullanılmaktadır. Diğer kimlik doğrulama sistemleri hakkında daha fazla bilgi için Google Hesabı Kimlik Doğrulaması belgelerine bakın.
Bir feed'in tamamını istemek için service.Query yöntemini çağırırsınız. Bu yöntem, bir FeedQuery nesnesi alır ve söz konusu URL'de bulunan feed'in tamamını döndürür. Daha ayrıntılı sorguların nasıl gönderileceğini bu belgenin ilerleyen bölümlerinde göstereceğiz.
Service sınıfının diğer yöntemleri gibi Query de kimlik doğrulamayı ve yönlendirmeleri gerektiği gibi işler.
Yeni öğe ekleme
Bir öğeyi Takvim feed'ine eklemek için aşağıdaki kodu kullanabilirsiniz:
AtomEntry entry = new AtomEntry();
AtomPerson author = new AtomPerson(AtomPersonType.Author);
author.Name = "Jo March";
author.Email = "jo@gmail.com";
entry.Authors.Add(author);
entry.Title.Text = "Tennis with Beth";
entry.Content.Content = "Meet for a quick lesson.";
Uri postUri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");
// Send the request and receive the response:
AtomEntry insertedEntry = service.Insert(postUri, entry);URL'yi ayarladıktan sonra bir AtomEntry nesnesi oluştururuz.
Giriş başlığı, metni çeşitli biçimlerde (düz metin, HTML veya XHTML) tutan bir sınıf olan AtomTextConstruct'dır. Giriş içeriği, XML ve ikili veriler de dahil olmak üzere düz metin veya diğer içerik biçimlerini barındırabilen bir sınıf olan AtomContent nesnesiyle temsil edilir.
Her yazar ad, URI ve e-posta adresi olarak gösterilir. (Bu örnekte URI'yi dahil etmiyoruz.) Bir girişe yazar eklemek için girişin Authors koleksiyonuna bir AtomAuthor nesnesi eklersiniz.
Önceki örnekte oluşturduğumuz Service nesnesini kullanıyoruz. Bu durumda, çağrılacak yöntem Insert'dır. Bu yöntem, belirtilen ekleme URL'sine bir öğe gönderir.
Hizmet, yeni oluşturulan girişi döndürür. Bu giriş, sunucu tarafından oluşturulan ek öğeler (ör. giriş için düzenleme URL'si) içerebilir.
Yukarıdaki kod, POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full göndermeye (uygun kimlik doğrulama ile) ve bir giriş sağlamaya eşdeğerdir.
Belirli bir girişi isteme
Aşağıdaki kod, önceki örnekte eklediğiniz belirli girişi istemenize olanak tanır.
Bu örnekler dizisi bağlamında, Takvim zaten eklenen girişi döndürdüğü için bu girişi almanız gerçekten gerekli değildir. Ancak bir girişin URL'sini bildiğiniz her durumda aynı teknik uygulanabilir.
FeedQuery singleQuery = new FeedQuery(); singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); AtomFeed newFeed = service.Query(singleQuery); AtomEntry retrievedEntry = newFeed.Entries[0];
Eklenen girişin, SelfUri özelliği vardır. Bu özellik, ToString() yöntemini kullanarak yeni bir URI nesnesi oluşturmak için kullanılabilecek bir AtomUri nesnesi döndürür.
Ardından, Entries koleksiyonunda yalnızca bir giriş bulunan yeni bir AtomFeed nesnesi almak için hizmetin Query yöntemini çağırmamız yeterlidir.
Yukarıdaki kod, GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID değerinin uygun kimlik doğrulamasıyla Takvim'e gönderilmesine eşdeğerdir.
Giriş arama
Tam metin aramasında ilk eşleşmeyi almak için aşağıdaki kodu kullanın:
FeedQuery myQuery = new Query(feedUrl);
myQuery.Query = "Tennis";
AtomFeed myResultsFeed = myService.Query(myQuery);
if (myResultsFeed.Entries.Count > 0) {
AtomEntry firstMatchEntry = myResultsFeed.Entries[0];
String myEntryTitle = firstMatchEntry.Title.Text;
}Bu örnekte, çoğunlukla bir URL'nin yanı sıra ilişkili sorgu parametrelerinden oluşan bir FeedQuery nesnesi oluşturularak başlanır. Standart GData sorgu parametrelerinin her birinin bir özelliği vardır.
FeedQuery oluşturulduktan sonra, sorgu sonuçlarını içeren bir feed döndüren hizmetin Query yöntemine iletilir. Alternatif bir yaklaşım, URL'yi kendiniz oluşturmak (feed URL'sine sorgu parametreleri ekleyerek) ve ardından Query yöntemini çağırmak olabilir. Ancak FeedQuery yöntemi, URL'yi kendiniz oluşturmak zorunda kalmamanız için yararlı bir soyutlama katmanı sağlar.
Feed'in Entries koleksiyonu, feed'deki girişlerin listesini döndürür. Entries.Count ise feed'deki girişlerin sayısını döndürür.
Bu durumda, sorgu herhangi bir sonuç döndürürse eşleşen ilk sonucu bir AtomEntry nesnesine atarız. Ardından, girişin başlığını almak için AtomEntry sınıfının Title özelliğini kullanırız.
Yukarıdaki kod, Takvim'e GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis göndermeye eşdeğerdir.
Kategoriye göre sorgulama
Not: Google Takvim, etiketleri etkinliklerle ilişkilendirmediği için bu örnek Takvim ile çalışmaz.
Önceki tam metin aramasıyla eşleşen ve belirli bir kategoride olan veya belirli bir etikete sahip tüm girişlerden oluşan bir feed'i almak için aşağıdaki kodu kullanın:
AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);AtomCategory sınıfı, kategori filtresinde kullanılacak bir kategoriyi temsil eder. QueryCategory sınıfı birden fazla kategori içerebilir ancak bu durumda yalnızca bir kategori içeren bir filtre oluşturuyoruz.
Ardından, bu filtreyi önceki örnekteki tam metin sorgu dizesini hâlâ içeren mevcut sorguya ekliyoruz.
Sorguyu hizmete göndermek için yine Query yöntemini kullanırız.
Takvim'de kategori aramasına izin verilseydi yukarıdaki kod, Takvim'e GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis göndermeye eşdeğer olurdu.
Öğe güncelleme
Mevcut bir öğeyi güncellemek için aşağıdaki kodu kullanın. Aşağıdaki örnekte, daha önce alınan girişin başlığını eski metninden ("Betül ile tenis") "Önemli toplantı" olarak değiştiriyoruz.
retrievedEntry.Title.Text = "Important meeting"; retrievedEntry.Update();
Öncelikle, daha önce getirdiğimiz giriş için yeni bir başlık belirleriz. Ardından, güncellenen girişi hizmete göndermek için Upate yöntemini çağırırız.
Hizmet, bu girişin yeni sürümüne ait yeni bir URL de dahil olmak üzere güncellenmiş girişi döndürür. (Giriş sürümleri hakkında daha fazla bilgi için v1 protokolü referans belgesinin Optimistik eşzamanlılık bölümüne bakın.)
Yukarıdaki kod, orijinal girişi değiştirmek için yeni girişle (Atom biçiminde) birlikte hizmete PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID göndermeye kabaca eşdeğerdir.
Öğe silme
Mevcut bir öğeyi silmek için aşağıdaki kodu kullanın:
updateEntry.Delete();
Silme için kullanılacak URL, düzenleme URL'siyle aynıdır. Bu nedenle, Update yerine Delete yöntemini çağırmamız dışında bu örnek, önceki örneğe çok benzer.
Yukarıdaki kod, hizmete DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID göndermeye kabaca eşdeğerdir.
Google Takvim feed'leriyle çalışma
Yukarıdaki örneklerde, genel GData feed'leriyle çalışmak için Google Data C# API'nin nasıl kullanılacağı açıklanmaktadır. Ancak özellikle bir Google Takvim feed'iyle çalışırken feed, temel API kitaplığındaki standart Atom odaklı nesneler kullanılarak kolayca erişilemeyen, takvime özel birçok veri içerir. Bu feed'lerle etkileşim kurmanıza yardımcı olmak için aşağıdaki uzantıları sunuyoruz:
using Google.GData.Extensions; using Google.GData.Calendar;
Extensions ad alanı genel olarak uzantılarla ilgilenir. Calendar ad alanı ise özelleştirilmiş bir takvim hizmetine, feed'e ve sorgu nesnesine erişmenizi sağlar. Bu uzantıların nasıl kullanıldığına dair daha ayrıntılı bir örneği C# API yüklemesinin /Samples alt dizininde bulabilirsiniz. Aşağıdaki nesneler eklenir:
- EventQuery
- Takvim hizmeti için iki özel parametre (start-min ve start-max) ayarlamanıza olanak tanıyan FeedQuery alt sınıfı.
- CalendarService
- Bir etkinlik feed'i döndürebilen bir hizmet alt sınıfı.
- EventFeed
- EventEntries'i gösteren bir AtomFeed alt sınıfı.
- EventEntry
- Takvim verileriyle ilgili ek özelliklere sahip olan AtomEntry'nin bir alt sınıfı.
Bu özel sınıflar hakkında daha fazla bilgi için API belgelerine ve örnek programa bakın.
Referans
C# istemci kitaplığıyla ilgili referans bilgileri için referans belgelerine bakın.