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

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

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

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

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

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

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

เนื้อหา

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

ผู้ชม

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

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

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

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

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

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

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

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

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

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

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

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

หากต้องการคอมไพล์ตัวอย่างในเอกสารนี้ คุณจะต้องใช้คำสั่ง using ต่อไปนี้

using Google.GData.Client;

การขอฟีด

ตามที่อธิบายไว้ในเอกสารประกอบของ Google Calendar 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 นั้น เราจะแสดงวิธีส่งคำค้นหาที่เฉพาะเจาะจงมากขึ้นในภายหลังในเอกสารนี้

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

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

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

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 ใหม่ โดยมีเพียง 1 รายการในคอลเล็กชัน 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 ไปยังปฏิทิน

การอัปเดตรายการ

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

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 การแก้ไข ดังนั้นตัวอย่างนี้จึงคล้ายกับตัวอย่างก่อนหน้ามาก ยกเว้นว่าเราเรียกใช้เมธอด 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 ระบบจะเพิ่มออบเจ็กต์ต่อไปนี้

EventQuery
คลาสย่อยของ FeedQuery ซึ่งช่วยให้คุณตั้งค่าพารามิเตอร์ที่กำหนดเอง 2 รายการสำหรับบริการปฏิทิน (start-min และ start-max) ได้
CalendarService
คลาสย่อยของบริการที่สามารถแสดงผลฟีดกิจกรรม
EventFeed
คลาสย่อยของ AtomFeed ที่แสดง EventEntry
EventEntry
คลาสย่อยของ AtomEntry ซึ่งมีพร็อพเพอร์ตี้เพิ่มเติมที่เกี่ยวข้องกับข้อมูลปฏิทิน

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

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

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

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