หน้านี้ได้รับการแปลโดย Cloud Translation API

การอ้างอิงโปรโตคอล

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

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

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

ผู้ชม

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

รายการสคีมาฟีด	การนําเสนอแบบ Atom
ชื่อฟีด	`/feed/title`
รหัสฟีด	`/feed/id`
ลิงก์ HTML ของฟีด	`/feed/link[@rel="alternate"]` `[@type="text/html"]/@href`
คําอธิบายฟีด	`/feed/subtitle`
ภาษาของฟีด	`/feed/@xml:lang`
ลิขสิทธิ์ฟีด	`/feed/rights`
ผู้เขียนฟีด	`/feed/author/name` `/feed/author/email` (ในบางกรณี โปรดดูข้อกําหนด Atom)
วันที่อัปเดตล่าสุดของฟีด	`/feed/updated` (รูปแบบ RFC 3339)
หมวดหมู่ฟีด	`/feed/category/@term`
รูปแบบฟีด	`/feed/category/@scheme`
โปรแกรมสร้างฟีด	`/feed/generator` `/feed/generator/@uri`
ไอคอนฟีด	`/feed/icon`
โลโก้ฟีด	`/feed/logo`

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

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

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

รายการสคีมาที่ป้อน	การนําเสนอแบบ Atom
รหัสรายการ	`/feed/entry/id`
ชื่อรายการ	`/feed/entry/title`
ลิงก์รายการ	`/feed/entry/link`
สรุปรายการ	`/feed/entry/summary` (ในบางกรณี โปรดดูข้อกําหนด Atom)
เนื้อหาการเข้า	`/feed/entry/content` (หากไม่มีองค์ประกอบเนื้อหา รายการจะต้องมีองค์ประกอบ `<link rel="alternate">` อย่างน้อย 1 รายการ)
ผู้เขียนรายการ	`/feed/entry/author/name` `/feed/entry/author/email` (ในบางกรณี โปรดดูข้อกําหนด Atom)
หมวดหมู่การเข้า	`/feed/entry/category/@term`
รูปแบบหมวดหมู่การเข้าร่วม	`/feed/entry/category/@scheme`
วันที่เผยแพร่	`/feed/entry/published` (RFC 3339)
วันที่อัปเดตรายการ	`/feed/entry/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 รองรับ GET แบบมีเงื่อนไข HTTP API ที่ใช้โปรโตคอลจะกําหนดส่วนหัวการตอบกลับแก้ไขล่าสุดโดยอิงตามค่าของเอลิเมนต์ <atom:updated> ในฟีดหรือรายการที่แสดง ไคลเอ็นต์จะส่งค่านี้เป็นค่าของส่วนหัว If-Modified-Since เพื่อหลีกเลี่ยงการดึงเนื้อหาอีกครั้งหากไม่ได้เปลี่ยนแปลง หากเนื้อหาไม่มีการเปลี่ยนแปลงตั้งแต่ If-Modified-Since เวลา บริการจะแสดงการตอบกลับ HTTP 304 (ไม่มีการแก้ไข)

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

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

พารามิเตอร์	ความหมาย	หมายเหตุ
`alt`	ประเภททางเลือก	หากไม่ระบุพารามิเตอร์ `alt` บริการจะแสดงฟีด Atom ซึ่งเทียบเท่ากับ `alt=atom` `alt=rss` แสดงผลฟีด RSS 2.0 (สําหรับการอ่านเท่านั้น) เมื่อคุณขอข้อมูลจากบริการในรูปแบบ RSS บริการจะมีฟีด (หรือการแสดงทรัพยากรอื่นๆ) ในรูปแบบ RSS หากไม่มีพร็อพเพอร์ตี้ RSS ที่เทียบเท่าสําหรับพร็อพเพอร์ตี้ Data API บริการจะใช้พร็อพเพอร์ตี้ Atom โดยติดป้ายกํากับด้วยเนมสเปซที่เหมาะสมเพื่อระบุว่าเป็นส่วนขยายสําหรับ RSS `alt=json` แสดงผลการนําเสนอ JSON ของฟีด ข้อมูลเพิ่มเติม `alt=json-in-script` ขอการตอบกลับที่มี JSON ในแท็กสคริปต์ ข้อมูลเพิ่มเติม `alt=atom-in-script` ขอการตอบกลับ Atom ที่รวมสตริง XML ในแท็กสคริปต์ `alt=rss-in-script` ขอการตอบกลับ RSS ที่รวมสตริง XML ในแท็กสคริปต์ `alt=atom-service` ขอเอกสารบริการ Atom ที่อธิบายฟีด
`author`	ผู้เขียนรายการ	บริการจะแสดงรายการที่ชื่อผู้เขียนและ/หรืออีเมลตรงกับสตริงคําค้นหา
`category`	ตัวกรองการค้นหาหมวดหมู่	อีกทางเลือกหนึ่งในการใช้ตัวกรองหมวดหมู่ ทั้ง 2 วิธีมีความแตกต่างกัน หากต้องการดําเนินการ `OR` ระหว่างคํา ให้ใช้อักขระไปป์ (\|) โดยเข้ารหัส URL เป็น `%7C` เช่น `http://www.example.com/feeds?category=Fritz%7CLaurie` แสดงผลรายการที่ตรงกับทั้ง 2 หมวดหมู่ หากต้องการ `AND` ระหว่างคํา ให้ใช้อักขระคอมมา (,) เช่น `http://www.example.com/feeds?category=Fritz,Laurie` เพื่อแสดงรายการที่ตรงกับทั้ง 2 หมวดหมู่
`/-/category`	ตัวกรองการค้นหาหมวดหมู่	ระบุแต่ละหมวดหมู่ให้เสมือนเป็นส่วนหนึ่งของ URI ของทรัพยากรในรูปแบบ `/categoryname/` ซึ่งเป็นข้อยกเว้นสําหรับแบบฟอร์ม `name=value` ปกติ แสดงหมวดหมู่ทั้งหมดก่อนพารามิเตอร์การค้นหาอื่นๆ ขึ้นต้นหมวดหมู่แรกด้วย `/-/` เพื่อให้เข้าใจชัดเจนว่าเป็นหมวดหมู่ ตัวอย่างเช่น หากฟีดของโจมีหมวดหมู่สําหรับรายการเกี่ยวกับฟรีซ คุณก็สามารถขอรายการลักษณะนี้ได้: `http://www.example.com/feeds/jo/-/Fritz` ซึ่งจะทําให้ใช้งานเพื่อแยก URI คําค้นหาที่จัดหมวดหมู่หมวดหมู่จาก URI ทรัพยากรได้ คุณสามารถค้นหาในหลายหมวดหมู่ด้วยการแสดงพารามิเตอร์หลายหมวดหมู่โดยคั่นด้วยเครื่องหมายทับ บริการจะแสดงรายการทั้งหมดที่ตรงกับหมวดหมู่ทั้งหมด (เช่น การใช้ `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)`
รหัสรายการ	รหัสของรายการที่ต้องการเรียก	หากระบุรหัสรายการข้อมูล คุณจะระบุพารามิเตอร์อื่นๆ ไม่ได้ รูปแบบของรหัสรายการจะกําหนดโดยบริการ รหัสรายการระบุรหัสเป็นส่วนหนึ่งของ URI ไม่ใช่คู่ชื่อ=ค่า ซึ่งแตกต่างจากพารามิเตอร์การค้นหาอื่นๆ ส่วนใหญ่ ตัวอย่าง: `http://www.example.com/feeds/jo/entry1`
`fields`	ตัวกรองการตอบกลับ	โดยจะแสดงเฉพาะช่องที่ขอแทนการแสดงทรัพยากรแบบเต็ม ตัวอย่างเช่น http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit'])) เมื่อได้รับคําขอนี้ เซิร์ฟเวอร์จะส่งการตอบกลับที่มีเฉพาะองค์ประกอบลิงก์และรายการของฟีดเท่านั้น นอกจากนี้ องค์ประกอบของรายการที่แสดงผลจะเป็นรายการบางส่วนที่มีเฉพาะ ETag, รหัส, อัปเดต และแก้ไขความสัมพันธ์ของลิงก์เท่านั้น ค่าในช่องต้องได้รับการเข้ารหัส URL เช่นเดียวกับค่าพารามิเตอร์การค้นหาทั้งหมด ดูข้อมูลเพิ่มเติมได้ในส่วนการตอบกลับบางส่วน พารามิเตอร์นี้เป็นฟีเจอร์ทดลองในขณะนี้
`max-results`	จํานวนครั้งสูงสุดที่สามารถดึงผลลัพธ์ได้	สําหรับบริการใดก็ตามที่มีค่าเริ่มต้น `max-results` (เพื่อจํากัดขนาดของฟีดเริ่มต้น) คุณสามารถระบุจํานวนมากได้ หากต้องการรับฟีดทั้งหมด
`prettyprint`	แสดงการตอบกลับ XML ด้วยการระบุตัวตนและการขึ้นบรรทัดใหม่	หาก `prettyprint=true` เซิร์ฟเวอร์จะอ่าน XML ที่กลับมาอ่านได้ (พิมพ์ค่อนข้างสวยงาม) ค่าเริ่มต้น: `prettyprint=false`
`published-min` `published-max`	ขอบเขตในวันที่เผยแพร่รายการ	ใช้รูปแบบการประทับเวลา RFC 3339 เช่น `2005-08-09T10:57:00-08:00` ขอบเขตล่างจะแบ่งแยก ขณะที่ขอบเขตบนจะแยกกัน
`q`	สตริงคําค้นหาแบบเต็มข้อความ	เมื่อสร้างคําค้นหา ให้ระบุข้อความค้นหาโดยคั่นด้วยเว้นวรรค ในรูปแบบ `q=term1 term2 term3` (เช่นเดียวกับค่าพารามิเตอร์การค้นหาทั้งหมด พื้นที่ทํางานต้องเข้ารหัส URL) บริการจะแสดงรายการทั้งหมดที่ตรงกับข้อความค้นหาทั้งหมด (เช่น ใช้ `AND` ระหว่างคํา) บริการนี้จะค้นหาคําที่สมบูรณ์ (และคําที่เกี่ยวข้องที่มีรากฐานเดียวกัน) เช่นเดียวกับสตริงย่อย เช่นเดียวกับการค้นเว็บของ Google หากต้องการค้นหาวลีที่ตรงกัน ให้ใส่วลีในเครื่องหมายคําพูด `q="exact phrase".` หากต้องการยกเว้นรายการที่ตรงกับคําที่ระบุ ให้ใช้แบบฟอร์ม `q=-term` การค้นหาจะไม่คํานึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ เช่น หากต้องการค้นหารายการทั้งหมดที่มีวลี "Elizabeth Bennet" และคําว่า "Darcy" แต่ไม่มีคําว่า "Austen" ให้ใช้คําค้นหาต่อไปนี้: `?q="Elizabeth Bennet" Darcy -Austen`
`start-index`	ดัชนีแบบ 1 รายการของผลการค้นหาแรกที่จะเรียก	โปรดทราบว่านี่ไม่ใช่กลไกเคอร์เซอร์ทั่วไป หากคุณส่งคําค้นหาด้วย `?start-index=1&max-results=10` ครั้งแรกแล้วส่งการค้นหาอื่นด้วย `?start-index=11&max-results=10` บริการไม่สามารถรับประกันได้ว่าผลลัพธ์จะเท่ากับ `?start-index=1&max-results=20` เนื่องจากการแทรกและการลบอาจเกิดขึ้นระหว่างคําค้นหา 2 คํา
`strict`	การตรวจสอบพารามิเตอร์การค้นหาอย่างเข้มงวด	ตั้งค่า `strict=true` เพื่อยืนยันว่าพารามิเตอร์การค้นหาแต่ละรายการจดจําได้โดยบริการ ระบบจะแสดงผลข้อผิดพลาดหากไม่รู้จักพารามิเตอร์ ค่าเริ่มต้น: `strict=false`
`updated-min` `updated-max`	ขอบเขตในวันที่อัปเดตรายการ	ใช้รูปแบบการประทับเวลา RFC 3339 เช่น `2005-08-09T10:57:00-08:00` ขอบเขตล่างจะแบ่งแยก ขณะที่ขอบเขตบนจะแยกกัน ในบางกรณี (เช่น เมื่อใช้ Calendar Data API เวอร์ชัน 2.1 ขึ้นไป) การระบุ `updated-min` ที่ย้อนหลังนานเกินไปจะทําให้ได้รับสถานะ HTTP 410 (ไม่มีแล้ว)

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

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

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

เราพยายามทําให้สามารถใช้

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

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

ข้อเสียของวิธีนี้คือเรากําหนดให้คุณต้องใช้ /-/ ในคําค้นหาของประเภทประเภทนี้ เพื่อที่จะสามารถแยกความแตกต่างระหว่างการค้นหาหมวดหมู่กับ 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 และ Data API ดังต่อไปนี้ (รวมถึงองค์ประกอบอื่นๆ ที่ระบุไว้ในข้อกําหนด 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="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <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>[email protected]</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 gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
    <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>[email protected]</email>
    </author>
  </entry>
  <entry gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
    <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>[email protected]</email>
    </author>
  </entry>
</feed>

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

รหัสสถานะ HTTP

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

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

การกําหนดเวอร์ชันทรัพยากร (ETag)

บางครั้งคุณอาจต้องการอ้างอิงรายการที่เฉพาะเจาะจงเวอร์ชันหนึ่งๆ

โดยมีความจําเป็น 2 กรณี ดังนี้

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

Google Data API จัดการทั้งสองกรณีโดยใช้ ETag ซึ่งเป็นส่วนมาตรฐานของ HTTP

ETag คือตัวระบุที่ระบุเวอร์ชันของรายการหนึ่งๆ เซิร์ฟเวอร์จะแนบ ETag กับองค์ประกอบของฟีดและฟีดที่จะส่งไปยังไคลเอ็นต์ เมื่อรายการหรือฟีดมีการเปลี่ยนแปลง ETag ก็จะเปลี่ยนแปลงเช่นกัน

Google Data API มี ETag อยู่ 2 อย่างด้วยกัน ได้แก่ ในส่วนหัว HTTP ของ ETag และในแอตทริบิวต์ gd:etag ขององค์ประกอบ <feed> และ <entry>

ใน Google Data API ปกติแล้ว ETag จะเป็นสตริงตัวอักษรและตัวเลข บางครั้งก็รวมถึงขีดกลางและจุด และโดยปกติแล้วสตริงจะอยู่ภายในเครื่องหมายคําพูด (เครื่องหมายคําพูดเป็นส่วนหนึ่งของ ETag) เช่น นี่คือ ETag จากรายการ Data API: "S0wCTlpIIip7ImA0X0QI"

ETag มีอยู่ 2 ประเภท ได้แก่ รัดกุมและอ่อน ETag ที่มีประสิทธิภาพจะระบุเวอร์ชันที่เจาะจงของแต่ละรายการ และสามารถนํามาใช้เพื่อเขียนทับการเปลี่ยนแปลงของลูกค้ารายอื่นได้ ETag ที่ไม่รัดกุมในบริบทของ Google Data API จะใช้เพื่อการดึงข้อมูลตามเงื่อนไขเท่านั้น ETag อ่อน เริ่มต้นด้วย W/ เสมอ เช่น W/"D08FQn8-eil7ImA9WxZbFEw."

Google Data API บางรายการไม่รองรับ ETag ที่มีประสิทธิภาพ สําหรับแท็กที่ใช้ ETag ที่มีประสิทธิภาพจะใช้สําหรับรายการเท่านั้น ส่วน ETag ในฟีดมักจะไม่มีประสิทธิภาพ

ต่อไปนี้คือตัวอย่างของฟีด (รวมถึงส่วนหัว HTTP บางส่วน) ที่ดึงมาจากบริการที่รองรับ ETag ที่มีประสิทธิภาพ

GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  ...
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    ...
  </entry>
</feed>

ไลบรารีของไคลเอ็นต์ที่รองรับ Data API เวอร์ชัน 2 จะจัดการ ETag ให้คุณอย่างโปร่งใส ข้อมูลต่อไปนี้มีไว้สําหรับลูกค้าที่ไม่ได้ใช้ไลบรารีของไคลเอ็นต์ และสําหรับผู้อ่านที่สนใจเกี่ยวกับวิธีจัดการการกําหนดเวอร์ชันที่ระดับโปรโตคอล

หมายเหตุ: หากต้องการข้อมูลเกี่ยวกับระบบการกําหนดเวอร์ชันทรัพยากรที่ใช้ API ข้อมูลเวอร์ชัน 1.0 โปรดดูคู่มืออ้างอิงเวอร์ชัน 1.0

การดึงข้อมูลเงื่อนไข

หากต้องการเรียกข้อมูลที่ดึงมาก่อนหน้านี้ คุณสามารถปรับปรุงประสิทธิภาพได้โดยแจ้งให้เซิร์ฟเวอร์ส่งรายการเฉพาะในกรณีที่มีการเปลี่ยนแปลงนับตั้งแต่ครั้งล่าสุดที่คุณเรียกข้อมูล

ในการเรียกใช้การดึงข้อมูลแบบมีเงื่อนไขประเภทนี้ ให้ส่งคําขอ HTTP GET ที่มีส่วนหัว HTTP If-None-Match ระบุ ETag ของรายการในส่วนหัว

ต่อไปนี้คือตัวอย่างของส่วนหัว If-None-Match

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

เมื่อเซิร์ฟเวอร์ได้รับคําขอนี้ ระบบจะตรวจสอบว่ารายการที่คุณขอมี ETag เดียวกับ ETag ที่คุณระบุหรือไม่ หาก ETag ตรงกัน แสดงว่ารายการไม่มีการเปลี่ยนแปลง และเซิร์ฟเวอร์จะแสดงรหัสสถานะ Not Modified 304 ของ HTTP

หาก ETag ไม่ตรงกัน ระบบจะแก้ไขรายการนับตั้งแต่ครั้งล่าสุดที่คุณขอ และเซิร์ฟเวอร์ส่งรายการกลับมา

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

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

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

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

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

ใช้ส่วนหัว HTTP ของ If-Match
ใช้แอตทริบิวต์ gd:etag ในองค์ประกอบ <atom:entry>

เราขอแนะนําให้ใช้แนวทาง If-Match หากเป็นไปได้

หากต้องการอัปเดตรายการโดยใช้ If-Match ให้เริ่มต้นด้วยการหารายการที่คุณกําลังอัปเดต ทําการเปลี่ยนแปลงที่ต้องการในรายการ จากนั้นสร้างคําขอ PUT ใหม่ที่มีรายการที่แก้ไข (โปรดดูรายละเอียดเกี่ยวกับ URL ในเอกสารประกอบเฉพาะบริการ)

ก่อนส่ง PUT ให้เพิ่มส่วนหัว HTTP If-Match ที่มี ETag จากรายการเดิม ดังนี้

If-Match: "S0wCTlpIIip7ImA0X0QI"

จากนั้นส่งคําขอ PUT

หากอัปเดตสําเร็จ เซิร์ฟเวอร์จะแสดงรหัสสถานะ HTTP 200 OK และสําเนาของรายการที่อัปเดตแล้ว

หากการอัปเดตไม่สําเร็จเนื่องจาก ETag ที่คุณระบุไม่ตรงกับ ETag ปัจจุบันในรายการ (ซึ่งหมายความว่ารายการมีการเปลี่ยนแปลงบนเซิร์ฟเวอร์ตั้งแต่ครั้งล่าสุดที่คุณเรียกข้อมูล) เซิร์ฟเวอร์จะแสดงรหัสสถานะ HTTP 412 Precondition Failed

หากคุณเขียนส่วนหัว HTTP ไม่ได้หรือมีเหตุผลอื่นๆ ในการหลีกเลี่ยงการใช้ส่วนหัว If-Match ให้ใช้แอตทริบิวต์ gd:etag แทน

หากคุณไม่ส่งส่วนหัว If-Match เซิร์ฟเวอร์จะใช้ค่าแอตทริบิวต์ gd:etag ของรายการที่อัปเดตแล้วเป็นค่า If-Match โดยนัย

หากต้องการลบล้างระบบการกําหนดเวอร์ชันและอัปเดตรายการโดยไม่คํานึงถึงว่าบุคคลอื่นได้อัปเดตหรือไม่หลังจากที่คุณดึงข้อมูล ให้ใช้ If-Match: * แทนการระบุ ETag ในส่วนหัว

สําหรับข้อมูลเกี่ยวกับบริการที่รองรับ ETag ที่มีประสิทธิภาพ โปรดดูคําแนะนําในการย้ายข้อมูล

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

การลบรายการที่ใช้ ETag ที่มีประสิทธิภาพจะทํางานคล้ายกับการอัปเดต

หากต้องการลบรายการที่มี ETag ที่รัดกุม ก่อนอื่นให้เรียกข้อมูลรายการที่ต้องการลบ จากนั้นส่งคําขอ DELETE ไปยัง URL แก้ไขของรายการ

หากต้องการตรวจสอบว่าคุณไม่ได้ลบรายการที่เปลี่ยนแปลงโดยไคลเอ็นต์อื่นนับตั้งแต่ดึงข้อมูลมา ให้ใส่ส่วนหัว HTTP If-Match ที่มีค่า ETag ของรายการเดิม

หากคุณต้องการลบล้างระบบการกําหนดเวอร์ชันและลบรายการ ไม่ว่าผู้อื่นจะอัปเดตข้อมูลขณะที่คุณดึงข้อมูลไว้หรือไม่ ให้ใช้ If-Match: * แทนการระบุ ETag ในส่วนหัว

หากรายการไม่มี ETag ที่รัดกุม คําขอ DELETE จะประสบความสําเร็จเสมอ

การตอบกลับบางส่วน (ทดลอง)

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

หากต้องการดูว่ามีการตอบกลับบางส่วนสําหรับผลิตภัณฑ์ที่คุณใช้อยู่หรือไม่ ให้ดูเอกสารประกอบของ API

หากต้องการขอการตอบกลับบางส่วน ให้ใช้พารามิเตอร์การค้นหา fields เพื่อระบุองค์ประกอบหรือแอตทริบิวต์ที่ต้องการส่งคืน เช่น

http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))

การตอบสนองของเซิร์ฟเวอร์มีเฉพาะองค์ประกอบลิงก์และรายการสําหรับฟีดเท่านั้น องค์ประกอบของรายการมีเฉพาะ ETag, ID, อัปเดต และแก้ไขข้อมูลของลิงก์ ไวยากรณ์พารามิเตอร์การค้นหา fields ครอบคลุมในส่วนต่อไปนี้ โปรดดูรายละเอียดเพิ่มเติมเกี่ยวกับการตอบกลับที่หัวข้อการจัดการคําตอบบางส่วน

หมายเหตุ: คุณใช้พารามิเตอร์การค้นหา fields กับคําขอที่แสดงผลข้อมูลได้ นอกจาก GET แล้ว ยังรวมถึง POST และ PUT (รวมถึง PATCH ซึ่งใช้สําหรับการอัปเดตบางส่วน) อย่างไรก็ตาม พารามิเตอร์การค้นหา fields จะส่งผลต่อข้อมูลการตอบกลับเท่านั้น แต่จะไม่ส่งผลต่อข้อมูลที่คุณต้องระบุ หรือช่องที่อัปเดตหรือสร้าง

สรุปไวยากรณ์ของพารามิเตอร์ช่อง

รูปแบบของค่าพารามิเตอร์การค้นหา fields จะอิงตามไวยากรณ์ XPath แต่รองรับนิพจน์ XPath ที่ถูกต้องเพียงบางส่วน ไวยากรณ์ที่รองรับจะสรุปไว้ด้านล่าง และตัวอย่างเพิ่มเติมจะอยู่ในส่วนต่อไปนี้

ใช้รายการที่คั่นด้วยคอมมาเพื่อเลือกหลายช่อง
ใช้ a/b เพื่อเลือกองค์ประกอบ b ที่ฝังอยู่ภายในองค์ประกอบ a ใช้ a/b/c เพื่อเลือกองค์ประกอบ c ที่ฝังอยู่ภายใน b
ใช้คํานําหน้า '@' เพื่อระบุ แอตทริบิวต์ ที่มีชื่อที่ระบุ อย่าใส่คํานําหน้า '@' เพื่ออ้างถึงองค์ประกอบ
ใช้เงื่อนไขของช่องเพื่อเลือกองค์ประกอบที่ตรงกับเกณฑ์บางประการ โดยวางนิพจน์ในวงเล็บ "[ ]" หลังองค์ประกอบที่ต้องการจํากัด
เช่น fields=entry[author/name='Elizabeth'] จะแสดงเฉพาะรายการฟีดที่เอลิซาเบธเป็นผู้เขียน
ระบุตัวเลือกช่องย่อยให้ขอเฉพาะแอตทริบิวต์หรือองค์ประกอบย่อยโดยวางนิพจน์ในวงเล็บ "( )" ไว้หลังองค์ประกอบที่เลือก
เช่น fields=entry(id,author/email) จะแสดงเฉพาะรหัสและอีเมลของผู้เขียนแต่ละรายการในฟีด
คุณจํากัดสตริงโดยใช้เครื่องหมายคําพูดแบบคู่หรือเดี่ยวได้

หากต้องการออกจากเครื่องหมายคําพูดคู่หรือเดี่ยว ให้ใส่เครื่องหมายคําพูดซ้ํา ตัวอย่างเช่น """Hello,"" he said" จะสร้างสตริง "Hello," he said และ '''Hello,'' he said' จะสร้างสตริง 'Hello,' he said
คุณใช้ไวลด์การ์ดในการเลือกช่องได้
เช่น entry/gd:* เลือกองค์ประกอบย่อยทั้งหมดของรายการในเนมสเปซ gd และ entry/@gd:* เลือกแอตทริบิวต์องค์ประกอบย่อยในเนมสเปซเดียวกัน

พารามิเตอร์การค้นหา fields ทําหน้าที่เป็นตัวกรองเอาต์พุต ซึ่งหมายความว่าระบบจะคํานวณคําตอบบางส่วนหลังจากประมวลผลการค้นหาที่เหลือเท่านั้น ตัวอย่างเช่น หากคุณระบุพารามิเตอร์การค้นหา max-results เพื่อระบุว่าคุณต้องการผลการค้นหา 20 รายการต่อหน้า ระบบจะสร้างผลการค้นหา 20 รายการแรกและการตอบสนองบางส่วนจะคํานวณจากผลลัพธ์นั้น หากข้อมูลจําเพาะของ fields ไม่ตรงกับ 20 รายการแรกที่เลือกจากคําค้นหา คุณจะได้รับฟีดว่างเปล่า และจะไม่แสดงผลรายการที่ตรงกัน 20 รายการแรก

หมายเหตุ: อย่าพยายามใช้เงื่อนไขของช่องเป็นตัวเลือกการค้นหา กล่าวคือ อย่าพยายามเรียกข้อมูลฟีดที่สมบูรณ์แล้วใช้เงื่อนไขของช่องเพื่อกรองรายการที่สนใจออกจากชุดข้อมูลขนาดใหญ่มาก หากเป็นไปได้ ให้ใช้พารามิเตอร์การค้นหาอื่นๆ เช่น start-index และ max-results เพื่อลดผลลัพธ์ของการค้นหาแต่ละรายการเป็นขนาดที่จัดการได้ มิฉะนั้น ประสิทธิภาพการทํางานอาจลดลงเมื่อใช้การตอบสนองบางส่วนอาจมีน้ําหนักมากกว่าประสิทธิภาพที่ลดลงอย่างมากอันเป็นผลมาจากการใช้งานที่ไม่เหมาะสม

การจัดรูปแบบค่าพารามิเตอร์ช่อง

หลักเกณฑ์ต่อไปนี้อธิบายวิธีสร้างค่าพารามิเตอร์การค้นหา fields หลักเกณฑ์แต่ละรายการจะมีตัวอย่างและให้คําอธิบายว่าค่าพารามิเตอร์ส่งผลต่อการตอบกลับอย่างไร

หมายเหตุ: เช่นเดียวกับค่าพารามิเตอร์ทั้งหมด ค่าพารามิเตอร์ fields ต้องมีการเข้ารหัส URL ตัวอย่างด้านล่างจะละเว้นการเข้ารหัสเพื่อให้อ่านง่ายขึ้น

ระบุช่องที่ต้องการแสดงผลหรือเลือกช่อง

ค่าพารามิเตอร์การค้นหา fields คือรายการองค์ประกอบหรือแอตทริบิวต์ที่คั่นด้วยคอมมา (เรียกรวมกันว่าช่อง) และจะระบุแต่ละช่องให้สัมพันธ์กับองค์ประกอบรากของการแสดงทรัพยากร ดังนั้น หากคุณกําลังเรียกดูฟีด ช่องจะระบุให้สัมพันธ์กับองค์ประกอบ <feed> และหากคุณเรียกข้อมูลรายการเดียว ระบบจะระบุช่องให้สัมพันธ์กับองค์ประกอบ <entry> หากองค์ประกอบที่คุณเลือกเป็น (หรือเป็นส่วนหนึ่งของ) องค์ประกอบที่เกิดซ้ําในฟีด บริการจะแสดงอินสแตนซ์ทั้งหมดขององค์ประกอบนั้น

ตัวอย่างระดับฟีดมีดังนี้

ตัวอย่าง	ผลกระทบ
`entry`	แสดงผลองค์ประกอบ `<entry>` ทั้งหมดและองค์ประกอบย่อยทั้งหมดของรายการเหล่านั้น แต่ไม่แสดงองค์ประกอบย่อยอื่นๆ ของ `<feed>`
`id,entry`	แสดงผลทั้งฟีด `<id>` และองค์ประกอบ `<entry>` ทั้งหมด
`entry/title`	แสดงผลองค์ประกอบ `<title>` สําหรับรายการฟีดทั้งหมด เมื่อใดก็ตามที่มีการส่งองค์ประกอบที่ซ้อนกัน การตอบกลับจะรวมถึงแท็กแนบสําหรับองค์ประกอบระดับบนของ แท็กระดับบนไม่มีองค์ประกอบหรือแอตทริบิวต์ย่อยอื่นๆ เว้นแต่ว่าได้เลือกไว้อย่างชัดเจนแล้ว
`entry/author/uri`	แสดงเฉพาะองค์ประกอบย่อย `<uri>` ขององค์ประกอบ `<author>` สําหรับรายการฟีดทั้งหมด
`entry/*:rating`	แสดงเฉพาะองค์ประกอบย่อยที่มีชื่อท้องถิ่น `rating` ในเนมสเปซของรายการฟีดทั้งหมด

ตัวอย่างระดับเริ่มต้นมีดังนี้

ตัวอย่าง	ผลกระทบ
`author`	แสดงผลองค์ประกอบย่อย `<author>` ของรายการเป้าหมาย
`@gd:etag`	แสดงผลแอตทริบิวต์ `etag` ของรายการเป้าหมาย
`author/uri`	แสดงผลองค์ประกอบย่อย `<uri>` ขององค์ประกอบ `<author>` สําหรับรายการเป้าหมาย
`media:group/media:*`	แสดงผลช่องย่อยทั้งหมดของ `<media:group>` ในเนมสเปซ `media` สําหรับรายการเป้าหมาย

จํากัดคําตอบให้ช่องที่เลือกที่ตรงกับเกณฑ์บางรายการ หรือใช้เงื่อนไขของช่อง

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

ตัวอย่าง	ผลกระทบ
`entry[link/@rel='edit']`	แสดงผลรายการฟีดที่มีเอลิเมนต์ `<link>` พร้อมค่าแอตทริบิวต์ `rel` เป็น `'edit'`
`entry/title[text()='Today']`	แสดงผลองค์ประกอบ `<title>` ที่เกิดขึ้นในรายการฟีดหากเนื้อหาคือ `'Today'`
`entry/author[name='Jo']`	แสดงผลองค์ประกอบ `<author>` ที่เกิดขึ้นในรายการฟีดหากมีองค์ประกอบย่อย `<name>` ที่มีเนื้อหา `'Jo'`
`author[name='Jo']`	แสดงผลองค์ประกอบ `<author>` ในรายการเป้าหมายหากมีองค์ประกอบย่อย `<name>` ที่มีเนื้อหา `'Jo'`

ขอเฉพาะบางส่วนขององค์ประกอบที่เลือก หรือใช้การเลือกช่องย่อย

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

ตัวอย่าง	ผลกระทบ
`entry/author(uri)`	แสดงเฉพาะองค์ประกอบย่อย `<uri>` สําหรับผู้เขียนในรายการฟีด
`entry/author[name='Jo'](uri)`	แสดงผลองค์ประกอบย่อย `<uri>` ของ `<author>` เท่านั้นสําหรับทุกรายการที่มีชื่อผู้เขียนเป็น `'Jo'`
`entry(link(@rel,@href))`	แสดงผลเฉพาะค่าของแอตทริบิวต์ `rel` และ `href` สําหรับองค์ประกอบ `<link>` แต่ละรายการในรายการฟีด
`entry(title,link[@rel='edit'])`	แสดงผลเฉพาะองค์ประกอบ `<title>` และ `<link>` ที่มีแอตทริบิวต์แก้ไข `rel` สําหรับรายการฟีดแต่ละรายการ
`entry(title,author(uri)`	แสดงทั้งองค์ประกอบ `<title>` และองค์ประกอบ `<uri>` ของรายการฟีดแต่ละรายการ

ข้อมูลเพิ่มเติมเกี่ยวกับไวยากรณ์เงื่อนไขของช่อง

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

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

ตารางต่อไปนี้แสดงโอเปอเรเตอร์ XPath ที่รองรับเงื่อนไขของช่องและแสดงตัวอย่างบางส่วน

โอเปอเรเตอร์	ไวยากรณ์	ตัวอย่าง
การเปรียบเทียบสตริง	`=` หรือ `eq` `!=` หรือ `ne`	แสดงผลข้อมูลทั้งหมดหากมีองค์ประกอบ `<link>` ที่มีแอตทริบิวต์ `rel` ตั้งค่าเป็น "`self'`": `entry[link/@rel='self']` แสดงผลข้อมูลทั้งหมดหากมีองค์ประกอบ `<title>` ที่มีเนื้อหาเท่ากับสตริง `'unknown'` `entry[title eq 'unknown']` แสดงผลทั้ง `<title>` องค์ประกอบหากเนื้อหาไม่ใช่ `'unknown'`: `title[text() != 'unknown']`
การเปรียบเทียบเชิงตรรกะ	`and or not`	แสดงลิงก์ที่มีการตั้งค่าแอตทริบิวต์ `rel` เป็น `'self'` หรือ `'edit'`: `link[@rel='self' or @rel='edit']` แสดงลิงก์ที่มีการตั้งค่าแอตทริบิวต์ `rel` เป็น `'self'` และแอตทริบิวต์ `type` ที่ตั้งค่าเป็น `'application/atom+xml'`: `link[@rel='self' and @type='application/atom+xml']` แสดงผลลิงก์ที่ไม่มีแอตทริบิวต์ `rel` ที่มีค่า `'self'`: `link[not(@rel='self')]` โปรดทราบว่าใน XPath นั้น `not` มีลักษณะเหมือนการเรียกใช้ฟังก์ชัน
การเปรียบเทียบตัวเลข	`=` หรือ `eq` `!=` หรือ `ne` `>` หรือ `gt` `>`= หรือ `ge` `<` หรือ `lt` `<=` หรือ `le`	แสดงผลองค์ประกอบ `<gd:rating>` ที่มีแอตทริบิวต์ `value` ซึ่งสามารถแปลงเป็นจํานวนเต็ม 5 ได้ `gd:rating[@value=5]` แสดงผลองค์ประกอบ `<gd:rating>` ที่มีแอตทริบิวต์ `average` ซึ่งสามารถแปลงเป็นแบบลอยที่มีขนาดใหญ่กว่า 4.3 ได้ `gd:rating[@average gt 4.3]`
การเปรียบเทียบวันที่	ใช้โอเปอเรเตอร์การเปรียบเทียบตัวเลข ดังที่แสดงในตัวอย่าง	หากต้องการเปรียบเทียบวันที่หรือวันที่/เวลา คุณสามารถแคสต์องค์ประกอบ แอตทริบิวต์ หรือสตริงตามตัวอักษรลงใน `xs:date` หรือ `xs:dateTime` ได้ สําหรับ `xs:dateTime` เขตเวลาเริ่มต้นคือ UTC แต่วิธีที่ดีที่สุดคือให้ระบุเขตเวลาอย่างชัดเจน แสดงผลองค์ประกอบ `<yt:recorded>` ที่มีวันที่ตั้งแต่วันที่ 1 ม.ค. 2005 `yt:recorded[xs:date(text())>=xs:date('2005-01-01')]` แสดงข้อมูลที่ได้รับการอัปเดตหลังจากเวลาที่ระบุ ตามเขตเวลา UTC: `entry[xs:dateTime(updated)>xs:dateTime('2008-07-25T08:19:37.549Z')]`
การใช้งาน	ใช้ชื่อองค์ประกอบหรือแอตทริบิวต์ดังที่แสดงในตัวอย่าง	ส่งกลับรายการใดก็ตามที่มีลิงก์ที่มีแอตทริบิวต์ `rel`: `entry[link/@rel]` แสดงผลองค์ประกอบ `<gd:rating>` ที่มีแอตทริบิวต์ชื่อ `value`: `entry/gd:rating[@value]`
บูลีน	`true()false()`	บูลีนจะมีประโยชน์ระหว่างการทดสอบเพื่อบังคับให้เงื่อนไขของช่องอยู่ในสถานะจริงหรือเท็จ แสดงองค์ประกอบ `<link>`: `link[true()]`

การจัดการคําตอบบางส่วน

หลังจากที่เซิร์ฟเวอร์ที่รองรับการตอบกลับบางส่วนประมวลผลคําขอที่ถูกต้องที่มีพารามิเตอร์การค้นหา fields จากนั้นเซิร์ฟเวอร์จะส่งรหัสสถานะ HTTP 200 OK พร้อมกับแอตทริบิวต์หรือองค์ประกอบที่ขอ หากพารามิเตอร์การค้นหา fields มีข้อผิดพลาดหรือไม่ถูกต้อง เซิร์ฟเวอร์จะแสดงรหัสสถานะ HTTP 400 Bad Request

องค์ประกอบรูทของการตอบกลับคือ <feed> หรือ <entry> โดยขึ้นอยู่กับ URI เป้าหมาย เนื้อหาขององค์ประกอบรากจะมีเฉพาะช่องที่เลือกสําหรับฟีดหรือรายการนั้น รวมถึงแท็กที่เกี่ยวข้องสําหรับองค์ประกอบระดับบน

ค่าของพารามิเตอร์การค้นหาfieldsของคําขอจะสะท้อนกลับมาได้ 2 วิธี ดังนี้

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

หมายเหตุ: หากต้องการดูค่าแอตทริบิวต์ gd:fields เหล่านี้ในการตอบกลับบางส่วน คุณต้องใส่ค่าเหล่านี้ในข้อกําหนดพารามิเตอร์การค้นหา fields ซึ่งทําได้อย่างชัดแจ้งโดยใช้ @gd:fields หรือใช้ @gd:* ทั่วไปซึ่งรวมถึงข้อมูล ETag ด้วย

คําค้นหาตัวอย่างต่อไปนี้จะขอให้เซิร์ฟเวอร์แสดงเอกสารที่มีเฉพาะแอตทริบิวต์ในเนมสเปซ gd (ทั้งในระดับฟีดและระดับรายการ) รวมถึงรหัสฟีด ชื่อ และลิงก์แก้ไขสําหรับรายการฟีดแต่ละรายการ

http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])

เซิร์ฟเวอร์แสดงการตอบสนองบางส่วนต่อไปนี้พร้อมกับรหัสสถานะ HTTP 200 Successful:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
    gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
  <id>http://example.com/myFeed</id>
  <entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <title>This year</title>
  </entry>
  <entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/2/'/>
    <title>Last year</title>
  </entry>
  <entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/3/'/>
    <title>Today</title>
  </entry>
</feed>

หากช่องที่เลือกไม่ตรงกับสิ่งใด บริการจะยังคงส่งคืนรหัสสถานะ HTTP 200 Successful แต่การตอบสนองบางส่วนเป็นฟีดว่าง:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
  gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
</feed>

อัปเดตบางส่วน (ทดลอง)

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

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

หากต้องการดูว่ามีการอัปเดตบางส่วนสําหรับผลิตภัณฑ์ที่คุณใช้อยู่หรือไม่ โปรดดูเอกสารประกอบเฉพาะผลิตภัณฑ์

การส่งคําขออัปเดตบางส่วน

หากต้องการส่งคําขออัปเดตบางส่วน คุณต้องส่งคําขอ HTTP PATCH ไปยัง URL เดียวกันกับที่มักใช้กับ PUT เพื่ออัปเดตทรัพยากร เนื้อหาของคําขอ PATCH เป็นเอลิเมนต์ <entry> บางส่วนที่ระบุช่องที่คุณต้องการเพิ่มหรือแก้ไข แอตทริบิวต์ gd:fields ของรายการระบุช่องที่คุณต้องการลบ

เซิร์ฟเวอร์ประมวลผลคําขอ PATCH รายการตามลําดับที่เจาะจง ดังนี้

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

หมายเหตุ: เนื่องจากเนื้อหาของคําขอ PATCH มักจะไม่เป็นไปตามรูปแบบการเผยแพร่ Atom ดังนั้น Content-Type ที่คุณใช้กับคําขอ PATCH จึงเท่ากับ application/xml

ต่อไปนี้คือตัวอย่างคําขออัปเดตบางส่วน

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='description'>
  <title>New title</title>
</entry>

คําขอ PATCH นี้ทําการเปลี่ยนแปลงต่อไปนี้กับการแสดงทรัพยากรที่เก็บไว้ในเซิร์ฟเวอร์สําหรับรายการของ URI เป้าหมาย

นําองค์ประกอบ <description> ออก
อัปเดตองค์ประกอบ <title>

ความหมายของคําขออัปเดตบางส่วน

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

การลบช่อง ใช้แอตทริบิวต์ gd:fields ขององค์ประกอบ <entry> เพื่อระบุช่องที่ต้องการลบจากทรัพยากร ตัวอย่างคําขอต่อไปนี้จะลบชื่อและสรุปที่เชื่อมโยงกับรายการ แต่คําขอจะไม่เพิ่มหรืออัปเดตข้อมูลอื่นๆ สําหรับรายการ
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='title,summary'/>
```
การเพิ่มหรืออัปเดตช่อง ใช้เนื้อความขององค์ประกอบ <entry> เพื่อระบุข้อมูลที่ต้องการเพิ่มหรืออัปเดตสําหรับทรัพยากร ช่องต่อไปนี้จะรวมเข้าเป็นข้อมูลที่มีอยู่สําหรับทรัพยากร หลังจากทําการลบออกตามกฎต่อไปนี้
- มีการเพิ่มช่องที่ยังไม่ได้นําเสนอ หากข้อมูลทรัพยากรไม่ได้ระบุค่าสําหรับช่องใดช่องหนึ่ง ระบบจะเพิ่มช่องนั้นลงในข้อมูลที่มีอยู่ ตัวอย่างเช่น หากรายการไม่มีชื่อ และคําขอ PATCH ของคุณมีองค์ประกอบ <title> ระบบจะเพิ่มชื่อใหม่ลงในรายการ
- ช่องต่างๆ ที่มีอยู่แล้วจะถูกแทนที่หรือต่อท้าย ลักษณะการทํางานที่เจาะจงสําหรับการผสานช่องที่ระบุไว้ในข้อมูลทรัพยากรอยู่แล้วจะขึ้นอยู่กับลักษณะของช่อง
  - ระบบจะแทนที่ช่องที่ซ้ํากัน หากข้อมูลทรัพยากรระบุค่าสําหรับองค์ประกอบที่ซ้ํากันไม่ได้ ค่าที่คุณระบุในคําขอ PATCH จะแทนที่ค่าที่มีอยู่สําหรับองค์ประกอบนั้น ในตัวอย่างด้านล่าง ชื่อใหม่จะแทนที่ชื่อที่มีอยู่
```
PATCH /myFeed/1/1/
Content-Type: application/xml

  <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <title>New Title</title>
</entry>
```
    ดูตัวอย่างที่ซับซ้อนกว่าด้านล่าง ในตัวอย่างนี้ สมมติว่ารายการมีผู้เขียนได้เพียงรายเดียวเท่านั้น และทรัพยากรเป้าหมายมีค่าสําหรับชื่อและอีเมลของผู้เขียนอยู่แล้ว แม้ว่าองค์ประกอบ <author> จะมีช่องย่อย 2 ช่อง แต่จะมีเพียงองค์ประกอบ <name> ในข้อมูลที่ระบุ ด้วยเหตุนี้ ระบบจะเขียนทับเฉพาะค่าของช่องดังกล่าวเท่านั้น ค่าขององค์ประกอบ <email> ซึ่งหายไปจากข้อมูลที่ระบุจะไม่เปลี่ยนแปลง
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <author>
    <name>New Name</name>
  </author>
</entry>
```
  - ระบบจะเติมข้อมูลในช่องที่ซ้ํากัน หากข้อมูลทรัพยากรระบุค่าสําหรับองค์ประกอบที่เกิดซ้ํา ก็จะเพิ่มองค์ประกอบใหม่ให้กับชุดค่าที่มีอยู่แล้ว
    
    โปรดทราบว่าบางครั้งคุณอาจต้องการทําอย่างอื่นนอกเหนือจากการเพิ่มอินสแตนซ์ใหม่ขององค์ประกอบที่ซ้ํากัน ตัวอย่างเช่น คุณควรทําอย่างใดอย่างหนึ่งต่อไปนี้
    - แทนที่รายการทั้งหมดขององค์ประกอบที่ซ้ํากัน คุณสามารถลบช่องที่ซ้ําทั้งหมดได้โดยใช้แอตทริบิวต์ gd:fields (เช่น gd:fields='ns:accessControl') และระบุชุดช่องแทนที่ที่ครบถ้วน เนื่องจากองค์ประกอบที่มีอยู่ทั้งหมดจะถูกลบก่อน ชุดช่องที่คุณระบุจะไม่ขัดแย้งกับค่าที่มีอยู่เมื่อมีการต่อท้าย
    - แทนที่ค่าหนึ่งในชุดค่าที่มีอยู่สําหรับองค์ประกอบที่เกิดซ้ํา ในกรณีนี้ เพียงนําองค์ประกอบเดียวออกโดยการกําหนดมูลค่า gd:fields ให้แคบพอเพื่อหลีกเลี่ยงการลบค่าอื่นๆ ที่คุณต้องการเก็บไว้ เช่น หากต้องการนําการควบคุมการเข้าถึงออกด้วย action ของ embed เท่านั้น คุณอาจใช้ gd:fields='ns:accessControl[@action="embed"]' จากนั้นระบุช่องเดียวที่ต้องการแทนที่ด้วยช่องขององค์ประกอบ <entry>
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='ns:accessControl[@action="embed"]>
  <ns:accessControl action="embed" permission="allowed" />
</entry>
```

การจัดการกับการอัปเดตบางส่วน

หลังจากประมวลผลคําขอการอัปเดตบางส่วนที่ถูกต้องแล้ว API จะส่งโค้ดตอบกลับ HTTP ของ 200 OK โดยค่าเริ่มต้น ส่วนเนื้อหาของการตอบกลับคือรายการทั้งหมดที่คุณอัปเดต เซิร์ฟเวอร์จะอัปเดตค่า ETag เมื่อประมวลผลคําขอ PATCH สําเร็จ เช่นเดียวกับที่ PUT ดําเนินการ

หากคําขอ PATCH ทําให้เกิดสถานะทรัพยากรใหม่ที่ไม่ถูกต้องตามไวยากรณ์หรือไม่ถูกต้อง เซิร์ฟเวอร์จะแสดงรหัสสถานะ HTTP HTTP 400 Bad Request หรือ 422 Unprocessable Entity และสถานะทรัพยากรจะไม่เปลี่ยนแปลง ตัวอย่างเช่น หากคุณพยายามลบช่องที่ต้องกรอกและไม่ได้ใส่ค่าทดแทน เซิร์ฟเวอร์จะแสดงข้อผิดพลาด

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

คําอธิบายสํารองเมื่อไม่รองรับ PWatch

หากไฟร์วอลล์ของคุณไม่อนุญาตให้ PATCH ให้ส่งคําขอ HTTP POST และตั้งค่าส่วนหัวการลบล้างเป็น PATCH ดังที่แสดงด้านล่าง

POST /myfeed/1/1/ X-HTTP-Method-Override: PATCH Content-Type: application/xml ...

กําลังใช้คําตอบบางส่วนกับการอัปเดตบางส่วน

คุณสามารถใช้การตอบกลับบางส่วนเป็นฐานของคําขออัปเดตบางส่วนที่ตามมา หากระบุ ให้ระบุพารามิเตอร์การค้นหา fields ที่มีลิงก์สําหรับแก้ไข และ @gd:* ซึ่งจะช่วยให้มั่นใจว่าการตอบสนองบางส่วนประกอบด้วยข้อมูล เช่น ค่าแอตทริบิวต์ ETag และ gd:fields ซึ่งมีความสําคัญต่อคําขอที่ตามมา

ต่อไปนี้เป็นตัวอย่างการตอบกลับการตอบกลับบางส่วนที่คุณสามารถใช้เป็นพื้นฐานสําหรับการอัปเดตบางส่วนในอนาคตได้

http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who

เซิร์ฟเวอร์จะตอบสนอง:

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"E0UKRAREeCp7IWA6WhJT"'
    gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
  <link href='http://example.com/myFeed/1/1/'/>
  <gd:who email='[email protected]'/>
  <gd:who email='[email protected]'/>
  <gd:who email='[email protected]'/>
</entry>

สมมติว่าคุณต้องการนําผู้ใช้ที่มีอีเมล '[email protected]' ออก ให้เพิ่มผู้ใช้ที่มีอีเมล '[email protected]' และเปลี่ยนอีเมลของผู้ใช้ที่ใช้ '[email protected]' เป็น '[email protected]'

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

ลบ <gd:who email='jane'/> จากรายการองค์ประกอบที่ระบุ
เพิ่ม <gd:who email='[email protected]'/> ลงในรายการองค์ประกอบที่ให้ไว้
แทนที่ <gd:who email='[email protected]'/> ด้วย <gd:who email='[email protected]'/>

คําขอ PATCH ที่อิงจากคําตอบแบบบางส่วนซึ่งแสดงออกโดยอัตโนมัติมีดังนี้

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
    gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <link href='http://example.com/myFeed/1/1'/>
  <gd:who email='[email protected]'/>
  <gd:who email='[email protected]'/>
  <gd:who email='[email protected]'/>
</entry>

หมายเหตุ: วิธีนี้จะอาศัยแอตทริบิวต์ gd:fields และ gd:etag (หากรองรับ) ที่รวมอยู่ในการตอบกลับบางส่วนของรายการ ส่วนเนื้อหาของรายการบางส่วนต้องเก็บช่องและแอตทริบิวต์ทั้งหมดที่มีอยู่ในคําตอบบางส่วน ยกเว้นรายการที่ต้องการนําออกอย่างชัดเจน คุณสามารถอัปเดตช่องที่มีอยู่ในเนื้อหาด้วยค่าใหม่และใส่ช่องใหม่ที่ต้องการเพิ่มได้

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

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

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

แอปพลิเคชันเดสก์ท็อปควรใช้ระบบการตรวจสอบสิทธิ์เฉพาะของ Google ที่เรียกว่าการตรวจสอบสิทธิ์บัญชีสําหรับแอปพลิเคชันที่ติดตั้ง (หรือที่เรียกว่า "ClientLogin") (ไคลเอ็นต์บนเว็บไม่ควรใช้ระบบนี้)
ไคลเอ็นต์บนเว็บ เช่น ส่วนหน้าของบุคคลที่สามสําหรับบริการของ Google ควรใช้ระบบการตรวจสอบสิทธิ์เฉพาะของ Google ที่ชื่อ Account Authentication Proxy for Web-based Application (หรือที่เรียกว่า "AuthSub")

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

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

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

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

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

สถานะเซสชัน

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

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

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

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

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

การเปรียบเทียบ Atom และ RSS จากการทํางานร่วมกัน
ภาพรวมของ Atom จาก IBM
ส่วนขยาย Dublin Core ไปยัง RSS
คําจํากัดความของเมธอด HTTP 1.1 ข้อกําหนดของ GET, POST, PUT และ DELETE
คําจํากัดความของรหัสสถานะ HTTP 1.1
วิธีสร้างโปรโตคอล REST
การสร้างบริการเว็บด้วย REST
ข้อมูลเบื้องต้นทางเทคนิคเกี่ยวกับ XML
เนมสเปซ XML ตามตัวอย่าง
ส่วน ETag ของข้อกําหนด HTTP

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