Halaman ini diterjemahkan oleh Cloud Translation API.

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 kumpulan library klien untuk berinteraksi dengan layanan yang mendukung GData, dalam berbagai bahasa pemrograman. Dengan library ini, Anda dapat membuat permintaan GData, mengirimkannya ke layanan, dan menerima respons.

Dokumen ini menyediakan serangkaian contoh penggunaan umum library klien versi C#, yang 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 juga harus aktual untuk semua patch.

Download library klien .NET.

Contoh 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 menggunakan Kalender, baca Panduan Developer Calendar Data API.

Daftar Isi

Audiens
Ringkasan model data
Tutorial dan contoh
Referensi

Audiens

Dokumen ini ditujukan untuk 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. Asumsi ini juga mengasumsikan bahwa Anda tahu cara memprogram di C#.

Ringkasan model data

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

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

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

Jika ingin, Anda dapat mengurai dan/atau membuat XML; cara termudah untuk melakukannya adalah dengan library pihak ketiga yang sesuai.

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

Tutorial dan contoh

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

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

Membuat dan menjalankan klien Anda

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

using Google.GData.Client;

Meminta feed

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

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

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

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

Untuk meminta feed Kalender menggunakan library klien C#, untuk 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 merepresentasikan koneksi klien (dengan autentikasi) ke layanan GData. Prosedur umum untuk mengirim kueri ke layanan menggunakan library klien terdiri dari langkah-langkah berikut:

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

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

Untuk meminta seluruh feed, panggil 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 class Service lainnya, Query menangani autentikasi dan pengalihan sesuai kebutuhan.

Menyisipkan item baru

Untuk menyisipkan item ke 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 akan membuat objek AtomEntry.

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

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

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

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

Kode di atas sama 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 tertentu yang Anda sisipkan dalam contoh sebelumnya.

Dalam konteks rangkaian contoh ini, mengambil entri tersebut tidaklah benar-benar diperlukan, karena Kalender sudah mengembalikan entri yang disisipkan; tetapi teknik yang sama dapat diterapkan setiap kali Anda mengetahui URL 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, dengan metode ToString(), dapat digunakan untuk membuat objek URI baru.

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

Kode di atas sama 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 ditambah 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 pertama yang cocok ke objek AtomEntry. Kemudian, kita menggunakan properti Title class AtomEntry untuk mengambil judul entri.

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

Membuat kueri berdasarkan kategori

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

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

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

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

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

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

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

Memperbarui item

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

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

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

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

Kode di atas kira-kira setara dengan mengirim PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID ke layanan, bersama dengan 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 edit, sehingga contoh ini sangat mirip dengan yang sebelumnya, kecuali tentu saja kita memanggil metode Delete, bukan Update.

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

Bekerja dengan feed Google Kalender

Contoh di atas menguraikan cara menggunakan Google Data C# API agar dapat berfungsi dengan feed GData generik. Namun, saat Anda bekerja dengan feed Google Kalender, feed 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 memberikan ekstensi berikut:

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

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

KueriPeristiwa: Subclass FeedQuery, yang memungkinkan Anda menetapkan dua parameter kustom untuk layanan Kalender (start-min dan start-max).
LayananKalender: Subclass layanan, yang dapat menampilkan feed peristiwa.
Feed Peristiwa: Subclass AtomFeed, yang menampilkan EventEntries.
Entri Peristiwa: Subclass AtomEntry, yang memiliki properti tambahan yang terkait dengan data kalender.

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

Referensi

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

Kembali ke atas