Panduan Developer Library Klien .NET

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

Google menyediakan serangkaian library klien untuk berinteraksi dengan layanan yang kompatibel dengan GData, dalam berbagai bahasa pemrograman. Dengan menggunakan library ini, Anda dapat membuat permintaan GData, mengirimkannya ke layanan, dan menerima respons.

Dokumen ini memberikan serangkaian contoh penggunaan umum library klien versi C#, diikuti dengan informasi lain tentang penulisan klien GData. Di akhir dokumen ini terdapat link ke dokumentasi referensi untuk library klien C#, dalam format NDoc.

Untuk menggunakan library klien ini, Anda memerlukan runtime .NET 1.1, dan Anda juga harus menginstal semua patch terbaru.

Download library klien .NET.

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

Daftar Isi

  1. Penonton
  2. Ringkasan model data
  3. Tutorial dan contoh
  4. Referensi

Audiens

Dokumen ini ditujukan bagi programmer C# yang ingin menulis aplikasi klien yang dapat berinteraksi dengan layanan GData.

Dokumen ini mengasumsikan bahwa Anda memahami ide umum di balik protokol Google Data API. Selain itu, Anda dianggap telah memahami cara memprogram di C#.

Ringkasan model data

Library klien C# menyediakan serangkaian class yang sesuai dengan elemen dan jenis data yang digunakan oleh Google Data API. Misalnya, ada class Feed, yang sesuai dengan elemen <atom:feed>; class ini memiliki metode untuk membuat entri, mendapatkan dan menetapkan nilai berbagai sub-elemen, dan sebagainya. Ada juga class Entry, yang sesuai dengan elemen <atom:entry>. Tidak setiap elemen yang ditentukan di Google Data API memiliki class-nya sendiri; untuk mengetahui detailnya, lihat dokumentasi referensi.

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

Untuk mengirimkan feed atau entri ke layanan, Anda membuat objek Feed atau Entry, lalu memanggil metode library (seperti metode insert) untuk menerjemahkan objek secara otomatis ke XML dan mengirimkannya.

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

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

Tutorial dan contoh

Contoh berikut menunjukkan cara mengirim berbagai permintaan GData menggunakan library klien C#.

Untuk membuatnya lebih konkret, contoh ini menunjukkan cara berinteraksi dengan layanan tertentu: Google Kalender. Kami akan menunjukkan tempat-tempat yang membuat Kalender berbeda dari layanan Google lainnya, untuk membantu Anda menyesuaikan contoh ini agar dapat digunakan dengan layanan lain. Untuk mengetahui informasi selengkapnya tentang Kalender, lihat dokumentasi Google Calendar Data API.

Membangun dan menjalankan klien

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

using Google.GData.Client;

Meminta feed

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

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

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

Anda juga harus memberikan autentikasi yang sesuai. Perhatikan bahwa sistem autentikasi yang kita gunakan di sini (dikenal sebagai "Autentikasi Google untuk Aplikasi yang Diinstal") hanya cocok untuk digunakan dalam aplikasi klien yang diinstal seperti klien desktop, bukan untuk digunakan dalam aplikasi web. Untuk mengetahui informasi selengkapnya tentang autentikasi, lihat dokumentasi Autentikasi Akun Google.

Untuk meminta feed Kalender menggunakan library klien C#, bagi pengguna dengan alamat email "jo@gmail.com" dan sandi "mypassword", gunakan kode berikut:

// Create a query and service object:

FeedQuery query = new FeedQuery();
Service service = new Service("cl", "exampleCo-exampleApp-1"));
// Set your credentials:
service.setUserCredentials("jo@gmail.com", "mypassword");

// Create the query object:
query.Uri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Tell the service to query:
AtomFeed calFeed = service.Query(query);

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

  1. Dapatkan atau buat URL yang sesuai.
  2. Jika Anda mengirim data ke layanan (misalnya, jika Anda menyisipkan entri baru), ubah data mentah menjadi objek menggunakan class library klien. (Langkah ini tidak berlaku jika Anda hanya meminta feed, seperti yang kami lakukan dalam contoh ini.)
  3. Buat instance Service baru, tetapkan nama layanan (seperti "cl" untuk Kalender) dan nama aplikasi Anda (dalam bentuk companyName-applicationName-versionID).
  4. Tetapkan kredensial yang sesuai.
  5. Panggil metode untuk mengirim permintaan dan menerima hasil apa pun.

Metode service.setUserCredentials menetapkan properti service.Credentials dengan objek kredensial Jaringan .NET standar. Kredensial ditetapkan ke ID dan sandi pengguna yang atas nama siapa klien Anda mengirimkan kueri. Contoh dalam dokumen ini menggunakan sistem autentikasi "Authentication for Installed Applications"; untuk mengetahui informasi selengkapnya tentang sistem autentikasi lainnya, lihat dokumentasi Autentikasi Akun Google.

Untuk meminta seluruh feed, Anda memanggil metode service.Query, yang mengambil objek FeedQuery dan menampilkan seluruh feed yang ditemukan di URL tersebut. Kami akan menunjukkan cara mengirim kueri yang lebih spesifik nanti dalam dokumen ini.

Seperti metode lain dari class Service, Query menangani autentikasi dan pengalihan sesuai kebutuhan.

Menyisipkan item baru

Untuk menyisipkan item ke dalam feed Kalender, Anda dapat menggunakan kode berikut:

AtomEntry entry = new AtomEntry();
AtomPerson author = new AtomPerson(AtomPersonType.Author);
author.Name = "Jo March"; 
author.Email = "jo@gmail.com";
entry.Authors.Add(author);
entry.Title.Text = "Tennis with Beth"; 
entry.Content.Content = "Meet for a quick lesson.";

Uri postUri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Send the request and receive the response:
AtomEntry insertedEntry = service.Insert(postUri, entry);

Setelah menetapkan URL, kita membuat objek AtomEntry.

Judul entri adalah AtomTextConstruct, sebuah class yang menyimpan teks dalam berbagai bentuk (teks biasa, HTML, atau XHTML). Konten entri diwakili oleh objek AtomContent, yaitu class yang dapat menyimpan teks biasa atau bentuk konten lainnya, termasuk XML dan data biner.

Setiap penulis ditampilkan sebagai nama, URI, dan alamat email. (Dalam contoh ini, kita tidak menyertakan URI.) Anda menambahkan penulis ke entri dengan menambahkan objek AtomAuthor ke koleksi Authors entri.

Kita menggunakan objek Service yang sama dengan yang kita buat dalam contoh sebelumnya. Dalam hal ini, metode yang akan dipanggil adalah Insert, yang mengirimkan item ke URL penyisipan yang ditentukan.

Layanan ini menampilkan entri yang baru dibuat, yang mungkin berisi elemen tambahan yang dihasilkan server, seperti URL pengeditan untuk entri.

Kode di atas setara dengan mengirim POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (dengan autentikasi yang tepat) dan memberikan entri.

Meminta entri tertentu

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

Dalam konteks rangkaian contoh ini, pengambilan entri tersebut tidak terlalu diperlukan, karena Kalender sudah menampilkan entri yang dimasukkan; tetapi teknik yang sama dapat diterapkan kapan pun Anda mengetahui URL untuk suatu entri.

FeedQuery singleQuery = new FeedQuery();
singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); 
AtomFeed newFeed = service.Query(singleQuery);
AtomEntry retrievedEntry = newFeed.Entries[0];

Entri yang disisipkan memiliki properti, SelfUri, yang menampilkan objek AtomUri yang, menggunakan metode ToString(), dapat digunakan untuk membuat objek URI baru.

Kemudian, kita hanya perlu memanggil metode Query layanan untuk mendapatkan objek AtomFeed baru, dengan hanya satu entri dalam koleksi Entri-nya.

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

Menelusuri entri

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

FeedQuery myQuery = new Query(feedUrl);
myQuery.Query = "Tennis"; 
AtomFeed myResultsFeed = myService.Query(myQuery);
if (myResultsFeed.Entries.Count > 0) {
  AtomEntry firstMatchEntry = myResultsFeed.Entries[0]; 
  String myEntryTitle = firstMatchEntry.Title.Text; 
}

Contoh ini dimulai dengan membuat objek FeedQuery, yang sebagian besar terdiri dari URL dan parameter kueri terkait. Setiap parameter kueri GData standar memiliki properti.

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

Koleksi Entries feed menampilkan daftar entri dalam feed; Entries.Count menampilkan jumlah entri dalam feed.

Dalam hal ini, jika kueri menampilkan hasil apa pun, kita akan menetapkan hasil yang cocok pertama ke objek AtomEntry. Kemudian, kita menggunakan properti Title class AtomEntry untuk mengambil judul entri.

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

Mengirim kueri menurut kategori

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

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

AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);

Tentu saja, class AtomCategory mewakili kategori yang akan digunakan dalam filter kategori. Class QueryCategory dapat berisi beberapa kategori, tetapi dalam kasus ini kita membuat filter dengan hanya satu kategori.

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

Kita kembali menggunakan metode Query untuk mengirim kueri ke layanan.

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

Memperbarui item

Untuk memperbarui item yang ada, gunakan kode berikut. Dalam contoh berikut, kita mengubah judul entri yang sebelumnya diambil dari teks lamanya ("Tennis with Beth") menjadi "Important meeting".

retrievedEntry.Title.Text = "Important meeting";
retrievedEntry.Update();

Pertama, kita menetapkan judul baru untuk entri yang kita ambil sebelumnya. Kemudian, kita hanya memanggil metode Upate untuk mengirim entri yang diperbarui ke layanan.

Layanan menampilkan entri yang diperbarui, termasuk URL baru untuk versi baru entri ini. (Untuk mengetahui informasi selengkapnya tentang versi entri, lihat bagian Optimistic concurrency dalam dokumen referensi protokol v1.)

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

Menghapus item

Untuk menghapus item yang ada, gunakan kode berikut:

updateEntry.Delete();

URL yang digunakan untuk penghapusan sama dengan URL pengeditan, jadi contoh ini sangat mirip dengan contoh sebelumnya, kecuali tentu saja kita memanggil metode Delete, bukan Update.

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

Bekerja dengan feed Google Kalender

Contoh di atas menguraikan cara menggunakan Google Data C# API untuk bekerja dengan feed GData generik. Namun, saat Anda bekerja dengan feed Google Kalender, feed tersebut berisi banyak data khusus kalender yang tidak mudah diakses menggunakan objek berorientasi Atom standar di library API dasar. Untuk membantu Anda berinteraksi dengan feed tersebut, kami menyediakan ekstensi berikut:

using Google.GData.Extensions;
using Google.GData.Calendar;

Namespace Ekstensi menangani ekstensi secara umum; namespace Kalender memberi Anda akses ke layanan kalender, feed, dan objek kueri yang disesuaikan. Anda dapat menemukan contoh yang lebih rumit tentang cara penggunaan ekstensi tersebut di subdirektori /Samples pada penginstalan C# API. Objek berikut ditambahkan:

EventQuery
Subclass FeedQuery, yang memungkinkan Anda menetapkan dua parameter kustom untuk layanan Kalender (start-min dan start-max).
CalendarService
Subclass layanan, yang dapat menampilkan feed acara.
EventFeed
Subclass AtomFeed, yang mengekspos EventEntries.
EventEntry
Subkelas AtomEntry, yang memiliki properti tambahan terkait data kalender.

Untuk mengetahui detail selengkapnya tentang class khusus tersebut, lihat dokumentasi API dan program contoh.

Referensi

Untuk informasi referensi tentang library klien C#, lihat dokumentasi referensi.

Kembali ke atas