יצירה וניהול של מכשירים

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

יצירת מכשירים

אחרי שהמשתמשים מאמתים את החשבון שלהם באמצעות התהליך OAuth 2.0 לאפליקציות במכשירי טלוויזיה ומכשירים עם יכולות קלט מוגבלות, יוצרים מכשיר בחשבון Google Photos שלהם.

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

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

יצירת מכשירים פשוטה יותר באמצעות OAuth

‫Ambient API מציע תהליך OAuth יעיל. אם תעבירו את הפרמטר הנוסף state בבקשת ה-OAuth הראשונית ותקראו ל-devices.create עם הערך התואם של requestId, תוכלו לקשר את תהליך יצירת המכשיר ישירות לתהליך הכניסה של המשתמש. כך תוכלו לפשט את חוויית המשתמש על ידי צמצום מספר קודי ה-QR שהמשתמשים צריכים לסרוק.

פרטים נוספים ודוגמה זמינים במדריך תהליך אימות יעיל ל-Ambient API.

מגבלות על מכשירים

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

ניהול מכשירים

אחרי שיוצרים מכשיר ומקשרים אותו לחשבון Google Photos של משתמש, יכול להיות שתצטרכו לנהל את מחזור החיים שלו.

אחזור מכשירים

כדי לאחזר מידע על מכשיר ספציפי, משתמשים ב-method‏ devices.get עם ה-id הייחודי שלו. האפשרות הזו שימושית לבדיקת סטטוס המכשיר, למשל אם mediaSourcesSet מוגדר כ-True.

עדכון המכשירים

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

הערה: מומלץ לתת למשתמשים אפשרות לתת שם למכשיר לפני שיוצרים אותו. כך למשתמשים יהיה קל יותר לזהות את המכשיר שלהם כשהם בוחרים קובצי מדיה בחשבון Google Photos.

מחיקת מכשירים

הטמיעו אסטרטגיה למחיקת מכשירים כדי לנקות את המערכת כמו שצריך ולשלוט במשתמשים. אפשר למחוק מכשיר באמצעות ה-method‏ devices.delete.

כדאי להביא בחשבון את התרחישים הבאים למחיקת מכשירים:

• ניתוק משתמש: אם משתמש מנתק את האפליקציה שלכם מחשבון Google Photos שלו, אתם צריכים למחוק את המכשיר המתאים.
• מכשירים מיותמים: אם איבדתם את המעקב אחרי id אבל עדיין יש לכם את requestId ששימש ליצירה, אתם יכולים להשתמש ב-requestId עם devices.delete כדי להסיר מכשיר מיותם. כך אפשר למנוע כפילויות בטעות ולשמור על הסדר בחשבון של המשתמש.

שיקולים חשובים ושיטות מומלצות

• מחזור החיים של המכשיר והרשאות המשתמשים: תצטרכו לנהל את מחזור החיים של המכשירים ואת אסימוני ההרשאות של המשתמשים. חשוב להביא בחשבון את משך הזמן שבו המכשירים נשארים פעילים, ואיך לטפל ברענון של טוקנים או בהרשאה מחדש אם מכשיר הופך ללא פעיל או אם פג התוקף של הטוקן שלו.
• טיפול בשגיאות: צריך להטמיע טיפול חזק בשגיאות בכל קריאות ה-API שקשורות למכשיר. כדאי להתכונן לתרחישים כמו:
  • ‫NOT_FOUND: אם המכשיר לא קיים או לא בבעלות המשתמש.
  • ‫RESOURCE_EXHAUSTED: אם חורגים ממגבלת המכשירים.
  • ‫ALREADY_EXISTS: אם מנסים ליצור מכשיר עם requestId שכבר קיים.

השלבים הבאים

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