הפניית פרוטוקול נתונים של Google Data APIs

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

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

Audience

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

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

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

  • להעריך את הארכיטקטורה של נתוני Google
  • תכנות באמצעות הפרוטוקול בלי להשתמש בספריות הלקוח שסופקו של Google Data
  • כתיבת ספריית לקוח בשפה חדשה

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

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

פרטי הפרוטוקול

בקטע הזה מתוארים הפורמט של מסמכים ב-Google Data ותחביר השאילתות.

פורמט המסמך

הנתונים של Google, של עדכון Atom ושל RSS 2.0 חולקים את אותו מודל נתונים בסיסי: מאגר שמכיל כמה נתונים גלובליים וכל מספר של ערכים. לכל פרוטוקול, הסכימה מוגדרת על ידי סכימה בסיסית, אבל אפשר להרחיב אותה באמצעות מרחבי שמות זרים.

ממשקי ה-API של נתוני Google יכולים להשתמש בפורמט ההפצה של Atom (לקריאה וכתיבה) או בפורמט RSS (לקריאה בלבד).

Atom הוא פורמט ברירת המחדל של נתוני Google. כדי לבקש תגובה בפורמט RSS, משתמשים בפרמטר /alt=rss/. מידע נוסף זמין במאמר בקשות לשאילתות.

כשמבקשים נתונים בפורמט RSS, מערכת Google Data מספקת פיד (או ייצוג אחר של המשאב) בפורמט RSS. אם אין נכס RSS מקביל לנכס נתון של נתוני Google, מערכת Google Data משתמשת בנכס Atom כדי להוסיף לו מרחב שמות מתאים, כדי לציין שמדובר בתוסף מסוג RSS.

הערה: רוב הפידים של נתוני Google בפורמט Atom משתמשים במרחב השמות של Atom כמרחב השמות המוגדר כברירת מחדל על ידי ציון מאפיין xmlns ברכיב הפיד. עיינו בדוגמאות לדוגמה לביצוע פעולה זו. לכן, הדוגמאות במסמך הזה לא מציינות באופן מפורש את atom: לרכיבים בפיד בפורמט Atom.

בטבלאות הבאות מוצגים הייצוגים של Atom ו-RSS של רכיבי הסכימה. כל הנתונים שאינם מוזכרים בטבלאות אלו נחשבים כ-XML פשוט, ומופיעים בשני הייצוגים. אם לא צוין אחרת, רכיבי ה-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 חושפים חלק מהרכיבים של OpenSearch 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:

פריט בסכימת כניסה ייצוג Atom ייצוג RSS
מזהה הרשומה /feed/entry/id /rss/channel/item/guid
מזהה גרסת רשומה ניתן להטמיע אותו ב-EditURI (אפשר לקרוא את הקטע החיוב בו-זמנית במסמך הזה). —
כותרת הרשומה /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"> אחד.)

 /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)

שאילתות

בקטע הזה מתואר איך להשתמש במערכת השאילתות.

עקרונות עיצוב של שאילתות

מודל השאילתה פשוט מאוד בכוונה. העקרונות הבסיסיים הם:

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

בקשות שאילתה

לקוח שולח שאילתה לשירות נתונים של Google על ידי הנפקת בקשת HTTP GET. ה-URI של השאילתה מורכב מה-URI של המשאב (המכונה FeedURI ב-Atom) ולאחר מכן פרמטרים של שאילתה. רוב הפרמטרים של שאילתות מיוצגים כפרמטרים רגילים של כתובת אתר ?name=value[&...]. פרמטרים של קטגוריות מטופלים באופן שונה. ראה בהמשך.

לדוגמה, אם ה-URI הוא http://www.example.com/feeds/jo, תוכל לשלוח שאילתה עם ה-URI הבא:

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

שירותי הנתונים של Google תומכים ב-HTTP Conditional GET. הן מגדירות את כותרת התגובה "השינוי האחרון" על סמך הערך של הרכיב <atom:updated> בפיד או בערך שהוחזרו. לקוח יכול לשלוח את הערך הזה חזרה כערך של כותרת הבקשה 'אם השתנה מאז' כדי למנוע אחזור של התוכן אם הוא לא השתנה. אם התוכן לא השתנה מאז 'אם השתנה מאז', שירות הנתונים של Google יחזיר תגובת 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.
  • החיפוש לא תלוי באותיות רישיות.
  • לדוגמה: כדי לחפש את כל הרשומות שמכילות את הביטוי המדויק "אליזבת בנט" והמילה "דארסי", אך לא מכילות את המילה "אוסטין", משתמשים בשאילתה הבאה: ?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 מחזירה ערכים שתואמים לשתי הקטגוריות.
  • כדי לבצע OR בין מונחים, צריך להשתמש בקו אנכי (|) בקידוד כתובת URL כמו %7C. לדוגמה: הפונקציה http://www.example.com/feeds/jo/-/Fritz%7CLaurie מחזירה ערכים שתואמים לכל אחת מהקטגוריות.
  • ערך תואם לקטגוריה מסוימת אם הרשומה נמצאת בקטגוריה עם מונח תואם או תווית תואמת, כפי שמוגדר במפרט של 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 מסנן קטגוריות
  • דרך חלופית לביצוע סינון לפי קטגוריות. שתי השיטות מקבילות.
  • כדי לבצע OR בין מונחים, צריך להשתמש בצינור (|), כתובת ה-URL מקודדת כ-%7C. לדוגמה: הפונקציה http://www.example.com/feeds?category=Fritz%7CLaurie מחזירה ערכים שתואמים לכל אחת מהקטגוריות.
  • כדי לבצע AND בין המונחים, צריך להשתמש בתו פסיק (,). לדוגמה: הפונקציה http://www.example.com/feeds?category=Fritz,Laurie מחזירה ערכים שתואמים לשתי הקטגוריות.
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 אינדקס מבוסס-תוצאה אחת של התוצאה הראשונה שאוחזרה
  • שימו לב: לא מדובר במנגנון סימון כללי. אם תשלחו בפעם הראשונה שאילתה עם ?start-index=1&max-results=10 ולאחר מכן תשלחו שאילתה נוספת עם ?start-index=11&max-results=10, השירות לא יכול להבטיח שהתוצאות מקבילות ל-?start-index=1&max-results=20, מפני שייתכן שהתבצעו כניסות ומחיקות בין שתי השאילתות.
max-results מספר התוצאות המקסימלי לאחזור לכל שירות עם ערך ברירת מחדל של max-results (כדי להגביל את גודל הפיד שמוגדר כברירת מחדל), אפשר לציין מספר גדול מאוד אם רוצים לקבל את הפיד כולו.
IDID המזהה של רשומה ספציפית לאחזור
  • אם מציינים מזהה רשומה, אי אפשר לציין פרמטרים אחרים.
  • הטופס של מזהה הרשומה נקבע על ידי שירות נתוני 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
האינדקס מבוסס-התוצאה של התוצאה הראשונה.
openSearch:itemsPerPage
המספר המקסימלי של פריטים שמופיעים בדף אחד. כך הלקוחות יכולים ליצור קישורים ישירים לכל קבוצה של דפים עוקבים. עם זאת, כדי שתהיה כמה שגיאות פחות נפוצות בשימוש במספר הזה, עליך לעיין בהערה לגבי start-index בטבלה שבקטע בקשות לשאילתות.

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

קוד הסבר
200 תקין אין שגיאה.
201 נוצרו יצירת המשאב הצליחה.
304 ללא שינוי המשאב לא השתנה מאז השעה שצוינה בכותרת 'אם השתנה מאז' של הבקשה.
בקשה פגומה 400 URI או כותרת לא חוקיים של בקשה, או פרמטר לא סטנדרטי לא נתמך.
401 לא מורשה דרוש אישור
403 FORBIDDEN פרמטר סטנדרטי לא נתמך, או שהאימות או ההרשאה נכשלו.
404 לא נמצא המשאב (למשל פיד או ערך) לא נמצא.
409 התנגשות מספר הגרסה שצוין לא תואם למספר הגרסה העדכני של המשאב.
שגיאה 500 בשרת פנימי שגיאה פנימית. זהו קוד ברירת המחדל שנעשה בו שימוש עבור כל השגיאות שאינן מזוהות.

בו-זמנית אופטימית (גרסה)

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

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

לא כל הפידים של נתוני Google תומכים בו-זמנית. בפיד שתומך בו, אם השרת יזהה התנגשות בין גרסאות ב-PUT או ב-DELETE, השרת יגיב באמצעות 409 Conflict. גוף התגובה מכיל את המצב הנוכחי של הרשומה (מסמך של רשומת Atom). ללקוח מומלץ לפתור את הבעיה ולהגיש מחדש את הבקשה, באמצעות ה-EditURI מהתגובה 409.

הערות לגבי המוטיבציה והעיצוב

הגישה שלנו בו-זמנית אופטימית מאפשרת לנו ליישם את הסמנטיקה שאנחנו רוצים בלי לדרוש סימון חדש למזהי גרסאות, וכך התגובות של נתוני Google תואמות לנקודות הקצה (endpoints) שאינן של Google Data.

במקום לציין מזהי גרסאות, יכול להיות שבחרנו לבדוק את חותמת הזמן של העדכון בכל רשומה (/atom:entry/atom:updated). עם זאת, יש שתי בעיות בשימוש בחותמת הזמן של העדכון:

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

אימות

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

הגישה שבה לקוח צריך להשתמש לאימות תלויה בסוג הלקוח:

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

אם האימות מצליח, מערכת האימות מחזירה אסימון שהלקוח משתמש בו לאחר מכן (בכותרת הרשאת HTTP) כאשר הוא שולח בקשות לנתוני Google.

אם האימות נכשל, השרת מחזיר קוד סטטוס 403 אסור, יחד עם כותרת WWW-Authenticate שמכילה אתגר הרלוונטי לאימות.

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

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

מצב הסשן

הטמעות רבות של לוגיקה עסקית דורשות דביקות בביקור – מעקב אחרי מצב הסשן של המשתמש.

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

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

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

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

חזרה למעלה