Menggunakan Java Client Library

Dokumen ini menjelaskan cara menggunakan library klien Java untuk mengirim kueri Google Data API ("GData") dan menafsirkan respons yang ditampilkan.

Google menyediakan kumpulan library klien, dalam berbagai bahasa pemrograman, untuk berinteraksi dengan layanan yang memiliki API data. Dengan library ini, Anda dapat membuat permintaan GData, mengirimkannya ke layanan, dan menerima respons.

Dokumen ini menyediakan beberapa informasi umum tentang penggunaan library klien Java, bersama dengan serangkaian contoh penggunaan umum.

Untuk menggunakan library klien ini, Anda harus menjalankan Java 1.5.

Download library klien Java.

Contoh panduan ini merujuk ke Google Calendar API, tetapi panduan ini bukan panduan yang akurat atau terbaru untuk menggunakan Calendar API. Untuk informasi tentang cara menggunakan library klien Java dengan Data API layanan tertentu, lihat dokumentasi khusus layanan. Misalnya, jika Anda menggunakan Kalender, baca Panduan Developer Calendar Data API.

Daftar Isi

  1. Audiens
  2. Ringkasan model data
  3. Tutorial dan contoh
    1. Mem-build dan menjalankan klien
    2. Meminta feed
    3. Menyisipkan item baru
    4. Meminta entri tertentu
    5. Menelusuri entri
    6. Melakukan kueri berdasarkan kategori
    7. Memperbarui item
    8. Menghapus item
  4. Referensi

Audiens

Dokumen ini ditujukan untuk pemrogram Java yang ingin menulis aplikasi klien yang dapat berinteraksi dengan layanan GData.

Dokumen ini mengasumsikan bahwa Anda memahami ide umum di balik protokol Google Data API. Hal ini juga mengasumsikan bahwa Anda tahu cara memprogram di Java.

Untuk informasi referensi tentang class dan metode yang disediakan oleh library klien, lihat referensi API library klien Java (dalam format Javadoc).

Dokumen ini dirancang untuk dibaca secara berurutan; setiap contoh dibuat berdasarkan contoh sebelumnya.

Ringkasan model data

Library klien Java menggunakan sekumpulan class untuk mewakili elemen yang digunakan oleh Google Data API. Misalnya, ada class Feed yang sesuai dengan elemen <atom:feed>; dan memiliki metode untuk membuat entri, mendapatkan dan menetapkan nilai berbagai sub-elemen, dan sebagainya. Ada juga Class entri, yang sesuai dengan elemen <atom:entry>. Tidak setiap elemen yang ditentukan di Google Data API memiliki class-nya sendiri; untuk mengetahui detailnya, lihat dokumentasi referensi.

Library dapat secara otomatis mengurai konten Atom dan memasukkan nilai elemen Atom ke dalam objek yang sesuai. Misalnya, metode getFeed mendapatkan feed, mengurainya, dan menampilkan objek Feed dengan nilai yang dihasilkan.

Untuk mengirim feed atau entri ke layanan, buat objek Feed atau Entri, lalu panggil metode library (seperti metode insert) untuk menerjemahkan objek secara otomatis ke dalam XML dan mengirimkannya.

Anda dapat mengurai dan/atau membuat XML sendiri jika menginginkannya; cara termudah untuk melakukannya adalah dengan library pihak ketiga yang sesuai seperti Roma.

Seperti halnya sintaksis XML Google Data API yang dapat diperluas, model objek yang sesuai dapat diperluas. Misalnya, library klien menyediakan class yang sesuai dengan elemen yang ditentukan dalam namespace Data Google.

Tutorial dan contoh

Contoh berikut menunjukkan cara mengirim berbagai permintaan API data menggunakan library klien Java.

Agar lebih konkret, contoh berikut menunjukkan cara berinteraksi dengan layanan tertentu: Google Kalender. Kami akan menunjukkan perbedaan tempat Kalender berbeda dengan layanan Google lainnya, untuk membantu Anda menyesuaikan contoh ini agar digunakan dengan layanan lain. Untuk informasi selengkapnya tentang Kalender, lihat dokumentasi API Data Google Kalender.

Membuat dan menjalankan klien Anda

Untuk mengompilasi contoh dalam dokumen ini, Anda harus menggunakan pernyataan impor berikut:

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;

Meminta feed

Seperti yang dijelaskan dalam dokumen Google Calendar Data API, Anda dapat meminta feed Kalender dengan mengirim permintaan HTTP berikut ke Kalender:

GET http://www.google.com/calendar/feeds/userID/private/full

Tentu saja, Anda harus mengganti userID dengan alamat email pengguna; lihat dokumen Kalender untuk detailnya. Sebagai gantinya, Anda dapat menggunakan URL default khusus untuk berinteraksi dengan Kalender (seperti yang dijelaskan dalam dokumen Kalender), tetapi dalam dokumen ini, kami akan menggunakan URL feed lengkap pribadi, yang berisi ID pengguna.

Anda juga harus memberikan autentikasi yang sesuai. Perbedaan utama antara contoh ini dan contoh pertama dalam dokumen Kalender adalah bahwa (1) contoh ini menyertakan autentikasi, dan (2) contoh ini menggunakan class GoogleService yang lebih umum, bukan class CalendarService khusus Kalender.

Perhatikan bahwa sistem autentikasi yang kami gunakan di sini (dikenal sebagai "Google Authentication untuk Aplikasi Terinstal") hanya sesuai untuk digunakan dalam aplikasi klien yang diinstal seperti klien desktop, bukan untuk digunakan dalam aplikasi web. Untuk informasi selengkapnya tentang autentikasi, lihat dokumentasi Autentikasi Akun Google.

Untuk meminta feed Kalender menggunakan library klien Java, untuk pengguna dengan alamat email "liz@gmail.com" dan sandi "mypassword", gunakan kode berikut:

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

Class GoogleService merepresentasikan koneksi klien (dengan autentikasi) ke layanan GData. Prosedur umum untuk mengirim kueri ke layanan menggunakan library klien terdiri dari langkah-langkah berikut:

  1. Dapatkan atau buat URL yang sesuai.
  2. Jika Anda mengirimkan data ke layanan (misalnya, jika Anda menyisipkan entri baru), ubah data mentah menjadi objek menggunakan class library klien. (Langkah ini tidak berlaku jika Anda hanya meminta feed, seperti yang kami lakukan dalam contoh ini.)
  3. Buat instance GoogleService baru, dengan menetapkan nama layanan (seperti "cl" untuk Kalender) dan nama aplikasi Anda (dalam bentuk companyName-applicationName-versionID).
  4. Tetapkan kredensial yang sesuai.
  5. Tunjukkan ke library klien ekstensi mana yang akan digunakan feed, sehingga library dapat mengurai feed yang ditampilkan dengan benar.
  6. Panggil metode untuk mengirim permintaan dan menerima hasilnya.

Metode setUserCredentials menentukan ID dan sandi pengguna yang atas namanya klien Anda mengirimkan kueri. Contoh dalam dokumen ini menggunakan sistem autentikasi "Autentikasi untuk Aplikasi yang Diinstal"; untuk informasi lebih lanjut tentang sistem autentikasi, lihat dokumentasi Autentikasi Akun Google.

Setelah menyetel kredensial, Anda menunjukkan ekstensi mana yang akan digunakan feed dengan memanggil metode declareExtensions. Dalam hal ini, kami menyatakan bahwa feed tersebut adalah feed Peristiwa, sehingga akan menggunakan ekstensi yang ditentukan oleh jenis Peristiwa.

Untuk meminta seluruh feed, panggil metode getFeed, yang menggunakan URL dan menampilkan seluruh feed yang ditemukan di URL tersebut. Kami akan menunjukkan cara mengirim kueri yang lebih spesifik nanti dalam dokumen ini.

Seperti metode class GoogleService lainnya, getFeed menangani autentikasi dan pengalihan sesuai kebutuhan.

Menyisipkan item baru

Untuk membuat acara kalender baru, Anda dapat menggunakan kode berikut:

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

Setelah menetapkan URL, kita membuat objek EventEntry; EventEntry berasal dari class dasar abstrak BaseEntry, yang juga merupakan class induk untuk class Entry, yang mewakili elemen <atom:entry>.

Class EventEntry mewakili jenis Peristiwa; untuk informasi selengkapnya, lihat dokumen Jenis. Untuk layanan selain Kalender, Anda dapat menetapkan entri yang ditampilkan ke objek Entry, bukan objek EventEntry.

Judul entri adalah TextConstruct, class yang menyimpan teks dalam berbagai bentuk (teks biasa, HTML, atau XHTML). Konten entri direpresentasikan oleh objek Content, class yang dapat menyimpan teks biasa atau bentuk konten lainnya, termasuk data XML dan biner. (Namun, metode setContent juga dapat menerima TextConstruct.)

Setiap penulis ditunjukkan sebagai nama, URI, dan alamat email. (Dalam contoh ini, kami tidak menyertakan URI.) Anda menambahkan penulis ke entri dengan memanggil metode getAuthors().add entri.

Kita menggunakan objek GoogleService yang sama dengan yang dibuat dalam contoh sebelumnya. Dalam hal ini, metode yang akan dipanggil adalah insert, yang mengirimkan item ke URL penyisipan yang ditentukan.

Layanan ini menampilkan entri yang baru dibuat, yang mungkin berisi elemen lain yang dihasilkan server, seperti URL edit untuk entri tersebut.

Kode status HTTP ditampilkan sebagai pengecualian.

Kode di atas sama dengan mengirim POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (dengan autentikasi yang tepat) dan memberikan entri dalam bentuk jenis Peristiwa.

Meminta entri tertentu

Kode berikut memungkinkan Anda meminta entri tertentu yang Anda sisipkan dalam contoh sebelumnya.

Dalam konteks rangkaian contoh ini, mengambil entri tersebut tidak benar-benar diperlukan, karena Kalender sudah mengembalikan entri yang disisipkan; tetapi teknik yang sama dapat diterapkan setiap kali Anda mengetahui URI entri.

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

Entri yang dimasukkan memiliki metode, getSelfLink, yang menampilkan objek Link yang menyertakan URL entri. Class Link memiliki metode getHref yang menampilkan URL sebagai String, tempat kita dapat membuat objek URL.

Selanjutnya, kita hanya perlu memanggil metode getEntry layanan untuk mendapatkan entri.

Perhatikan bahwa kita memberikan EventEntry.class sebagai parameter ke getEntry, yang menunjukkan bahwa kita secara khusus mengharapkan layanan menampilkan Peristiwa, bukan hanya entri biasa. Untuk layanan selain Kalender, Anda dapat meneruskan Entry.class.

Kode di atas sama dengan mengirim GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ke Kalender, dengan autentikasi yang tepat.

Menelusuri entri

Untuk mengambil kecocokan pertama dari penelusuran teks lengkap, gunakan kode berikut:

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

Contoh ini dimulai dengan membuat objek Query, yang sebagian besar terdiri dari URL ditambah parameter kueri terkait. Setiap parameter kueri GData standar memiliki metode penyetel. Anda juga dapat menetapkan parameter kueri kustom untuk layanan tertentu, menggunakan metode addCustomParameter.

Setelah membuat Query, kita meneruskannya ke metode query layanan, yang menampilkan feed yang berisi hasil kueri. Pendekatan alternatifnya adalah membuat URL sendiri (dengan menambahkan parameter kueri ke URL feed), lalu memanggil metode getFeed, tetapi metode query memberikan lapisan abstraksi yang berguna sehingga Anda tidak perlu membuat URL sendiri.

Metode getEntries feed menampilkan daftar entri dalam feed; getEntries().size menampilkan jumlah entri dalam feed.

Dalam hal ini, jika kueri menampilkan hasil apa pun, kita akan menetapkan hasil pertama yang cocok ke objek Entry. Kemudian, kita menggunakan metode getTitle().getPlainText class Entry untuk mengambil judul entri dan mengonversinya menjadi teks.

Kode di atas sama dengan mengirim GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis ke Kalender.

Membuat kueri berdasarkan kategori

Catatan: Google Kalender tidak mengaitkan label dengan acara, sehingga contoh ini tidak berfungsi dengan Kalender.

Untuk mengambil feed yang terdiri dari semua entri yang cocok dengan penelusuran teks lengkap sebelumnya dan yang berada di kategori tertentu atau memiliki label tertentu, gunakan kode berikut:

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

Class Category, tentu saja, mewakili kategori yang akan digunakan dalam filter kategori. Class Query.CategoryFilter dapat berisi beberapa kategori, tetapi dalam hal ini kita membuat filter hanya dengan satu kategori.

Kemudian, kita menambahkan filter tersebut ke kueri yang ada, yang masih berisi string kueri teks lengkap dari contoh sebelumnya.

Sekali lagi, kita menggunakan metode query untuk mengirim kueri ke layanan.

Jika Kalender mengizinkan penelusuran kategori, kode di atas akan setara dengan mengirim GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis ke Kalender.

Memperbarui item

Untuk memperbarui item yang ada, gunakan kode berikut. Dalam contoh ini, kami mengubah judul entri yang sebelumnya diambil dari teks lamanya ("Tennis dengan Darcy") menjadi "Rapat penting".

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

Pertama, kita menetapkan judul baru untuk entri yang kita ambil sebelumnya. Kemudian, kita mendapatkan URL edit untuk entri tersebut, menggunakan metode getEditLink. Kemudian, kita memanggil metode update layanan untuk mengirim entri yang diperbarui.

Layanan ini menampilkan entri yang diperbarui, termasuk URL baru untuk versi baru entri ini. (Untuk informasi selengkapnya tentang versi entri, lihat bagian Serentak optimis di dokumen referensi protokol.)

Kode di atas kira-kira setara dengan mengirim PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ke layanan, bersama dengan entri baru (dalam format Atom) untuk menggantikan entri asli.

Menghapus item

Untuk menghapus entri yang diperbarui, gunakan kode berikut:

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

URL yang digunakan untuk penghapusan sama dengan URL edit, sehingga contoh ini sangat mirip dengan yang sebelumnya, kecuali tentu saja kita memanggil metode delete, bukan update.

Kode di atas kurang lebih sama dengan mengirim DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ke layanan.

Referensi

Untuk informasi referensi tentang class dan metode yang disediakan oleh library klien, lihat referensi API library klien Java (dalam format Javadoc).

Kembali ke atas