การใช้ไลบรารีของไคลเอ็นต์ Java

เอกสารนี้อธิบายวิธีใช้ไลบรารีของไคลเอ็นต์ Java เพื่อส่งคําค้นหา Google Data API ("GData") และตีความคําตอบที่ส่งคืน

Google มีชุดไลบรารีของไคลเอ็นต์ในภาษาโปรแกรมต่างๆ สําหรับการโต้ตอบกับบริการที่มี API ข้อมูล เมื่อใช้ไลบรารีเหล่านี้ คุณจะสร้างคําขอ GData ส่งคําขอไปยังบริการ และรับการตอบกลับได้

เอกสารนี้ให้ข้อมูลทั่วไปเกี่ยวกับการใช้ไลบรารีของไคลเอ็นต์ Java พร้อมด้วยชุดตัวอย่างการใช้งานทั่วไป

หากต้องการใช้ไลบรารีของไคลเอ็นต์นี้ คุณต้องใช้ Java 1.5

ดาวน์โหลดไลบรารีของไคลเอ็นต์ Java

ตัวอย่างของคู่มือนี้เรียกว่า API ของ Google ปฏิทิน แต่คู่มือนี้ไม่ใช่คําแนะนําที่ถูกต้องหรือเป็นปัจจุบันเกี่ยวกับการใช้ API ของปฏิทิน สําหรับข้อมูลเกี่ยวกับการใช้ไลบรารีของไคลเอ็นต์ Java กับ Data API ของบริการหนึ่งๆ โปรดดูเอกสารเฉพาะบริการ ตัวอย่างเช่น หากคุณกําลังใช้งานปฏิทิน โปรดอ่านคู่มือสําหรับนักพัฒนาซอฟต์แวร์ API ข้อมูลปฏิทิน

เนื้อหา

  1. ผู้ชม
  2. ภาพรวมของโมเดลข้อมูล
  3. บทแนะนําและตัวอย่าง
    1. การสร้างและเรียกใช้ไคลเอ็นต์
    2. การขอฟีด
    3. การแทรกรายการใหม่
    4. การขอรายการที่เจาะจง
    5. การค้นหารายการ
    6. การค้นหาตามหมวดหมู่
    7. การอัปเดตรายการ
    8. การลบรายการ
  4. Reference

ผู้ชม

เอกสารนี้มีไว้สําหรับโปรแกรมเมอร์ Java ที่ต้องการเขียนแอปพลิเคชันไคลเอ็นต์ซึ่งโต้ตอบกับบริการ GData ได้

เอกสารนี้จะถือว่าคุณเข้าใจแนวคิดทั่วไปเบื้องหลังโปรโตคอล Google Data API และจะถือว่าคุณรู้วิธีเขียนโปรแกรมใน Java ด้วย

สําหรับข้อมูลอ้างอิงเกี่ยวกับคลาสและวิธีการที่ไลบรารีของไคลเอ็นต์มีให้ โปรดดูเอกสารอ้างอิงไลบรารีของไคลเอ็นต์ Java (ในรูปแบบ JavaScript)

เอกสารนี้ออกแบบมาให้อ่านตามลําดับ โดยตัวอย่างแต่ละรายการจะสร้างขึ้นจากตัวอย่างก่อนหน้านี้

ภาพรวมของโมเดลข้อมูล

ไลบรารีของไคลเอ็นต์ Java ใช้ชุดคลาสเพื่อแสดงองค์ประกอบที่ Google Data API ใช้ เช่น มีคลาสฟีดซึ่งสอดคล้องกับองค์ประกอบ <atom:feed> ซึ่งมีวิธีการสร้างรายการ การรับค่า ขององค์ประกอบย่อยต่างๆ เป็นต้น นอกจากนี้ยังมีคลาสรายการที่ตรงกับองค์ประกอบ <atom:entry> องค์ประกอบบางอย่างที่กําหนดไว้ใน Google Data API จะไม่มีคลาสของตัวเอง โปรดดูรายละเอียดในเอกสารอ้างอิง

ไลบรารีจะแยกวิเคราะห์เนื้อหา Atom โดยอัตโนมัติและใส่ค่าขององค์ประกอบ Atom ลงในออบเจ็กต์ที่เหมาะสม เช่น เมธอด getFeed จะได้รับฟีด แยกวิเคราะห์ และแสดงผลออบเจ็กต์ Feed ด้วยค่าผลลัพธ์

หากต้องการส่งฟีดหรือรายการไปยังบริการ ให้สร้างออบเจ็กต์ฟีดหรือรายการ จากนั้นเรียกใช้เมธอดของไลบรารี (เช่นเมธอด insert) เพื่อแปลออบเจ็กต์เป็น XML และส่งโดยอัตโนมัติ

คุณจะแยกวิเคราะห์และ/หรือสร้าง XML ด้วยตนเองได้หากต้องการ วิธีที่ง่ายที่สุดในการดําเนินการดังกล่าวคือด้วยไลบรารีของบุคคลที่สามที่เหมาะสม เช่น Rome

โมเดล XML ของ Google นั้นขยายได้ง่ายเช่นเดียวกับไวยากรณ์ XML ของ Google Data API ตัวอย่างเช่น ไลบรารีของไคลเอ็นต์จะมีคลาสที่ตรงกับองค์ประกอบที่กําหนดไว้ในเนมสเปซของ Google Data

บทแนะนําและตัวอย่าง

ตัวอย่างต่อไปนี้แสดงวิธีส่งคําขอ API ข้อมูลหลายรายการโดยใช้ไลบรารีของไคลเอ็นต์ Java

เพื่อให้ข้อมูลมีความเฉพาะเจาะจงมากขึ้น ตัวอย่างเหล่านี้แสดงวิธีโต้ตอบกับบริการหนึ่งๆ โดยเฉพาะ: Google ปฏิทิน เราจะกําหนดตําแหน่งที่ปฏิทินแตกต่างจากบริการอื่นๆ ของ Google เพื่อช่วยคุณปรับตัวอย่างเหล่านี้สําหรับใช้กับบริการอื่นๆ โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับปฏิทินในเอกสารประกอบของ Google ปฏิทิน Data API

การสร้างและเรียกใช้ไคลเอ็นต์

ในการรวบรวมตัวอย่างในเอกสารนี้ คุณจะต้องใช้ข้อความนําเข้าต่อไปนี้

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;
import java.net.URL;

การขอฟีด

ตามที่อธิบายไว้ในเอกสาร Google ปฏิทิน Data API คุณสามารถขอฟีดปฏิทินได้โดยการส่งคําขอ HTTP ต่อไปนี้ไปยังปฏิทิน

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

แน่นอนว่าคุณต้องแทนที่ userID ด้วยอีเมลของผู้ใช้ โปรดดูรายละเอียดในเอกสารปฏิทิน แต่คุณสามารถใช้ URL เริ่มต้นพิเศษสําหรับการโต้ตอบกับปฏิทินได้ (ดังที่อธิบายไว้ในเอกสารปฏิทิน) แต่เราจะใช้ URL แบบเต็มของฟีดส่วนตัวซึ่งมีรหัสผู้ใช้แทนในเอกสารนี้

และคุณยังต้องระบุการตรวจสอบสิทธิ์ที่เหมาะสมด้วย ความแตกต่างที่สําคัญระหว่างตัวอย่างนี้กับตัวอย่างแรกในเอกสารปฏิทินคือ (1) ตัวอย่างนี้มีการตรวจสอบสิทธิ์ และ (2) ตัวอย่างนี้ใช้คลาส GoogleService ทั่วไปมากกว่าคลาส CalendarService เฉพาะปฏิทิน

โปรดทราบว่าระบบการตรวจสอบสิทธิ์ที่เราใช้ที่นี่ (เรียกว่า "การตรวจสอบสิทธิ์ Google สําหรับแอปพลิเคชันที่ติดตั้งไว้") จะเหมาะกับการใช้งานในแอปพลิเคชันไคลเอ็นต์ที่ติดตั้งไว้ เช่น ไคลเอ็นต์บนเดสก์ท็อป เท่านั้น ห้ามใช้ในเว็บแอปพลิเคชัน โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับการตรวจสอบสิทธิ์ในเอกสารประกอบการตรวจสอบสิทธิ์บัญชี Google

หากต้องการขอฟีดปฏิทินโดยใช้ไลบรารีของไคลเอ็นต์ Java สําหรับผู้ใช้ที่มีอีเมล "liz@gmail.com" และรหัสผ่าน "mypassword" ให้ใช้โค้ดต่อไปนี้

// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");

// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());

// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);

คลาส GoogleService แสดงถึงการเชื่อมต่อไคลเอ็นต์ (ที่มีการตรวจสอบสิทธิ์) กับบริการ GData ขั้นตอนทั่วไปสําหรับการส่งคําขอไปยังบริการโดยใช้ไลบรารีของไคลเอ็นต์ประกอบด้วยขั้นตอนต่อไปนี้

  1. รับหรือสร้าง URL ที่เหมาะสม
  2. หากส่งข้อมูลไปยังบริการ (เช่น หากคุณแทรกรายการใหม่) ให้แปลงข้อมูลดิบเป็นออบเจ็กต์โดยใช้คลาสไลบรารีของไคลเอ็นต์ (ขั้นตอนนี้จะไม่มีผลหากคุณเพียงแค่ขอฟีด เช่นเดียวกับที่เราทําในตัวอย่างนี้)
  3. สร้างอินสแตนซ์ GoogleService ใหม่ โดยตั้งชื่อบริการ (เช่น "cl" สําหรับปฏิทิน) และชื่อแอปพลิเคชัน (ในรูปแบบ companyName-applicationName-versionID)
  4. ตั้งค่าข้อมูลเข้าสู่ระบบที่เหมาะสม
  5. ระบุไลบรารีที่ฟีดจะใช้ฟีดเพื่อให้ไลบรารีสามารถแยกวิเคราะห์ฟีดที่ส่งกลับได้อย่างถูกต้อง
  6. เรียกใช้วิธีในการส่งคําขอและรับผลลัพธ์

เมธอด setUserCredentials จะระบุรหัสและรหัสผ่านของผู้ใช้ที่ไคลเอ็นต์ส่งคําค้นหา ตัวอย่างในเอกสารนี้ใช้ระบบการตรวจสอบสิทธิ์ "การตรวจสอบสิทธิ์สําหรับแอปพลิเคชันที่ติดตั้ง" โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับระบบการตรวจสอบสิทธิ์ที่หัวข้อการตรวจสอบสิทธิ์บัญชี Google

หลังจากตั้งค่าข้อมูลเข้าสู่ระบบแล้ว คุณจะสามารถระบุส่วนขยายที่ฟีดจะใช้ได้โดยเรียกใช้เมธอด declareExtensions ในกรณีนี้ สมมติว่าฟีดเป็นฟีดเหตุการณ์ ดังนั้นจึงจะใช้ส่วนขยายที่กําหนดโดยประเภทเหตุการณ์

หากต้องการขอฟีดทั้งหมด คุณจะเรียกเมธอด getFeed ซึ่งจะใช้ URL และส่งฟีดทั้งหมดที่พบใน URL นั้น เราจะแสดงวิธีส่งคําค้นหาที่เฉพาะเจาะจงมากขึ้นในเอกสารนี้

getFeed จะจัดการการตรวจสอบสิทธิ์และการเปลี่ยนเส้นทางตามที่จําเป็นเช่นเดียวกับวิธีอื่นๆ ของชั้นเรียน GoogleService

การแทรกรายการใหม่

คุณอาจใช้รหัสต่อไปนี้เพื่อสร้างกิจกรรมใหม่ในปฏิทิน

URL postUrl =
  new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();

myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));

Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);

DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);

// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);

หลังจากตั้งค่า URL แล้ว เราจะสร้างออบเจ็กต์ EventEntry EventEntry มาจากคลาสฐานนามธรรม BaseEntry ซึ่งเป็นคลาสระดับบนสุดสําหรับคลาส Entry ซึ่งแสดงองค์ประกอบ <atom:entry>

คลาส EventEntry แสดงถึงประเภทของเหตุการณ์ ดูข้อมูลเพิ่มเติมได้ที่เอกสารประเภท สําหรับบริการอื่นๆ นอกเหนือจากปฏิทิน คุณอาจกําหนดรายการส่งคืนให้กับออบเจ็กต์ Entry แทนที่จะเป็นออบเจ็กต์ EventEntry

ชื่อรายการคือ TextConstruct ซึ่งเป็นคลาสที่เก็บข้อความหลายรูปแบบ (ข้อความธรรมดา, HTML หรือ XHTML) เนื้อหารายการจะแสดงด้วยออบเจ็กต์ Content ซึ่งเป็นคลาสที่สามารถเก็บข้อความธรรมดาหรือเนื้อหารูปแบบอื่นๆ ซึ่งรวมถึง XML และข้อมูลไบนารี (แต่เมธอด setContent ยังยอมรับ TextConstruct ได้ด้วย)

ผู้เขียนแต่ละคนจะแสดงเป็นชื่อ, URI และอีเมล (ในตัวอย่างนี้เราจะยกเว้น URI) คุณเพิ่มผู้เขียนลงในรายการได้โดยเรียกใช้เมธอด getAuthors().add ของรายการ

เราใช้ออบเจ็กต์ GoogleService เดียวกันกับที่เราสร้างขึ้นในตัวอย่างก่อนหน้านี้ ในกรณีนี้ วิธีเรียกคือ insert ซึ่งจะส่งรายการไปยัง URL การแทรกที่ระบุ

บริการจะแสดงผลรายการที่สร้างขึ้นใหม่ซึ่งอาจมีองค์ประกอบอื่นๆ ที่เซิร์ฟเวอร์สร้างขึ้น เช่น URL สําหรับแก้ไข

รหัสสถานะ HTTP จะแสดงเป็นข้อยกเว้น

รหัสข้างต้นเทียบเท่ากับการส่ง POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (ที่มีการตรวจสอบสิทธิ์ที่เหมาะสม) และระบุรายการในรูปแบบของเหตุการณ์

การขอรายการที่เจาะจง

โค้ดต่อไปนี้ช่วยให้คุณขอรายการที่เจาะจงที่คุณแทรกไว้ในตัวอย่างก่อนหน้านี้ได้

ในบริบทของตัวอย่างชุดนี้ การดึงข้อมูลนั้นไม่จําเป็นมาก เนื่องจากปฏิทินส่งคืนรายการที่แทรกอยู่แล้ว แต่สามารถใช้เทคนิคเดียวกันเมื่อคุณรู้ URI ของรายการนั้น

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

รายการที่แทรกมีเมธอด getSelfLink ที่แสดงผลออบเจ็กต์ Link ที่มี URL ของรายการ คลาส Link มีวิธี getHref ที่จะแสดงผล URL เป็น String ซึ่งคุณจะสร้างออบเจ็กต์ URL ได้

จากนั้นเราจึงต้องเรียกใช้เมธอด getEntry ของบริการเพื่อรับรายการ

โปรดทราบว่าเราใช้ EventEntry.class เป็นพารามิเตอร์สําหรับ getEntry ซึ่งบ่งบอกว่าเราคาดหวังอย่างเจาะจงว่าบริการจะส่งคืนเหตุการณ์ ไม่ใช่เพียงรายการธรรมดา สําหรับบริการอื่นที่ไม่ใช่ปฏิทิน คุณอาจส่งเพียง Entry.class แทน

รหัสข้างต้นเทียบเท่ากับการส่ง GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ไปยังปฏิทิน โดยมีการตรวจสอบสิทธิ์ที่เหมาะสม

รายการที่ค้นหา

หากต้องการเรียกข้อมูลรายการที่ตรงกันครั้งแรกจากการค้นหาข้อความแบบเต็ม ให้ใช้โค้ดต่อไปนี้

Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
  Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
  String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}

ตัวอย่างนี้เริ่มต้นด้วยการสร้างออบเจ็กต์ Query ซึ่งประกอบด้วย URL ส่วนใหญ่และพารามิเตอร์การค้นหาที่เกี่ยวข้อง พารามิเตอร์การค้นหา GData มาตรฐานแต่ละรายการมีวิธีการตั้งค่า นอกจากนี้ คุณยังตั้งค่าพารามิเตอร์การค้นหาที่กําหนดเองสําหรับบางบริการได้โดยใช้เมธอด addCustomParameter

หลังจากสร้าง Query เราจะส่งต่อเมธอดไปยังเมธอด query ของบริการ ซึ่งจะแสดงฟีดที่มีผลการค้นหา อีกวิธีการหนึ่งคือการสร้าง URL ด้วยตัวเอง (โดยใส่พารามิเตอร์การค้นหาต่อท้าย URL ของฟีด) จากนั้นเรียกเมธอด getFeed แต่เมธอด query จะให้นามธรรมที่มีประโยชน์อีกระดับ คุณจึงไม่ต้องสร้าง URL ด้วยตัวเอง

เมธอด getEntries ของฟีดจะแสดงรายการของรายการในฟีด getEntries().size จะแสดงผลจํานวนรายการในฟีด

ในกรณีนี้ หากการค้นหาแสดงผลการค้นหาใดๆ เราจะกําหนดผลลัพธ์แรกที่ตรงกันให้กับออบเจ็กต์ Entry จากนั้น เราจะใช้เมธอด getTitle().getPlainText ของคลาส Entry เพื่อดึงชื่อรายการและแปลงเป็นข้อความ

รหัสข้างต้นเทียบเท่ากับการส่ง GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis ไปยังปฏิทิน

การค้นหาตามหมวดหมู่

หมายเหตุ: Google ปฏิทินจะไม่เชื่อมโยงป้ายกํากับกับกิจกรรม ดังนั้นตัวอย่างนี้จึงใช้กับปฏิทินไม่ได้

หากต้องการเรียกฟีดซึ่งประกอบด้วยรายการทั้งหมดที่ตรงกับการค้นหาแบบทั้งข้อความก่อนหน้านี้และอยู่ในหมวดหมู่ใดหมวดหมู่หนึ่งหรือมีป้ายกํากับที่ต้องการ ให้ใช้โค้ดต่อไปนี้

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

แน่นอนว่าคลาส Category แสดงถึงหมวดหมู่ที่จะใช้ในตัวกรองหมวดหมู่ คลาส Query.CategoryFilter อาจมีได้หลายหมวดหมู่ แต่ในกรณีนี้เราจะสร้างตัวกรองที่มีเพียงหมวดหมู่เดียว

จากนั้นเราจะเพิ่มตัวกรองนั้นไปยังคําค้นหาที่มีอยู่ โดยยังคงมีสตริงคําค้นหาแบบเต็มจากตัวอย่างก่อนหน้านี้

เราใช้เมธอด query อีกครั้งเพื่อส่งคําค้นหาไปยังบริการ

หากปฏิทินอนุญาตให้ค้นหาหมวดหมู่ รหัสข้างต้นจะเท่ากับการส่ง GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis ไปยังปฏิทิน

กําลังอัปเดตรายการ

หากต้องการอัปเดตรายการที่มีอยู่ ให้ใช้โค้ดต่อไปนี้ ในตัวอย่างนี้ เราจะเปลี่ยนชื่อรายการที่ได้รับก่อนหน้านี้จากข้อความเก่า ("เทนนิสที่มีดาร์ซี") เป็น "การประชุมสําคัญ"

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

ก่อนอื่น เราตั้งชื่อใหม่สําหรับรายการที่ดึงไว้ก่อนหน้านี้ จากนั้นเราจึงจะได้รับ URL แก้ไขสําหรับรายการโดยใช้เมธอด getEditLink จากนั้น เราจะเรียกใช้เมธอด update ของบริการเพื่อส่งรายการที่อัปเดต

บริการส่งคืนรายการที่อัปเดตแล้ว รวมถึง URL ใหม่สําหรับเวอร์ชันใหม่ของรายการนี้ (หากต้องการข้อมูลเพิ่มเติมเกี่ยวกับเวอร์ชันที่ป้อน โปรดดูส่วนการเกิดขึ้นพร้อมกันของผลกระทบของเอกสารอ้างอิงโปรโตคอล)

โค้ดข้างต้นเทียบเท่ากับการส่ง PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ไปยังบริการโดยประมาณ พร้อมกับรายการใหม่ (ในรูปแบบ Atom) เพื่อแทนที่รายการเดิม

กําลังลบรายการ

หากต้องการลบรายการที่อัปเดตแล้ว ให้ใช้โค้ดต่อไปนี้

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

URL ที่จะใช้สําหรับการลบจะเหมือนกับ URL การแก้ไข ดังนั้นตัวอย่างนี้จึงคล้ายกับ URL ก่อนหน้านี้มาก ยกเว้นเราจะเรียกใช้เมธอด delete แทน update

โค้ดด้านบนเทียบเท่ากับการส่ง DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ไปยังบริการคร่าวๆ

ข้อมูลอ้างอิง

สําหรับข้อมูลอ้างอิงเกี่ยวกับคลาสและวิธีการที่ไลบรารีของไคลเอ็นต์มีให้ โปรดดูเอกสารอ้างอิงไลบรารีของไคลเอ็นต์ Java (ในรูปแบบ JavaScript)

กลับไปด้านบน