עקרונות בסיסיים בנושא פרוטוקולי Google Data APIs

במסמך הזה נתאר את העקרונות הבסיסיים של הפרוטוקול שנעשה בו שימוש בממשקי ה-API של הנתונים של Google, כולל דוגמאות לאופן שבו שאילתה נראית, איך נראות התוצאות וכו'.

למידע נוסף על Google Data APIs, יש לעיין במסמך Google Data Developer Guide ובמדריך העזר.

Audience

המסמך הזה מיועד לכל מי שרוצה להבין את הרעיון הכללי של פורמט ה-XML והפרוטוקול שמשמשים את ממשקי ה-API של נתונים של Google.

גם אם אתם רוצים רק לכתוב קוד שמשתמש בספריות הלקוח הספציפיות לשפה, כדאי שתקראו את המסמך הזה, כדי להבין מה קורה מתחת לשכבת ההפשטה של ספריית הלקוח.

המסמך הזה מניח שאתה מבין את היסודות של XML, מרחבי שמות, עדכונים מופצים, ואת הבקשות GET, POST, PUT, ו- DELETE ב-HTTP, כמו גם את הקונספט של "משאב" ב-HTTP. למידע נוסף על הדברים האלה, אפשר לעיין בקטע משאבים נוספים במסמך הזה.

מסמך זה אינו מסתמך על שפת תכנות מסוימת; הלקוח שלך יכול לבצע אינטראקציה עם השרת באמצעות כל שפת תכנות המאפשרת לך לשלוח בקשות HTTP ולנתח תגובות המבוססות על XML.

דוגמאות

הדוגמאות הבאות מציגות בקשות של פרוטוקולים של Data API חשופים שאתם עשויים לשלוח לשירות כללי, ואת התוצאות שאתם עשויים לקבל. כדי לראות איך לשלוח את הבקשות בשפות תכנות שונות, ניתן לעיין בדוגמאות ובשפות הספציפיות לשפות. למידע על השימוש בממשקי ה-API של Google Data בשירותי 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>

חשוב לשים לב שאינך מספק את הרכיבים הרגילים של Atom <id>, <link> או <updated>. השרת יוצר את הרכיבים האלה בתגובה לבקשת 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 במסמך העזר של הפרוטוקול.

מקורות מידע נוספים

המסמכים הבאים של צד שלישי עשויים להועיל לך:

חזרה למעלה