אישור
כל הבקשות ל-Google Photos Library API חייבות להיות מאושרות על ידי משתמש מאומת.
הפרטים של תהליך ההרשאה ל-OAuth 2.0 משתנים מעט בהתאם לסוג האפליקציה שאתם כותבים. התהליך הכללי הבא חל על כל סוגי האפליקציות:
- כדי להתכונן לתהליך ההרשאה, בצעו את הפעולות הבאות:
- רושמים את האפליקציה באמצעות מסוף Google API.
- מפעילים את Library API ומאחזרים פרטי OAuth כמו מזהה לקוח וסוד לקוח. מידע נוסף זמין במאמר תחילת העבודה.
- כדי לגשת לנתוני המשתמשים, האפליקציה שולחת ל-Google בקשה להיקף גישה מסוים.
- Google מציגה למשתמש מסך הסכמה שמבקש ממנו לאשר לאפליקציה לבקש חלק מהנתונים שלו.
- אם המשתמש מאשר, Google מספקת לאפליקציה אסימון גישה שהתוקף שלו פג אחרי פרק זמן קצר.
- האפליקציה שולחת בקשה לנתוני המשתמש ומצרפת לבקשה את אסימון הגישה.
- אם Google תקבע שהבקשה והאסימון תקפים, היא תחזיר את הנתונים המבוקשים.
במאמר היקפי הרשאות מוסבר אילו היקפי הרשאות מתאימים לאפליקציה שלכם.
התהליך בחלק מסוגי האפליקציות כולל שלבים נוספים, כמו שימוש באסימוני רענון כדי לקבל אסימוני גישה חדשים. למידע מפורט על תהליכי העבודה עם סוגים שונים של אפליקציות, תוכלו לקרוא את המאמר שימוש ב-OAuth 2.0 לגישה לממשקי API של Google.
שמירה במטמון
שמירה על עדכניות הנתונים.
אם אתם צריכים לאחסן מדיה באופן זמני (כמו תמונות ממוזערות, תמונות או סרטונים) מטעמי ביצועים, אל תשמרו אותה במטמון למשך יותר מ-60 דקות בהתאם להנחיות השימוש שלנו.
גם לא כדאי לאחסן את האפליקציה baseUrls, שהתוקף שלה פג אחרי כ-60 דקות.
מזהי פריטי מדיה ומזהי אלבומים שמזהים באופן ייחודי תוכן בספרייה של המשתמש פטורים מהגבלת השמירה במטמון. ניתן לאחסן את המזהים האלה ללא הגבלת זמן (בכפוף למדיניות הפרטיות של האפליקציה). השתמשו במזהי פריטי מדיה ובמזהי אלבומים כדי לאחזר שוב את כתובות ה-URL והנתונים נגישים באמצעות נקודות הקצה המתאימות. למידע נוסף, קראו את המאמר קבלת פריט מדיה או אלבומים.
במקרה שיש לכם הרבה פריטי מדיה לרענון, יכול להיות שעדיף לאחסן את הפרמטרים של החיפוש שהחזירו את פריטי המדיה ולשלוח מחדש את השאילתה כדי לטעון מחדש את הנתונים.
גישה ל-SSL
נדרש HTTPS לכל הבקשות של שירות האינטרנט של Library API באמצעות כתובת ה-URL הבאה:
https://photoslibrary.googleapis.com/v1/service/output?parameters
בקשות שנשלחות באמצעות HTTP נדחות.
טיפול בשגיאות
במאמר טיפול בשגיאות בממשקי Cloud API מוסבר איך לטפל בשגיאות.
ניסיון חוזר של בקשות שנכשלו
הלקוחות צריכים לנסות שוב במקרה של שגיאות 5xx עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff) כפי שמתואר
בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff). העיכוב המינימלי אמור להיות 1 s, אלא אם מתועד אחרת.
במקרה של שגיאות 429, הלקוח יכול לנסות שוב עם עיכוב של 30s לפחות. במקרה של שגיאות אחרות, ייתכן שהניסיון החוזר לא רלוונטי. ודאו שהבקשה אידמפוטנטית וקראו את הודעת השגיאה כדי לקבל הנחיות.
השהיה מעריכית לפני ניסיון חוזר (exponential backoff)
במקרים נדירים, משהו עלול להשתבש במהלך מילוי הבקשה.ייתכן שתקבלו קוד תגובת HTTP מסוג 4XX או 5XX, או שחיבור ה-TCP עלול להיכשל במקום כלשהו בין הלקוח לשרת של Google. לעיתים קרובות כדאי לנסות שוב את הבקשה. בקשת ההמשך עשויה להצליח אם הבקשה המקורית נכשלה. עם זאת, חשוב לא לחזור על בקשות שנשלחות לשרתים של Google כדי לא לחזור על עצמן. מצב הלולאה הזה עלול לגרום לעומס על הרשת בין הלקוח ל-Google ולגרום לבעיות אצל הרבה גורמים.
גישה טובה יותר היא לנסות שוב עם יותר עיכובים בין הניסיונות. בדרך כלל, ההשהיה מוגדלת בגורם הכפלה בכל ניסיון, גישה שנקראת השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
כדאי גם להיזהר שלא יהיה קוד לניסיון חוזר במיקום גבוה יותר בשרשרת הקריאות של האפליקציה, שמוביל לבקשות חוזרות ברצף מהיר.
שימוש מנומס ב-Google APIs
לקוחות API שלא תוכננו בצורה נכונה יכולים ליצור יותר עומס מהנדרש גם באינטרנט וגם בשרתים של Google. הקטע הבא מכיל כמה שיטות מומלצות ללקוחות שמשתמשים בממשקי ה-API. כדאי לפעול לפי השיטות המומלצות הבאות כדי למנוע את חסימת האפליקציה בגלל ניצול לרעה לא מכוון של ממשקי ה-API.
בקשות מסונכרנות
מספר גדול של בקשות מסונכרנות לממשקי ה-API של Google עלול להיראות כמו התקפת מניעת שירות מבוזרת (DDoS) בתשתית של Google, ולטפל בהן בהתאם. כדי למנוע זאת, חשוב לוודא שבקשות ה-API לא מסונכרנות בין הלקוחות.
לדוגמה, נניח שהאפליקציה מציגה את השעה באזור הזמן הנוכחי. האפליקציה הזו ככל הנראה תגדיר התראה במערכת ההפעלה של הלקוח שתעיר אותה בתחילת הדקה, כדי שיהיה אפשר לעדכן את השעה המוצגת. האפליקציה לא צריכה לבצע קריאות ל-API כחלק מהעיבוד שמשויך לאותה התראה.
ביצוע קריאות ל-API בתגובה לאזעקה קבועה הוא בעייתי, כי כתוצאה מכך הקריאות ל-API מסתנכרנות עם תחילת הדקה, אפילו בין מכשירים שונים, במקום לפזר אותן באופן שווה לאורך הזמן. אפליקציה שתוכננה בצורה גרועה מבצעת את הפעולה הזו ויוצרת עליות חדות בנפח התנועה בתחילת כל דקה פי 60 מהרמות הרגילות.
במקום זאת, אחד מהתכנון המתאים הוא להגדיר התראה שנייה למועד שנבחר באופן אקראי. כשההתראה השנייה מופעלת, האפליקציה מבצעת קריאות לכל ממשק ה-API שהיא צריכה ושומרת את התוצאות. כדי לעדכן את התצוגה בתחילת הדקות, האפליקציה משתמשת בתוצאות שנשמרו בעבר במקום לקרוא שוב ל-API. בשיטה הזו, הקריאות ל-API מפוזרות באופן שווה לאורך הזמן. בנוסף, הקריאות ל-API לא מעכבות את העיבוד כשמתבצע עדכון של המסך.
מלבד תחילת הדקה, שעות סנכרון נפוצות אחרות שכדאי להיזהר לא להתמקד בהן בתחילת השעה ובתחילת כל יום בחצות.