เอกสารนี้อธิบายวิธีใช้ไลบรารีของไคลเอ็นต์ Java เพื่อส่งคําค้นหา Google Data API ("GData") และตีความคําตอบที่ส่งคืน
Google มีชุดไลบรารีของไคลเอ็นต์ในภาษาโปรแกรมต่างๆ สําหรับการโต้ตอบกับบริการที่มี API ข้อมูล เมื่อใช้ไลบรารีเหล่านี้ คุณจะสร้างคําขอ GData ส่งคําขอไปยังบริการ และรับการตอบกลับได้
เอกสารนี้ให้ข้อมูลทั่วไปเกี่ยวกับการใช้ไลบรารีของไคลเอ็นต์ Java พร้อมด้วยชุดตัวอย่างการใช้งานทั่วไป
หากต้องการใช้ไลบรารีของไคลเอ็นต์นี้ คุณต้องใช้ Java 1.5
ดาวน์โหลดไลบรารีของไคลเอ็นต์ Java
ตัวอย่างของคู่มือนี้เรียกว่า API ของ Google ปฏิทิน แต่คู่มือนี้ไม่ใช่คําแนะนําที่ถูกต้องหรือเป็นปัจจุบันเกี่ยวกับการใช้ API ของปฏิทิน สําหรับข้อมูลเกี่ยวกับการใช้ไลบรารีของไคลเอ็นต์ Java กับ Data API ของบริการหนึ่งๆ โปรดดูเอกสารเฉพาะบริการ ตัวอย่างเช่น หากคุณกําลังใช้งานปฏิทิน โปรดอ่านคู่มือสําหรับนักพัฒนาซอฟต์แวร์ API ข้อมูลปฏิทิน
เนื้อหา
ผู้ชม
เอกสารนี้มีไว้สําหรับโปรแกรมเมอร์ 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 ขั้นตอนทั่วไปสําหรับการส่งคําขอไปยังบริการโดยใช้ไลบรารีของไคลเอ็นต์ประกอบด้วยขั้นตอนต่อไปนี้
- รับหรือสร้าง URL ที่เหมาะสม
- หากส่งข้อมูลไปยังบริการ (เช่น หากคุณแทรกรายการใหม่) ให้แปลงข้อมูลดิบเป็นออบเจ็กต์โดยใช้คลาสไลบรารีของไคลเอ็นต์ (ขั้นตอนนี้จะไม่มีผลหากคุณเพียงแค่ขอฟีด เช่นเดียวกับที่เราทําในตัวอย่างนี้)
- สร้างอินสแตนซ์
GoogleService
ใหม่ โดยตั้งชื่อบริการ (เช่น"cl"
สําหรับปฏิทิน) และชื่อแอปพลิเคชัน (ในรูปแบบcompanyName-applicationName-versionID
) - ตั้งค่าข้อมูลเข้าสู่ระบบที่เหมาะสม
- ระบุไลบรารีที่ฟีดจะใช้ฟีดเพื่อให้ไลบรารีสามารถแยกวิเคราะห์ฟีดที่ส่งกลับได้อย่างถูกต้อง
- เรียกใช้วิธีในการส่งคําขอและรับผลลัพธ์
เมธอด 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)