Halaman ini diterjemahkan oleh Cloud Translation API.

Referensi Protokol

Peringatan: Halaman ini membahas API lama Google, yaitu Google Data API; halaman ini hanya relevan dengan API yang tercantum dalam direktori Google Data API, banyak di antaranya telah diganti dengan API yang lebih baru. Untuk informasi tentang API baru tertentu, lihat dokumentasi API baru. Untuk informasi tentang memberi otorisasi permintaan dengan API baru, lihat Autentikasi dan Otorisasi Akun Google.

Dokumen ini menjelaskan Google Data Protocol yang digunakan oleh banyak Google API, termasuk informasi tentang tampilan kueri, tampilan hasil, dan sebagainya.

Untuk informasi selengkapnya tentang Protokol Data Google, lihat halaman ringkasan Panduan Developer dan dokumen Dasar-Dasar Protokol.

Audiens

Dokumen ini ditujukan bagi siapa saja yang ingin memahami detail format XML dan protokol yang digunakan oleh API yang menerapkan Protokol Data Google.

Jika hanya ingin menulis kode yang menggunakan salah satu API ini, Anda tidak perlu mengetahui detail tersebut; sebagai gantinya, Anda dapat menggunakan library klien bahasa tertentu.

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 Protokol Data Google
coding menggunakan protokol tanpa menggunakan library klien 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 Google Data Protocol 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 Google Data Protocol.

Format dokumen

Protokol Data Google dan Atom memiliki 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.

Atom adalah format default untuk Protokol Data Google. Untuk meminta respons dalam format lain, gunakan parameter kueri alt; untuk mengetahui informasi selengkapnya, lihat Permintaan kueri.

Catatan: Sebagian besar feed Google Data Protocol dalam format Atom menggunakan namespace Atom sebagai namespace default dengan menentukan atribut xmlns pada elemen feed, seperti yang terlihat pada contoh yang diberikan dalam Dasar-Dasar Protokol. Dengan demikian, contoh dalam dokumen ini tidak secara eksplisit menentukan atom: untuk elemen dalam feed format Atom.

Tabel berikut menunjukkan representasi Atom dari elemen skema. Semua data yang tidak disebutkan dalam tabel ini diperlakukan sebagai XML biasa. Kecuali dinyatakan lain, elemen XML dalam kolom tertentu berada di namespace Atom.

Catatan: 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 Google Data Protocol:

Item Skema Feed	Representasi Atom
Judul Feed	`/feed/title`
ID Feed	`/feed/id`
Link HTML Feed	`/feed/link[@rel="alternate"]`\ `[@type="text/html"]/@href`
Deskripsi Feed	`/feed/subtitle`
Bahasa Feed	`/feed/@xml:lang`
Hak Cipta Feed	`/feed/rights`
Pengarang Feed	`/feed/author/name` `/feed/author/email` (Diperlukan dalam kasus tertentu; lihat spesifikasi Atom.)
Tanggal Pembaruan Terakhir Feed	`/feed/updated` (Format RFC 3339)
Kategori Feed	`/feed/category/@term`
Skema Kategori Feed	`/feed/category/@scheme`
Pembuat Feed	`/feed/generator` `/feed/generator/@uri`
Ikon Feed	`/feed/icon`
Logo Feed	`/feed/logo`

Tabel berikut menampilkan elemen feed hasil penelusuran Google Data Protocol. Perlu diperhatikan bahwa protokol ini mengekspos beberapa elemen Respons OpenSearch 1.1 di feed hasil penelusuran.

Item Skema Feed Hasil Penelusuran	Representasi Atom
Jumlah Hasil Penelusuran	`/feed/openSearch:totalResults`
Indeks Awal Hasil Penelusuran	`/feed/openSearch:startIndex`
Jumlah Hasil Penelusuran Per Halaman	`/feed/openSearch:itemsPerPage`

Tabel berikut menunjukkan elemen entri Google Data Protocol:

Entri Skema Entri	Representasi Atom
ID entri	`/feed/entry/id`
Judul Entri	`/feed/entry/title`
Link Entri	`/feed/entry/link`
Ringkasan Entri	`/feed/entry/summary` (Diperlukan dalam kasus tertentu; lihat spesifikasi Atom.)
Konten Entri	`/feed/entry/content` (Jika tidak ada elemen konten, entri harus berisi setidaknya satu elemen `<link rel="alternate">`.)
Penulis Entri	`/feed/entry/author/name` `/feed/entry/author/email` (Diperlukan dalam kasus tertentu; lihat spesifikasi Atom.)
Kategori Entri	`/feed/entry/category/@term`
Skema Kategori Entri	`/feed/entry/category/@scheme`
Tanggal Publikasi Entri	`/feed/entry/published` (RFC 3339)
Tanggal Pembaruan Entri	`/feed/entry/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 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

Protokol Data Google mendukung GET Kondisional HTTP. API yang menerapkan protokol 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 akan menampilkan respons HTTP 304 (Not Modified).

API yang menerapkan Protokol Data Google harus mendukung 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
`alt`	Jenis representasi alternatif	Jika Anda tidak menentukan parameter `alt`, layanan akan menampilkan feed Atom. Fungsi ini setara dengan `alt=atom`. `alt=rss` menampilkan feed hasil RSS 2.0 (hanya untuk dibaca). Saat Anda meminta data dari layanan dalam format RSS, layanan tersebut akan menyediakan feed (atau representasi resource lainnya) dalam format RSS. Jika tidak ada properti RSS yang setara untuk properti Data API tertentu, layanan akan menggunakan properti Atom, melabelinya dengan namespace yang sesuai untuk menunjukkan bahwa properti tersebut merupakan ekstensi untuk RSS. `alt=json` menampilkan representasi JSON dari feed. Informasi selengkapnya `alt=json-in-script` Meminta respons yang menggabungkan JSON dalam tag skrip. Informasi selengkapnya `alt=atom-in-script` Meminta respons Atom yang menggabungkan string XML dalam tag skrip. `alt=rss-in-script` Meminta respons RSS yang menggabungkan string XML dalam tag skrip. `alt=atom-service` Meminta dokumen layanan Atom yang menjelaskan feed.
`author`	Penulis entri	Layanan akan menampilkan entri yang nama penulis dan/atau alamat emailnya cocok dengan string kueri Anda.
`category`	Filter kueri kategori	Cara alternatif untuk melakukan filter kategori. Kedua metode tersebut setara. Untuk melakukan `OR` antar-istilah, gunakan karakter pipa (\|), dienkode URL sebagai `%7C`. Misalnya: `http://www.example.com/feeds?category=Fritz%7CLaurie` menampilkan entri yang cocok dengan salah satu kategori. Untuk melakukan `AND` antar-istilah, gunakan karakter koma (,). Misalnya: `http://www.example.com/feeds?category=Fritz,Laurie` menampilkan entri yang cocok dengan kedua kategori.
`/-/category`	Filter kueri kategori	Cantumkan setiap kategori seolah-olah merupakan bagian dari URI resource, dalam bentuk `/categoryname/`—ini adalah pengecualian untuk formulir `name=value` biasa. Cantumkan semua kategori sebelum parameter kueri lainnya. Awali kategori pertama dengan `/-/` untuk memperjelas bahwa kategori tersebut adalah kategori. Misalnya, jika feed Jo memiliki kategori untuk entri tentang Fritz, Anda dapat meminta entri tersebut seperti ini: `http://www.example.com/feeds/jo/-/Fritz`. Hal ini memungkinkan implementasi untuk membedakan URI kueri predikat kategori dengan URI resource. Anda dapat membuat kueri di beberapa kategori dengan mencantumkan beberapa parameter kategori, yang dipisahkan dengan garis miring. Layanan ini menampilkan semua entri yang cocok dengan semua kategori (seperti menggunakan `AND` antar-istilah). Misalnya: `http://www.example.com/feeds/jo/-/Fritz/Laurie` menampilkan entri yang cocok dengan kedua kategori tersebut. Untuk melakukan `OR` di antara istilah, gunakan karakter pipa (`\|`), yang dienkode ke URL sebagai `%7C`. Misalnya: `http://www.example.com/feeds/jo/-/Fritz%7CLaurie` menampilkan entri yang cocok dengan salah satu kategori. Entri cocok dengan kategori yang ditentukan jika entri berada dalam kategori yang memiliki istilah atau label yang cocok, seperti yang ditentukan dalam spesifikasi Atom. (Secara kasar, "term" adalah string internal yang digunakan oleh software untuk mengidentifikasi kategori, sedangkan "label" adalah string yang dapat dibaca manusia yang ditampilkan kepada pengguna di antarmuka pengguna.) Untuk mengecualikan entri yang cocok dengan kategori tertentu, gunakan formulir `/-categoryname/`. Untuk membuat kueri kategori yang memiliki skema—seperti `<category scheme="urn:google.com" term="public"/>`—Anda harus menempatkan skema dalam tanda kurung kurawal sebelum nama kategori. Misalnya: `/{urn:google.com}public`. Jika skema berisi karakter garis miring (`/`), skema harus dienkode ke URL sebagai `%2F`. Untuk mencocokkan kategori yang tidak memiliki skema, gunakan sepasang tanda kurung kurawal kosong. Jika Anda tidak menentukan tanda kurung kurawal, kategori dalam skema apa pun akan cocok. Fitur di atas dapat digabungkan. Misalnya: `/A%7C-{urn:google.com}B/-C` berarti `(A OR (NOT B)) AND (NOT C)`.
IDmasuk	ID entri tertentu yang akan diambil	Jika menentukan ID entri, Anda tidak dapat menentukan parameter lainnya. Bentuk ID entri ditentukan oleh layanan. Tidak seperti kebanyakan parameter kueri lainnya, ID entri ditetapkan sebagai bagian dari URI, bukan sebagai pasangan name=value. Contoh: `http://www.example.com/feeds/jo/entry1`.
`fields`	Filter respons	Menampilkan kolom yang diminta saja, bukan representasi resource lengkap. Misalnya: http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit'])) Saat menerima permintaan ini, server akan menampilkan respons yang hanya berisi elemen link dan entri untuk feed. Selain itu, elemen entri yang ditampilkan adalah entri parsial yang hanya berisi hubungan link ETag, ID, updated, dan edit. Nilai kolom harus berenkode URL, seperti pada semua nilai parameter kueri. Untuk mengetahui informasi selengkapnya, lihat bagian Respons parsial. Parameter ini saat ini merupakan fitur eksperimental.
`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.
`prettyprint`	Menampilkan respons XML dengan identifikasi dan jeda baris	Jika `prettyprint=true`, XML yang ditampilkan oleh server akan dapat dibaca manusia (dicetak penuh). Default: `prettyprint=false`
`published-min`, `published-max`	Batas pada tanggal publikasi entri	Gunakan format stempel waktu RFC 3339. Contoh: `2005-08-09T10:57:00-08:00`. Batas bawah bersifat inklusif, sedangkan batas atasnya bersifat eksklusif.
`q`	String kueri teks lengkap	Saat membuat kueri, buat daftar istilah penelusuran yang dipisahkan dengan spasi, dalam bentuk `q=term1 term2 term3`. (Seperti semua nilai parameter kueri, spasi harus dienkode URL.) Layanan ini menampilkan semua entri yang cocok dengan semua istilah penelusuran (seperti menggunakan `AND` di antara istilah). Seperti penelusuran web Google, layanan menelusuri kata lengkap (dan kata terkait dengan kata dasar yang sama), bukan substring. Untuk menelusuri frasa yang tepat, apit frasa tersebut dengan tanda kutip: `q="exact phrase".` Untuk mengecualikan entri yang cocok dengan istilah tertentu, gunakan formulir `q=-term`. Penelusuran tidak peka huruf besar/kecil. Contoh: untuk menelusuri semua entri yang berisi frasa yang persis "Elizabeth Bennet" dan kata "Darcy", tetapi tidak berisi kata "Austen", gunakan kueri berikut: `?q="Elizabeth Bennet" Darcy -Austen`
`start-index`	Indeks berbasis 1 dari hasil pertama yang akan diambil	Perhatikan bahwa ini bukan mekanisme kursor umum. Jika pertama-tama Anda mengirim kueri dengan `?start-index=1&max-results=10`, lalu mengirim kueri lain dengan `?start-index=11&max-results=10`, layanan tidak dapat menjamin bahwa hasilnya setara dengan `?start-index=1&max-results=20`, karena penyisipan dan penghapusan dapat terjadi di antara kedua kueri tersebut.
`strict`	Pemeriksaan parameter kueri yang ketat	Setel `strict=true` untuk memverifikasi bahwa setiap parameter kueri Anda dikenali oleh layanan. Error akan ditampilkan jika parameter tidak dikenali. Default: `strict=false`
`updated-min`, `updated-max`	Batas pada tanggal pembaruan entri	Gunakan format stempel waktu RFC 3339. Contoh: `2005-08-09T10:57:00-08:00`. Batas bawah bersifat inklusif, sedangkan batas atasnya bersifat eksklusif. Dalam beberapa kasus (seperti saat menggunakan Calendar Data API v2.1 atau yang lebih baru), menetapkan `updated-min` yang terlalu lama akan menyebabkan status HTTP 410 (Hilang) ditampilkan.

Tentang kueri kategori

Kami memutuskan untuk memberikan format yang sedikit tidak biasa untuk kueri kategori. Daripada mengharuskan kueri seperti berikut:

http://example.com/jo?category=Fritz&category=2006

kami memungkinkan untuk 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 salah satu kueri yang paling umum.

Kekurangan pendekatan ini adalah Anda harus menggunakan /-/ dalam jenis kueri kategori ini, sehingga layanan 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-index pada tabel di bagian Permintaan kueri.

Feed dan entri respons Atom juga dapat menyertakan salah satu elemen Atom dan Data API berikut (serta elemen 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 type bergantung 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="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <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 gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
    <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 gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
    <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 Data API.

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.
410 JADI TIDAK ADA	Histori perubahan yang diminta tidak lagi tersedia di server. Lihat dokumentasi khusus layanan untuk detail selengkapnya.
KESALAHAN SERVER INTERNAL 500	Error internal. Ini adalah kode default yang digunakan untuk semua error server yang tidak dikenal.

Pembuatan versi resource (ETag)

Terkadang Anda perlu merujuk ke versi tertentu dari entri tertentu.

Hal ini penting dalam dua kasus khususnya:

Melakukan "pengambilan bersyarat", saat klien meminta entri, dan server mengirim entri hanya jika entri telah diubah sejak terakhir kali klien memintanya.
Memastikan beberapa klien tidak menimpa perubahan satu sama lain secara tidak sengaja. Data API melakukan hal ini dengan membuat pembaruan dan penghapusan gagal jika klien menentukan ID versi lama untuk entri tersebut.

Google Data API menangani kedua kasus ini menggunakan ETag, yang merupakan bagian standar dari HTTP.

ETag adalah ID yang menentukan versi entri tertentu. Server melampirkan ETag ke elemen feed dan entri yang dikirimkan ke klien. Jika entri atau feed berubah, ETag-nya juga akan berubah.

Google Data API menyediakan ETag di dua tempat: di header HTTP ETag, dan di atribut gd:etag dari elemen <feed> dan <entry>.

Di Google Data API, ETag biasanya berupa string huruf dan angka, terkadang juga mencakup tanda hubung dan titik. String ini biasanya diapit tanda kutip. (Tanda kutip adalah bagian dari ETag.) Misalnya, berikut adalah ETag dari entri Data API: "S0wCTlpIIip7ImA0X0QI".

Ada dua jenis ETag: kuat dan lemah. ETag yang kuat mengidentifikasi versi tertentu dari entri tertentu dan dapat digunakan untuk menghindari penimpaan perubahan klien lain. ETag yang lemah, dalam konteks Google Data API, hanya digunakan untuk pengambilan bersyarat. ETag yang lemah selalu dimulai dengan W/. Misalnya: W/"D08FQn8-eil7ImA9WxZbFEw.".

Tidak semua Google Data API mendukung ETag yang kuat. Untuk yang melakukannya, ETag yang kuat hanya digunakan untuk entri; ETag di feed selalu lemah.

Berikut adalah contoh feed (termasuk beberapa header HTTP) yang diambil dari layanan yang mendukung ETag yang kuat:

GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  ...
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    ...
  </entry>
</feed>

Library klien yang mendukung Data API versi 2 menangani ETag secara transparan. Informasi berikut ditujukan bagi klien yang tidak menggunakan library klien, dan untuk pembaca yang tertarik dengan cara penanganan versi pada tingkat protokol.

Catatan: Untuk mengetahui informasi tentang sistem pembuatan versi resource yang digunakan dalam Data API versi 1.0, lihat panduan referensi 1.0.

Pengambilan bersyarat

Jika ingin mengambil entri yang telah diambil sebelumnya, Anda dapat meningkatkan efisiensi dengan memberi tahu server untuk mengirim entri hanya jika entri telah diubah sejak terakhir kali Anda mengambilnya.

Untuk melakukan pengambilan bersyarat ini, kirim permintaan GET HTTP yang menyertakan header If-None-Match HTTP. Di header, tentukan ETag entri.

Berikut adalah contoh header If-None-Match:

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

Saat menerima permintaan ini, server akan memeriksa apakah entri yang Anda minta memiliki ETag yang sama dengan ETag yang Anda tentukan. Jika ETag cocok, entri tidak berubah, dan server menampilkan kode status Not Modified HTTP 304.

Jika ETag tidak cocok, entri telah diubah sejak terakhir kali Anda memintanya, dan server menampilkan entri.

Memperbarui entri

Cara termudah untuk menghindari penimpaan perubahan klien lain adalah agar server memastikan bahwa saat klien mengirim entri yang diperbarui, versi entri yang dimulai dengan klien sama dengan versi saat ini yang disimpan oleh server. Jika klien kedua melakukan update sebelum klien Anda melakukan update, update klien tersebut akan ditolak, karena klien tidak lagi mendasarkan modifikasinya pada versi terbaru.

Ketika klien Anda mengambil data dari layanan yang mendukung ETag yang kuat, setiap entri memiliki ETag yang berfungsi sebagai ID versi unik untuk versi entri tersebut.

Catatan: Mengupdate menggunakan ETag hanya akan berfungsi dengan ETag yang kuat. Untuk layanan yang menyediakan ETag yang lemah, semua update akan berhasil, terlepas dari apakah orang lain telah memperbarui entri tersebut sejak Anda mengambilnya; update terbaru selalu menimpa update sebelumnya. Jadi, jangan mengirim ETag yang lemah saat mengupdate atau menghapus; Anda akan mendapatkan pesan error jika mengupdatenya.

Jadi, saat klien mengirim update ke layanan ETag yang kuat, klien harus menentukan versi entri yang diupdate. Ada dua cara untuk melakukannya:

Gunakan header HTTP If-Match.
Gunakan atribut gd:etag dalam elemen <atom:entry>.

Sebaiknya gunakan pendekatan If-Match jika memungkinkan.

Untuk memperbarui entri menggunakan If-Match, mulai dengan mendapatkan entri yang diperbarui. Buat perubahan yang diinginkan pada entri, lalu buat permintaan PUT baru yang berisi entri yang diubah. (Untuk detail URL yang akan digunakan, lihat dokumentasi khusus layanan.)

Sebelum mengirim PUT, tambahkan header If-Match HTTP yang berisi ETag dari entri asli:

If-Match: "S0wCTlpIIip7ImA0X0QI"

Lalu kirim permintaan PUT.

Jika update berhasil, server akan menampilkan kode status 200 OK HTTP, dan salinan entri yang diperbarui.

Jika update gagal karena ETag yang ditentukan tidak cocok dengan ETag saat ini pada entri (yang menyiratkan bahwa entri telah berubah di server sejak terakhir kali Anda mengambilnya), server akan menampilkan kode status 412 Precondition Failed HTTP.

Jika Anda tidak dapat menulis header HTTP dengan mudah, atau memiliki alasan lain untuk menghindari penggunaan header If-Match, Anda dapat menggunakan atribut gd:etag sebagai gantinya.

Jika Anda tidak mengirimkan header If-Match, server akan menggunakan nilai atribut gd:etag entri yang diperbarui sebagai nilai If-Match tersirat.

Untuk mengganti sistem pembuatan versi dan mengupdate entri, terlepas dari apakah orang lain telah mengupdatenya sejak Anda mengambilnya atau tidak, gunakan If-Match: * sebagai ganti menentukan ETag di header.

Untuk mengetahui informasi tentang layanan yang mendukung ETag yang kuat, lihat Panduan Migrasi.

Menghapus entri

Menghapus entri yang menggunakan ETag yang kuat sangat mirip dengan mengupdatenya.

Untuk menghapus entri yang memiliki ETag yang kuat, pertama-tama Anda mengambil entri yang ingin dihapus, lalu kirimkan permintaan DELETE ke URL edit entri tersebut.

Jika ingin memastikan bahwa Anda tidak menghapus entri yang telah diubah oleh klien lain sejak mengambilnya, sertakan header If-Match HTTP yang berisi nilai ETag entri asli.

Jika Anda ingin mengganti sistem pembuatan versi dan menghapus entri, terlepas dari apakah orang lain telah memperbaruinya sejak Anda mengambilnya atau tidak, gunakan If-Match: * sebagai ganti menentukan ETag di header.

Jika entri tidak memiliki ETag yang kuat, permintaan DELETE akan selalu berhasil.

Respons sebagian (Eksperimental)

Secara default, server mengirimkan kembali representasi lengkap resource target setelah memproses permintaan. Respons sebagian memungkinkan Anda meminta hanya elemen atau atribut yang diminati, bukan representasi resource lengkap. Hal ini memungkinkan aplikasi klien menghindari transfer, penguraian, dan penyimpanan kolom yang tidak diperlukan, sehingga dapat menggunakan resource jaringan, CPU, dan memori secara lebih efisien.

Untuk mengetahui apakah respons parsial tersedia untuk produk yang Anda gunakan, lihat dokumentasi API.

Untuk meminta respons parsial, gunakan parameter kueri fields untuk menentukan elemen atau atribut yang ingin Anda tampilkan. Berikut contohnya:

http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))

Respons server hanya berisi elemen link dan entri untuk feed; elemen entri hanya berisi informasi ETag, ID, telah diperbarui, dan link untuk diedit. Sintaksis parameter kueri fields dibahas di bagian berikut. Untuk mengetahui detail selengkapnya tentang respons, lihat Menangani respons sebagian.

Catatan: Anda dapat menggunakan parameter kueri fields dengan permintaan apa pun yang menampilkan data. Selain GET, ini termasuk POST, dan PUT (serta PATCH, yang digunakan untuk membuat pembaruan sebagian). Namun, parameter kueri fields hanya memengaruhi data respons; parameter tersebut tidak memengaruhi data yang harus Anda berikan atau kolom yang diperbarui atau dibuat.

Ringkasan sintaksis parameter kolom

Format parameter value kueri fields didasarkan pada sintaksis XPath; tetapi hanya mendukung subset ekspresi XPath yang valid. Sintaksis yang didukung diringkas di bawah, dan contoh tambahan diberikan di bagian berikut.

Gunakan daftar yang dipisahkan koma untuk memilih beberapa kolom.
Gunakan a/b untuk memilih elemen b yang bertingkat di dalam elemen a; gunakan a/b/c untuk memilih elemen c yang disarangkan di dalam b.
Gunakan awalan '@' untuk mengidentifikasi atribut dengan nama yang diberikan; hapus awalan '@' untuk merujuk ke elemen.
Terapkan kondisi kolom untuk memilih elemen yang cocok dengan kriteria tertentu, dengan menempatkan ekspresi dalam tanda kurung "[ ]" setelah elemen yang ingin Anda batasi.
Misalnya, fields=entry[author/name='Elizabeth'] hanya menampilkan entri feed yang penulisnya adalah Elizabeth.
Tentukan sub-pemilih kolom untuk meminta atribut atau sub-elemen tertentu saja, dengan menempatkan ekspresi dalam tanda kurung "( )" setelah elemen yang dipilih.
Misalnya, fields=entry(id,author/email) hanya menampilkan ID dan email penulis untuk setiap entri feed.
Anda dapat membatasi string menggunakan tanda kutip ganda atau tunggal.

Untuk menghindari tanda kutip ganda atau tunggal, ulangi tanda kutip. Misalnya, """Hello,"" he said" menghasilkan string "Hello," he said, dan '''Hello,'' he said' menghasilkan string 'Hello,' he said.
Anda dapat menggunakan karakter pengganti dalam pilihan kolom.
Misalnya, entry/gd:* memilih semua elemen turunan dari entri di namespace gd, dan entry/@gd:* memilih atribut elemen turunan di namespace yang sama.

Parameter kueri fields berfungsi sebagai filter output. Ini berarti respons parsial dihitung hanya setelah pemrosesan kueri lainnya. Misalnya, jika Anda juga menentukan parameter kueri max-results untuk menunjukkan bahwa Anda menginginkan 20 hasil per halaman, 20 hasil pertama akan dibuat dan respons parsialnya akan dihitung. Jika spesifikasi fields tidak cocok dengan 20 entri pertama yang dipilih oleh kueri, Anda akan mendapatkan kembali feed kosong; Anda tidak mendapatkan kembali 20 entri pertama yang cocok.

Catatan: Jangan coba menggunakan kondisi kolom sebagai pemilih kueri. Artinya, jangan mencoba mengambil feed lengkap dan menerapkan kondisi kolom untuk memfilter item minat dari set data yang sangat besar. Jika memungkinkan, gunakan parameter kueri lain, seperti start-index dan max-results, untuk mengurangi hasil setiap kueri menjadi ukuran yang dapat dikelola. Jika tidak, peningkatan performa yang mungkin terjadi dengan respons parsial dapat diimbangi dengan penurunan performa serius yang disebabkan oleh penggunaan yang tidak tepat.

Memformat nilai parameter kolom

Panduan berikut menjelaskan cara membuat parameter value kueri fields. Setiap panduan menyertakan contoh dan memberikan deskripsi tentang bagaimana nilai parameter memengaruhi respons.

Catatan: Seperti semua nilai parameter kueri, nilai parameter fields harus dienkode URL. Agar lebih mudah dibaca, contoh di bawah menghilangkan encoding.

Identifikasi kolom yang ingin Anda kembalikan, atau buat pilihan kolom.

Nilai parameter kueri fields adalah daftar elemen atau atribut yang dipisahkan koma (secara kolektif disebut kolom), dan setiap kolom ditentukan relatif terhadap elemen root dari representasi resource. Jadi, jika Anda mengambil feed, kolom ditentukan relatif terhadap elemen <feed>, dan jika Anda mengambil satu entri, kolom ditentukan relatif terhadap elemen <entry>. Jika elemen yang Anda pilih adalah (atau merupakan bagian dari) elemen berulang dalam feed, layanan akan menampilkan semua instance elemen tersebut.

Berikut beberapa contoh tingkat feed:

Contoh	Efek
`entry`	Menampilkan semua elemen `<entry>` dan semua sub-elemen dari entri tersebut, tetapi tidak untuk elemen turunan lain dari `<feed>`.
`id,entry`	Menampilkan elemen feed `<id>` dan `<entry>`.
`entry/title`	Menampilkan elemen `<title>` untuk semua entri feed. Setiap kali elemen bertingkat ditampilkan, respons akan menyertakan tag yang disertakan untuk elemen induk apa pun. Tag induk tidak menyertakan elemen atau atribut turunan lainnya, kecuali jika juga dipilih secara eksplisit.
`entry/author/uri`	Hanya menampilkan sub-elemen `<uri>` dari elemen `<author>` untuk semua entri feed.
`entry/*:rating`	Hanya menampilkan sub-elemen dengan nama lokal `rating` di namespace apa pun untuk semua entri feed.

Berikut beberapa contoh entry-level:

Contoh	Efek
`author`	Menampilkan elemen turunan `<author>` dari entri target.
`@gd:etag`	Menampilkan atribut `etag` dari entri target.
`author/uri`	Menampilkan sub-elemen `<uri>` dari elemen `<author>` untuk entri target.
`media:group/media:*`	Menampilkan semua sub-kolom `<media:group>` di namespace `media` untuk entri target.

Batasi respons ke kolom yang dipilih yang cocok dengan kriteria tertentu, atau gunakan kondisi kolom.

Secara default, jika permintaan Anda menentukan elemen yang muncul lebih dari sekali, respons parsial akan menyertakan semua instance elemen tersebut. Namun, Anda juga dapat menentukan bahwa respons hanya boleh menyertakan elemen yang memiliki nilai atribut tertentu atau elemen yang memenuhi beberapa kondisi lain menggunakan sintaksis "[ ]", seperti yang ditunjukkan dalam contoh di bawah. Lihat bagian sintaksis kondisi kolom untuk detail selengkapnya.

Contoh	Efek
`entry[link/@rel='edit']`	Menampilkan entri feed yang berisi elemen `<link>` dengan nilai atribut `rel` dari `'edit'`.
`entry/title[text()='Today']`	Menampilkan elemen `<title>` apa pun yang muncul di entri feed jika kontennya `'Today'`.
`entry/author[name='Jo']`	Menampilkan elemen `<author>` apa pun yang terjadi di entri feed jika memiliki sub-elemen `<name>` dengan konten `'Jo'`.
`author[name='Jo']`	Menampilkan elemen `<author>` dalam entri target jika memiliki sub-elemen `<name>` dengan konten `'Jo'`.

Minta hanya bagian dari elemen yang dipilih, atau gunakan sub-pilihan kolom.

Secara default, jika permintaan Anda menentukan elemen tertentu, layanan akan menampilkan elemen secara keseluruhan. Anda dapat menentukan bahwa respons hanya boleh menyertakan sub-elemen tertentu dalam elemen yang dipilih. Anda melakukannya menggunakan sintaksis sub-pilihan "( )", seperti dalam contoh di bawah.

Contoh	Efek
`entry/author(uri)`	Hanya menampilkan sub-elemen `<uri>` untuk penulis di entri feed.
`entry/author[name='Jo'](uri)`	Hanya menampilkan sub-elemen `<uri>` dari `<author>` untuk setiap entri yang memiliki nama penulis `'Jo'`.
`entry(link(@rel,@href))`	Hanya menampilkan nilai atribut `rel` dan `href` untuk setiap elemen `<link>` dalam entri feed.
`entry(title,link[@rel='edit'])`	Menampilkan hanya elemen `<title>` dan `<link>` dengan atribut `rel` edit untuk setiap entri feed.
`entry(title,author(uri)`	Menampilkan elemen `<title>` dan elemen `<uri>` penulis untuk setiap entri feed.

Selengkapnya tentang sintaksis kondisi kolom

Anda dapat menggunakan kondisi kolom dengan kolom atau sub-kolom. Kondisi harus dievaluasi ke 'true' agar kolom yang dipilih dapat disertakan dalam hasil.Jika tidak ada kondisi kolom, semua kolom dari jenis yang dipilih akan disertakan.

Nilai teks dari kolom yang dipilih digunakan untuk perbandingan. Dalam konteks ini, jika kolom adalah elemen, nilai teks adalah kontennya; jika kolom adalah atribut, nilai teks adalah nilai atribut. Jika kolom tidak memiliki nilai teks, perbandingan akan gagal dan kolom tidak disertakan dalam hasil.

Tabel berikut menunjukkan operator XPath yang didukung untuk kondisi kolom dan memberikan beberapa contoh.

Operator	Sintaksis	Contoh
Perbandingan string	`=` atau `eq` `!=` atau `ne`	Menampilkan seluruh entri jika berisi elemen `<link>` dengan atribut `rel` yang disetel ke '`self'`: `entry[link/@rel='self']` Menampilkan seluruh entri jika berisi elemen `<title>` dengan konten yang sama dengan string `'unknown'`: `entry[title eq 'unknown']` Menampilkan seluruh elemen `<title>` jika kontennya bukan `'unknown'`: `title[text() != 'unknown']`
Perbandingan logis	`and or not`	Menampilkan link apa pun yang memiliki atribut `rel` yang disetel ke `'self'` atau `'edit'`: `link[@rel='self' or @rel='edit']` Menampilkan link apa pun yang memiliki atribut `rel` yang disetel ke `'self'` dan atribut `type` yang disetel ke `'application/atom+xml'`: `link[@rel='self' and @type='application/atom+xml']` Menampilkan link apa pun yang tidak memiliki atribut `rel` dengan nilai `'self'`: `link[not(@rel='self')]` Perhatikan bahwa, seperti di XPath, `not` terlihat seperti panggilan fungsi.
Perbandingan numerik	`=` atau `eq` `!=` atau `ne` `>` atau `gt` `>`= atau `ge` `<` atau `lt` `<=` atau `le`	Menampilkan elemen `<gd:rating>` apa pun dengan atribut `value` yang dapat diubah menjadi bilangan bulat 5: `gd:rating[@value=5]` Menampilkan elemen `<gd:rating>` apa pun dengan atribut `average` yang dapat diubah menjadi float yang lebih besar dari 4.3 : `gd:rating[@average gt 4.3]`
Perbandingan tanggal	Gunakan operator perbandingan numerik, seperti yang ditunjukkan pada contoh.	Untuk melakukan perbandingan tanggal atau tanggal/waktu, Anda dapat mentransmisikan elemen, atribut, atau literal string ke dalam `xs:date` atau `xs:dateTime`. Untuk `xs:dateTime`, zona waktu defaultnya adalah UTC, tetapi sebaiknya tetapkan zona waktu secara eksplisit. Menampilkan elemen `<yt:recorded>` apa pun yang berisi tanggal sejak 1 Januari 2005: `yt:recorded[xs:date(text())>=xs:date('2005-01-01')]` Menampilkan entri apa pun yang diperbarui setelah waktu yang ditentukan, yang ditentukan dalam zona waktu UTC: `entry[xs:dateTime(updated)>xs:dateTime('2008-07-25T08:19:37.549Z')]`
Keberadaan	Gunakan nama elemen atau atribut seperti yang ditunjukkan dalam contoh.	Menampilkan setiap entri yang berisi link dengan atribut `rel`: `entry[link/@rel]` Menampilkan elemen `<gd:rating>` apa pun yang memiliki atribut bernama `value`: `entry/gd:rating[@value]`
Boolean	`true()false()`	Boolean dapat berguna selama pengujian untuk memaksa kondisi kolom menjadi status benar atau salah. Menampilkan elemen `<link>` apa pun: `link[true()]`

Menangani respons parsial

Setelah server yang mendukung respons sebagian memproses permintaan valid yang menyertakan parameter kueri fields, server akan mengirimkan kembali kode status 200 OK HTTP beserta atribut atau elemen yang diminta. Jika parameter kueri fields memiliki error atau tidak valid, server akan menampilkan kode status 400 Bad Request HTTP.

Elemen root respons adalah <feed> atau <entry>, bergantung pada URI target. Konten elemen root hanya menyertakan kolom yang dipilih untuk feed atau entri tersebut, bersama dengan tag penutup untuk elemen induk apa pun.

Nilai parameter kueri fields permintaan dapat dipantulkan kembali dengan dua cara:

Elemen root memiliki atribut gd:fields yang menunjukkan nilai parameter kueri fields yang ditentukan dalam permintaan.
Jika URI target adalah feed, setiap entri yang dapat diedit memiliki atribut gd:fields yang menampilkan bagian dari pilihan fields yang berlaku untuknya.

Catatan: Untuk melihat nilai atribut gd:fields ini dalam respons parsial, Anda harus menyertakannya dalam spesifikasi parameter kueri fields. Anda dapat melakukannya secara eksplisit, menggunakan @gd:fields, atau menggunakan @gd:* yang lebih umum, yang juga mencakup informasi ETag.

Contoh kueri berikut ini meminta server untuk menampilkan dokumen yang hanya berisi atribut di namespace gd (di feed dan level entri), serta ID feed, judul, dan link edit untuk setiap entri feed.

http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])

Server menampilkan respons parsial berikut, bersama dengan kode status HTTP 200 Successful:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
    gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
  <id>http://example.com/myFeed</id>
  <entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <title>This year</title>
  </entry>
  <entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/2/'/>
    <title>Last year</title>
  </entry>
  <entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/3/'/>
    <title>Today</title>
  </entry>
</feed>

Jika kolom yang dipilih tidak cocok dengan apa pun, layanan tetap akan menampilkan kode status HTTP 200 Successful, tetapi respons sebagiannya adalah feed kosong:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
  gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
</feed>

Update sebagian (Eksperimental)

Produk Google yang mendukung respons sebagian dan resource yang dapat diedit juga memungkinkan Anda menggunakan update parsial. Dengan mengupdate sebagian, Anda hanya mengirim kolom yang ingin diperbarui, bukan mengirim versi modifikasi dari representasi resource secara lengkap. Hal ini memungkinkan aplikasi klien menjadi lebih efisien saat melakukan update, serta saat menggunakan respons parsial untuk mengambil data.

Namun, Anda harus menggunakan permintaan PATCH saat membuat update parsial, bukan menggunakan PUT. Semantik untuk PATCH cukup canggih untuk memungkinkan Anda menambahkan, mengganti, dan menghapus kolom tertentu untuk entri tertentu, semuanya dengan satu permintaan.

Untuk mengetahui apakah update parsial tersedia untuk produk yang Anda gunakan, lihat dokumentasi spesifik per produk.

Mengirimkan permintaan pembaruan sebagian

Untuk mengirimkan permintaan pembaruan sebagian, kirim permintaan PATCH HTTP ke URL yang sama dengan yang biasa Anda gunakan dengan PUT untuk memperbarui sumber daya. Isi permintaan PATCH adalah elemen <entry> parsial yang menentukan kolom yang ingin ditambahkan atau diubah. Atribut gd:fields entri menunjukkan kolom yang ingin dihapus.

Server memproses permintaan PATCH dalam urutan tertentu:

Fungsi ini pertama-tama menghapus kolom representasi yang ditentukan oleh atribut gd:fields dari representasi resource.
Sintaksis untuk atribut gd:fields sama dengan parameter kueri fields yang digunakan saat meminta respons parsial. Lihat Sintaksis yang didukung untuk detail selengkapnya.
Permintaan kemudian digabungkan ke dalam representasi resource yang ada untuk data yang disediakan dalam isi permintaan.
Detail selengkapnya tentang cara data digabungkan disediakan di Menambahkan atau memperbarui kolom di bawah.

Catatan: Karena isi permintaan PATCH biasanya tidak sesuai dengan Format Sindikasi Atom, Content-Type yang Anda gunakan dengan permintaan PATCH adalah application/xml.

Berikut adalah contoh permintaan update sebagian:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='description'>
  <title>New title</title>
</entry>

Permintaan PATCH ini membuat perubahan berikut pada representasi resource yang disimpan di server untuk entri URI target:

Menghapus elemen <description>.
Memperbarui elemen <title>.

Semantik permintaan pembaruan parsial

Petunjuk di bawah menjelaskan cara menyiapkan permintaan PATCH untuk menghapus, menambahkan, atau memperbarui kolom tertentu dalam entri. Satu permintaan PATCH dapat menjalankan kombinasi apa pun dari operasi ini.

Menghapus kolom. Gunakan atribut gd:fields elemen <entry> untuk mengidentifikasi kolom apa pun yang ingin Anda hapus dari resource. Contoh permintaan berikut menghapus judul dan ringkasan yang terkait dengan entri. Namun, permintaan ini tidak menambahkan atau memperbarui data lain untuk entri tersebut.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='title,summary'/>
```
Menambahkan atau memperbarui kolom. Gunakan isi elemen <entry> untuk menentukan data yang ingin ditambahkan atau diperbarui untuk resource. Kolom ini digabungkan ke dalam data yang ada untuk resource, setelah penghapusan dilakukan, sesuai dengan aturan berikut:
- Kolom yang belum ada akan ditambahkan. Jika data resource belum menentukan nilai untuk kolom, maka kolom tersebut akan ditambahkan ke data yang sudah ada. Misalnya, jika entri tidak memiliki judul, dan permintaan PATCH berisi elemen <title>, judul baru akan ditambahkan ke entri.
- Kolom yang sudah ada akan diganti atau ditambahkan. Perilaku tertentu untuk menggabungkan kolom yang sudah ditentukan dalam data resource bergantung pada karakteristik kolom:
  - Kolom yang tidak berulang diganti. Jika data resource sudah menentukan nilai untuk elemen yang tidak berulang, nilai yang Anda tentukan dalam permintaan PATCH akan menggantikan nilai yang ada untuk elemen tersebut. Misalnya, pada contoh di bawah, judul baru menggantikan judul yang ada.
```
PATCH /myFeed/1/1/
Content-Type: application/xml

  <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <title>New Title</title>
</entry>
```
    Berikut adalah contoh yang lebih kompleks. Untuk contoh ini, asumsikan bahwa entri hanya dapat memiliki satu penulis, dan bahwa resource target sudah memiliki nilai untuk nama dan alamat email penulis. Meskipun elemen <author> memiliki dua kolom turunan, hanya elemen <name> yang ada dalam data yang diberikan. Akibatnya, hanya nilai kolom tersebut yang ditimpa. Nilai elemen <email>, yang tidak ada di data yang disediakan, tidak berubah.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <author>
    <name>New Name</name>
  </author>
</entry>
```
  - Kolom berulang ditambahkan. Jika data sumber daya sudah menentukan nilai untuk elemen berulang, elemen baru yang Anda berikan akan ditambahkan ke kumpulan nilai yang ada.
    
    Perhatikan bahwa mungkin ada saatnya Anda ingin melakukan sesuatu selain menambahkan instance baru dari elemen berulang. Misalnya, Anda mungkin ingin melakukan salah satu hal berikut:
    - Mengganti seluruh daftar elemen berulang. Anda dapat menghapus semua kolom berulang menggunakan atribut gd:fields (misalnya, gd:fields='ns:accessControl') dan memberikan kumpulan lengkap kolom pengganti. Karena semua elemen yang ada telah dihapus terlebih dahulu, kumpulan kolom yang Anda berikan tidak bertentangan dengan nilai yang ada saat nilai tersebut ditambahkan.
    - Ganti satu nilai dalam kumpulan nilai yang ada untuk elemen berulang. Dalam hal ini, cukup hapus satu elemen dengan menentukan nilai gd:fields yang cukup sempit untuk menghindari penghapusan nilai lain yang ingin dipertahankan. Misalnya, untuk hanya menghapus kontrol akses dengan action dari embed, Anda dapat menggunakan gd:fields='ns:accessControl[@action="embed"]'. Kemudian, Anda memberikan kolom tunggal yang ingin diganti dengan isi elemen <entry>:
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='ns:accessControl[@action="embed"]>
  <ns:accessControl action="embed" permission="allowed" />
</entry>
```

Menangani respons terhadap update parsial

Setelah memproses permintaan pembaruan sebagian yang valid, API akan menampilkan kode respons HTTP 200 OK. Secara default, isi respons adalah entri lengkap yang Anda perbarui. Server memperbarui nilai ETag saat berhasil memproses permintaan PATCH, seperti yang dilakukan dengan PUT.

Jika permintaan PATCH menghasilkan status resource baru yang secara sintaksis atau semantik tidak valid, server akan menampilkan kode status HTTP HTTP 400 Bad Request atau 422 Unprocessable Entity, dan status resource tetap tidak berubah. Misalnya, jika Anda mencoba menghapus kolom yang wajib diisi dan tidak memberikan penggantinya, server akan menampilkan error.

Catatan: Penting untuk memahami bagaimana berbagai kolom saling terkait. Anda mungkin dapat menempatkan resource ke dalam keadaan yang tidak konsisten dengan mengupdate hanya sebagian dari nilai-nilai yang saling bergantung. Misalnya, waktu mulai mungkin akan diperbarui ke nilai lebih baru daripada waktu berakhir. Meskipun API akan menampilkan kode error, sebaiknya Anda menguji jenis kondisi ini sepenuhnya untuk memastikan konsistensi.

Notasi alternatif saat PATCH tidak didukung

Jika firewall Anda tidak mengizinkan PATCH, lakukan permintaan POST HTTP dan setel header penggantian ke PATCH, seperti yang ditunjukkan di bawah:

POST /myfeed/1/1/ X-HTTP-Method-Override: PATCH Content-Type: application/xml ...

Menggunakan respons sebagian dengan update parsial

Anda dapat menggunakan respons parsial sebagai dasar permintaan pembaruan parsial. Jika Anda melakukannya, tentukan parameter kueri fields yang menyertakan link edit, serta @gd:*. Hal ini memastikan bahwa respons parsial menyertakan informasi seperti nilai atribut ETag dan gd:fields yang penting untuk permintaan berikutnya.

Berikut adalah contoh yang menampilkan respons parsial yang dapat Anda gunakan sebagai dasar untuk update parsial mendatang:

http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who

Server merespons:

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"E0UKRAREeCp7IWA6WhJT"'
    gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
  <link href='http://example.com/myFeed/1/1/'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='jo@gmail.com'/>
  <gd:who email='jane@gmail.com'/>
</entry>

Misalkan Anda ingin menghapus pengguna dengan email 'jane@gmail.com', tambahkan pengguna dengan email 'will@gmail.com', dan ubah email untuk pengguna yang saat ini tercantum sebagai 'jo@gmail.com' menjadi 'josy@gmail.com'.

Anda dapat membuat perubahan ini hanya dengan memulai dengan hasil respons sebelumnya, memodifikasi hanya kolom yang berbeda, dan mengirimkan entri parsial yang dimodifikasi sebagai isi permintaan PATCH. Untuk contoh ini, modifikasi yang diperlukan adalah:

Hapus <gd:who email='jane'/> dari daftar elemen yang disediakan.
Tambahkan <gd:who email='will@gmail.com'/> ke daftar elemen yang disediakan.
Ganti <gd:who email='jo@gmail.com'/> dengan <gd:who email='josy@gmail.com'/>.

Permintaan PATCH berdasarkan respons parsial pevious ditunjukkan di bawah ini:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
    gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <link href='http://example.com/myFeed/1/1'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='josy@gmail.com'/>
  <gd:who email='will@gmail.com'/>
</entry>

Catatan: Pendekatan ini bergantung pada atribut gd:fields dan gd:etag (jika didukung) yang disertakan dalam respons sebagian untuk entri tersebut. Isi entri parsial harus mempertahankan semua kolom dan atribut yang ada di respons sebagian — kecuali untuk yang secara eksplisit ingin Anda hapus. Anda dapat memperbarui kolom yang ada dalam isi dengan nilai baru, dan Anda dapat menyertakan kolom baru yang ingin ditambahkan.

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, 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 mengirimkan permintaan Data API.

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 Google Data API 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, klien tersebut akan tetap berfungsi dengan Data API, tetapi performanya mungkin lebih buruk dibandingkan dengan 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, dan DELETE
Definisi kode status HTTP 1.1
Cara Membuat Protokol REST
Membuat Layanan Web dengan Cara REST
Pengantar Teknis XML
Namespace XML berdasarkan Contoh
Bagian ETag spesifikasi HTTP

Kembali ke atas