שאלות נפוצות

    סקירה כללית

  1. מה זה Google Data API?
  2. יש לי בקשה להוספת תכונה או דיווח על באג. איפה כדאי לפרסם?
  3. איפה כדאי לשאול שאלה לגבי API מסוים?
  4. מה זה JSON?
  5. האם צריך להשתמש ב-XML? האם יש פורמטים אחרים של נתונים?
  6. למה משתמשים ב-REST?
  7. יש לך טיפים או קוד לדוגמה קצר לבעיות נפוצות?
  8. האם ל-Gmail יש Data API?

    9. אימות

  9. מה שם השירות ב-ClientLogin לכל Data API?
  10. כשמשתמש מתנתק מאפליקציה, צריך ליידע את שרתי ה-API?
  11. האם לטוקן אימות של ClientLogin יש תאריך תפוגה?
  12. יש לי שאלה כללית לגבי חשבונות Google. לאן כדאי לי ללכת?
  13. איך מבצעים אימות ל-API?
  14. איזה ערך צריך להזין בפרמטר של היקף ההרשאות של AuthSub/OAuth 1?
  15. האם יש סוגים שונים של אסימוני AuthSub? Do the tokens expire?
  16. מה ההבדל העיקרי בין ClientLogin לבין AuthSub/OAuth 1?
  17. האם אפשר להשתמש באימות ClientLogin באפליקציות אינטרנט של צד שלישי?
  18. מה זה CAPTCHA?
  19. איך יוצרים אתגר CAPTCHA?
  20. האם כדאי להשתמש ב-ClientLogin באפליקציית האינטרנט שלי?
  21. איך אפשר לגלות את שם המשתמש כשמשתמשים ב-AuthSub או ב-OAuth 1?
  22. איך משתמשים ב-OAuth 1 עם ספריות הלקוח של Google Data API?
  23. איך משתמשים ב-AuthSub עם ספריות הלקוח של Google Data API?
  24. איך משתמשים ב-ClientLogin עם ספריות הלקוח של Google Data API?

    25. ספריות לקוח

  25. אילו שפות תכנות כוללות ספריות לקוח שנתמכות על ידי Google?
  26. איך מדווחים על באג או שולחים בקשה להוספת תכונה לאחת מהספריות של לקוח Google Data?
  27. איך מפעילים אפשרויות ניפוי באגים בספריות הלקוח?
  28. איפה אפשר למצוא מסמכי עזר לשיעורים בספריית הלקוח?

    29. פתרון בעיות

  29. אילו כלים מומלצים לניפוי באגים ב-HTTP?
  30. איך מקבלים מידע על רישום ביומן של HTTP בספריית הלקוח של Java?
  31. איך מקבלים מידע על רישום ביומן של HTTP בספריית הלקוח של ‎ .NET?
  32. איך אפשר להפעיל קידוד gzip מפידים של נתונים ב-Google?
  33. למה מופיעה השגיאה 'לא ניתן להתחבר ל-sslv2' כשאני משתמש בלקוח PHP?
  34. איך מקבלים את מסמך השירות של Atom שמתאר פיד?

סקירה כללית

מה זה Google Data API?

‫Google Data API הוא API שמבוסס על פרוטוקול Google Data. פרוטוקול Google Data מבוסס על פורמטי הסינדיקציה Atom 1.0 ו-RSS 2.0, וגם על פרוטוקול הפרסום Atom ‏ (APP).

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

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

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

‫JSON הוא ראשי תיבות של JavaScript Object Notation.

‫JSON הוא פורמט קל להחלפת נתונים, והפשטות שלו הובילה לשימוש נרחב בו בקרב מפתחי אתרים. קל לקרוא ולכתוב אותו, אפשר לנתח אותו באמצעות כל שפת תכנות, והמבנים שלו ממופים ישירות למבני נתונים שמשמשים ברוב שפות התכנות.

מידע נוסף על שימוש ב-JSON עם Google Data APIs

האם חובה להשתמש ב-XML? האם יש פורמטים אחרים של נתונים?
פורמט הנתונים שמוגדר כברירת מחדל ב-Google Data APIs הוא XML, בצורה של פיד Atom. עם זאת, כשמבקשים פיד אפשר לציין פורמט חלופי באמצעות פרמטר השאילתה alt.
  • alt=rss
    נתוני התגובה מעוצבים כפיד RSS.
  • ‫alt=json או alt=json-in-script
    מחזירה ייצוג JSON של מבנה ה-XML של פיד Atom. היתרון הנוסף של JSON הוא שקל יותר לבצע בו 'ניתוח' בקוד לקוח של JavaScript. בשלב הזה, השימוש ב-JSON זמין רק כאפשרות לקריאה בלבד. עם זאת, שימוש בספריית הלקוח של JavaScript עם השירותים Blogger,‏ Contacts או Calendar מאפשר גם קריאה וגם כתיבה של נתונים.

    מידע נוסף על בקשת פידים בפורמט JSON ושימוש בהם

  • alt=atom-in-script
    דומה ל-alt=json-in-script, אבל התוצאות מוחזרות כמחרוזת Atom XML ולא כמחרוזת JSON.
  • alt=rss-in-script
    בדומה ל-alt=atom-in-script, אבל התוצאות מוחזרות כמחרוזת XML של RSS ולא כ-Atom.

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

למה אתה משתמש ב-REST?
‫
REST הוא פשוט, קל משקל, ניתן להתאמה, ומתאים מאוד לייצוג ולחשיפה של נתונים.
יש לך טיפים או קוד לדוגמה קצר לבעיות נפוצות?
מומלץ לעיין בבלוג בנושא טיפים לשימוש ב-Google Data API כדי לקבל עזרה בנוגע לספריות הלקוח שלנו וליצירת בקשות גולמיות.
האם ל-Gmail יש Data API?

לא, אבל אפשר להשתמש בפיד Atom של Gmail עם AuthSub או OAuth 1 כדי לבקש גישה לקריאה בלבד להודעות שלא נקראו של משתמש. ההיקף צריך להיות https://mail.google.com/mail/feed/atom/. דוגמה לשאילתה:

GET https://mail.google.com/mail/feed/atom/

אם אתם רוצים לנהל את האימייל שלכם, Gmail תומך גם ב-IMAP/POP.

אימות

במסמכי התיעוד של Google Data APIs, המונח 'OAuth' מתייחס ל-OAuth 1. פרטים על OAuth 2.0 מופיעים במסמכי התיעוד של כל API בנפרד.

מה שם השירות ב-ClientLogin לכל Data API?
'שם שירות' הוא מחרוזת קצרה שמערכת האימות ClientLogin משתמשת בה כדי לזהות שירות של Google.
Google API שם השירות
ממשקי Google Analytics Data API analytics
ממשקי API של G Suite
(Domain Information & Management)		 apps
Google Sites Data API jotspot
Blogger Data API blogger
Book Search Data API print
Calendar Data API cl
Google Code Search Data API codesearch
Contacts Data API cp
Content API for Shopping structuredcontent
Documents List Data API writely
Finance Data API finance
עדכון Atom ב-Gmail mail
Health Data API health
weaver (ארגז חול H9)
Maps Data APIs local
Picasa Web Albums Data API lh2
Sidewiki Data API annotateweb
Spreadsheets Data API wise
Webmaster Tools API sitemaps
YouTube Data API youtube

מידע נוסף על הפרמטרים האחרים שמשמשים בבקשת ClientLogin זמין במאמר בנושא ClientLogin.

כשמשתמש מתנתק מאפליקציה, צריך לעדכן את שרתי ה-API?
לא, אין צורך להודיע ל-Google Data API כשמשתמש מתנתק מאפליקציה. עם זאת, אם האפליקציה שלכם כבר לא צריכה להשתמש באסימון AuthSub שהונפק, היא צריכה לבטל את האסימון.
האם לטוקן אימות של ClientLogin יש תאריך תפוגה?
אסימון ClientLogin יכול להיות בתוקף למשך שבועיים מתאריך ההנפקה, אבל המגבלה הזו היא ספציפית לשירות ויכולה להיות קצרה יותר.
יש לי שאלה כללית לגבי חשבונות Google. לאן כדאי לי ללכת?
אפשר להיכנס אל מרכז העזרה של חשבונות Google.
איך מבצעים אימות ל-API?
בקשת ה-HTTP צריכה לכלול כותרת Authorization שמכילה טוקן שהתקבל באמצעות ClientLogin,‏ AuthSub או OAuth 1.
איזה ערך צריך להזין לפרמטר ההיקף של AuthSub/OAuth 1?
פרמטר scope נדרש על ידי AuthSub ו-OAuth 1 כדי לזהות לאילו שירותי Google תהיה לאפליקציה שלכם גישה. פרטים על OAuth 2.0 מופיעים במסמכי העזרה של ה-API הספציפי.

Google API שם השירות ClientLogin
Data API ל-Google Analytics https://www.google.com/analytics/feeds/
Google Sites Data API http(s)://sites.google.com/feeds/
Blogger Data API http://www.blogger.com/feeds/
Book Search Data API http://www.google.com/books/feeds/
Calendar Data API http(s)://www.google.com/calendar/feeds/
Contacts Data API http(s)://www.google.com/m8/feeds/
Content API for Shopping https://www.googleapis.com/auth/structuredcontent
Documents List Data API http(s)://docs.google.com/feeds/
Finance Data API http://finance.google.com/finance/feeds/
עדכון Atom ב-Gmail https://mail.google.com/mail/feed/atom/
Health Data API https://www.google.com/health/feeds/
https://www.google.com/h9/feeds/ (ארגז חול H9)
Maps Data API http://maps.google.com/maps/feeds/
Picasa Web Albums Data API http://picasaweb.google.com/data/
Portable Contacts API http://www-opensocial.googleusercontent.com/api/people
Sidewiki Data API http://www.google.com/sidewiki/feeds/
Spreadsheets Data API http(s)://spreadsheets.google.com/feeds/
Webmaster Tools API http://www.google.com/webmasters/tools/feeds/
YouTube Data API http://gdata.youtube.com
האם יש סוגים שונים של אסימוני AuthSub? האם יש תוקף לטוקנים?
יש שני סוגים של טוקנים של AuthSub. האסימון הראשון הוא אסימון לשימוש חד-פעמי שמוצג לאפליקציית האינטרנט באמצעות פרמטר השאילתה token. התוקף של הטוקן הזה יפוג בפעם הראשונה שמשתמשים בו בשירות שאליו הוא הונפק, או כשהוא מוחלף בטוקן סשן.

התוקף של אסימוני סשן לא פג אלא אם האסימון בוטל באופן מפורש על ידי המשתמש או על ידי קריאה ל-API‏ AuthSubRevokeToken. אפשר להמיר טוקן לשימוש חד-פעמי לטוקן סשן רק אם כתובת ה-URL המקורית של AuthSubRequest צוינה כפרמטר שאילתה session=1.
מה ההבדל העיקרי בין ClientLogin לבין AuthSub/OAuth 1?

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

‫ClientLogin מיועד לאפליקציות מותקנות למחשב. היא מחייבת את האפליקציה השולחת להעביר ל-Google את פרטי הכניסה של המשתמש בשמו.

מידע נוסף זמין במאמרי העזרה בנושא Google Account Authentication API.

האם אפשר להשתמש באימות ClientLogin באפליקציות אינטרנט של צד שלישי?
מותר להשתמש ב-ClientLogin באפליקציות אינטרנט של צד שלישי, אבל לא מומלץ לעשות זאת. מומלץ שאפליקציית האינטרנט אף פעם לא תבקש מהמשתמש את פרטי הכניסה שלו (היא עלולה להיות פגיעה לריחרוח). במקום זאת, האפליקציה צריכה לאחסן את פרטי הכניסה של המשתמש בצד השרת, ולהשתמש בחשבון שירות יחיד לצורך אימות ב-Google.
מה זה CAPTCHA?
CAPTCHA (מבחן טיורינג ציבורי אוטומטי לחלוטין להבחנה בין מחשבים לבני אדם) הוא סוג של מבחן אתגר-תגובה שמשמש כדי לקבוע אם המשתמש הוא אדם. המונח הוא סימן מסחרי של אוניברסיטת קרנגי מלון. פרטים נוספים זמינים בויקיפדיה. הטמענו CAPTCHA ב-ClientLogin.
איך יוצרים אתגר CAPTCHA?
אלגוריתם קנייני משמש לקביעה מתי נדרש אתגר CAPTCHA במהלך האימות. ניסיונות חוזרים לאימות עם פרטי כניסה שגויים לרוב יובילו לאתגר CAPTCHA.
האם כדאי להשתמש ב-ClientLogin באפליקציית האינטרנט שלי?
לא, צריך להשתמש ב-ClientLogin באפליקציות מותקנות בחומרה שבבעלות המשתמש. השימוש ב-ClientLogin API באפליקציות אינטרנט לא מאובטח, ואנחנו ממליצים להימנע ממנו.
איך אפשר לגלות את שם המשתמש של המשתמש כשמשתמשים ב-AuthSub/OAuth 1?
מכיוון שאתם מקבלים מ-Google רק טוקן שמעניק גישה לעדכונים של המשתמש, יכול להיות שאתם לא יודעים מה שם המשתמש שלו. זה יכול להיות בעייתי אם כתובת ה-URL של העדכון שבה אתם רוצים להשתמש כוללת את שם המשתמש כחלק ממנה. במקרה כזה, אפשר להשתמש בשם המשתמש המיוחד default כדי לציין "המשתמש שאני משתמש באסימון האימות שלו".
איך משתמשים ב-OAuth 1 עם ספריות הלקוח של Google Data API?
אפשר לעיין במאמר שימוש ב-OAuth 1 עם ספריות הלקוח של Google Data API.
איך משתמשים ב-AuthSub עם ספריות הלקוח של Google Data API?
אפשר לעיין במאמר שימוש ב-AuthSub עם ספריות הלקוח של Google Data API.
איך משתמשים ב-ClientLogin עם ספריות הלקוח של Google Data API?
אפשר לעיין במאמר שימוש ב-ClientLogin עם ספריות הלקוח של Google Data API.

ספריות לקוח

אילו שפות תכנות נתמכות בספריות לקוח של Google?

ספריות הלקוח של Java, ‏ ‎.NET, ‏ Python ו-Objective-C נתמכות רשמית על ידי Google. בנוסף, השותף שלנו Zend כתב ספריית לקוח PHP. באמצעות הספריות האלה, אפשר ליצור בקשות של פרוטוקול Google Data, לשלוח אותן לשירות ולעבד את התגובות של השרת. יש גם ספריית לקוח של JavaScript שתומכת כרגע רק ב-Blogger, ביומן Google ובאנשי הקשר של Google.

אם אתם כותבים ספריית לקוח בשפה שאינה Java,‏ ‎.Net, ‏ Python או Objective-C, ואתם רוצים לשתף אותה עם קהילת המפתחים של Data API, אתם יכולים לפרסם אותה בקבוצת הדיון של Google Data APIs. נשמח לשמוע ממך.

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

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

אחרי שפרסמתם את הבאג, צרו שרשור בפורום המפתחים של ה-API המתאים.

איך מפעילים אפשרויות ניפוי באגים בספריות הלקוח של Google Data API?
במאמר הבא מוסבר איך להפעיל ניפוי באגים באמצעות חלק מספריות הלקוח: ניפוי באגים בלקוחות של Google Data API: בדיקת התנועה מתוך התוכנית
איפה אפשר למצוא מסמכי עזר לגבי מחלקות בספריית הלקוח?
ספריית לקוח מדריך עזר
Java Javadoc
JavaScript JSdoc
‎.NET NDoc
PHP phpDoc
Python PyDoc

פתרון בעיות

אילו כלים טובים יש לניפוי באגים ב-HTTP?

בהמשך מפורטים כמה כלים, אבל כדאי גם לקרוא את המאמר On the Wire: Network Capture Tools for API Developers שמתאר לעומק דוגמאות לשימוש ב-WireShark וב-Fiddler.

Wireshark
‫
Wireshark הוא כלי לניתוח פרוטוקולי רשת. הוא מאפשר לכם לתעד את התנועה ברשת ולנתח את התוכן. הוא שימושי מאוד לניפוי באגים בתנועה בספריות שאין לכם גישה ישירה לזרמי הבקשות והתגובות של HTTP. אי אפשר לנתח את תעבורת הנתונים בין האפליקציה לבין שירותי האימות באמצעות Wireshark, כי התקשורת מוצפנת באמצעות SSL. אפשר להשתמש ב-Wireshark גם כדי לנתח תנועה שנתפסה באמצעות כלים כמו tcpdump. התוכנה Wireshark זמינה מהמפתחים גם כקוד מקור וגם כקובץ התקנה ל-Windows. חבילות של צד שלישי זמינות להרבה פלטפורמות.
Fiddler
‫
Fiddler הוא "כלי Proxy לניפוי באגים ב-HTTP". אם אתם יכולים להגדיר את הקוד או את סביבת זמן הריצה כך שישתמשו בשרת proxy לתנועת HTTP,‏ Fiddler ימוקם בין האפליקציה לבין שירותי הנתונים של Google, ויאפשר לכם לבדוק את התנועה. ‫Fiddler 2 כולל תמיכה ב-SSL. Fiddler זמין כרגע רק ל-Windows.
cURL
‫
cURL הוא כלי לשורת הפקודה שיכול לבצע בקשות HTTP/HTTPS. היא שימושית מאוד לבדיקה מהירה של אינטראקציות עם שירות בלי לבנות קודם תמיכה ב-HTTP בלקוח.
איך מקבלים מידע על רישום ביומן של HTTP בספריית הלקוח של Java?

ספריות הלקוח של Java משתמשות בחבילה java.util.logging כדי לאפשר רישום ביומן של בקשות HTTP. כך תוכלו להפעיל רישום ביומן של כותרות לבקשות ולתגובות, וגם של קודי סטטוס וכתובות URL של בקשות. בשלב הזה, המערכת לא רושמת ביומן את הזרמים המלאים של הבקשות והתגובות. השם של הכלי לרישום ביומן שמשמש ליומנים האלה הוא com.google.gdata.client.http.HttpGDataRequest.

אם קוד שגיאה מוחזר מהשרתים, נוצרת חריגה. מחלקות החריגים עוברות בירושה מ-com.google.gdata.util.ServiceException וכוללות שיטה ציבורית בשם getResponseBody(). מידע נוסף זמין ב-Javadoc.

איך מקבלים מידע מרישום ביומן של HTTP בספריית הלקוח של ‎ .NET?
ספריית ‎ .NET משתמשת בשיטות המעקב System.Diagnostics כדי לרשום ביומן את נתיב הביצוע, אם המעקב מופעל. בנוסף, במקרה של שגיאה, מופעלת חריגה (exception) מסוג GDataRequestException. החריגה מכילה ResponseString שמאפשר לכם לגשת לגוף של תגובת ה-HTTP.
איך אפשר להפעיל קידוד gzip מפידים של נתונים ב-Google?

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

User-Agent: my program (gzip)
Accept-Encoding: gzip
למה מופיעה השגיאה "לא ניתן להתחבר ל-sslv2" כשמשתמשים בלקוח PHP?

החל מיולי 2009, התחלנו להשבית את SSLv2 בשרתים שלנו כאמצעי זהירות לשיפור האבטחה. לצערנו, יש באג בגרסאות מוקדמות של ספריית הלקוח של PHP שפורסמו לפני יולי 2007 (גרסה 1.0.0 וגרסאות קודמות), שמכריח חיבורים להשתמש ב-SSLv2. כשמתחברים לשרת שבו SSLv2 מושבת, מופיעה השגיאה הבאה:

PHP Fatal error:  Uncaught exception 'Zend_Http_Client_Adapter_Exception' with message 'Unable to Connect to sslv2://www.google.com:443.'

כדי לתקן את השגיאה הזו, צריך לשדרג לגרסה חדשה יותר של ספריית הלקוח של PHP, שזמינה בכתובת http://framework.zend.com/download.

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

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));
איך מקבלים את מסמך השירות של Atom שמתאר פיד?

אפשר לקבל את מסמך השירות של Atom על ידי העברת הפרמטר alt=atom-service בבקשה. הערה: רק גרסה 2 של Google Data APIs תחזיר מסמך שירות שתואם לתחביר של מסמך השירות של AtomPub. גרסה 1 של Google Data APIs עדיין תחזיר מסמך שירות, אבל הוא מבוסס על טיוטה מוקדמת יותר של מפרט AtomPub (יש שינויים בתחביר ובמרחב השמות בין שתי הגרסאות).