Bu dokümanda, Google Data API ("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, çeşitli programlama dillerinde GData özellikli hizmetlerle etkileşimde bulunmak için bir dizi istemci kitaplığı sağlar. Bu kitaplıkları kullanarak GData istekleri oluşturabilir, bunları bir hizmete gönderebilir ve yanıtları alabilirsiniz.
Bu dokümanda, istemci kitaplığının C# sürümünün yaygın kullanımlarına yönelik örnekler ve ardından GData istemcileri yazmayla ilgili diğer bilgiler sağlanmaktadır. Bu dokümanın sonunda, C# istemci kitaplığı için NDoc biçimindeki referans dokümanların bağlantısı bulunur.
Bu istemci kitaplığını kullanmak için .NET 1.1 çalışma zamanına sahip olmanız ve tüm yamalarda güncel olmanız gerekir.
.NET istemci kitaplığını indirin.
Bu kılavuzdaki örnekler, Google Calendar API'yi işaret etmektedir ancak bu kılavuz, Calendar API'yi kullanmayla ilgili doğru veya güncel bir kılavuz değildir. .NET istemci kitaplığını belirli bir hizmetin Data API'siyle kullanma hakkında bilgi edinmek için hizmete özel dokümanları inceleyin. Örneğin, Takvim ile çalışıyorsanız Calendar Data API Geliştirici Kılavuzu'nu okuyun.
İçindekiler
Kitle
Bu belge, GData hizmetleriyle etkileşime girebilecek istemci uygulamaları yazmak isteyen C# programcıları için hazırlanmıştır.
Bu dokümanda, Google Veri API'leri protokolü ile ilgili genel fikirleri anladığınız varsayılmaktadır. Ayrıca, C# dilinde nasıl programlama yapacağınızı bildiğiniz varsayılır.
Veri modeline genel bakış
C# istemci kitaplığı, Google Veri API'ları tarafından kullanılan öğelere ve veri türlerine karşılık gelen bir sınıf kümesi sağlar. Örneğin, <atom:feed> öğesine karşılık gelen bir Feed sınıfı vardır. Bu giriş, giriş oluşturma, çeşitli alt öğelerin değerlerini alma ve ayarlama yöntemlerine sahiptir. Ayrıca, <atom:entry> öğesine karşılık gelen bir Giriş 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 dokümanlarını inceleyin.
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, feed'i ayrıştırır ve elde edilen değerlerle bir Feed nesnesi döndürür.
Bir feed'i veya girişi bir hizmete göndermek için Feed veya Giriş nesnesi oluşturur, ardından nesneyi otomatik olarak XML'e çevirmek ve göndermek için bir kitaplık yöntemi (insert yöntemi gibi) çağırırsınız.
Dilerseniz XML'i kendiniz ayrıştırabilir ve/veya oluşturabilirsiniz. Bunun en kolay yolu uygun bir üçüncü taraf kitaplığıdır.
Google Data API'sinin XML söz diziminin genişletilebilir olması 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.
Bunları daha somut hale getirmek için belirli bir hizmetle nasıl etkileşimde bulunulacağını gösteren şu örnekler gösterilmektedir: Google Takvim. Takvim'in diğer Google hizmetlerinden farklı olduğu noktalara dikkat çekmek için bu örnekleri diğer hizmetlerle birlikte kullanmanıza yardımcı olacağız. Takvim hakkında daha fazla bilgi için Google Calendar Data API dokümanlarını inceleyin.
İstemcinizi oluşturma ve çalıştırma
Bu dokümandaki örnekleri derlemek için aşağıdaki ifadeyi kullanmanız gerekir:
using Google.GData.Client;
Feed isteme
Google Calendar Data API dokümanlarında açıklandığı gibi, Takvim'e aşağıdaki HTTP isteğini göndererek Takvim 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ını inceleyin. Bunun yerine, Takvim ile etkileşimde bulunmak için özel varsayılan URL'yi (Takvim dokümanında açıklandığı gibi) kullanabilirsiniz ancak bu belgede, kullanıcı kimliğini içeren gizli tam feed URL'si kullanılacaktır.
Ayrıca, uygun kimlik doğrulama işlemini tamamlamanız gerekir. Burada kullandığımız kimlik doğrulama sisteminin ("Yüklü Uygulamalar İçin Google Kimlik Doğrulaması" olarak bilinir), web uygulamaları için değil, yalnızca masaüstü istemcileri gibi yüklü istemci uygulamaları için uygun olduğunu unutmayın. Kimlik doğrulama hakkında daha fazla bilgi için Google Hesabı Kimlik Doğrulaması dokümanlarına göz atın.
C# istemci kitaplığını kullanarak bir Takvim feed'i istemek için "jo@gmail.com" e-posta adresine ve "mypassword" şifresine sahip bir kullanıcı için 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 hizmetiyle olan istemci kimliğini (kimlik doğrulamalı) temsil eder. İstemci kitaplığını kullanarak bir hizmete sorgu göndermeye ilişkin 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) istemci kitaplığı sınıflarını kullanarak ham verileri nesnelere dönüştürün. (Bu örnekte olduğu gibi bu adım, yalnızca feed isteğinde bulunduğunuzda geçerli değildir.)
- Hizmet adını (Takvim için
"cl"gibi) 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öntem arayın.
service.setUserCredentials yöntemi, service.Credentials özelliğini standart bir .NET Network kimlik bilgileri nesnesiyle ayarlar.
Kimlik bilgileri, müşteriniz adına sorgu gönderen 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 edinmek için Google Hesabı Kimlik Doğrulaması dokümanlarına bakın.
Feed'in tamamını istemek için service.Query yöntemini çağırırsınız. Bu yöntem, FeedQuery nesnesini alır ve söz konusu URL'de bulunan feed'in tamamını döndürür. Bu belgenin ilerleyen bölümlerinde nasıl daha spesifik sorgular göndereceğinizi göstereceğiz.
Service sınıfının diğer yöntemleri gibi Query de kimlik doğrulama ve yönlendirmeleri gerektiği şekilde işler.
Yeni öğe ekleme
Takvim feed'ine öğe 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 ayarlandıktan sonra AtomEntry nesnesi oluşturulur.
Giriş başlığı, çeşitli biçimlerde (düz metin, HTML veya XHTML) metin barındıran bir sınıftır. AtomTextConstruct Giriş içeriği, düz metin veya XML ve ikili program verileri de dahil olmak üzere diğer içerik biçimlerini barındırabilen bir sınıf olan AtomContent nesnesiyle gösterilir.
Her yazar bir ad, URI ve e-posta adresi olarak gösterilir. (Bu örnekte, URI'yı kullanımdan kaldırıyoruz.) Girişin Authors koleksiyonuna AtomAuthor nesnesi ekleyerek girişe yazar ekleyebilirsiniz.
Önceki örnekte oluşturduğumuz Service nesnenin aynısını kullanıyoruz. Bu durumda, öğe belirtilen belirtilen URL'ye gönderen Insert yöntemidir.
Hizmet, yeni oluşturulan girişi döndürür. Bu giriş, girişin düzenleme URL'si gibi sunucu tarafından oluşturulan ek öğeler içerebilir.
Yukarıdaki kod, POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full gönderilmesini (doğru kimlik doğrulama işlemiyle) ve bir giriş sağlamaya eşdeğerdir.
Belirli bir giriş isteme
Aşağıdaki kod, önceki örnekte eklediğiniz giriş için istekte bulunmanıza olanak tanır.
Bu örnek dizisi bağlamında, Takvim eklenen girişi zaten döndürdüğü için bu girişi almak aslında gerekli değildir, ancak bir girişin URL'sini bildiğinizde 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ş, ToString() yöntemini kullanarak yeni bir URI nesnesi oluşturmak için kullanılabilecek bir AtomUri nesnesi döndüren SelfUri özelliğine sahip.
Ardından, Entries koleksiyonunda yalnızca tek bir giriş olacak şekilde yeni bir AtomFeed nesnesi edinmek 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 uygulamasına Takvim'e kimlik doğrulaması yapılmasıyla eşdeğerdir.
Bir girişi arama
Tam metin aramasındaki 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 örnek, çoğunlukla bir URL ve ilişkili sorgu parametrelerinden oluşan bir FeedQuery nesnesi oluşturarak başlar. Standart GData sorgu parametrelerinin her biri bir özellik içerir.
FeedQuery oluşturulduktan sonra hizmeti Query yöntemine geçiririz. Bu yöntem, sorgu sonuçlarını içeren bir feed döndürür. Alternatif bir yaklaşım da, URL'yi kendiniz oluşturup (feed parametrelerini URL parametrelerine ekleyerek) ve ardından Query yöntemini çağırmanız olabilir. Ancak FeedQuery yöntemi, URL'yi kendiniz yapmak zorunda kalmadan faydalı bir soyutlama katmanı sunar.
Feed'in Entries koleksiyonu, feed'deki girişlerin listesini, Entries.Count, feed'deki girişlerin sayısını döndürür.
Bu durumda, sorgu sonuç döndürdüyse 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ğinden bu örnek Takvim'de kullanılamaz.
Önceki tam metin aramasıyla eşleşen ve belirli bir kategoride ya da belirli bir etikete sahip olan tüm girişlerden oluşan bir feed 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);
Elbette AtomCategory sınıfı, kategori filtresinde kullanılacak bir kategoriyi temsil eder. QueryCategory sınıfı birden fazla kategori içerebilir ancak bu örnekte yalnızca bir kategori içeren bir filtre oluşturuyoruz.
Ardından bu filtreyi mevcut sorguya ekleriz ve bu sorgu önceki örnekte bulunan tam metin sorgu dizesini içerir.
Sorguyu hizmete göndermek için tekrar Query yöntemini kullanırız.
Takvim bir kategori aramasına izin verdiyse yukarıdaki kod GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis uygulamasına Takvim göndermekle eşdeğer olur.
Öğ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 metinden ("Beten ile Tenis") "Önemli toplantı" olarak değiştiriyoruz.
retrievedEntry.Title.Text = "Important meeting"; retrievedEntry.Update();
Daha önce aldığımız giriş için yeni bir başlık belirledik. Ardından, güncellenen girişi hizmete göndermek için Upate yöntemini çağırıyoruz.
Hizmet, bu girişin yeni sürümü için yeni bir URL 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 dokümanındaki Optimum eşzamanlılık bölümüne bakın.)
Yukarıdaki kod, orijinal girişin yerini alacak yeni girişle (Atom biçiminde) birlikte yaklaşık olarak PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID hizmetinin hizmete gönderilmesine eşdeğerdir.
Öğe silme
Mevcut bir öğeyi silmek için aşağıdaki kodu kullanın:
updateEntry.Delete();
Silme işlemi için kullanılacak URL, düzenleme URL'si ile aynı olduğundan bu örnek, önceki yönteme çok benzer ancak bu örnekte Update yerine Delete yöntemi kullanılmaktadır.
Yukarıdaki kod, yaklaşık olarak hizmete DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID göndermeyle eşdeğerdir.
Google Takvim feed'leriyle çalışma
Yukarıdaki örneklerde, genel GData feed'leriyle çalışmak için Google Data C# API'sinin nasıl kullanılacağı gösterilmektedir. Bununla birlikte, özellikle bir Google Takvim feed'iyle çalışırken feed, temel API kitaplığındaki standart Atom odaklı nesneler kullanılarak kolayca erişilemeyen takvime özgü çok fazla 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;
Uzantılar ad alanı genel olarak uzantılarla ilgilidir. Takvim ad alanı, özelleştirilmiş bir takvim hizmetine, feed'e ve sorgu nesnesine erişmenizi sağlar. C# API yüklemesinin /Samples alt dizininde bu uzantıların nasıl kullanıldığına dair daha ayrıntılı bir örnek bulabilirsiniz. Aşağıdaki nesneler eklenir:
- EtkinlikSorgusu
- Feed hizmeti için iki özel parametre ayarlamanızı sağlayan bir FeedQuery alt sınıfıdır (start-min ve start-max).
- Takvim Hizmeti
- Etkinlik feed'i döndürebilen bir hizmet alt sınıfı.
- EtkinlikFeed'i
- AtomFeed'in bir alt sınıfı olan EventEntries.
- Etkinlik Girişi
- 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 programına göz atabilirsiniz.
Referans
C# istemci kitaplığı hakkında referans bilgiler için referans dokümanlarına bakın.