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

אישור

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

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

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

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

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

שמירה במטמון

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

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

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

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

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

גישת SSL

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

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

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

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

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

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

הלקוחות צריכים לנסות שוב בשגיאות 5xx עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff), כפי שמתואר ב- השהיה מעריכית לפני ניסיון חוזר (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 לא מעכבות את הרינדור כשהתצוגה מתעדכנת.

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