יסודות הפרוטוקול

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

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

למידע נוסף על פרוטוקול הנתונים של Google, עיין בדף הסקירה הכללית של המדריך למפתחים ובפרוטוקול האתר.

Audience

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

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

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

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

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

דוגמאות

הדוגמאות הבאות מציגות בקשות HTTP שאתם יכולים לשלוח לשירות כללי באמצעות פרוטוקול Google Data Protocol API ישירות, ואת התוצאות שאתם עשויים לקבל. כדי לראות איך לשלוח את הבקשות בשפות תכנות שונות, ניתן לעיין בדוגמאות ובשפות הספציפיות לשפות. למידע על השימוש בפרוטוקול הנתונים של Google בשירותים ספציפיים של Google, יש לעיין במסמכים הספציפיים לשירות.

בקשת פיד או משאב אחר

נניח שיש פיד בשם /myFeed, ומניח שהוא לא מכיל כרגע רשומות כלשהן. כדי להציג את הנתונים, צריך לשלוח לשרת את בקשת ה-HTTP הבאה:

GET /myFeed

השרת מגיב:

200 OK

<?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."'>
  <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>

לתשומת ליבכם: אף על פי שהפיד לא מכיל ערכים, הוא מכיל מטא-נתונים, כמו שם ושם של מחבר. הוא מכיל גם מזהה גרסה, בפורמט ETag של HTTP.

הוספה של רשומה חדשה

כדי ליצור רשומה חדשה, שולחים בקשת POST ומספקים את ייצוג ה-XML של הרשומה החדשה:

POST /myFeed

<?xml version='1.0' encoding='utf-8'?>
<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' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <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' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>
  <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 gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/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>

עדכון רשומה

כדי לעדכן רשומה קיימת, עליך לבצע את השלבים הבאים.

  1. מאחזרים את הרשומה שרוצים לעדכן.
  2. משנים אותה לפי הצורך.
  3. שליחה של בקשת PUT, עם הרשומה המעודכנת בגוף ההודעה, ל-URI של העריכה של הרשומה. ה-URI של העריכה מופיע בדוגמה הקודמת כמאפיין href של הרכיב <link rel='edit'>.

כמו כן, עליך לציין את ה-ETag של הערך המקורי כדי להבטיח שלא תחליף שינויים של מישהו אחר.

בדוגמה הבאה אנחנו משנים את הטקסט של הערך מהערך הישן ("זו הרשומה שלי") לערך חדש ("זו הרשומה הראשונה שלי"):

PUT /myFeed/1/1/

<?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='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/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' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/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>

לתשומת ליבכם: ה-ETag השתנה. למידע נוסף על גרסאות של משאבים, אפשר לעיין בקטע יצירת גרסאות של משאבים (ETags) במסמך העזר של הפרוטוקול.

כדי להציג את הערך החדש לפי הקשר, יש לבקש את המשאב כולו פעם נוספת:

GET /myFeed

השרת מגיב:

200 OK

<?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/"D08FQn8-eil7ImA9WxZbFEw."'>
  <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 gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/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>
</feed>

הערה:אם חומת האש לא מאפשרת PUT, יש להגדיר HTTP POST ולהגדיר את כותרת הדרך לביטול השיטה הבאה:

X-HTTP-Method-Override: PUT

מחיקת רשומה

כדי למחוק רשומה קיימת, צריך לשלוח בקשת DELETE באמצעות ה-URI של רשומת הערך (כפי שסופק על ידי השרת בדוגמה הקודמת).

אם חומת האש לא מאפשרת DELETE, יש לבצע HTTP POST ולהגדיר את כותרת הביטול של השיטה באופן הבא:

X-HTTP-Method-Override: DELETE

כשמוחקים רשומה, אפשר לבחור אם למחוק אותה באופן מותנה (יש למחוק אפשרות זו רק אם הרשומה לא השתנתה מאז הפעם האחרונה ששלפתם אותה) או למחוק אותה באופן לא מותנה. למידע נוסף, עיינו בסעיף גרסאות משאבים (ETags) במסמך העיון של הפרוטוקול. כדי לבצע מחיקה לא מותנית, מגדירים את כותרת ה-HTTP הבאה:

If-Match: *

הדוגמה הבאה מוחקת רשומה (אם הכותרות מוגדרות כראוי):

DELETE /myFeed/1/

השרת מגיב:

200 OK

מבצעים GET נוספת כדי לראות שהעדכון אינו מכיל כעת ערכים:

GET /myFeed

השרת מגיב עם פיד שאינו מכיל מטא-נתונים:

200 OK

<?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/"D0cERnk-eip7ImA9WBBXGEg."'>
  <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 במסמך העזר של הפרוטוקול.

בקשת פידים או רשומות חלקיות (ניסיוני)

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

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

בדוגמה הבאה מבקשים רק את מזהה הפיד, ואת המחבר והשם של כל פיד בפיד,

GET /myFeed?fields=id,entry(author)

השרת מגיב:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

אתם יכולים להשתמש בפרמטר fields עם כל סוג של בקשה שמחזיר נתונים. נוסף על GET, נתונים אלה כוללים את POST, PUT וכן את PATCH המשמשים לשליחת בקשות עדכון חלקי).

הערה: פרמטר השאילתה fields שולט רק בנתונים שנשלחים חזרה בתגובה לבקשה. הוא לא משפיע על הנתונים שצריך לספק בגוף הבקשה PUT, POST או PATCH.

למטה מוצגות דוגמאות לPOST ולPUT.

  • גם כששולחים בקשה POST לקבלת תגובה חלקית, עדיין צריך לספק את אותם נתונים כמתואר בסעיף הוספת רשומה חדשה. הדוגמה הבאה מבקשת תגובה חלקית שמכילה רק את הכותרת של הרשומה החדשה שנוצרה: 
    POST /myFeed?fields=title
      
...data...

    השרת מגיב:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
  • כששולחים בקשה PUT לקבלת תגובה חלקית, עדיין צריך לספק גרסה שונה של ייצוג המשאבים המלא, כפי שמתואר במאמר עדכון רשומה. הדוגמה הבאה מבקשת תגובה חלקית המכילה רק את הערך החדש של ETag של הערך שהשתנה: 
    PUT /myFeed/1/1?fields=@gd:etag
  
...data...

    השרת מגיב:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>

עדכון שדות ספציפיים (ניסיוני)

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

כדי להשתמש בעדכון חלקי, עליך לשלוח בקשת PATCH לאותו URI עריכה שבו השתמשת עם PUT. הנתונים ששולחים באמצעות PATCH צריכים לעמוד בתנאים מסוימים. אבל הסמנטיקה היא גמישה מספיק כדי לאפשר לכם להחליף נתונים במשאב היעד, להוסיף לה או אפילו למחוק ממנה את הכול, והכול בבקשה אחת.

הערה: כמו ב-PUT, יש לציין את ה-ETag של הערך המקורי, כדי לוודא שלא תעשו שינויים בשינויים של מישהו אחר.

מידע נוסף על PATCH ועל הסמנטיקה שלו זמין במאמר עדכון חלקי במסמך ההפניה לפרוטוקול.

בדוגמה הזו מוצגת בקשת עדכון חלקית שמשנה את הכותרת של הערך:

PATCH /myFeed/1/1/

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

כאשר השרת מקבל בקשת PATCH, הוא מסיר תחילה את כל השדות שצוינו באמצעות מאפיין הערך gd:fields (אם קיים), ולאחר מכן ממזג את הנתונים שסופקו בגוף הבקשה עם משאב היעד. בדוגמה הזו, רכיב הכותרת יוסר תחילה ממשאב היעד, ולאחר מכן הערך של הכותרת החדשה ימוזג. למעשה, הבקשה הזו מחליפה את הכותרת הישנה בכותרת החדשה.

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

  • אם השדה יכול להתקיים רק פעם אחת ברשומת היעד, בעת המיזוג, השדה בייצוג החלקי מחליף את השדה המתאים ברשומת היעד.
  • אם השדה יכול להתקיים יותר מפעם אחת ברשומת היעד, במיזוג, השדה החלקי מתווסף לרשומת היעד.

ההבדל בין שדות שחוזרים על עצמם לשדות שאינם חוזרים מוצג בדוגמה הבאה, המוסיפה כותרת ומחבר חדשים לרשומה מבלי להשתמש במאפיין gd:fields כדי להסיר אחד מהם תחילה.

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

מכיוון שהייצוג החלקי של המאפיין אינו כולל מאפיין gd:fields, לא יוסרו שדות. עם זאת, הערכים החדשים של הרכיבים <title> ושל <author> ימוזגו עם משאב היעד:

  • מאחר ש-Atom מאפשר רק כותרת אחת לכל רשומה, הכותרת החדשה תחליף את הערך הקיים. 
  • מאחר ש-Atom מאפשר מחברים מרובים לכל ערך, המחבר החדש מצורף לרשימת רכיבי המחבר שכבר נמצאים במשאב היעד.

    הערה: לא כל ממשקי ה-API תואמים לתקן Atom. לדוגמה, ממשקי API מסוימים מאפשרים שימוש רק ברכיב אחד <author> לכל רשומה, ואחרים יורשים את מחבר הרשומה מרמת הפיד, כך שהשדה מוגדר לקריאה בלבד.

לאחר שהשרת מעבד בקשת PATCH חוקית, הוא מחזיר קוד סטטוס HTTP 200, יחד עם עותק של הייצוג המלא של הרשומה המעודכנת.

אם אתם מעדיפים שהשרת יחזיר רק רכיבים או מאפיינים מסוימים, תוכלו להשתמש בפרמטר השאילתה fields עם PATCH כדי לבקש תגובה חלקית.

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

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

חזרה למעלה