คู่มือสําหรับนักพัฒนาซอฟต์แวร์เกี่ยวกับไลบรารีของไคลเอ็นต์ .NET

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

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

เอกสารนี้มีตัวอย่างการใช้งานทั่วไปของไลบรารีของไคลเอ็นต์เวอร์ชัน C# ตามด้วยข้อมูลอื่นๆ เกี่ยวกับการเขียนไคลเอ็นต์ GData ส่วนท้ายของเอกสารนี้คือลิงก์ไปยังเอกสารอ้างอิงสําหรับไลบรารีของไคลเอ็นต์ C# ในรูปแบบ NDoc

หากต้องการใช้ไลบรารีของไคลเอ็นต์นี้ คุณต้องมีรันไทม์ .NET 1.1 และควรเป็นปัจจุบันบนแพตช์ทั้งหมดด้วย

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

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

เนื้อหา

  1. ผู้ชม
  2. ภาพรวมของโมเดลข้อมูล
  3. บทแนะนําและตัวอย่าง
  4. Reference

ผู้ชม

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

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

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

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

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

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

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

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

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

ตัวอย่างต่อไปนี้แสดงวิธีส่งคําขอ GData ต่างๆ โดยใช้ไลบรารีของไคลเอ็นต์ C#

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

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

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

using Google.GData.Client;

การขอฟีด

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

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

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

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

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

// 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);

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

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

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

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

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

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

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

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);

หลังจากตั้งค่า URL แล้ว เราจะสร้างออบเจ็กต์ AtomEntry

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

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

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

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

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

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

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

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

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

รายการที่แทรกมีพร็อพเพอร์ตี้ SelfUri ที่ส่งคืนออบเจ็กต์ AtomUri ซึ่งใช้เมธอด ToString() เพื่อสร้างออบเจ็กต์ URI ใหม่ได้

จากนั้นเราจึงต้องเรียกใช้เมธอด Query ของบริการเพื่อรับออบเจ็กต์ AtomFeed ใหม่ โดยจะมีรายการเพียงรายการเดียวในรายการ Entries

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

การค้นหารายการ

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

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; 
}

ตัวอย่างนี้เริ่มต้นด้วยการสร้างออบเจ็กต์ FeedQuery ซึ่งประกอบด้วย URL ส่วนใหญ่และพารามิเตอร์การค้นหาที่เกี่ยวข้อง พารามิเตอร์การค้นหา GData มาตรฐานแต่ละรายการมีพร็อพเพอร์ตี้

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

คอลเล็กชัน Entries ของฟีดส่งคืนรายการในฟีด Entries.Count จะแสดงผลจํานวนในฟีด

ในกรณีนี้ หากการค้นหาแสดงผลการค้นหาใดๆ เราจะกําหนดผลลัพธ์แรกที่ตรงกันให้กับออบเจ็กต์ AtomEntry จากนั้นเราจะใช้พร็อพเพอร์ตี้ Title ของคลาส AtomEntry เพื่อดึงชื่อรายการ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

หากต้องการลบรายการที่มีอยู่ ให้ใช้โค้ดต่อไปนี้

updateEntry.Delete();

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

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

การทํางานกับฟีด Google ปฏิทิน

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

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

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

การค้นหาเหตุการณ์
ฟีดย่อยของ FeedQuery ซึ่งให้คุณตั้งค่าพารามิเตอร์ที่กําหนดเอง 2 รายการสําหรับบริการปฏิทิน (เวลาเริ่มต้นและสูงสุด)
บริการปฏิทิน
คลาสย่อยของบริการที่ส่งคืนฟีดเหตุการณ์ได้
ฟีดเหตุการณ์
คลาสย่อยของ AtomFeed จากช่อง EventEntries
รายการกิจกรรม
คลาสย่อยของ AtomEntry ซึ่งมีพร็อพเพอร์ตี้เพิ่มเติมเกี่ยวกับข้อมูลปฏิทิน

สําหรับรายละเอียดเพิ่มเติมเกี่ยวกับชั้นเรียนพิเศษ โปรดดูเอกสาร API และโปรแกรมตัวอย่าง

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

หากต้องการข้อมูลอ้างอิงเกี่ยวกับไลบรารีของไคลเอ็นต์ C# โปรดดูเอกสารอ้างอิง

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