Menggunakan Library Klien JavaScript (v2.0)

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 cara menggunakan library klien JavaScript untuk mengirim kueri Google Data API 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 bisa membuat permintaan API, mengirimkannya ke layanan, dan menerima respons.

Dokumen ini memberikan beberapa informasi umum tentang penggunaan library klien JavaScript, bersama dengan kumpulan contoh penggunaan umum.

Audiens

Dokumen ini ditujukan untuk pemrogram JavaScript yang ingin menulis aplikasi klien yang dapat berinteraksi dengan layanan Data Google.

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

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

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

Persyaratan penggunaan

Anda setuju untuk mematuhi Persyaratan Penggunaan Library Klien Google JavaScript saat menggunakan library klien JavaScript.

Ringkasan model data dan alur kontrol

Library klien JavaScript menggunakan sekumpulan class untuk mewakili elemen yang digunakan oleh Google Data API.

Catatan: Representasi data yang mendasari adalah JSON, tetapi library klien menyediakan lapisan abstraksi sehingga Anda tidak perlu menggunakan data JSON secara langsung. Jika Anda ingin bekerja secara langsung dengan JSON, tanpa library klien, lihat Menggunakan JSON dengan Google Data API.

Library menyediakan metode yang memungkinkan Anda mengirim data secara asinkron ke dan menerima data dari layanan yang memiliki data API. Misalnya, metode google.gdata.calendar.CalendarService.getEventsFeed() mengirim permintaan untuk feed ke Google Kalender. Salah satu parameter yang Anda teruskan adalah fungsi kelanjutan, yang juga dikenal sebagai callback; layanan menampilkan feed, dalam format JSON, dengan memanggil fungsi kelanjutan. Klien kemudian dapat memanggil berbagai metode get untuk menggunakan data dalam bentuk objek JavaScript.

Untuk menambahkan entri baru, buat entri menggunakan class dan metode library klien, lalu panggil metode feed.insertEntry() untuk mengirim entri baru ke layanan. Sekali lagi, Anda menyediakan fungsi kelanjutan, yang dipanggil layanan saat entri berhasil ditambahkan.

Jika Anda baru mengenal JavaScript, alur kontrol mungkin sedikit membingungkan. Setelah memanggil metode seperti getEventsFeed() atau insertEntry(), dalam kebanyakan kasus skrip Anda berakhir. Eksekusi dilanjutkan dalam fungsi lanjutan saat layanan menampilkan data yang diminta. Oleh karena itu, apa pun yang dilakukan klien ke data yang ditampilkan harus dilakukan di fungsi kelanjutan, atau dipanggil dari fungsi tersebut. Anda mungkin perlu membuat beberapa variabel menjadi global untuk menggunakannya dalam beberapa fungsi.

Untuk mengetahui informasi selengkapnya tentang gaya pemrograman ini, lihat "Gaya penerusan-lanjutan" di Wikipedia.

Tentang lingkungan yang didukung

Saat ini, kami hanya mendukung aplikasi klien JavaScript yang berjalan di halaman web di browser. Browser yang saat ini didukung adalah:

  • Firefox 2.x & amp; 3.x
  • Internet Explorer 6, 7, & amp; 8
  • Safari 3.x & amp; 4.x
  • Google Chrome (semua versi)

Library klien JavaScript menangani semua komunikasi dengan server layanan. Jika Anda adalah developer JS yang berpengalaman, Anda mungkin berpikir, "Namun, bagaimana dengan kebijakan asal yang sama?" Library klien JavaScript memungkinkan klien Anda mengirim permintaan Data Google dari domain mana pun sekaligus tetap mematuhi model keamanan browser.

Untuk ringkasan tentang cara mengautentikasi dengan Google Data API, lihat Ringkasan Autentikasi Google Data API. Bagian lainnya dalam dokumen ini mengasumsikan bahwa Anda sudah memahami dasar-dasar cara kerja sistem ini.

Contoh aplikasi klien

Untuk melihat cara kerja library klien JavaScript, kunjungi halaman contoh kami.

Tutorial dan contoh

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

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 mengetahui informasi selengkapnya tentang Kalender, lihat dokumen Google Calendar Data API.

Memuat library

Sebelum klien Anda dapat menggunakan library klien, klien tersebut harus meminta kode library klien dari server.

Mulailah dengan menggunakan tag <script> di bagian <head> pada dokumen HTML Anda untuk mengambil loader Google AJAX API:

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

Anda dapat meminimalkan bolak-balik ke server Google dan mengurangi latensi dengan melakukan pramuat library. Untuk melakukan pramuat paket tertentu langsung dari loader Google AJAX API (tanpa menggunakan google.load(), lihat di bawah), gunakan kode berikut:

<script type="text/javascript"
      src="https://www.google.com/jsapi?autoload=%7Bmodules%3A%5B%7Bname%3Agdata%2Cversion%3A2.x%2Cpackages%3A%5Bblogger%2Ccontacts%5D%7D%5D%7D"></script>

Catatan: URL src skrip harus dienkode ke URL sepenuhnya. Misalnya, contoh sebelumnya adalah
<script type="text/javascript" src="https://www.google.com/jsapi?autoload={modules:[{name:gdata,version:2.x,packages:[blogger,contacts]}]}"></script>.

Jika tidak memuat modul secara otomatis, Anda dapat memuat library klien Data Google dengan menggunakan contoh berikutnya dalam kode penyiapan JavaScript, setelah mengambil loader umum. Panggilan ini harus dilakukan dari bagian <head> dokumen HTML Anda (atau dari file JavaScript yang disertakan menggunakan tag <script> di bagian <head> pada dokumen HTML Anda):

google.load("gdata", "2");

Atau, Anda dapat meminta layanan tertentu, bukan seluruh library. Contoh ini hanya mendownload paket untuk Blogger dan Kontak:

google.load("gdata", "2.x", {packages: ["blogger", "contacts"]});

Parameter kedua untuk google.load() adalah nomor versi library klien JavaScript yang diminta.Skema penomoran versi kami dibuat sesuai model yang digunakan oleh Google Maps API. Berikut ini kemungkinan nomor versi dan artinya:

"1"
Revisi dari versi kedua hingga terakhir dari versi utama 1.
"1.x"
Revisi terbaru dari versi utama 1.
"1.s"
Revisi stabil terbaru dari versi utama 1. Terkadang kami akan mendeklarasikan versi library library tertentu menjadi "stabil", berdasarkan masukan yang kami terima dari developer. Namun, versi tersebut mungkin tidak memiliki fitur terbaru.
"1.0", "1.1", dsb.
Versi library tertentu, dengan nomor revisi utama dan minor yang ditentukan.

Setelah memanggil google.load(), Anda harus memberi tahu loader untuk menunggu hingga halaman selesai dimuat, lalu panggil kode Anda:

google.setOnLoadCallback(getMyFeed);

Dengan getMyFeed() adalah fungsi yang ditentukan di bagian berikutnya dari dokumen ini. Gunakan pendekatan ini, bukan menambahkan pengendali onload ke elemen <body>.

Meminta feed yang tidak diautentikasi

Untuk meminta feed yang tidak diautentikasi, tambahkan kode berikut ke file JavaScript Anda, atau ke tag <script> dalam file HTML Anda.

Dalam kode berikut, getMyFeed() dipanggil terlebih dahulu (oleh loader AJAX API, seperti yang dijelaskan di bagian sebelumnya).

Layanan ini memanggil setupMyService() untuk membuat koneksi (diwakili oleh objek CalendarService) ke Google Kalender. Kita telah menarik kode pembuatan layanan ke dalam fungsi terpisah untuk modularitas; nanti, kita akan memodifikasi fungsi setupMyService(), tergantung pilihan autentikasi Anda.

Setelah menyiapkan layanan, getMyFeed() memanggil metode getEventsFeed() library klien untuk meminta feed.

Kita menentukan URL feed dalam variabel global sehingga dapat digunakan di fungsi berikutnya. Dalam contoh ini, kami menggunakan URL feed publik (tidak diautentikasi) untuk pengguna bernama liz@gmail.com Anda juga dapat menggunakan default sebagai pengganti alamat email pengguna untuk mewakili pengguna terautentikasi.

var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/public/full";

function setupMyService() {
  var myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
  return myService;
}

function getMyFeed() {
  myService = setupMyService();

  myService.getEventsFeed(feedUrl, handleMyFeed, handleError);
}

Perhatikan bahwa kita membuat myService variabel global, untuk kemudahan penggunaan di fungsi berikutnya.

Agar kode di atas berfungsi di klien Anda sendiri, Anda harus menggunakan alamat email pengguna yang sebenarnya, untuk akun Kalender dengan kalender yang dibagikan secara publik.

Catatan: Saat Anda membuat objek CalendarService baru, library klien akan memanggil metode bernama google.gdata.client.init(), yang memeriksa apakah browser yang menjalankan klien didukung. Jika ada error, library klien akan menampilkan pesan error kepada pengguna. Jika ingin menangani error semacam ini sendiri, Anda dapat memanggil google.gdata.client.init(handleInitError) secara eksplisit sebelum membuat layanan, dengan handleInitError() sebagai fungsi Anda. Jika terjadi error init, fungsi Anda akan menerima objek Error standar; Anda dapat melakukan apa pun yang diinginkan dengan objek tersebut.

Pada panggilan ke getEventsFeed(), argumen kedua adalah handleMyFeed, yang merupakan fungsi callback; lihat di bawah. Google Kalender akan memproses permintaan, lalu meneruskan objek "root feed" yang berisi feed yang diminta ke callback jika permintaan berhasil. Root feed adalah objek container yang berisi feed.

Argumen ketiga untuk getEventsFeed() adalah fungsi penanganan error opsional; jika library klien mengalami error, argumen tersebut akan memanggil pengendali error yang ditentukan, bukan fungsi callback yang berhasil. Objek yang diteruskan library klien sebagai argumen ke pengendali error adalah instance objek Error JavaScript, dengan properti cause tambahan.

Berikut adalah versi sederhana fungsi callback dan pengendali error: 

function handleMyFeed(myResultsFeedRoot) {
  alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
}

function handleError(e) {
  alert("There was an error!");
  alert(e.cause ? e.cause.statusText : e.message);
}

Kami menangani error hanya dengan menampilkannya kepada pengguna; pengendali error klien Anda mungkin akan lebih canggih. Dalam beberapa konteks, mungkin tidak ada penyebab yang ditetapkan, jadi dalam kasus tersebut, pengendali error contoh kita akan kembali menampilkan properti message standar.

Perlu diperhatikan bahwa karena kode ini tidak melakukan autentikasi, Anda hanya dapat menggunakannya untuk mendapatkan feed publik.

Mengautentikasi

Library klien JavaScript dapat digunakan dalam dua mode. Jika Anda menulis gadget, gadget akan menggunakan fitur yang disebut Proxy OAuth untuk autentikasi. Jika diakses dari aplikasi JavaScript mandiri, sistem ini menggunakan sistem autentikasi AuthSub. Untuk informasi tentang autentikasi, lihat dokumen Ringkasan Autentikasi Google Data API. Bagian lainnya mengasumsikan bahwa Anda sudah memahami dasar-dasar cara kerja sistem ini.

Sebelum menggunakan autentikasi dengan kode contoh yang diberikan dalam dokumen ini, ubah URL feed dari publik menjadi pribadi:

var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/private/full";

Mengautentikasi dalam klien web dengan AuthSub

Sistem otorisasi "AuthSub for JavaScript" Google tidak lagi tersedia.

Sebagai gantinya, sebaiknya gunakan OAuth 2.0 untuk aplikasi sisi klien.

Mengautentikasi dalam Gadget dengan Proxy OAuth

Berikut adalah gambaran singkat tentang apa yang terjadi selama proses autentikasi untuk gadget:

  1. Gadget Anda dimuat untuk pertama kali dan berupaya mengakses data pengguna menggunakan salah satu Google Data API.
  2. Permintaan gagal karena pengguna belum memberikan akses ke data mereka. Objek respons berisi URL (di response.oauthApprovalUrl) untuk halaman persetujuan OAuth. Gadget Anda harus menyediakan metode untuk meluncurkan jendela baru dengan URL tersebut.
  3. Di halaman persetujuan, pengguna memilih untuk memberikan/menolak akses ke gadget Anda. Jika berhasil, pengguna akan diarahkan ke halaman oauth_callback yang Anda tentukan. Untuk pengalaman pengguna terbaik, gunakan http://oauth.gmodules.com/gadgets/oauthcallback.
  4. Selanjutnya, pengguna menutup jendela pop-up. Untuk membantu memberi tahu gadget Anda bahwa pengguna telah memberikan persetujuan, kami telah menyediakan pengendali pop-up yang dapat digunakan untuk mendeteksi penutupan jendela persetujuan. Atau, gadget Anda dapat menampilkan link (mis. "Saya telah menyetujui akses") untuk diklik pengguna secara manual setelah jendela ini ditutup.
  5. Gadget Anda mencoba mengakses Google Data API untuk kedua kalinya dengan meminta kembali data pengguna. Upaya ini berhasil.
  6. Gadget telah diautentikasi dan dapat mulai beroperasi secara normal.

Di gadget, tambahkan elemen <OAuth> di bagian <ModulePrefs>:

<ModulePrefs>
...
<OAuth>
  <Service name="google">
    <Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" /> 
    <Request url="https://www.google.com/accounts/OAuthGetRequestToken?
                  scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" /> 
    <Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
                        oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" /> 
  </Service>
</OAuth>
...
</ModulePrefs>

Di bagian ini, ubah parameter kueri berikut:

  • scope

    Parameter yang diperlukan di URL Permintaan. Gadget Anda hanya dapat mengakses data dari scope yang digunakan dalam parameter ini. Dalam contoh ini, gadget akan mengakses data Blogger dan Kalender Anda. Gadget dapat meminta data untuk satu cakupan atau beberapa cakupan (seperti yang dilakukan contoh ini).

  • oauth_callback

    Parameter opsional di URL Otorisasi. Halaman persetujuan OAuth akan dialihkan ke URL ini setelah pengguna menyetujui akses ke data mereka. Anda dapat memilih untuk tidak menyertakan parameter ini, menetapkannya ke "halaman yang disetujui", atau sebaiknya gunakan http://oauth.gmodules.com/gadgets/oauthcallback. Selanjutnya, akan memberikan pengalaman pengguna terbaik saat pengguna menginstal gadget untuk pertama kali. Halaman tersebut menyediakan cuplikan JavaScript yang otomatis menutup jendela pop-up.

Selanjutnya, muat library klien JavaScript di bagian <Content> pada gadget Anda. Ubah fungsi setupMyService() dari contoh sebelumnya untuk memanggil metode useOAuth() objek layanan. Tindakan ini akan memberi tahu gadget untuk menggunakan Proxy OAuth untuk mengautentikasi, bukan AuthSub. Template di bawah ini akan membantu Anda memulai:

<Content type="html">
<![CDATA[
  ...
  <script src="https://www.google.com/jsapi"></script>
  <script type="text/javascript">
    var myService = null;
    
    function setupMyService() {
      myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
      myService.useOAuth('google');
      fetchData();
    }
    
    function initGadget() {
      google.load('gdata', '2.x');
      google.setOnLoadCallback(setupMyService);
    }

    function fetchData() {            
      var callback = function(response) {
        if (response.oauthApprovalUrl) {
        
          // TODO: Display "Sign in" link (response.oauthApprovalUrl contains the URL) 
          
        } else if (response.feed) {
        
          // TODO: show results
          
        } else {
        
          // TODO: handle the error
          
        }
      };

      myService.getEventsFeed('http://www.google.com/calendar/feeds/default/public/full', callback, callback);
    }
    
    gadgets.util.registerOnLoadHandler(initGadget);
  </script>
  ...
]]> 
</Content>

Perlu diperhatikan bahwa panggilan ke google.accounts.user.login(scope) telah dihapus. Proxy menangani autentikasi untuk Anda.

Untuk informasi selengkapnya tentang cara menulis gadget Google Data API, termasuk detail tentang apa yang harus dimuat fetchData(), lihat artikel kami tentang Membuat Gadget Data Google atau lihat dokumentasi Menulis Gadget OAuth lengkap.

Menyisipkan item baru

Untuk membuat acara kalender baru, lanjutkan eksekusi dari contoh sebelumnya dengan mengubah bagian akhir fungsi handleMyFeed() untuk memanggil fungsi baru:

function handleMyFeed(myResultsFeedRoot) {
  alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
  insertIntoMyFeed(myResultsFeedRoot);
}

Dalam fungsi baru, pertama-tama gunakan konstruktor CalendarEventEntry untuk membuat entri baru. Kemudian, masukkan entri, dengan memberikan callback untuk layanan yang akan dipanggil saat penyisipan selesai.

function insertIntoMyFeed(feedRoot) {
  var newEntry = new google.gdata.calendar.CalendarEventEntry({
      authors: [{
        name: "Elizabeth Bennet",
        email: "liz@gmail.com"
      }],
      title: {
        type: 'text', 
        text: 'Tennis with Darcy'
      },
      content: {
        type: 'text', 
        text: 'Meet for a quick lesson'
      },
      locations: [{
        rel: "g.event",
        label: "Event location",
        valueString: "Netherfield Park tennis court"
      }],
      times: [{
        startTime: google.gdata.DateTime.fromIso8601("2007-09-23T18:00:00.000Z"),
        endTime: google.gdata.DateTime.fromIso8601("2007-09-23T19:00:00.000Z")
      }]
  });
  feedRoot.feed.insertEntry(newEntry, handleMyInsertedEntry, handleError);
}

Perhatikan bahwa nama setiap properti objek yang digunakan dalam konstruktor cocok dengan nama metode penyetel yang digunakan untuk properti tersebut. (Misalnya, cocok dengan nama kolom JSON yang sesuai, misalnya.)

Perhatikan juga bahwa Anda tidak dapat hanya memberikan string tanggal dan waktu ISO 8601 untuk startTime dan endTime; Anda harus menjalankan string tersebut melalui metode fromIso8601() terlebih dahulu.

Layanan menampilkan salinan entri yang disisipkan sebagai objek entryRoot, dan meneruskan objek tersebut ke callback:

function handleMyInsertedEntry(insertedEntryRoot) {
  alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
  alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
}

Meminta entri tertentu

Untuk meminta entri tertentu, ubah fungsi handleMyInsertedEntry() terlebih dahulu untuk memanggil fungsi permintaan entri baru:

function handleMyInsertedEntry(insertedEntryRoot) {
  alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
  alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
  requestMySpecificEntry(insertedEntryRoot.entry.getSelfLink().getHref());
}

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.

function requestMySpecificEntry(entryURI) {
  myService.getEventsEntry(entryURI, handleMySpecificEntry, handleError);
}

function handleMySpecificEntry(retrievedEntryRoot) {
  myEntryRoot = retrievedEntryRoot; // Global variable for later use
  alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
}

Contoh ini pada dasarnya sama dengan contoh getEventsFeed(), kecuali bahwa kita memanggil metode getEventEntry() layanan untuk mendapatkan entri tertentu, dan URI sedikit berbeda—contoh ini menggunakan "default" untuk merujuk ke kalender utama untuk pengguna terautentikasi, dan memiliki ID entri di akhir menggunakannya.

Selain itu, kita harus dapat menggunakan entri yang diambil nanti, jadi kita menyalinnya ke dalam variabel global.

Menelusuri entri

Untuk melakukan penelusuran teks lengkap, ubah fungsi handleMySpecificEntry() terlebih dahulu untuk memanggil fungsi penelusuran baru:

function handleMySpecificEntry(retrievedEntryRoot) {
  myEntryRoot = retrievedEntryRoot; // Global variable for later use
  alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
  searchMyFeed();
}

Kemudian, untuk mengambil kecocokan pertama dari penelusuran, gunakan kode berikut:

function searchMyFeed() {
  var myQuery = new google.gdata.calendar.CalendarEventQuery(feedUrl);
  myQuery.setFullTextQuery("Tennis");
  myQuery.setMaxResults(10);
  myService.getEventsFeed(myQuery, handleMyQueryResults, handleError);
}

function handleMyQueryResults(myResultsFeedRoot) {
  if (myResultsFeedRoot.feed.getEntries()[0]) {
    alert("The first search-match entry's title is: " + myResultsFeedRoot.feed.getEntries()[0].getTitle().getText());
  }
  else {
    alert("There are no entries that match the search query.");
  }
}

Memperbarui item

Untuk mengupdate item yang ada, tambahkan baris di akhir handleMyQueryResults() terlebih dahulu untuk memanggil fungsi update baru:

  updateMyEntry();

Lalu, gunakan kode berikut. Dalam contoh ini, kami mengubah judul entri yang sebelumnya diambil (yang terdapat dalam objek global bernama myEntryRoot di contoh sebelumnya) dari teks lamanya ("Tenis dengan Darcy") menjadi "Rapat penting".

function updateMyEntry() {
  myEntryRoot.entry.getTitle().setText("Important meeting");
  myEntryRoot.entry.updateEntry(handleMyUpdatedEntry, handleError);
}

function handleMyUpdatedEntry(updatedEntryRoot) {
  alert("Entry updated. The new title is: " + updatedEntryRoot.entry.getTitle().getText());
}

Seperti semua metode Kalender, metode updateEntry() secara otomatis menentukan URI edit yang benar untuk digunakan dalam memperbarui entri, sehingga Anda tidak perlu menyediakan URI tersebut secara eksplisit.

Menghapus item

Untuk menghapus entri yang diperbarui, pertama tambahkan baris ke handleMyUpdatedEntry():

 deleteMyEntry(updatedEntryRoot);

Lalu gunakan kode berikut:

function deleteMyEntry(updatedEntryRoot) {
  updatedEntryRoot.entry.deleteEntry(handleMyDeletedEntry, handleError);
}

function handleMyDeletedEntry() {
  alert("Entry deleted");
}

Sekali lagi, metode deleteEntry() secara otomatis menentukan URI edit yang benar untuk digunakan dalam menghapus entri.

Perhatikan bahwa tidak ada entri yang ditampilkan. Jika callback dipanggil, maka kita tahu bahwa penghapusan berhasil; jika penghapusan gagal, deleteEntry() akan memanggil handleError(), bukan memanggil handleMyDeletedEntry().

Menggunakan ETag

Catatan: ETag hanya dapat digunakan dengan layanan yang menjalankan Google Data Protocol v2.0.

Pengantar

Versi 2 dalam Klien Data Google JavaScript memperkenalkan dukungan untuk ETag. ETag adalah ID yang menetapkan versi entri tertentu; hal ini penting dalam dua kasus:

  • 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 ini dengan membuat pembaruan dan penghapusan gagal jika klien menentukan ETag lama untuk entri.

Ada dua jenis ETag: lemah dan kuat. ETag yang lemah selalu diawali dengan W/, misalnya: W/"D08FQn8-eil7ImA9WxZbFEw". ETag yang lemah tidak dijamin akan berubah saat entri berubah, sehingga HTTP memungkinkannya digunakan hanya untuk pengambilan bersyarat. ETag yang kuat mengidentifikasi versi tertentu dari entri tertentu, dan dapat digunakan baik untuk pengambilan bersyarat maupun selama update atau penghapusan untuk menghindari menimpa perubahan klien lain. Karena perbedaan ini, library klien tidak akan mengizinkan Anda mengirim ETag yang lemah dengan permintaan update atau penghapusan.

ETag dapat ditemukan di dua lokasi dalam respons server:

  • Di header HTTP ETag.
  • Di feed/entri, sebagai atribut gd:etag.

Jika layanan mendukung Versi 2, setiap feed dan objek entri akan memiliki metode getEtag() untuk mengambil nilai ETag.

Klien JavaScript mendukung dua metode untuk menyertakan ETag dengan permintaan. Yang pertama adalah objek opt_params baru. Semua fungsi get/update/insert di Library klien Versi 2 memiliki parameter opt_params baru. Objek ini digunakan untuk menentukan parameter opsional saat membuat permintaan. Untuk saat ini, 'etag' adalah satu-satunya parameter opsional yang didukung (meskipun parameter lain mungkin diperkenalkan di masa mendatang). Misalnya, Anda dapat menambahkan ETag ke permintaan GET seperti ini:

var opt_params = {};
opt_params['etag'] = 'ETAG GOES HERE';
service.getFeed(uri, successHandler, errorHandler, opt_params);

Anda juga dapat menambahkan ETag langsung ke feed atau objek entri dengan memanggil metode setEtag() pada feed/entri.

Anda dapat mempelajari ETag lebih lanjut dari Referensi Protokol GData.

Menggunakan ETag untuk Mengambil Data

ETag dapat membantu mengurangi bandwidth dan waktu eksekusi saat mengambil data. ETag dapat disertakan dalam permintaan GET dengan menggunakan If-None-Match header:

If-None-Match: ETAG GOES HERE

Jika ETag mencocokkan versi feed atau entri saat ini, server akan merespons dengan respons 304 NOT MODIFIED dan isi kosong. Jika tidak, server akan merespons dengan respons 200 OK dan data feed atau entri.

Anda dapat menggunakan ETag di klien JavaScript dengan menyertakan parameter 'etag' saat membuat permintaan:

var etag = feed.getEtag(); // Feed loaded from a previous request
var opt_params = {};
opt_params['etag'] = etag;
service.getFeed(feedUrl, successHandler, errorHandler, opt_params);

Pengambilan kondisional berfungsi dengan ETag yang kuat dan lemah. Jika ETag adalah kecocokan, pengendali error akan dipanggil dengan respons 304:

function successHandler(feedRoot) {
  // 200 response
  // Update UI to display updates
}

function errorHandler(errorObj) {
  if (errorObj.cause.getStatus() == 304) {
    // 304 response, do nothing
  }
  // otherwise the response is some other error
}

Lihat contoh Pengambilan Kondisional Menggunakan Blogger untuk melihat contoh yang lebih praktis tentang penggunaan ETag di klien JavaScript. Contoh ini mengumpulkan informasi tentang Blogger dalam interval 5 detik yang mencari info terbaru ke blog Anda. Jika ada perubahan, contoh ini akan memperbarui daftar postingan.

Menggunakan ETag untuk Memperbarui dan Menghapus Data

Penggunaan ETag pada permintaan update/hapus memastikan bahwa beberapa klien tidak menimpa perubahan satu sama lain secara tidak sengaja. Dalam hal ini, ETag disertakan dengan header If-Match:

If-Match: ETAG GOES HERE

Jika ETag dalam permintaan cocok dengan ETag di server, update/hapus akan berhasil. Namun, ketidakcocokan ETag menunjukkan bahwa entri telah berubah, dan pembaruan/penghapusan gagal. Dalam hal ini, aplikasi harus meminta instance data yang baru, lalu coba perbarui/hapus lagi.

Dalam kasus tertentu, Anda mungkin ingin memaksa perubahan Anda, terlepas dari perubahan lain pada entri. Anda dapat melakukannya dengan meneruskan * ke header If-Match:

If-Match: *

Perhatikan bahwa tindakan ini akan menggantikan perubahan yang dibuat oleh klien lain, jadi gunakan dengan cermat.

Anda hanya dapat memperbarui/menghapus entri dengan ETag yang kuat. Menentukan ETag yang lemah akan menghasilkan error. Untuk melindungi kasus ini, klien JavaScript tidak akan menetapkan ETag yang lemah pada permintaan update dan penghapusan.

ETag digunakan dengan cara yang sama seperti pengambilan bersyarat:

function updateData(entry, service) {
  var etag = entry.getEtag();
  var opt_params = {};
  opt_params['etag'] = etag; // Or use '*' to force an update.
  service.updateEntry(successHandler, errorHandler, opt_params);
}

function successHandler(response) {
  // Successful update
}

function errorHandler(errorObj) {
  // ERROR - Update failed. Could be due to an ETag mismatch, but check the
  // error message to make sure. An ETag error will be in the format:
  // Mismatch: etags = ["Qnc-fTVSLyp7ImA9WxJbFEsDRAw."], version = [1249675665358000]
}

Saat melakukan update, ETag dapat ditentukan di dua tempat:

  1. Pada entri itu sendiri, menggunakan metode getEtag() dan setEtag().
  2. Di header, menggunakan objek opt_params (seperti yang ditunjukkan di atas).

Entri yang dimuat dari permintaan GET sebelumnya akan memiliki kolom ETag yang telah ditetapkan. Jadi, menentukan ETag yang sama dalam objek opt_params menjadi redundan. Jika ETag ditentukan dalam isi entri dan di opt_params, ETag dalam opt_params akan diprioritaskan. Hal ini dapat sedikit membingungkan, jadi jika Anda mengalami masalah dengan update bersyarat, pastikan untuk memeriksa ETag di entri dan objek opt_params.

Untuk mempermudah, class google.gdata.Entry juga memiliki metode updateEntry() dan deleteEntry() sendiri. Jika class entri sudah memiliki ETag, Anda tidak perlu menambahkannya ke permintaan; library klien akan melakukannya secara otomatis untuk Anda. Contoh:

// entry was loaded from a previous request.  No need to specify
// an ETag in opt_params here, it is added automatically.
entry.deleteEntry(successHandler, errorHandler);

Hal ini memberi Anda manfaat ETag tanpa khawatir jika Anda menyetelnya dengan benar. Namun, jika Anda ingin memaksa pembaruan menggunakan '*', Anda harus selalu menyertakan objek opt_params dengan 'etag' = '*'.

Anda dapat melihat update bersyarat di tempat kerja pada Update Kondisional di Kontak. Pertama-tama, sampel akan membuat Grup Kontak pengujian tempat semua data yang digunakan oleh contoh ini akan dibuat. Jangan ragu untuk menghapus Grup Kontak ini setelah Anda selesai menggunakan sampel. Contoh tersebut kemudian memuat dua iframe dengan konten dari Grup Kontak. Anda dapat melakukan pembaruan di satu iframe dan melihat pengaruhnya terhadap pembaruan di iframe lainnya. Buka contoh untuk detail selengkapnya tentang cara menggunakannya.

Contoh

Referensi

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

Kembali ke atas