Dokumen ini menjelaskan protokol yang digunakan oleh Google Data API, termasuk informasi tentang tampilan kueri, seperti apa hasilnya, dan sebagainya.
Untuk informasi selengkapnya tentang Google Data API, lihat dokumen Panduan Developer Data Google dan Panduan Protokol.
Audiens
Dokumen ini ditujukan bagi siapa saja yang ingin memahami detail format XML dan protokol yang digunakan oleh Google Data API.
Jika Anda hanya ingin menulis kode yang menggunakan API klien Data Google, Anda tidak perlu mengetahui detail tersebut; sebagai gantinya, Anda dapat menggunakan library klien khusus bahasa.
Namun, jika Anda ingin memahami protokolnya, baca dokumen ini. Misalnya, Anda mungkin ingin membaca dokumen ini untuk membantu melakukan salah satu tugas berikut:
- mengevaluasi arsitektur Data Google
- coding menggunakan protokol tanpa menggunakan library klien Data Google yang disediakan
- menulis library klien dalam bahasa baru
Dokumen ini mengasumsikan bahwa Anda memahami dasar-dasar XML, namespace, feed yang dipublikasikan, serta permintaan GET, POST, PUT, dan DELETE di HTTP, serta konsep HTTP tentang "resource". Untuk informasi selengkapnya tentang hal-hal tersebut, lihat bagian Referensi tambahan dalam dokumen ini.
Dokumen ini tidak bergantung pada bahasa pemrograman tertentu. Anda dapat mengirim dan menerima pesan Data Google menggunakan bahasa pemrograman apa pun yang memungkinkan Anda mengeluarkan permintaan HTTP dan mengurai respons berbasis XML.
Detail protokol
Bagian ini menjelaskan format dokumen dan sintaksis kueri Data Google.
Format dokumen
Google Data, Atom, dan RSS 2.0 menggunakan model data dasar yang sama: penampung yang menyimpan beberapa data global dan jumlah entri. Untuk setiap protokol, format ditentukan oleh skema dasar, tetapi dapat diperluas menggunakan namespace asing.
Google Data API dapat menggunakan format sindikasi Atom (untuk operasi baca dan tulis) atau format RSS (hanya untuk dibaca).
Atom adalah format default Google Data. Untuk meminta respons dalam format RSS, gunakan parameter /alt=rss/; untuk informasi lebih lanjut, lihat Permintaan kueri.
Saat Anda meminta data dalam format RSS, Data Google akan menyediakan feed (atau representasi resource lainnya) dalam format RSS. Jika tidak ada properti RSS yang setara untuk properti Data Google tertentu, Google Data akan menggunakan properti Atom, melabelinya dengan namespace yang sesuai untuk menunjukkan bahwa properti tersebut merupakan ekstensi untuk RSS.
Catatan: Sebagian besar feed Data Google dalam format Atom menggunakan namespace Atom sebagai namespace default dengan menentukan atribut xmlns pada elemen feed; lihat bagian contoh tentang cara melakukannya. Dengan demikian, contoh dalam dokumen ini tidak secara eksplisit menentukan atom: untuk elemen dalam feed format Atom.
Tabel berikut menampilkan representasi Atom dan RSS dari elemen skema. Semua data yang tidak disebutkan dalam tabel ini diperlakukan sebagai XML biasa dan muncul sama di kedua representasi. Kecuali dinyatakan lain, elemen XML dalam kolom tertentu berada di namespace yang sesuai dengan kolom tersebut. Ringkasan ini menggunakan notasi XPath standar: khususnya, garis miring menampilkan hierarki elemen, dan tanda @ menunjukkan atribut elemen.
Di setiap tabel berikut, item yang disoroti diperlukan.
Tabel berikut menunjukkan elemen feed Data Google:
| Item Skema Feed | Representasi Atom | Representasi RSS |
|---|---|---|
| Judul Feed | /feed/title |
/rss/channel/title |
| ID Feed | /feed/id |
/rss/channel/atom:id |
| Link HTML Feed | /feed/link[@rel="alternate"]\[@type="text/html"]/@href |
/rss/channel/link |
| Deskripsi Feed | /feed/subtitle |
/rss/channel/description |
| Bahasa Feed | /feed/@xml:lang |
/rss/channel/language |
| Hak Cipta Feed | /feed/rights |
/rss/channel/copyright |
| Pengarang Feed |
(Diperlukan dalam kasus tertentu; lihat spesifikasi Atom.) |
/rss/channel/managingEditor |
| Tanggal Pembaruan Terakhir Feed | /feed/updated(Format RFC 3339) |
/rss/channel/lastBuildDate(Format RFC 822) |
| Kategori Feed | /feed/category/@term |
/rss/channel/category |
| Skema Kategori Feed | /feed/category/@scheme |
/rss/channel/category/@domain |
| Pembuat Feed | /feed/generator/feed/generator/@uri |
/rss/channel/generator |
| Ikon Feed | /feed/icon |
/rss/channel/image/url (kecuali jika ada juga logo, dalam kasus ini ikon tidak disertakan dalam feed) |
| Logo Feed | /feed/logo |
/rss/channel/image/url |
Tabel berikut menunjukkan elemen feed hasil penelusuran Data Google. Perlu diketahui bahwa Data Google mengekspos beberapa elemen Respons OpenSearch 1.1 di feed hasil penelusurannya.
| Item Skema Feed Hasil Penelusuran | Representasi Atom | Representasi RSS/OpenSearch |
|---|---|---|
| Jumlah Hasil Penelusuran | /feed/openSearch:totalResults |
/rss/channel/openSearch:totalResults |
| Indeks Awal Hasil Penelusuran | /feed/openSearch:startIndex |
/rss/channel/openSearch:startIndex |
| Jumlah Hasil Penelusuran Per Halaman | /feed/openSearch:itemsPerPage |
/rss/channel/openSearch:itemsPerPage |
Tabel berikut menunjukkan elemen entri Data Google:
| Entri Skema Entri | Representasi Atom | Representasi RSS |
|---|---|---|
| ID entri | /feed/entry/id |
/rss/channel/item/guid |
| ID Versi Entri | Secara opsional, sematkan di EditURI (lihat bagian Serentak optimis di dokumen ini). | — |
| Judul Entri | /feed/entry/title |
/rss/channel/item/title |
| Link Entri | /feed/entry/link |
/rss/channel/item/link/rss/channel/item/enclosure/rss/channel/item/comments |
| Ringkasan Entri |
(Diperlukan dalam kasus tertentu; lihat spesifikasi Atom.) |
/rss/channel/item/atom:summary |
| Konten Entri |
(Jika tidak ada elemen konten, entri harus berisi setidaknya satu elemen |
/rss/channel/item/description |
| Penulis Entri |
(Diperlukan dalam kasus tertentu; lihat spesifikasi Atom.) |
/rss/channel/item/author |
| Kategori Entri | /feed/entry/category/@term |
/rss/channel/item/category |
| Skema Kategori Entri | /feed/entry/category/@scheme |
/rss/channel/item/category/@domain |
| Tanggal Publikasi Entri | /feed/entry/published(RFC 3339) |
/rss/channel/item/pubDate(RFC 822) |
| Tanggal Pembaruan Entri | /feed/entry/updated(RFC 3339) |
/rss/channel/item/atom:updated(RFC 3339) |
Kueri
Bagian ini menjelaskan cara menggunakan sistem kueri.
Prinsip desain model kueri
Model kueri sengaja dibuat sangat sederhana. Prinsip dasarnya adalah:
- Kueri dinyatakan sebagai URI HTTP, bukan sebagai header HTTP atau sebagai bagian dari payload. Salah satu manfaat pendekatan ini adalah Anda dapat menautkan ke kueri.
- Predikat tercakup dalam satu item. Oleh karena itu, tidak ada cara untuk mengirimkan kueri korelasi seperti "temukan semua email dari orang-orang yang mengirimi saya setidaknya 10 email hari ini".
- Kumpulan properti yang dapat predikat kueri sangat terbatas; sebagian besar kueri hanyalah kueri penelusuran teks lengkap.
- Pengurutan hasil bergantung pada implementasi.
- Protokol tersebut dapat diperluas secara alami. Jika ingin mengekspos predikat atau pengurutan tambahan dalam layanan, Anda dapat melakukannya dengan mudah melalui pengantar parameter baru.
Permintaan kueri
Klien mengkueri layanan Data Google dengan mengeluarkan permintaan GET HTTP. URI kueri terdiri dari URI resource (disebut FeedURI di Atom) yang diikuti dengan parameter kueri. Sebagian besar parameter kueri direpresentasikan sebagai parameter URL ?name=value[&...] tradisional. Parameter kategori ditangani secara berbeda; lihat di bawah ini.
Misalnya, jika FeedURI adalah http://www.example.com/feeds/jo, Anda mungkin mengirim kueri dengan URI berikut:
http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z
Layanan Data Google mendukung GET Kondisional HTTP. Keduanya menetapkan header respons Last-Modified berdasarkan nilai elemen <atom:updated> dalam feed atau entri yang ditampilkan. Klien dapat mengirimkan kembali nilai ini sebagai nilai header permintaan If-Modified-Since untuk menghindari pengambilan konten lagi jika belum berubah. Jika konten tidak berubah sejak waktu If-Modified-Since, layanan Data Google akan menampilkan respons HTTP 304 (Not Modified).
Layanan Data Google harus mendukung kueri kategori dan kueri alt; dukungan untuk parameter lainnya bersifat opsional. Meneruskan parameter standar yang tidak dipahami oleh layanan tertentu akan menghasilkan respons 403 Forbidden. Meneruskan parameter non-standar yang tidak didukung akan menghasilkan respons 400 Bad Request. Untuk mengetahui informasi tentang kode status lainnya, lihat bagian Kode status HTTP pada dokumen ini.
Parameter kueri standar diringkas dalam tabel berikut. Semua nilai parameter harus dienkode URL.
| Parameter | Arti | Catatan |
|---|---|---|
q |
String kueri teks lengkap |
|
/-/category |
Filter kategori |
|
category |
Filter kategori |
|
author |
Penulis entri |
|
alt |
Jenis representasi alternatif |
|
updated-min, updated-max |
Batas pada tanggal pembaruan entri |
|
published-min, published-max |
Batas pada tanggal publikasi entri |
|
start-index |
Indeks berbasis 1 dari hasil pertama yang akan diambil |
|
max-results |
Jumlah maksimum hasil yang akan diambil | Untuk layanan apa pun yang memiliki nilai max-results default (untuk membatasi ukuran feed default), Anda dapat menentukan jumlah yang sangat besar jika ingin menerima seluruh feed. |
| ID entri | ID entri tertentu yang akan diambil |
|
Tentang kueri kategori
Kami memutuskan untuk menentukan format yang sedikit tidak biasa untuk kueri kategori. Sebagai ganti kueri seperti berikut:
http://example.com/jo?category=Fritz&category=2006
kami menggunakan:
http://example.com/jo/-/Fritz/2006
Pendekatan ini mengidentifikasi resource tanpa menggunakan parameter kueri, dan menghasilkan URI yang lebih bersih. Kami memilih pendekatan ini untuk kategori karena kami merasa bahwa kueri kategori akan menjadi kueri yang paling umum.
Kekurangan pendekatan ini adalah Anda harus menggunakan /-/ dalam kueri kategori sehingga layanan Data Google dapat membedakan kueri kategori dari URI resource lainnya, seperti http://example.com/jo/MyPost/comments.
Respons kueri
Kueri menampilkan feed Atom, entri Atom, atau feed RSS, bergantung pada parameter permintaan.
Hasil kueri berisi elemen OpenSearch berikut langsung di bawah elemen <feed> atau elemen <channel> (bergantung pada apakah hasilnya adalah Atom atau RSS):
openSearch:totalResults- Jumlah total hasil penelusuran untuk kueri (tidak harus semua ada di feed hasil).
openSearch:startIndex- Indeks berbasis 1 dari hasil pertama.
openSearch:itemsPerPage- Jumlah maksimum item yang muncul di satu halaman. Hal ini memungkinkan klien untuk membuat link langsung ke kumpulan halaman berikutnya. Namun, untuk kemungkinan kesalahan dalam menggunakan nomor ini, lihat catatan mengenai
start-indexpada tabel di bagian Permintaan kueri.
Feed dan entri respons Atom juga dapat menyertakan salah satu elemen Atom dan Data Google berikut (serta yang lainnya yang tercantum dalam spesifikasi Atom):
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>- Menentukan URI yang dapat diambil oleh feed Atom lengkap.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>- Menentukan PostURI feed Atom (tempat entri baru dapat diposting).
<link rel="self" type="..." href="..."/>- Berisi URI resource ini. Nilai atribut
typebergantung pada format yang diminta. Jika tidak ada data yang berubah untuk sementara, pengiriman GET lain ke URI ini akan menampilkan respons yang sama. <link rel="previous" type="application/atom+xml" href="..."/>- Menentukan URI dari bagian sebelumnya dari kumpulan hasil kueri ini, jika dipotong.
<link rel="next" type="application/atom+xml" href="..."/>- Menentukan URI bagian berikutnya dari kumpulan hasil kueri ini, jika dipotong.
<link rel="edit" type="application/atom+xml" href="..."/>- Menentukan EditURI entri Atom (tempat Anda mengirim entri yang diperbarui).
Berikut adalah contoh isi respons yang merespons kueri penelusuran:
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
<id>http://www.example.com/feed/1234.1/posts/full</id>
<updated>2005-09-16T00:42:06Z</updated>
<title type="text">Books and Romance with Jo and Liz</title>
<link rel="alternate" type="text/html" href="http://www.example.net/"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="http://schemas.google.com/g/2005#post"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="self" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<generator version="1.0"
uri="http://www.example.com">Example Generator Engine</generator>
<openSearch:totalResults>2</openSearch:totalResults>
<openSearch:startIndex>0</openSearch:startIndex>
<entry>
<id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id>
<published>2005-01-09T08:00:00Z</published>
<updated>2005-01-09T08:00:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1009</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
<entry>
<id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id>
<published>2005-01-07T08:00:00Z</published>
<updated>2005-01-07T08:02:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1007</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
</feed>
Jika feed yang diminta dalam format Atom, jika tidak ada parameter kueri yang ditentukan, dan jika hasilnya tidak berisi semua entri, elemen berikut akan dimasukkan ke feed tingkat teratas: <link rel="next" type="application/atom+xml" href="..."/>. Titik ini mengarah ke feed yang berisi kumpulan entri berikutnya. Set berikutnya berisi elemen <link rel="previous" type="application/atom+xml" href="..."/> yang sesuai. Dengan mengikuti semua link berikutnya, klien dapat mengambil semua entri dari feed.
Kode status HTTP
Tabel berikut menjelaskan arti berbagai kode status HTTP dalam konteks layanan Data Google.
| Kode | Penjelasan |
|---|---|
| 200 Oke | Tidak ada kesalahan. |
| 201 DIBUAT | Pembuatan resource berhasil. |
| 304 TIDAK DIUBAH | Resource belum berubah sejak waktu yang ditentukan di header If-Modified-Since permintaan. |
| 400 PERMINTAAN BURUK | Header atau URI permintaan tidak valid, atau parameter non-standar tidak didukung. |
| 401 TIDAK DIBERIKAN | Dibutuhkan otorisasi. |
| 403 DILARANG | Parameter standar tidak didukung, atau autentikasi atau otorisasi gagal. |
| 404 TIDAK DITEMUKAN | Resource (seperti feed atau entri) tidak ditemukan. |
| 409 KONFLIK | Nomor versi yang ditentukan tidak cocok dengan nomor versi terbaru resource. |
| KESALAHAN SERVER INTERNAL 500 | Error internal. Ini adalah kode default yang digunakan untuk semua error yang tidak dikenal. |
Serentak optimis (pembuatan versi)
Terkadang penting untuk memastikan bahwa beberapa klien tidak menimpa perubahan satu sama lain secara tidak sengaja. Cara ini paling mudah dilakukan dengan memastikan bahwa versi entri yang dimodifikasi oleh klien saat ini sama dengan versi yang digunakan klien untuk memodifikasinya. Jika klien kedua melakukan update sebelum klien pertama melakukannya, update klien pertama akan ditolak, karena klien pertama tidak lagi mendasarkan modifikasinya pada versi terbaru.
Di feed Data Google yang mendukung pembuatan versi, kami mencapai semantik ini dengan menambahkan ID versi ke EditURI setiap entri. Perhatikan bahwa hanya EditURI yang terpengaruh, bukan ID entri. Dalam skema ini, setiap update akan mengubah EditURI entri, sehingga menjamin bahwa update berikutnya berdasarkan versi aslinya akan gagal. Tentu saja, penghapusan identik dengan pembaruan sehubungan dengan fitur ini; jika Anda mengirim penghapusan dengan nomor versi lama, penghapusan akan gagal.
Tidak semua feed Data Google mendukung konkurensi optimistis. Dalam feed yang mendukungnya, jika server mendeteksi konflik versi pada PUT atau DELETE, server akan merespons dengan 409 Conflict. Isi respons memuat status entri saat ini (dokumen entri Atom). Klien tersebut disarankan untuk menyelesaikan konflik dan mengirimkan ulang permintaan tersebut, menggunakan EditURI dari respons 409.
Catatan motivasi dan desain
Pendekatan optimis serentak ini memungkinkan kami menerapkan semantik yang diinginkan tanpa memerlukan markup baru untuk ID versi, yang membuat respons Google Data kompatibel dengan endpoint Atom Data non-Google.
Daripada menentukan ID versi, kita dapat memilih untuk melihat stempel waktu update di setiap entri (/atom:entry/atom:updated). Namun, ada dua masalah saat menggunakan stempel waktu update:
- Ini hanya berfungsi untuk pembaruan dan bukan penghapusan.
- Pengujian ini memaksa aplikasi untuk menggunakan nilai tanggal/waktu sebagai ID versi, yang akan mempersulit penyesuaian Data Google di atas banyak penyimpanan data yang sudah ada.
Autentikasi
Saat klien mencoba mengakses layanan, klien mungkin perlu memberikan kredensial pengguna ke layanan, untuk menunjukkan bahwa pengguna memiliki wewenang untuk melakukan tindakan yang dimaksud.
Pendekatan yang harus digunakan klien untuk autentikasi bergantung pada jenis klien:
- Aplikasi desktop harus menggunakan sistem autentikasi khusus Google yang disebut Autentikasi Akun untuk Aplikasi Terinstal (juga dikenal sebagai "ClientLogin"). (Klien berbasis web tidak boleh menggunakan sistem ini.)
- Klien berbasis web, seperti front-end pihak ketiga ke layanan Google Data, harus menggunakan sistem autentikasi khusus Google yang disebut Proxy Autentikasi Akun untuk Aplikasi Berbasis Web (juga dikenal sebagai "AuthSub").
Di sistem ClientLogin, klien desktop akan meminta kredensial pengguna, lalu mengirimkan kredensial tersebut ke sistem autentikasi Google.
Jika autentikasi berhasil, sistem autentikasi akan menampilkan token yang kemudian digunakan klien (di header Otorisasi HTTP) saat permintaan Google Data dikirim.
Jika autentikasi gagal, server akan menampilkan kode status 403 Forbidden, beserta header WWW-Authenticate yang berisi verifikasi yang berlaku untuk autentikasi.
Sistem AuthSub berfungsi mirip, tetapi bukan meminta kredensial pengguna, tetapi menghubungkan pengguna ke layanan Google yang meminta kredensial. Layanan tersebut kemudian menampilkan token yang bisa digunakan aplikasi web; keuntungan dari pendekatan ini adalah Google (bukan front end web) menangani dan menyimpan kredensial pengguna dengan aman.
Untuk mengetahui detail tentang sistem autentikasi ini, baca Ringkasan Autentikasi Data Google atau dokumentasi Autentikasi Akun Google.
Status sesi
Banyak penerapan logika bisnis memerlukan loyalitas sesi—melacak status sesi pengguna.
Google melacak status sesi dengan dua cara: menggunakan cookie dan menggunakan token yang dapat dikirim sebagai parameter kueri. Kedua metode tersebut memberikan efek yang sama. Sebaiknya klien mendukung salah satu metode pelacakan status sesi berikut (salah satu metode ini sudah cukup). Jika klien tidak mendukung salah satu metode tersebut, layanan klien Google akan tetap berfungsi dengan layanan Data Google, tetapi performanya mungkin lebih buruk dibandingkan klien yang mendukung metode ini. Khususnya, jika klien tidak mendukung metode ini, setiap permintaan akan menghasilkan pengalihan, sehingga setiap permintaan (dan data apa pun yang terkait) dikirim ke server dua kali, yang memengaruhi performa klien dan server.
Library klien Google menangani status sesi untuk Anda, jadi jika menggunakan library, Anda tidak perlu melakukan apa pun untuk mendapatkan dukungan status sesi.
Referensi lainnya
Dokumen pihak ketiga berikut mungkin berguna untuk Anda:
- Perbandingan Atom dan RSS dari satu sama lain
- Ringkasan Atom dari IBM
- Ekstensi Dublin Core ke RSS
- Definisi metode HTTP 1.1; spesifikasi untuk
GET,POST,PUT, danDELETE - Definisi kode status HTTP 1.1
- Cara Membuat Protokol REST
- Membuat Layanan Web dengan Cara REST
- Pengantar Teknis XML
- Namespace XML berdasarkan Contoh