הגדרת האפליקציה ל-Ambient API

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

האפליקציה שלכם מבצעת פעולות ב-Ambient API בשם משתמש של Ambient API. המשתמש מאשר את בקשות ה-API האלה באמצעות פרוטוקול OAuth 2.0.

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

הגדרת האפליקציה

קודם מפעילים את ה-API ואז מבקשים מזהה לקוח ב-OAuth 2.0.

הפעלת ה-API

כדי להשתמש ב-Ambient API, צריך להפעיל אותו בפרויקט.

1. עוברים אל מסוף Google API.
2. בסרגל התפריטים, בוחרים פרויקט או יוצרים פרויקט חדש.
3. כדי לפתוח אחד מממשקי ה-API של Google Photos, בתפריט הניווט בוחרים באפשרות APIs & Services (ממשקי API ושירותים) > Library (ספרייה).
4. מחפשים את 'Ambient API'. בוחרים את Ambient API ולוחצים על Enable.

בקשה למזהה לקוח ב-OAuth 2.0

כדי לבקש מזהה לקוח ב-OAuth ולהגדיר אותו לאפליקציה, פועלים לפי השלבים הבאים. ב-Ambient API נעשה שימוש ב-OAuth 2.0 לאפליקציות במכשירי טלוויזיה ומכשירים עם יכולות קלט מוגבלות.

1. נכנסים ל-Google API Console ובוחרים את הפרויקט.
2. בתפריט, בוחרים באפשרות APIs & Services (ממשקי API ושירותים) > Credentials (פרטי כניסה).

3. בדף Credentials, לוחצים על Create Credentials > OAuth client ID.

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

4. בוחרים את סוג האפליקציה. בדוגמה הזו, סוג האפליקציה הוא טלוויזיות והתקני קלט עם הגבלות.

5. נותנים שם ללקוח OAuth 2.0 ולוחצים על Create.

6. מעתיקת הפרטים הבאים מתיבת הדו-שיח של לקוח ה-OAuth שנוצרה:

   • Client-ID
   • סוד לקוח

בעזרת הערכים האלה, האפליקציה יכולה לגשת לממשקי Google API המופעלים.

כדי להפעיל אפליקציה ציבורית שמשתמשת ב-Ambient API, האפליקציה צריכה לעבור בדיקה של Google. ההודעה 'אפליקציה לא מאומתת' תופיע במסך כשתנסו את האפליקציה, עד שהיא תאומת.

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

• יצירה וניהול של מכשירים
• הצגת רשימה של פריטי מדיה ואחזור שלהם

שינוי מזהה הלקוח

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

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

תהליך אימות פשוט יותר ל-Ambient API

בתהליך האימות הרגיל של Ambient API, המשתמשים צריכים לסרוק 2 קודי QR:

• 1. נכנסים לחשבון Google (אם עדיין לא נכנסתם).
• קישור שני שמקשר את מכשיר ה-Ambient החדש שנוצר לחשבון Google Photos שלהם, שבו הם יכולים לבחור את פריטי המדיה שיוצגו.

התהליך המשופר מאפשר לספק למשתמשים קוד QR יחיד על ידי העברת הפרמטר הנוסף state בקריאה הראשונית לאימות.

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

פרמטרים
requestId	string חובה. מזהה ייחודי של הבקשה הזו שסופק על ידי הלקוח. הוא משמש כדי למנוע כפילויות של משאבים במקרה של כשל ברשת. המזהה הזה חייב להיות בפורמט של מחרוזת UUID (גרסה 4) ולעמוד בדרישות הבאות: אסור לכלול מידע רגיש ומזהה על המשתמש. חייב להכיל 32 תווים הקסדצימליים שמחולקים לחמש קבוצות מופרדות במקפים, בפורמט "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (או 8-4-4-4-12).
displayName	string זה שינוי אופציונלי. שם מוצג שהמשתמש נתן למכשיר הזה. המידע הזה יוצג למשתמשים בהגדרות של אפליקציית Google Photos, אבל ניתן יהיה לערוך אותו רק דרך ה-API הזה. שמות מוצגים תקינים חייבים להכיל בין 1 ל-100 תווים (כולל).

לדוגמה, אפשר לעיין בקוד הבא:

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

תגובה מוצלחת תכלול את הערכים user_code ו-verification_url, שצריך להציג למשתמש (סביר להניח כקוד QR) כדי שהוא יוכל לנווט אליה במכשיר נפרד. אם תכללו את הפרמטר state, כשתבצעו מאוחר יותר קריאה ל-createDevice באמצעות Ambient API, תוכלו לדלג על הצגת settingsUri בקוד QR שני, כי השלב האחרון בתהליך OAuth יפנה אוטומטית למיקום הזה.

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

פרטים על תהליך האימות המשופר

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

OAuth 2.0 לאפליקציות במכשירי טלוויזיה ומכשירים עם יכולות קלט מוגבלות:

1. האפליקציה שולחת בקשה לשרת ההרשאות של Google, שמזהה את ההיקפים של הגישה שהאפליקציה תבקש.
2. השרת משיב עם כמה פרטי מידע שיהיו בשימוש בשלבים הבאים, כמו קוד מכשיר וקוד משתמש.
3. אתם מציגים מידע שהמשתמש יכול להזין במכשיר נפרד כדי להעניק הרשאה לאפליקציה.
4. האפליקציה מתחילה לבצע סקרים לשרת ההרשאות של Google כדי לקבוע אם המשתמש העניק הרשאה לאפליקציה.
5. המשתמש עובר למכשיר עם יכולות קלט עשירות יותר, מפעיל דפדפן אינטרנט, עובר לכתובת ה-URL שמוצגת בשלב 3 ומזין קוד שמוצג גם בשלב 3. לאחר מכן, המשתמש יוכל להעניק (או לדחות) גישה לאפליקציה.
6. התשובה הבאה לבקשת הסקרים מכילה את האסימונים שהאפליקציה צריכה כדי לאשר בקשות בשם המשתמש. (אם המשתמש דחה את הגישה לאפליקציה, התגובה לא תכלול אסימונים).

תהליך Ambient API:

1. בודקים אם יש טוקן OAuth קיים, ומרעננים את הטוקן או מבקשים טוקן חדש.
2. אחרי שמקבלים אסימון OAuth, יוצרים מכשיר חדש.
3. מציגים את settingsUri למשתמש ומתחילים לבצע סקרים במכשיר עד ש-mediaSourcesSet מחזיר את הערך true.
4. המשתמש עובר אל settingsUri ובוחר את התמונות שהוא רוצה לשתף עם האפליקציה.
5. אחרי ש-mediaSourcesSet מחזירה את הערך true, מאחזרים את הרשימה של mediaItems.
6. עכשיו אפשר להתחיל את המצגת או את חוויית האווירה.

שני התהליכים כוללים שלב שבו אתם מציגים למשתמש כתובת URL, והמשתמש מנווט אליה במכשיר הקלט העשיר יותר שלו. אם תכללו את הפרמטר state בקריאה הראשונית ל-OAuth, תוכלו להימנע מהצגת כתובת ה-URL השנייה.

הסיבה לכך היא שבשלב האחרון בתהליך של OAuth 2.0 לאפליקציות במכשירי טלוויזיה ובמכשירים עם יכולות קלט מוגבלות, המשתמש מופנה בדרך כלל לדף שבו כתוב "עכשיו אפשר לחזור למכשיר". אם תכללו את פרמטר המצב, השלב האחרון בתהליך ינסה להפנות אתכם אל settingsUri. האפליקציה עדיין תקבל אסימון OAuth. צריך להשתמש באסימון הזה כדי לקרוא ל-createDevice באמצעות אותו requestId. אחרי שייווצר מכשיר עם אותו מזהה, תהליך ה-OAuth הראשוני יפנה את המשתמש לדף הנכון באפליקציית Photos במכשיר העשיר.

חשוב לזכור את הנקודות הבאות:

• עדיין מומלץ להציג את settingsUri למקרה שתהיה בעיה באימות.
• עדיין תוכלו להשתמש ב-settingsUri במקרים אחרים, למשל כשמשתמש רוצה לעדכן את בחירת התמונות שלו.