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

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

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

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

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

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

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

เนื้อหา

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

ผู้ชม

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

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

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

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

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

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

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

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

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

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

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

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

ตัวอย่างเหล่านี้แสดงวิธีโต้ตอบกับบริการหนึ่งๆ อย่าง Google ปฏิทิน เพื่อให้เห็นภาพได้ชัดเจนยิ่งขึ้น เราจะระบุจุดที่ปฏิทินแตกต่างจากบริการอื่นๆ ของ Google เพื่อช่วยให้คุณปรับตัวอย่างเหล่านี้ไปใช้กับบริการอื่นๆ ได้ ดูข้อมูลเพิ่มเติมเกี่ยวกับปฏิทินได้ในเอกสารประกอบของ Google Calendar 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 Calendar 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 method ระบุรหัสและรหัสผ่านของผู้ใช้ที่ไคลเอ็นต์ของคุณส่งคําค้นหาในนามของผู้ใช้ ตัวอย่างในเอกสารนี้ใช้ระบบการตรวจสอบสิทธิ์ "การตรวจสอบสิทธิ์สำหรับแอปพลิเคชันที่ติดตั้ง" ดูข้อมูลเพิ่มเติมเกี่ยวกับระบบการตรวจสอบสิทธิ์ได้ในเอกสารประกอบการตรวจสอบสิทธิ์บัญชี Google

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

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

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

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

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

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 ด้วย และคลาส 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 มาตรฐานแต่ละรายการมีเมธอด Setter นอกจากนี้ คุณยังตั้งค่าพารามิเตอร์การค้นหาที่กำหนดเองสำหรับบริการหนึ่งๆ ได้ด้วยการใช้เมธอด 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 การแก้ไข ดังนั้นตัวอย่างนี้จึงคล้ายกับตัวอย่างก่อนหน้ามาก ยกเว้นว่าเราเรียกใช้เมธอด delete แทน update

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

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

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

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