Bu dokümanda, Google Data API ("GData") sorguları göndermek ve döndürülen yanıtları yorumlamak için Java istemci kitaplığının nasıl kullanılacağı açıklanmaktadır.
Google, veri API'leri olan hizmetlerle etkileşimde bulunmak 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ıtları alabilirsiniz.
Bu dokümanda Java istemci kitaplığının kullanımıyla ilgili bazı genel bilgilerin yanı sıra yaygın kullanımlara dair örnekler de sağlanmaktadır.
Bu istemci kitaplığını kullanmak için Java 1.5 kullanıyor olmanız gerekir.
Java 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. Belirli bir hizmetin Data API'siyle Java istemci kitaplığını 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 Java 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, Java'da programlamayı bildiğiniz varsayılır.
İstemci kitaplığı tarafından sağlanan sınıflar ve yöntemler hakkında referans bilgiler için Java istemci kitaplığı API referansı (Javadoc biçiminde) başlıklı makaleye bakın.
Bu belge, düzenli bir şekilde okunacak şekilde tasarlanmıştır. Her örnek önceki örneklere dayanır.
Veri modeline genel bakış
Java istemci kitaplığı, Google Veri API'ları tarafından kullanılan öğeleri temsil eden bir sınıf kümesi kullanır. Ö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. Bunu yapmanın en kolay yolu Roma gibi 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, Java istemci kitaplığını kullanarak çeşitli veri API'si 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 içe aktarma ifadelerini kullanmanız gerekir:
import com.google.gdata.client.*; import com.google.gdata.client.calendar.*; import com.google.gdata.data.*; import com.google.gdata.data.extensions.*; import com.google.gdata.util.*; import java.net.URL;
Feed isteme
Google Calendar Data API dokümanı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. Bu örnek ile Takvim dokümanındaki ilk örnek arasındaki temel farklar şunlardır: (1) bu örnek kimlik doğrulama içerir ve (2) bu örnek, Takvim'e özgü Takvim Hizmeti sınıfı yerine daha genel bir GoogleService sınıfı kullanır.
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.
Java istemci kitaplığını kullanarak bir Takvim feed'i istemek için, "liz@gmail.com" e-posta adresine ve "mypassword" şifresine sahip bir kullanıcı için aşağıdaki kodu kullanın:
// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");
// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());
// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);
GoogleService sınıfı, bir GData hizmetiyle olan istemci bağlantısını (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 birGoogleServiceörneği oluşturun. - Uygun kimlik bilgilerini ayarlayın.
- Feed'in hangi uzantıları kullanacağını istemci kitaplığına bildirin. Böylece kitaplık, döndürülen feed'leri doğru şekilde ayrıştırabilir.
- İsteği göndermek ve sonuçları almak için bir yöntem arayın.
setUserCredentials yöntemi, müşteriniz adına sorgu gönderen kullanıcının kimliğini ve şifresini belirtir. Bu belgedeki örneklerde "Yüklü Uygulamalar İçin Kimlik Doğrulama" kimlik doğrulama sistemi kullanılmaktadır. Kimlik doğrulama sistemleri hakkında daha fazla bilgi edinmek için Google Hesabı Kimlik Doğrulaması dokümanlarına bakın.
Kimlik bilgilerini ayarladıktan sonra declareExtensions yöntemini çağırarak feed'in hangi uzantıları kullanacağını belirtirsiniz. Bu örnekte, feed'in bir Etkinlik feed'i olduğunu ve dolayısıyla Etkinlik türü ile tanımlanan uzantıları kullanacağını belirtiyoruz.
Feed'in tamamını istemek için getFeed yöntemini çağırırsınız. Bu yöntem, bir URL 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.
GoogleService sınıfının diğer yöntemleri gibi getFeed de kimlik doğrulama ve yönlendirmeleri gerektiği şekilde işler.
Yeni öğe ekleme
Yeni bir takvim etkinliği oluşturmak için aşağıdaki kodu kullanabilirsiniz:
URL postUrl =
new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();
myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));
Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);
DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);
// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);
URL ayarlandıktan sonra EventEntry nesnesi oluşturulur. EventEntry nesnesi, BaseEntry soyut temel sınıfından türetilir. Bu sınıf, aynı zamanda bir <atom:entry> öğesini temsil eden Entry sınıfının üst sınıfıdır.
EventEntry sınıfı bir Etkinlik türünü temsil eder. Daha fazla bilgi için Türler belgesini inceleyin. Takvim dışındaki hizmetler için döndürülen girişi EventEntry nesnesi yerine bir Entry nesnesine atayabilirsiniz.
Giriş başlığı, çeşitli biçimlerde (düz metin, HTML veya XHTML) metin barındıran bir sınıftır. TextConstruct 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 Content nesnesiyle gösterilir. (Ancak setContent yöntemi, TextConstruct'ni de kabul edebilir.)
Her yazar bir ad, URI ve e-posta adresi olarak gösterilir. (Bu örnekte, URI'yı kullanımdan kaldırıyoruz.) Bir girişe getAuthors().add yöntemi çağırarak yazar ekleyebilirsiniz.
Önceki örnekte oluşturduğumuz GoogleService 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.
HTTP durum kodları istisna olarak döndürülür.
Yukarıdaki kod, POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full göndermeye (uygun kimlik doğrulamayla) ve bir Etkinlik türü biçiminde 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 zaten eklenen girişi döndürdüğünden bu girişi almak çok da gerekli değildir, ancak bir girişin URI'sını bildiğinizde aynı teknik uygulanabilir.
URL entryUrl = new URL(insertedEntry.getSelfLink().getHref()); EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);
Eklenen girişte, girişin URL'sini içeren bir Link nesnesi döndüren getSelfLink yöntemi bulunmaktadır. Link sınıfı, URL'yi String olarak döndüren bir getHref yöntemi içerir. Bu URL'de bir URL nesnesi oluşturabiliriz.
Ardından, girişi almak için hizmetin getEntry yöntemini çağırmamız yeterli.
EventEntry.class parametresini getEntry için bir parametre olarak sunuyoruz. Bu durum, hizmetin yalnızca düz giriş yerine bir Etkinlik döndürmesini beklediğimizi gösterir. Takvim dışındaki hizmetler için Entry.class ayarını iletmeniz yeterlidir.
Yukarıdaki kod, GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID uygulamasına Takvim'e kimlik doğrulaması yapılmasıyla eşdeğerdir.
Girişler aranıyor
Tam metin aramasından ilk eşleşmeyi almak için aşağıdaki kodu kullanın:
Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}
Bu örnek, çoğunlukla bir URL ve ilişkili sorgu parametrelerinden oluşan bir Query nesnesi oluşturarak başlar. Standart GData sorgu parametrelerinin her biri bir setter yöntemine sahiptir. Ayrıca, addCustomParameter yöntemini kullanarak belirli bir hizmet için özel sorgu parametreleri de ayarlayabilirsiniz.
Query 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 getFeed yöntemini çağırmanız olabilir. Ancak query yöntemi, URL'yi kendiniz yapmak zorunda kalmadan faydalı bir soyutlama katmanı sunar.
Feed'in getEntries yöntemi, feed'deki girişlerin listesini, getEntries().size, 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 Entry nesnesine atarız. Ardından, Entry sınıfının getTitle().getPlainText yöntemini kullanarak girişin başlığını alır ve metne dönüştürürüz.
Yukarıdaki kod, Takvim'e GET http://www.google.com/calendar/feeds/liz@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:
Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);
Elbette Category sınıfı, kategori filtresinde kullanılacak bir kategoriyi temsil eder. Query.CategoryFilter 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/liz@gmail.com/private/full/-/by_liz?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. Bu örnekte, daha önce alınan girişin başlığını eski metninden ("Tenis'in Darty ile") "Önemli toplantı" olarak değiştiriyoruz.
retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);
Daha önce aldığımız giriş için yeni bir başlık belirledik. Ardından, getEditLink yöntemini kullanarak girişin düzenleme URL'sini alırız. Ardından, güncellenmiş girişi göndermek için hizmetin update yöntemini çağırırız.
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 protokol referansı belgesinin 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/liz@gmail.com/private/full/entryID hizmetinin hizmete gönderilmesine eşdeğerdir.
Öğe silme
Güncellenen girişi silmek için aşağıdaki kodu kullanın:
URL deleteUrl = new URL(updatedEntry.getEditLink().getHref()); myService.delete(deleteUrl);
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/liz@gmail.com/private/full/entryID göndermeyle eşdeğerdir.
Referans
İstemci kitaplığı tarafından sağlanan sınıflar ve yöntemler hakkında referans bilgiler için Java istemci kitaplığı API referansı (Javadoc biçiminde) başlıklı makaleye bakın.