סקירה כללית של המדריך למפתחים

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

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

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

Audience

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

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

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

רקע

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

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

אם כותבים קוד שמשתמש ישירות ב-Google Data Protocol, הוא ניגש ל-API באמצעות בקשות HTTP כמו GET או POST. באמצעות בקשות אלה, נתונים המאוחסנים על ידי מוצר Google מועברים הלוך וחזור באמצעות חוט בצורה של עדכוני נתונים. עדכוני הנתונים הם פשוט רשימות מובנות המכילות את הנתונים. בעבר, הפורמט של הפיד הראשי היה AtomPub XML, אבל עכשיו הוא JSON, או JavaScript Object Notation, והוא זמין גם כפורמט חלופי.

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

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

גרסאות הפרוטוקול

גרסה 2.0 לעומת גרסה 1.0

הגרסה הראשונה של פרוטוקול הנתונים של Google פותחה לפני השלמת הפרוטוקול של Atom Publishing Protocol. הגרסה השנייה של Google Data Protocol תואמת באופן מלא לתקן AtomPub RFC 5023.

גרסה 2.0 של Google Data Protocol כוללת גם תמיכה עבור:

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

האפליקציה מתעדכנת

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

עדכון לקוח על סמך ספריית הלקוח

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

• יש גרסת API שתומכת בתכונות של Google Data Protocol v2.0.
• ספריית הלקוח שבה אתם משתמשים תומכת גם בגרסת ה-API הזו.

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

עדכון לקוח HTTP גולמי

אם כתבת את אפליקציית הלקוח שלך ישירות באמצעות Google Data Protocol, עליך לבצע את השינויים הבאים:

• בקשות לגרסאות שאינן מוגדרות כברירת מחדל. צריך להוסיף כותרת לגרסת HTTP (GData-Version: X.0) לכל בקשת HTTP ששולחים, כאשר X היא גרסת ה-API שתומכת בתכונות של Google Data Protocol v2.0. לחלופין, אפשר להוסיף פרמטר שאילתה (v=X.0) לכתובת ה-URL של כל בקשה, כאשר X היא שוב הגרסה הנכונה של ה-API. אם לא תציינו גרסה מאוחרת יותר, הבקשות שלכם יישלחו כברירת מחדל לגרסה הנתמכת המוקדמת ביותר של ה-API.
• בו-זמנית אופטימית. אם השתמשתם בגרסה של API שתומכת בו-זמנית ב-API אופטי, ייתכן שתצטרכו לשנות את העדכון ולמחוק את הקוד כדי להשתמש ב-ETags. למידע נוסף, קראו את הקטע בנושא תגים במסמכי התיעוד של Google Data Protocol וקוראים את הקטע 'עדכון ומחיקה' במדריך למפתחים בנושא השירות שבו משתמש אפליקציית הלקוח.
• URIs עצמית או עריכה. אם הלקוח שלך עוקב אחר מזהי URI של הפרסום העצמי או העצמי שלו עבור פידים או רשומות, ייתכן שמזהי ה-URI האלה השתנו. כדי לקבל את ה-URI החדש, יש לבקש מחדש את הפריט באמצעות ה-URI הישן, אך לסמן את הבקשה כבקשה לגרסה X.0, כאשר X היא גרסת ה-API שתומך בתכונות של Google Data Protocol v2.0. השרת מחזיר את הייצוג החדש של הרשומה, כולל מזהי ה-URI החדשים, שאפשר לשמור במקום הישנים.
• URIs של מרחב שמות. אם הלקוח שלכם מאחסן URI של מרחב שמות של Google Data Protocol API באופן מקומי או אם הוא מקודד באופן קשיח, תצטרכו לעדכן אותן:
  • מרחב השמות של AtomPub (הקידומת app) השתנה מ-http://purl.org/atom/app ל-http://www.w3.org/2007/app.
  • מרחב השמות של OpenSearch (הקידומת openSearch) השתנה מ-http://a9.com/-/spec/opensearchrss/1.0/ ל-http://a9.com/-/spec/opensearch/1.1/.