שאלות נפוצות

סקירה כללית

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

אימות

9. מהו שם השירות ב-ClientLogin לכל Data API?
10. כשמשתמש מתנתק מאפליקציה, האם צריך להודיע על כך לשרתי ה-API?
11. האם פג התוקף של אסימון האימות של ClientLogin?
12. יש לי שאלה כללית בנוגע לחשבונות Google. איפה כדאי לבקר?
13. איך מבצעים אימות ל-API?
14. באיזה ערך צריך להשתמש בשביל הפרמטר AuthSub/OAuth 1 ?
15. האם יש סוגים שונים של אסימוני AuthSub? האם התוקף של האסימונים פג?
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. באילו שפות תכנות נתמכות ספריות לקוח של Google?
26. איך מדווחים על באג או על בקשה לתכונה של אחת מספריות הלקוח של Google Data?
27. איך מפעילים את האפשרויות לניפוי באגים בספריות הלקוח?
28. איפה ניתן למצוא מסמכי עזר לכיתות של ספריית הלקוח?

פתרון בעיות

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

---

סקירה כללית

מהו Google Data API?

ממשק API של Google Data הוא ממשק API שמבוסס על פרוטוקול הנתונים של Google. הפרוטוקול של Google Data מבוסס על הפורמטים Atom 1.0 ו-RSS 2.0, בנוסף ל-Atom Publishing Protocol (APP).

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

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

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

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

איפה שואלים שאלה ב-API מסוים?

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

• G Suite (הצגת ממשקי API נפרדים בתוך משפחת G Suite)
• Base
• Blogger
• יומן
• חיפוש קוד
• אנשי קשר
• Google Sites
• גיליונות אלקטרוניים
• רשימת מסמכים
• איחוד / OpenID
• פיננסים
• קופת
• Google Photos
• כלי מנהלי האתרים
• YouTube

מהו JSON?

JSON מתייחס ל-JavaScript Object Notation.

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

מידע נוסף על שימוש ב-JSON עם Google Data 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, אנשי קשר או יומן מאפשר קריאה וכתיבה של נתונים.

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

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

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

למה בחרת להשתמש ב-REST?

REST הוא מודל פשוט, קליל וניתן להתאמה וממפה טוב מאוד לייצוג ולחשיפת נתונים.

האם יש לך טיפים או קוד לדוגמה קצר לבעיות נפוצות?

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

האם ל-Gmail יש ממשק 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	שם השירות
ממשקי API לניתוח נתונים של Google Analytics	analytics
ממשקי API של G Suite (מידע וניהול דומיין)	apps
ממשק API לשילוב נתונים של Google Sites	jotspot
ממשק API של Blogger Data	blogger
ממשק API לשילוב נתונים של Book Search	print
ממשק API לנתוני יומן	cl
ממשק API לנתוני חיפוש של Google Code	codesearch
ממשק API לנתוני אנשי קשר	cp
Content API for Shopping	structuredcontent
ממשק API לנתוני מסמכים	writely
Finance Data API	finance
פיד Atom של Gmail	mail
ממשק ה-API של Health Data	health weaver (ארגז חול של H9)
ממשקי API של מפות Google לנתונים	local
ממשק API של אלבומי Google	lh2
ממשק API לשילוב נתונים של SAML	annotateweb
ממשק API לשילוב נתונים של גיליונות אלקטרוניים	wise
ממשק API של כלי מנהלי האתרים	sitemaps
YouTube Data API	youtube

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

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

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

האם לקוד האימות של ClientLogin יש תאריך תפוגה?

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

יש לי שאלה כללית לגבי חשבונות Google. איפה כדאי לבקר?

כניסה למרכז העזרה של חשבונות Google.

איך מבצעים אימות ל-API?

בקשת ה-HTTP שלך חייבת לכלול כותרת הרשאה שמכילה אסימון שהתקבל באמצעות 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/
ממשק API לשילוב נתונים של Google Sites	http(s)://sites.google.com/feeds/
ממשק API של Blogger Data	http://www.blogger.com/feeds/
ממשק API לשילוב נתונים של Book Search	http://www.google.com/books/feeds/
ממשק API לנתוני יומן	http(s)://www.google.com/calendar/feeds/
ממשק API לנתוני אנשי קשר	http(s)://www.google.com/m8/feeds/
Content API for Shopping	https://www.googleapis.com/auth/structuredcontent
ממשק 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/
ממשק ה-API של Health Data	https://www.google.com/health/feeds/ https://www.google.com/h9/feeds/ (ארגז חול של H9)
API לנתוני מפות	http://maps.google.com/maps/feeds/
ממשק API של אלבומי Google	http://picasaweb.google.com/data/
ממשק API של אנשי קשר ניידים	http://www-opensocial.googleusercontent.com/api/people
ממשק API לשילוב נתונים של SAML	http://www.google.com/sidewiki/feeds/
ממשק API לשילוב נתונים של גיליונות אלקטרוניים	http(s)://spreadsheets.google.com/feeds/
ממשק 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 Authentication API.

האם אפשר להשתמש באימות ClientLogin באפליקציות אינטרנט של צד שלישי?

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

מה זה CAPTCHA?

CAPTCHA הוא ניסוי בדיקה אוטומטי לחלוטין שמטרתו לזהות מחשבים ואנשים? הוא סוג של בדיקת אתגר שנועדה לקבוע אם המשתמש הוא אנושי. המונח נחשב כסימן מסחרי על ידי אוניברסיטת קרנגי מלון. פרטים נוספים זמינים בוויקיפדיה. הטמענו CAPTCHA ב-ClientLogin.

איך יוצרים אתגר CAPTCHA?

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

האם כדאי להשתמש ב-ClientLogin באפליקציית האינטרנט שלי?

לא, צריך להשתמש ב-ClientLogin על ידי אפליקציות מותקנות בחומרה בבעלות משתמש. השימוש ב-ClientLogin API ביישומי אינטרנט אינו מאובטח ומומלץ שלא להשתמש בו.

איך אפשר למצוא את שם המשתמש של המשתמש באמצעות AuthSub/OAuth 1?

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

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

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

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

• Java
• JavaScript
• .NET
• PHP
• Python
• מטרה C

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

איך מפעילים את האפשרויות לניפוי באגים בספריות הלקוח ב-Google Data API?

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

איפה אפשר למצוא מסמכי עזר לכיתות של ספריית הלקוח?

ספריית לקוח	מדריך עזר
Java	Javadoc
JavaScript	JSdoc
‎.NET	מסמך ללא שם
PHP	phpDoc
Python	PyDoc

---

פתרון בעיות

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

בהמשך מופיעים מספר כלים, אבל כדאי גם לקרוא את המאמר ב-Wire: Network Camera כלים ל-API למפתחים, שכולל דוגמאות מעמיקות של WireShark ו-Fiddler.

Wireshark

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

ה ההצעות

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

איך מפעילים קידוד gzip מפידים של נתוני Google?

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