ข้อมูลเบื้องต้นเกี่ยวกับโปรโตคอล Google Data API

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

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

ผู้ชม

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

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

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

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

ตัวอย่าง

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

การขอฟีดหรือทรัพยากรอื่นๆ

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

GET /myFeed

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

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
</feed>

โปรดทราบว่าถึงแม้ว่าฟีดจะไม่มีรายการใดเลย แต่ก็มีข้อมูลเมตา เช่น ชื่อและชื่อผู้เขียน

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

หากต้องการสร้างรายการใหม่ ให้ส่งคําขอ POST และจัดเตรียม XML ของรายการใหม่ ดังนี้

POST /myFeed

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my entry</content>
</entry>

โปรดทราบว่าคุณไม่ได้ใส่องค์ประกอบ <id>, <link> หรือ <updated> ของ Atom มาตรฐาน เซิร์ฟเวอร์จะสร้างองค์ประกอบเหล่านั้นเพื่อตอบสนองต่อคําขอ POST ของคุณ นอกจากนี้ โปรดทราบว่าผู้เขียนฟีดไม่จําเป็นต้องเป็นบุคคลเดียวกับผู้เขียนรายการ

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

201 CREATED

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/1/"/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my entry</content>
</entry>

กําลังค้นหาสตริง

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

GET /myFeed?q=This

เซิร์ฟเวอร์จะตอบกลับรายการทั้งหมดที่ตรงกับสตริงการค้นหา This (ในกรณีนี้มีเพียงคําขอเดียว)

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
  <entry>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/1/"/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
    <title type="text">Entry 1</title>
    <content type="text">This is my entry</content>
  </entry>
</feed>

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

หากต้องการอัปเดตรายการที่มีอยู่ ให้ใช้ PUT ด้วย URI การแก้ไขของรายการ (ตามที่เซิร์ฟเวอร์ในตัวอย่างก่อนหน้านี้ในองค์ประกอบ <link rel="edit">)

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

X-HTTP-Method-Override: PUT

ในตัวอย่างต่อไปนี้ เราจะแก้ไขข้อความของรายการจากค่าเดิม ("นี่คือรายการของฉัน") เป็นค่าใหม่ ("นี่คือรายการแรกของฉัน")

PUT /myFeed/1/1/

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/1/"/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my first entry.</content>
</entry>

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

200 OK

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <title type="text">Entry 1</title>
  <content type="text">This is my first entry.</content>
</entry>

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

หากต้องการดูรายการใหม่ในบริบท ให้ขอทรัพยากรทั้งหมดอีกครั้งโดยทําดังนี้

GET /myFeed

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

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
  <entry>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
    <title type="text">Entry 1</title>
    <content type="text">This is my first entry.</content>
  </entry>
</feed>

การลบรายการ

หากต้องการลบรายการที่มีอยู่ ให้ส่งคําขอ DELETE โดยใช้ URI การแก้ไขของรายการ (ตามที่ระบุโดยเซิร์ฟเวอร์ในตัวอย่างก่อนหน้านี้)

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

 X-HTTP-Method-Override: DELETE

ตัวอย่างต่อไปนี้จะลบข้อมูลต่อไปนี้

DELETE /myFeed/1/2/

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

200 OK

ทํา GET อีกครั้งเพื่อดูว่าฟีดไม่มีรายการดังนี้

GET /myFeed

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

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href="/myFeed" rel="self"/>
</feed>

หากลบไม่สําเร็จ เซิร์ฟเวอร์จะตอบกลับพร้อมรหัสข้อผิดพลาด สําหรับข้อมูลเพิ่มเติม โปรดดูรหัสสถานะ HTTP ในเอกสารอ้างอิงโปรโตคอล

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

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

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