การอ้างอิงโปรโตคอลของ Google Data API

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

สําหรับข้อมูลเพิ่มเติมเกี่ยวกับ Google Data API โปรดดูเอกสารคู่มือสําหรับนักพัฒนาซอฟต์แวร์ Google และคู่มือโปรโตคอล

ผู้ชม

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

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

แต่หากคุณต้องการทําความเข้าใจโปรโตคอล โปรดอ่านเอกสารนี้ เช่น คุณควรอ่านเอกสารนี้เพื่อช่วยในการทํางานต่อไปนี้

  • การประเมินสถาปัตยกรรมข้อมูลของ Google
  • เขียนโค้ดโดยใช้โปรโตคอลโดยไม่ใช้ไลบรารีของไคลเอ็นต์ Google ที่ระบุ
  • การเขียนไลบรารีของไคลเอ็นต์ในภาษาใหม่

เอกสารนี้จะถือว่าคุณเข้าใจข้อมูลพื้นฐานของ XML, เนมสเปซ, ฟีดที่เผยแพร่ และคําขอ GET, POST, PUT และ DELETE ใน HTTP รวมถึงแนวคิดของ HTTP ว่า "ทรัพยากร" สําหรับข้อมูลเพิ่มเติม โปรดดูส่วนแหล่งข้อมูลเพิ่มเติมของเอกสารนี้

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

รายละเอียดโปรโตคอล

ส่วนนี้อธิบายรูปแบบเอกสารข้อมูลของ Google และไวยากรณ์การค้นหา

รูปแบบเอกสาร

ข้อมูลของ Google, Atom และ RSS 2.0 ต่างใช้โมเดลข้อมูลพื้นฐานเดียวกัน นั่นคือคอนเทนเนอร์ที่มีทั้งข้อมูลทั่วโลกและข้อมูลทั้งหมด สําหรับแต่ละโปรโตคอล รูปแบบจะกําหนดโดยสคีมาฐาน แต่ขยายได้โดยใช้เนมสเปซต่างประเทศ

Google Data API สามารถใช้รูปแบบการเผยแพร่ Atom (สําหรับทั้งการอ่านและการเขียน) หรือรูปแบบ RSS (สําหรับการอ่านเท่านั้น)

Atom เป็นรูปแบบเริ่มต้นของ Google Data หากต้องการขอการตอบกลับในรูปแบบ RSS ให้ใช้พารามิเตอร์ /alt=rss/ ดูข้อมูลเพิ่มเติมได้ที่คําขอการค้นหา

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

หมายเหตุ: ฟีดข้อมูล Google ส่วนใหญ่ในรูปแบบ Atom ใช้เนมสเปซ Atom เป็นเนมสเปซเริ่มต้น โดยการระบุแอตทริบิวต์ xmlns ในองค์ประกอบฟีด ดูตัวอย่างของส่วนตัวอย่างได้ ดังนั้น ตัวอย่างในเอกสารนี้จึงไม่ได้ระบุ atom: อย่างชัดแจ้งสําหรับองค์ประกอบในฟีดรูปแบบ Atom

ตารางต่อไปนี้แสดง Atom และ RSS ที่แสดงองค์ประกอบของสคีมา ข้อมูลทั้งหมดที่ไม่ได้กล่าวถึงในตารางเหล่านี้จะถือว่าเป็น XML ธรรมดาและปรากฏเหมือนกันในทั้ง 2 ตัวแทน เอลิเมนต์ XML ในคอลัมน์ที่ระบุอยู่ในเนมสเปซที่สอดคล้องกับคอลัมน์นั้น เว้นแต่จะระบุไว้เป็นอย่างอื่น สรุปนี้ใช้สัญลักษณ์ XPath มาตรฐาน โดยเฉพาะอย่างยิ่ง เครื่องหมายทับจะแสดงลําดับชั้นขององค์ประกอบ และเครื่องหมาย @ จะบ่งชี้ถึงแอตทริบิวต์ขององค์ประกอบ

ในตารางแต่ละรายการต่อไปนี้ จะต้องมีรายการที่ไฮไลต์

ตารางต่อไปนี้แสดงองค์ประกอบของฟีดข้อมูล Google

รายการสคีมาฟีด การนําเสนอแบบ Atom การนําเสนอ RSS
ชื่อฟีด /feed/title /rss/channel/title
รหัสฟีด /feed/id /rss/channel/atom:id
ลิงก์ HTML ของฟีด /feed/link[@rel="alternate"]
[@type="text/html"]/@href		 /rss/channel/link
คําอธิบายฟีด /feed/subtitle /rss/channel/description
ภาษาของฟีด /feed/@xml:lang /rss/channel/language
ลิขสิทธิ์ฟีด /feed/rights /rss/channel/copyright
ผู้เขียนฟีด

/feed/author/name
/feed/author/email

(ในบางกรณี โปรดดูข้อกําหนด Atom)

 /rss/channel/managingEditor
วันที่อัปเดตล่าสุดของฟีด /feed/updated
(รูปแบบ RFC 3339)		 /rss/channel/lastBuildDate
(รูปแบบ RFC 822)
หมวดหมู่ฟีด /feed/category/@term /rss/channel/category
รูปแบบฟีด /feed/category/@scheme /rss/channel/category/@domain
โปรแกรมสร้างฟีด /feed/generator
/feed/generator/@uri		 /rss/channel/generator
ไอคอนฟีด /feed/icon /rss/channel/image/url (เว้นแต่จะมีโลโก้ด้วย ซึ่งในกรณีนี้ไอคอนจะไม่ปรากฏในฟีด)
โลโก้ฟีด /feed/logo /rss/channel/image/url

ตารางต่อไปนี้แสดงองค์ประกอบของฟีดผลการค้นหาของ Google โปรดทราบว่าข้อมูลของ Google แสดงองค์ประกอบการตอบกลับของ SearchSearch 1.1 ในฟีดผลการค้นหา

รายการสคีมาฟีดผลการค้นหา การนําเสนอแบบ Atom การนําเสนอ RSS/OpenSearch
จํานวนผลการค้นหา /feed/openSearch:totalResults /rss/channel/openSearch:totalResults
ดัชนีเริ่มต้นของผลการค้นหา /feed/openSearch:startIndex /rss/channel/openSearch:startIndex
จํานวนผลการค้นหาต่อหน้า /feed/openSearch:itemsPerPage /rss/channel/openSearch:itemsPerPage

ตารางต่อไปนี้แสดงองค์ประกอบของรายการ Google Data

รายการสคีมาที่ป้อน การนําเสนอแบบ Atom การนําเสนอ RSS
รหัสรายการ /feed/entry/id /rss/channel/item/guid
รหัสเวอร์ชันของรายการ (ไม่บังคับ) ฝังอยู่ใน EditorURI (ดูที่ส่วนการเพิ่มประสิทธิภาพพร้อมกันของเอกสารนี้) —
ชื่อรายการ /feed/entry/title /rss/channel/item/title
ลิงก์รายการ /feed/entry/link /rss/channel/item/link
/rss/channel/item/enclosure
/rss/channel/item/comments
สรุปรายการ

/feed/entry/summary

(ในบางกรณี โปรดดูข้อกําหนด Atom)

 /rss/channel/item/atom:summary
เนื้อหาการเข้า

/feed/entry/content

(หากไม่มีองค์ประกอบเนื้อหา รายการจะต้องมีองค์ประกอบ <link rel="alternate"> อย่างน้อย 1 รายการ)

 /rss/channel/item/description
ผู้เขียนรายการ

/feed/entry/author/name
/feed/entry/author/email

(ในบางกรณี โปรดดูข้อกําหนด Atom)

 /rss/channel/item/author
หมวดหมู่การเข้า /feed/entry/category/@term /rss/channel/item/category
รูปแบบหมวดหมู่การเข้าร่วม /feed/entry/category/@scheme /rss/channel/item/category/@domain
วันที่เผยแพร่ /feed/entry/published
(RFC 3339)		 /rss/channel/item/pubDate
(RFC 822)
วันที่อัปเดตรายการ /feed/entry/updated
(RFC 3339)		 /rss/channel/item/atom:updated
(RFC 3339)

คำค้นหา

ส่วนนี้จะอธิบายวิธีใช้ระบบการค้นหา

เต็นท์ออกแบบโมเดลการค้นหา

เราตั้งใจให้รูปแบบคําค้นหาเรียบง่ายมาก หลักการพื้นฐานมีดังนี้

  • การค้นหาจะแสดงเป็น URI URI แทนที่จะเป็นส่วนหัว HTTP หรือเป็นส่วนหนึ่งของเพย์โหลด ข้อดีอย่างหนึ่งของวิธีนี้คือคุณลิงก์กับคําค้นหาได้
  • ขอบเขตต่างๆ จะอยู่ในรายการเดียว ดังนั้น จึงไม่มีวิธีเชื่อมโยงความสัมพันธ์ เช่น "ค้นหาอีเมลทั้งหมดจากผู้ที่ส่งอีเมลอย่างน้อย 10 ฉบับในวันนี้"
  • ชุดของพร็อพเพอร์ตี้ที่คําค้นหาสามารถทําได้ล่วงหน้านั้นมีจํากัดอย่างมาก คําค้นหาส่วนใหญ่เป็นคําค้นหาที่ใช้การค้นหาข้อความแบบเต็มเท่านั้น
  • การเรียงลําดับผลลัพธ์ขึ้นอยู่กับการติดตั้งใช้งาน
  • โปรโตคอลนั้นสามารถขยายได้ตามธรรมชาติ หากต้องการแสดงการคาดการณ์หรือการจัดเรียงบริการเพิ่มเติม ก็สามารถทําได้โดยง่ายด้วยการใช้พารามิเตอร์ใหม่

คําขอการค้นหา

ไคลเอ็นต์ค้นหาบริการข้อมูลของ Google โดยออกคําขอ HTTP GET URI การค้นหาประกอบด้วย URI ของทรัพยากร (เรียกว่า FeedURI ใน Atom) ตามด้วยพารามิเตอร์การค้นหา พารามิเตอร์การค้นหาส่วนใหญ่จะแสดงเป็นพารามิเตอร์ของ URL ?name=value[&...] แบบดั้งเดิม พารามิเตอร์หมวดหมู่มีการจัดการแตกต่างกัน ดูด้านล่าง

เช่น หาก FeedURI เป็น http://www.example.com/feeds/jo คุณอาจส่งคําค้นหาที่มี URI ต่อไปนี้

http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z

บริการข้อมูลของ Google รองรับ HTTP แบบมีเงื่อนไข GET โดยจะตั้งค่าส่วนหัวการตอบกลับแบบแก้ไขล่าสุดตามค่าขององค์ประกอบ <atom:updated> ในฟีดหรือรายการที่แสดงผล ไคลเอ็นต์จะส่งค่านี้เป็นค่าของส่วนหัว If-Modified-Since เพื่อหลีกเลี่ยงการดึงเนื้อหาอีกครั้งหากไม่ได้เปลี่ยนแปลง หากเนื้อหาไม่มีการเปลี่ยนแปลงตั้งแต่ If-Modified-Since เวลา บริการ Google Data จะแสดงการตอบกลับ HTTP 304 (ไม่มีการแก้ไข)

บริการข้อมูลของ Google ต้องรองรับการค้นหาหมวดหมู่และคําค้นหา alt โดยจะรองรับพารามิเตอร์อื่นๆ หรือไม่ก็ได้ การส่งพารามิเตอร์มาตรฐานที่บริการหนึ่งๆ ไม่เข้าใจจะทําให้การตอบกลับได้รับ 403 Forbidden การส่งผ่านพารามิเตอร์ที่ไม่ใช่แบบมาตรฐานที่ไม่รองรับจะส่งผลให้เกิดการตอบกลับ 400 Bad Request สําหรับข้อมูลเกี่ยวกับรหัสสถานะอื่นๆ โปรดดูส่วนรหัสสถานะ HTTP ของเอกสารนี้

พารามิเตอร์การค้นหามาตรฐานจะสรุปไว้ในตารางต่อไปนี้ ค่าพารามิเตอร์ทั้งหมดต้องมีการเข้ารหัส URL

พารามิเตอร์ ความหมาย หมายเหตุ
q สตริงคําค้นหาแบบเต็มข้อความ
  • เมื่อสร้างคําค้นหา ให้ระบุข้อความค้นหาโดยคั่นด้วยเว้นวรรค ในรูปแบบ q=term1 term2 term3 (เช่นเดียวกับค่าพารามิเตอร์การค้นหาทั้งหมด พื้นที่ทํางานต้องเข้ารหัส URL) บริการข้อมูลของ Google จะแสดงรายการทั้งหมดที่ตรงกับข้อความค้นหาทั้งหมด (เช่น การใช้ AND ระหว่างคํา) บริการข้อมูลของ Google จะค้นหาคําที่สมบูรณ์ (และคําที่เกี่ยวข้องซึ่งมีรากเดียวกัน) เช่นเดียวกับสตริงย่อย เช่นเดียวกับการค้นเว็บของ Google
  • หากต้องการค้นหาวลีที่ตรงกัน ให้ใส่วลีในเครื่องหมายคําพูด q="exact phrase".
  • หากต้องการยกเว้นรายการที่ตรงกับคําที่ระบุ ให้ใช้แบบฟอร์ม q=-term
  • การค้นหาจะไม่คํานึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
  • เช่น หากต้องการค้นหารายการทั้งหมดที่มีวลี "Elizabeth Bennet" และคําว่า "Darcy" แต่ไม่มีคําว่า "Austen" ให้ใช้คําค้นหาต่อไปนี้: ?q="Elizabeth Bennet" Darcy -Austen
/-/category ตัวกรองหมวดหมู่
  • ระบุแต่ละหมวดหมู่ให้เสมือนเป็นส่วนหนึ่งของ URI ของทรัพยากรในรูปแบบ /categoryname/ ซึ่งเป็นข้อยกเว้นสําหรับแบบฟอร์ม name=value ปกติ
  • แสดงหมวดหมู่ทั้งหมดก่อนพารามิเตอร์การค้นหาอื่นๆ
  • ขึ้นต้นหมวดหมู่แรกด้วย /-/ เพื่อให้เข้าใจชัดเจนว่าเป็นหมวดหมู่ ตัวอย่างเช่น หากฟีดของโจมีหมวดหมู่สําหรับรายการเกี่ยวกับฟรีซ คุณก็สามารถขอรายการลักษณะนี้ได้: http://www.example.com/feeds/jo/-/Fritz ซึ่งจะทําให้ใช้งานเพื่อแยก URI คําค้นหาที่จัดหมวดหมู่หมวดหมู่จาก URI ทรัพยากรได้
  • คุณสามารถค้นหาในหลายหมวดหมู่ด้วยการแสดงพารามิเตอร์หลายหมวดหมู่โดยคั่นด้วยเครื่องหมายทับ บริการข้อมูลของ Google จะแสดงรายการทั้งหมดที่ตรงกับทุกหมวดหมู่ (เช่น การใช้ AND ระหว่างคํา) เช่น http://www.example.com/feeds/jo/-/Fritz/Laurie จะแสดงรายการที่ตรงกับทั้ง 2 หมวดหมู่
  • หากต้องการดําเนินการ OR ระหว่างคํา ให้ใช้อักขระไปป์ (|) ที่เข้ารหัส URL เป็น %7C เช่น http://www.example.com/feeds/jo/-/Fritz%7CLaurie แสดงผลรายการที่ตรงกับทั้ง 2 หมวดหมู่
  • รายการตรงกับหมวดหมู่ที่ระบุหากรายการอยู่ในหมวดหมู่ที่มีคําหรือป้ายกํากับที่ตรงกันตามที่กําหนดในข้อกําหนด Atom (คร่าวๆ คําว่า "คํา" คือสตริงภายในที่ซอฟต์แวร์ใช้เพื่อระบุหมวดหมู่ ส่วน "ป้ายกํากับ" คือสตริงที่ผู้ใช้อ่านได้ในอินเทอร์เฟซผู้ใช้)
  • หากต้องการยกเว้นรายการที่ตรงกับหมวดหมู่ที่ต้องการ ให้ใช้แบบฟอร์ม /-categoryname/
  • หากต้องการค้นหาหมวดหมู่ที่มีรูปแบบ เช่น <category scheme="urn:google.com" term="public"/> คุณต้องวางรูปแบบไว้ในวงเล็บปีกกาก่อนชื่อหมวดหมู่ เช่น /{urn:google.com}public หากรูปแบบมีอักขระเครื่องหมายทับ (/) ควรเข้ารหัส URL เป็น %2F หากต้องการจับคู่หมวดหมู่ที่ไม่มีสคีม ให้ใช้วงเล็บปีกกาคู่ว่าง หากไม่ระบุวงเล็บปีกกา หมวดหมู่ในรูปแบบใดก็ตามจะตรงกัน
  • คุณรวมฟีเจอร์ข้างต้นเข้าด้วยกันได้ เช่น /A%7C-{urn:google.com}B/-C หมายถึง (A OR (NOT B)) AND (NOT C)
category ตัวกรองหมวดหมู่
  • อีกทางเลือกหนึ่งในการใช้ตัวกรองหมวดหมู่ ทั้ง 2 วิธีมีความแตกต่างกัน
  • หากต้องการดําเนินการ OR ระหว่างคํา ให้ใช้อักขระไปป์ (|) โดยเข้ารหัส URL เป็น %7C เช่น http://www.example.com/feeds?category=Fritz%7CLaurie แสดงผลรายการที่ตรงกับทั้ง 2 หมวดหมู่
  • หากต้องการ AND ระหว่างคํา ให้ใช้อักขระคอมมา (,) เช่น http://www.example.com/feeds?category=Fritz,Laurie เพื่อแสดงรายการที่ตรงกับทั้ง 2 หมวดหมู่
author ผู้เขียนรายการ
  • บริการจะแสดงรายการที่ชื่อผู้เขียนและ/หรืออีเมลตรงกับสตริงคําค้นหา
alt ประเภททางเลือก
  • หากไม่ระบุพารามิเตอร์ alt บริการจะแสดงฟีด Atom ซึ่งเทียบเท่ากับ alt=atom
  • alt=rss แสดงผลฟีด RSS 2.0
  • alt=json แสดงผลการนําเสนอ JSON ของฟีด ข้อมูลเพิ่มเติม
  • alt=json-in-script ขอการตอบกลับที่มี JSON ในแท็กสคริปต์ ข้อมูลเพิ่มเติม
updated-min updated-max ขอบเขตในวันที่อัปเดตรายการ
  • ใช้รูปแบบการประทับเวลา RFC 3339 เช่น 2005-08-09T10:57:00-08:00
  • ขอบเขตล่างจะแบ่งแยก ขณะที่ขอบเขตบนจะแยกกัน
published-min published-max ขอบเขตในวันที่เผยแพร่รายการ
  • ใช้รูปแบบการประทับเวลา RFC 3339 เช่น 2005-08-09T10:57:00-08:00
  • ขอบเขตล่างจะแบ่งแยก ขณะที่ขอบเขตบนจะแยกกัน
start-index ดัชนีแบบ 1 รายการของผลการค้นหาแรกที่จะเรียก
  • โปรดทราบว่านี่ไม่ใช่กลไกเคอร์เซอร์ทั่วไป หากคุณส่งคําค้นหาด้วย ?start-index=1&max-results=10 ครั้งแรกแล้วส่งการค้นหาอื่นด้วย ?start-index=11&max-results=10 บริการไม่สามารถรับประกันได้ว่าผลลัพธ์จะเท่ากับ ?start-index=1&max-results=20 เนื่องจากการแทรกและการลบอาจเกิดขึ้นระหว่างคําค้นหา 2 คํา
max-results จํานวนครั้งสูงสุดที่สามารถดึงผลลัพธ์ได้ สําหรับบริการใดก็ตามที่มีค่าเริ่มต้น max-results (เพื่อจํากัดขนาดของฟีดเริ่มต้น) คุณสามารถระบุจํานวนมากได้ หากต้องการรับฟีดทั้งหมด
รหัสรายการ รหัสของรายการที่ต้องการเรียก
  • หากระบุรหัสรายการข้อมูล คุณจะระบุพารามิเตอร์อื่นๆ ไม่ได้
  • รูปแบบรหัสรายการจะกําหนดโดยบริการข้อมูลของ Google
  • รหัสรายการระบุรหัสเป็นส่วนหนึ่งของ URI ไม่ใช่คู่ชื่อ=ค่า ซึ่งแตกต่างจากพารามิเตอร์การค้นหาอื่นๆ ส่วนใหญ่
  • ตัวอย่าง: http://www.example.com/feeds/jo/entry1

เกี่ยวกับการค้นหาหมวดหมู่

เราจึงตัดสินใจระบุรูปแบบที่ผิดปกติเล็กน้อยสําหรับการค้นหาหมวดหมู่ แทนที่จะใช้คําค้นหาต่อไปนี้

http://example.com/jo?category=Fritz&category=2006

เราใช้ข้อมูลต่อไปนี้

http://example.com/jo/-/Fritz/2006

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

ข้อเสียของวิธีนี้คือกําหนดให้คุณต้องใช้ /-/ ในการค้นหาหมวดหมู่ เพื่อให้บริการข้อมูลของ Google สามารถแยกความแตกต่างระหว่างหมวดหมู่ต่างๆ กับ URI แหล่งข้อมูลอื่นๆ เช่น http://example.com/jo/MyPost/comments ได้

การตอบกลับการค้นหา

คําค้นหาจะแสดงฟีด Atom, รายการ Atom หรือฟีด RSS โดยขึ้นอยู่กับพารามิเตอร์คําขอ

ผลการค้นหามีองค์ประกอบ OpenSearch ต่อไปนี้ใต้องค์ประกอบ <feed> หรือองค์ประกอบ <channel> โดยตรง (ขึ้นอยู่กับว่าผลลัพธ์เป็น Atom หรือ RSS)

openSearch:totalResults
จํานวนผลการค้นหาทั้งหมดสําหรับคําค้นหานั้น (ไม่จําเป็นต้องแสดงในฟีดผลลัพธ์เสมอไป)
openSearch:startIndex
ดัชนีแบบ 1 รายการของผลการค้นหาแรก
openSearch:itemsPerPage
จํานวนสูงสุดของรายการที่ปรากฏในหน้าเดียว วิธีนี้ช่วยให้ลูกค้าสร้างการเชื่อมโยงโดยตรงไปยังหน้าเว็บชุดใดก็ได้ อย่างไรก็ตาม อาจมีข้อผิดพลาดจากการใช้หมายเลขนี้ โปรดดูหมายเหตุเกี่ยวกับ start-index ในตารางในส่วนคําขอการค้นหา

ฟีดและข้อมูล Atom อาจมีองค์ประกอบ Atom และ Google Data ดังต่อไปนี้ (รวมถึงองค์ประกอบอื่นๆ ที่ระบุไว้ในข้อกําหนด Atom)

<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>
ระบุ URI ที่จะเรียกข้อมูลฟีด Atom ที่สมบูรณ์ได้
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>
ระบุ PostURI ของฟีด Atom (สามารถโพสต์รายการใหม่ได้)
<link rel="self" type="..." href="..."/>
มี URI ของทรัพยากรนี้ ค่าของแอตทริบิวต์ type จะขึ้นอยู่กับรูปแบบที่ขอ หากไม่มีการเปลี่ยนแปลงข้อมูลในระหว่างนี้ การส่ง GET อื่นไปยัง URI นี้จะแสดงผลการตอบสนองเดียวกัน
<link rel="previous" type="application/atom+xml" href="..."/>
ระบุ URI ของชุดผลลัพธ์ก่อนหน้าของชุดการค้นหานี้หากเกิดการแบ่งเป็นส่วนๆ
<link rel="next" type="application/atom+xml" href="..."/>
ระบุ URI of the chunk ของชุดผลการค้นหานี้ หากแบ่งเป็นส่วนๆ
<link rel="edit" type="application/atom+xml" href="..."/>
ระบุ EditURI ของรายการ Atom (ตําแหน่งที่ส่งรายการที่อัปเดตแล้ว)

ต่อไปนี้คือตัวอย่างคําตอบในการตอบกลับคําค้นหา

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:atom="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
  <id>http://www.example.com/feed/1234.1/posts/full</id> 
  <updated>2005-09-16T00:42:06Z</updated> 
  <title type="text">Books and Romance with Jo and Liz</title> 
  <link rel="alternate" type="text/html" href="http://www.example.net/"/> 
  <link rel="http://schemas.google.com/g/2005#feed"
    type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <link rel="http://schemas.google.com/g/2005#post"
    type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <link rel="self" type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <generator version="1.0"
    uri="http://www.example.com">Example Generator Engine</generator> 
  <openSearch:totalResults>2</openSearch:totalResults> 
  <openSearch:startIndex>0</openSearch:startIndex> 
  <entry>
    <id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id> 
    <published>2005-01-09T08:00:00Z</published> 
    <updated>2005-01-09T08:00:00Z</updated> 
    <category scheme="http://www.example.com/type" term="blog.post"/> 
    <title type="text">This is the title of entry 1009</title> 
    <content type="xhtml">
      <div
        xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div> 
    </content>
    <link rel="alternate" type="text/html"
      href="http://www.example.com/posturl"/> 
    <link rel="edit" type="application/atom+xml"
      href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/> 
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
  </entry>
  <entry>
    <id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id> 
    <published>2005-01-07T08:00:00Z</published> 
    <updated>2005-01-07T08:02:00Z</updated> 
    <category scheme="http://www.example.com/type" term="blog.post"/> 
    <title type="text">This is the title of entry 1007</title> 
    <content type="xhtml">
      <div
        xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div> 
    </content>
    <link rel="alternate" type="text/html"
      href="http://www.example.com/posturl"/> 
    <link rel="edit" type="application/atom+xml"
      href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/> 
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
  </entry>
</feed>

หากฟีดที่ขออยู่ในรูปแบบ Atom หากไม่ได้ระบุพารามิเตอร์การค้นหาและหากผลการค้นหาไม่มีรายการทั้งหมด ระบบจะแทรกองค์ประกอบต่อไปนี้ลงในฟีดระดับบนสุด <link rel="next" type="application/atom+xml" href="..."/> ซึ่งชี้ไปยังฟีดที่มีชุดรายการถัดไป ชุดต่อๆ ไปมีองค์ประกอบ <link rel="previous" type="application/atom+xml" href="..."/> ที่เกี่ยวข้อง หากไปตามลิงก์ถัดไปทั้งหมด ลูกค้าจะเรียกข้อมูลรายการทั้งหมดจากฟีดได้

รหัสสถานะ HTTP

ตารางต่อไปนี้อธิบายความหมายของรหัสสถานะ HTTP ต่างๆ ในบริบทของบริการข้อมูล Google

รหัส คำอธิบาย
200 OK ไม่มีข้อผิดพลาด
201 สร้างแล้ว การสร้างทรัพยากรสําเร็จแล้ว
304 ไม่ได้แก้ไข ทรัพยากรไม่เปลี่ยนแปลงตั้งแต่เวลาที่ระบุในส่วนหัว If-Modified-Since ของคําขอ
คําขอ Bad 400 รายการ URI หรือส่วนหัวคําขอไม่ถูกต้อง หรือพารามิเตอร์ที่ไม่ใช่มาตรฐานที่ไม่รองรับ
401 ไม่ได้รับอนุญาต ต้องได้รับอนุญาต
403 การเสนอราคาล่วงหน้า ระบบไม่รองรับพารามิเตอร์มาตรฐานหรือการตรวจสอบสิทธิ์หรือการให้สิทธิ์ไม่สําเร็จ
404 ไม่พบ ไม่พบทรัพยากร (เช่น ฟีดหรือรายการ)
409 ความขัดแย้ง หมายเลขเวอร์ชันที่ระบุไม่ตรงกับหมายเลขเวอร์ชันล่าสุดของทรัพยากร
ข้อผิดพลาดภายในเซิร์ฟเวอร์ 500 ข้อผิดพลาดภายใน นี่คือโค้ดเริ่มต้นที่ใช้สําหรับข้อผิดพลาดที่ไม่รู้จักทั้งหมด

การเกิดขึ้นพร้อมกัน (การเพิ่มประสิทธิภาพ)

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

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

ฟีดข้อมูล Google บางรายการไม่รองรับการเพิ่มประสิทธิภาพพร้อมกัน ในฟีดที่รองรับ หากเซิร์ฟเวอร์ตรวจพบความขัดแย้งของเวอร์ชันใน PUT หรือ DELETE เซิร์ฟเวอร์จะตอบสนองด้วย 409 Conflict ส่วนเนื้อหาของการตอบกลับจะมีสถานะปัจจุบันของรายการ (เอกสารข้อมูล Atom) ไคลเอ็นต์แนะนําให้แก้ไขข้อขัดแย้งและส่งคําขออีกครั้งโดยใช้ EditorURI จากการตอบกลับข้อผิดพลาด 409

บันทึกแรงจูงใจและการออกแบบ

แนวทางการเกิดขึ้นพร้อมกันอย่างเหมาะสมนี้ช่วยให้เรานําความหมายที่เราต้องการได้โดยไม่ต้องใช้มาร์กอัปใหม่สําหรับรหัสเวอร์ชัน ซึ่งทําให้การตอบกลับของ Google ข้อมูลเข้ากันได้กับปลายทางที่ไม่ใช่ Google Data Atom

เราอาจเลือกดูการประทับเวลาการอัปเดตในแต่ละรายการ (/atom:entry/atom:updated) แทนที่จะระบุรหัสเวอร์ชัน แต่ปัญหา 2 ประการในการใช้การประทับเวลาการอัปเดตมีดังนี้

  • โดยจะใช้ได้กับการอัปเดตเท่านั้น และจะลบไม่ได้
  • แต่จะบังคับให้แอปพลิเคชันใช้ค่าวันที่/เวลาเป็นรหัสเวอร์ชัน ซึ่งจะทําให้ปรับปรุงข้อมูล Google เพิ่มเติมจากพื้นที่เก็บข้อมูลที่มีอยู่หลายแหล่งได้ยากขึ้น

การตรวจสอบสิทธิ์

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

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

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

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

หากตรวจสอบสิทธิ์ไม่สําเร็จ เซิร์ฟเวอร์จะแสดงรหัสสถานะต้องห้าม 403 พร้อมด้วยส่วนหัว WWW-Authentication ที่มีโจทย์ที่เกี่ยวข้องกับการตรวจสอบสิทธิ์

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

โปรดดูรายละเอียดเกี่ยวกับระบบการตรวจสอบสิทธิ์เหล่านี้ที่หัวข้อภาพรวมการตรวจสอบสิทธิ์ข้อมูลของ Google หรือเอกสารประกอบการตรวจสอบสิทธิ์บัญชี Google

สถานะเซสชัน

การใช้ตรรกะทางธุรกิจหลายอย่างต้องใช้ความสามารถในการคงเซสชันไว้ ซึ่งช่วยติดตามสถานะเซสชันของผู้ใช้

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

ไลบรารีของไคลเอ็นต์ Google จะจัดการสถานะเซสชันให้คุณ ดังนั้นหากคุณใช้ไลบรารีของเรา คุณไม่จําเป็นต้องดําเนินการใดๆ เพื่อรับการสนับสนุนสถานะเซสชัน

แหล่งข้อมูลเพิ่มเติม

เอกสารของบุคคลที่สามต่อไปนี้อาจมีประโยชน์

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