שיטות מומלצות

אישור

כל הבקשות לממשקי ה-API של Google Photos חייבות להיות מאושרות על ידי משתמש מאומת.

הפרטים של תהליך ההרשאה ב-OAuth 2.0 משתנים מעט בהתאם לסוג האפליקציה שאתם מפתחים. התהליך הכללי הבא חל על כל סוגי האפליקציות:

  1. כדי להתכונן לתהליך ההרשאה, מבצעים את הפעולות הבאות:
    • רושמים את האפליקציה באמצעות Google API Console.
    • הפעלת ממשקי ה-API של Photos ואחזור פרטי OAuth כמו מזהה לקוח וסוד לקוח. מידע נוסף זמין במאמר תחילת העבודה.
  2. כדי לגשת לנתוני משתמשים, האפליקציה שולחת ל-Google בקשה להיקף גישה ספציפי.
  3. Google מציגה למשתמש מסך הסכמה ומבקשת לאשר לאפליקציה לשלוח בקשה לחלק מהנתונים שלו.
  4. אם המשתמש מסכים, Google מספקת לאפליקציה אסימון גישה שפג תוקפו לאחר פרק זמן קצר.
  5. האפליקציה שולחת בקשה לקבלת נתוני המשתמש ומצרפת לבקשה את אסימון הגישה.
  6. אם Google תקבע שהבקשה והאסימון תקפים, היא תחזיר את הנתונים המבוקשים.

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

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

שמירה במטמון

שמירה על עדכניות הנתונים.

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

כמו כן, לא מומלץ לאחסן את baseUrls, שתוקפו פג לאחר כ-60 דקות.

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

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

גישה ל-SSL

צריך להשתמש ב-HTTPS בכל הבקשות לשירותי האינטרנט של Photos API באמצעות כתובת ה-URL הבאה:

https://photoslibrary.googleapis.com/v1/service/output?parameters

בקשות שנשלחות באמצעות HTTP נדחות.

טיפול בשגיאות

מידע נוסף על טיפול בשגיאות שמוחזרות מה-API זמין במאמר טיפול בשגיאות ב-Cloud APIs.

ניסיון חוזר של בקשות שנכשלו

לקוחות צריכים לנסות שוב כשמתקבלות שגיאות מסוג 5xx עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff), כפי שמתואר בקטע השהיה מעריכית לפני ניסיון חוזר. העיכוב המינימלי צריך להיות 1 s, אלא אם צוין אחרת.

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

השהיה מעריכית לפני ניסיון חוזר (exponential backoff)

במקרים נדירים, יכול להיות משהו השתבש בטיפול בבקשה.יכול להיות שתקבלו קוד תגובה מסוג HTTP‏ 4XX או 5XX, או שחיבורי ה-TCP יכשלו במקום כלשהו בין הלקוח לשרת של Google. לרוב כדאי לנסות שוב את הבקשה. יכול להיות שהבקשה הבאה תאושר גם אם הבקשה המקורית נכשלה. עם זאת, חשוב לא להיכנס ללופים ולשלוח בקשות חוזרות לשרתים של Google. התנהגות כזו של לולאה עלולה לגרום לעומס ברשת בין הלקוח ל-Google ולגרום לבעיות אצל גורמים רבים.

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

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

שימוש מנומס ב-Google APIs

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

בקשות מסונכרנות

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

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

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

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

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