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

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

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

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

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

יצירת מכשיר בצורה יעילה יותר באמצעות OAuth

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

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

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

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

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

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

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

כדי לאחזר מידע על מכשיר ספציפי, משתמשים בשיטה devices.get עם הערך הייחודי של id. האפשרות הזו שימושית לבדיקה של סטטוס המכשיר, למשל כדי לבדוק אם הערך של mediaSourcesSet הוא true.

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

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

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

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

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

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

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

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

השלבים הבאים