דף זה תורגם על ידי Cloud Translation API.

מספר הפרוטוקול

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

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

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

Audience

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

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

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

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

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

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

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

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

פורמט המסמך

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

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

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

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

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

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

בטבלה הבאה מוצגים הרכיבים של פיד של Google Data Protocol:

פריט בסכימת פיד	ייצוג 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. שימו לב שבפרוטוקול מופיעים חלק מהרכיבים של OpenSearch 1.1 בפידים של תוצאות חיפוש.

פריט של סכימת פיד של תוצאת חיפוש	ייצוג Atom
מספר תוצאות החיפוש	`/feed/openSearch:totalResults`
אינדקס התחלה של תוצאות חיפוש	`/feed/openSearch:startIndex`
מספר תוצאות החיפוש לכל דף	`/feed/openSearch:itemsPerPage`

הטבלה הבאה מציגה את הרכיבים של ערך Google Data Protocol:

פריט בסכימת כניסה	ייצוג Atom
מזהה הרשומה	`/feed/entry/id`
כותרת הרשומה	`/feed/entry/title`
קישור כניסה	`/feed/entry/link`
סיכום רשומה	`/feed/entry/summary` (חובה במקרים מסוימים, כדאי לעיין במפרט של Atom.)
תוכן הרשומה	`/feed/entry/content` (אם אין תוכן, הערך חייב להכיל לפחות רכיב `<link rel="alternate">` אחד.)
מחבר הרשומה	`/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)

שאילתות

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

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

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

השאילתות מבוטאות כ-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. ממשקי API שמטמיעים את הפרוטוקול מגדירים את כותרת התגובה 'שינוי אחרון' על סמך הערך של הרכיב <atom:updated> בפיד או בערך המוחזר. לקוח יכול לשלוח את הערך הזה חזרה כערך של כותרת הבקשה 'אם השתנה מאז' כדי למנוע אחזור של התוכן אם הוא לא השתנה. אם התוכן לא השתנה מאז, אם הוא השתנה מאז, השירות יחזיר תגובת 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`	מסנן שאילתות לקטגוריה	דרך חלופית לביצוע סינון לפי קטגוריות. שתי השיטות מקבילות. כדי לבצע `OR` בין מונחים, צריך להשתמש בצינור (\|), כתובת ה-URL מקודדת כ-`%7C`. לדוגמה: הפונקציה `http://www.example.com/feeds?category=Fritz%7CLaurie` מחזירה ערכים שתואמים לכל אחת מהקטגוריות. כדי לבצע `AND` בין המונחים, צריך להשתמש בתו פסיק (,). לדוגמה: הפונקציה `http://www.example.com/feeds?category=Fritz,Laurie` מחזירה ערכים שתואמים לשתי הקטגוריות.
`/-/category`	מסנן שאילתות לקטגוריה	יש לציין כל קטגוריה כאילו היא חלק מה-URI של המשאב, בפורמט `/categoryname/` – חריגה זו מהטופס הרגיל של `name=value`. יש לרשום את כל הקטגוריות לפני פרמטרים אחרים של שאילתה. אפשר להקדים את הקטגוריה הראשונה עם `/-/` כדי להבהיר שמדובר בקטגוריה. לדוגמה, אם הפיד של יוסי כולל קטגוריה לרשומות בנושא 'פריץ', תוכלו לבקש את הערכים האלה: `http://www.example.com/feeds/jo/-/Fritz`. כך ניתן להשתמש בהבחנה בין URIי שאילתה בקטגוריות ספציפיות למזהי URI של משאבים. אפשר ליצור שאילתה לגבי כמה קטגוריות על ידי ציון מספר פרמטרים של קטגוריות, מופרדים על ידי קווים נטויים. השירות מחזיר את כל הערכים שתואמים לכל הקטגוריות (למשל, שימוש ב-`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)`.
IDID	המזהה של רשומה ספציפית לאחזור	אם מציינים מזהה רשומה, אי אפשר לציין פרמטרים אחרים. הצורה של מזהה הרשומה נקבעת על ידי השירות. בניגוד לרוב הפרמטרים האחרים של שאילתות, מזהה הרשומה מצוין כחלק מה-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`. החיפוש לא תלוי באותיות רישיות. לדוגמה: כדי לחפש את כל הרשומות שמכילות את הביטוי המדויק "אליזבת בנט" והמילה "דארסי", אך לא מכילות את המילה "אוסטין", משתמשים בשאילתה הבאה: `?q="Elizabeth Bennet" Darcy -Austen`
`start-index`	אינדקס מבוסס-תוצאה אחת של התוצאה הראשונה שאוחזרה	שימו לב: לא מדובר במנגנון סימון כללי. אם תשלחו בפעם הראשונה שאילתה עם `?start-index=1&max-results=10` ולאחר מכן תשלחו שאילתה נוספת עם `?start-index=11&max-results=10`, השירות לא יכול להבטיח שהתוצאות מקבילות ל-`?start-index=1&max-results=20`, מפני שייתכן שהתבצעו כניסות ומחיקות בין שתי השאילתות.
`strict`	בדיקה קפדנית של פרמטרים של שאילתה	מגדירים את `strict=true` כדי לוודא שכל הפרמטרים של השאילתה מזוהים על ידי השירות. אם הפרמטר לא מזוהה, מוצגת הודעת שגיאה. ברירת מחדל: `strict=false`
`updated-min`, `updated-max`	גבולות בתאריך העדכון של הרשומה	צריך להשתמש בחותמת הזמן RFC 3339 לדוגמה: `2005-08-09T10:57:00-08:00`. הגבול התחתון כולל את הגבול התחתון, והגבול העליון בלעדי. במקרים מסוימים (למשל, כשמשתמשים בגרסה 2.1 או בגרסה חדשה יותר של ה-API של יומן הנתונים), ציון `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: האינדקס מבוסס-התוצאה של התוצאה הראשונה.
openSearch:itemsPerPage: המספר המקסימלי של פריטים שמופיעים בדף אחד. כך הלקוחות יכולים ליצור קישורים ישירים לכל קבוצה של דפים עוקבים. עם זאת, כדי שתהיה כמה שגיאות פחות נפוצות בשימוש במספר הזה, עליך לעיין בהערה לגבי start-index בטבלה שבקטע בקשות לשאילתות.

פיד התגובות ופיד Atom של 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 של הגוש הבא של קבוצת תוצאות השאילתה הזו, אם היא מחולקת.
<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>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 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>liz@gmail.com</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>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 בהקשר של ממשקי API של נתונים.

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

ניהול גרסאות של משאבים (ETags)

לפעמים נדרשת יכולת להפנות לגרסה ספציפית של רשומה מסוימת.

זה חשוב במיוחד בשני מקרים:

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

שני ממשקי ה-API של הנתונים של Google מטפלים בשני המקרים האלה באמצעות ETags, שהם חלקים רגילים של HTTP.

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

ממשקי ה-API של נתוני Google מספקים ETags בשני מקומות: בכותרת HTTP מסוג ETag, ובמאפיין gd:etag של הרכיבים <feed> ו-<entry>.

בממשקי API של Google Data, ETag הוא בדרך כלל מחרוזת של אותיות ומספרים, ולפעמים כולל גם מקפים ונקודות. המחרוזת מוקפת בדרך כלל במירכאות. (המירכאות הן חלק מ-ETag). למשל, זה ETag מרשומת Data API: "S0wCTlpIIip7ImA0X0QI".

יש שני סוגים של תגים אלקטרוניים: חזקים וחלש. תגי Estrong חזקים מזהים גרסה ספציפית של ערך ספציפי, וניתן להשתמש בהם כדי למנוע שינויים של לקוחות אחרים. ETags חלשים, בהקשר של Google Data APIs, משמשים לאחזור מותנה בלבד. ETag חלש תמיד מתחיל ב-W/. לדוגמה: W/"D08FQn8-eil7ImA9WxZbFEw."

לא כל Google Data APIs תומך ב-ETags חזקים. לתגים האלה, ה-ETags החזקים משמשים רק לרשומות. ETags בפידים תמיד חלשים.

הנה דוגמה לעדכון (כולל חלק מכותרות ה-HTTP) שאוחזר משירות שתומך ב-ETags חזקים:

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>

ספריות הלקוח שתומכות בגרסה 2 של Data API מטפלות עבורכם ב-ETags בשקיפות. המידע הבא מיועד ללקוחות שאינם משתמשים בספריות לקוח, ולקוראים המעוניינים באופן שבו הגרסאות מנוהלות ברמת הפרוטוקול.

הערה: מידע על המערכת להמרת משאבים שבה נעשה שימוש בגרסה 1.0 של ממשקי API של נתונים זמין במאמר מדריך עזר 1.0.

אחזור מותנה

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

כדי לבצע אחזור מותנה כזה, יש לשלוח בקשת HTTP GET שכוללת כותרת HTTP If-None-Match. בכותרת מציינים את ה-ETag של הערך.

דוגמה לכותרת של If-None-Match:

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

כאשר השרת מקבל את הבקשה הזו, הוא בודק אם הערך שביקשתם ב-ETag זהה ל-ETag שציינתם. אם ה-ETags תואמים, הערך לא השתנה והשרת מחזיר קוד מצב HTTP 304 Not Modified.

אם ה-ETags לא תואמים, הערך השתנה מאז הפעם האחרונה שביקשתם אותו, והשרת מחזיר את הערך.

מתבצע עדכון של הרשומות

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

כאשר הלקוח מאחזר נתונים משירות שתומך ב-ETags חזקים, לכל רשומה יש ETag שמשמש כמזהה הגרסה הייחודית של הגרסה הזו של הרשומה.

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

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

צריך להשתמש בכותרת HTTP If-Match.
אפשר להשתמש במאפיין gd:etag ברכיב <atom:entry>.

אנחנו ממליצים להשתמש בגישה If-Match כאשר הדבר אפשרי.

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

לפני שליחת 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 בכותרת.

לקבלת מידע על השירותים התומכים ב-ETags חזקים, כדאי לעיין במדריך ההעברה.

מחיקת רשומות

מחיקת רשומות שמשתמשות ב-ETags חזקים דומה מאוד לעדכון שלהן.

כדי למחוק רשומה בעלת ETag חזק, קודם צריך לאחזר את הרשומה שברצונך למחוק, ואז לשלוח בקשת DELETE לכתובת ה-URL של עריכת הרשומה.

אם ברצונך לוודא שלא מחקת רשומה ששונתה על ידי לקוח אחר מאז אחזורה, יש לכלול כותרת HTTP מסוג If-Match שמכילה את ערך ה-ETag של הערך המקורי.

אם רוצים לבטל את מערכת הגרסאות ולמחוק את הרשומה בלי קשר שמישהו אחר עדכן אותה מאז שאחזרתם אותה, יש להשתמש ב-If-Match: * במקום לציין את ה-ETag בכותרת.

אם ברשומה אין תג ETag חזק, בקשת DELETE תמיד תצליח.

תגובה חלקית (ניסיוני)

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

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

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

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

תגובת השרת מכילה רק רכיבי קישור ורשומה עבור הפיד. רכיבי הרשומה מכילים רק ETag, מזהה, עדכון ועריכה של פרטי קישור. התחביר של פרמטר השאילתה 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` של רשומת היעד.

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

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

דוגמאות	השפעה
`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>` בכל רשומה בפיד.

מידע נוסף על התחביר של תנאי השדה

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

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

בטבלה הבאה מוצגים האופרטורים של 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]`
השוואת תאריכים	להשתמש באופרטורים של השוואה מספרית, כפי שמתואר בדוגמאות.	כדי להשוות בין תאריכים או תאריכים/שעות, אפשר להעביר (cast) רכיבים, מאפיינים או מחרוזות של מחרוזת לתוך `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()`	מדדים בוליאניים יכולים להיות שימושיים במהלך בדיקה, כדי לאכוף תנאי שדה למצב true או false. הפונקציה מחזירה רכיבים של `<link>`: `link[true()]`

טיפול בתגובות חלקיות

לאחר ששרת שתומך בתגובה חלקית מעבד בקשה חוקית שכוללת את פרמטר השאילתה fields, הוא שולח חזרה קוד סטטוס HTTP 200 OK יחד עם המאפיינים או הרכיבים הנדרשים. אם פרמטר השאילתה fields מכיל שגיאה או שהוא לא חוקי מסיבה אחרת, השרת מחזיר קוד סטטוס HTTP 400 Bad Request.

רכיב הבסיס של התגובה הוא <feed> או <entry>, בהתאם ל-URI היעד. התוכן של רכיב הבסיס כולל רק את השדות שנבחרו של אותו פיד או של רשומה, לצד תגי הסוגריים של רכיבי ההורה.

ניתן לחזור ולהחזיר את הערך של fields פרמטר השאילתה של הבקשה בשתי דרכים:

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

סימון חלופי כשאין תמיכה ב-PATCH

אם חומת האש שלך לא מאפשרת את 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='liz@gmail.com'/>
  <gd:who email='jo@gmail.com'/>
  <gd:who email='jane@gmail.com'/>
</entry>

נניח שברצונך להסיר את המשתמש בעל כתובת האימייל 'jane@gmail.com', להוסיף משתמש עם כתובת האימייל 'will@gmail.com', ולשנות את כתובת האימייל של המשתמש הרשום כרגע כ'jo@gmail.com' לכתובת 'josy@gmail.com'.

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

מחיקת <gd:who email='jane'/> מרשימת הרכיבים שסיפקת.
מוסיפים את <gd:who email='will@gmail.com'/> לרשימת הרכיבים שצוינה.
מחליפים את <gd:who email='jo@gmail.com'/> ב-<gd:who email='josy@gmail.com'/>.

הבקשה 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='liz@gmail.com'/>
  <gd:who email='josy@gmail.com'/>
  <gd:who email='will@gmail.com'/>
</entry>

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

אימות

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

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

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

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

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

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

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

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

מצב הסשן

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

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

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

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

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

השוואה בין עדכוני Atom ו-RSS
סקירה כללית של Atom מ-IBM
תוספי Dublin Core ל-RSS
הגדרות שיטה מסוג HTTP 1.1; מפרט עבור GET, POST, PUT, ו-DELETE
הגדרות קוד הסטטוס של HTTP 1.1
איך יוצרים פרוטוקול REST
בניית שירותי אינטרנט בשיטת REST
מבוא טכני ל-XML
מרחבי XML לפי דוגמה
קטע ETag במפרט ה-HTTP

חזרה למעלה