מתן הרשאה לחשבון

אחרי שיוצרים את הפרויקטים ב-Google Cloud וב-Device Access, אפשר לתת הרשאה לחשבון Google עם מכשיר Google Nest נתמך ל-SDM API.

קישור החשבון

כדי לראות את המבנים והמכשירים, צריך לקשר חשבון Google לפרויקטDevice Access באמצעות PCM.‏ PCM מאפשר ל- user להעניק הרשאה ל- developers לגשת למבנים ולנתוני המכשירים שלהם.

במדריך הזה, אתם גם user וגם developer.

1. פותחים את הקישור הבא בדפדפן אינטרנט ומחליפים את:

   1. project-id עם Device Access Project התעודה המזהה
   2. ‫oauth2-client-id עם מזהה הלקוח ב-OAuth2 מפרטי הכניסה ב-Google Cloud

   https://nestservices.google.com/partnerconnections/project-id/auth?redirect_uri=https://www.google.com&access_type=offline&prompt=consent&client_id=oauth2-client-id&response_type=code&scope=https://www.googleapis.com/auth/sdm.service
   

2. אם נכנסתם לאחרונה ל-Google עם כמה חשבונות, יכול להיות שיוצג לכם מסך ראשוני עם האפשרות בחירת חשבון ורשימה של חשבונות Google. אם זה קורה, בוחרים את חשבון Google שמקושר למכשירים שרוצים לתת להם הרשאה ל- Device Access.
3. מסך ההרשאות של Google Nest הוא בעצם PCM. כאן אפשר להעניק הרשאות למבנה ולמכשירים. מעבירים את המתג למצב מופעל ליד ההרשאות לבית (שלב 1) ולכל המכשירים בבית שתומכים ב-SDM API (שלב 2), ואז לוחצים על הבא.
4. במסך Choose an account to continue to Project Name (בחירת חשבון להמשך אל שם הפרויקט), שבו שם הפרויקט הוא שם הפרויקט שלכם ב-Google Cloud, בוחרים את חשבון Google שרוצים לתת לו הרשאה ל-SDM API. צריך להשתמש באותו חשבון Google כמו קודם.
5. אחרי שבוחרים חשבון, יכול להיות שיוצג מסך אזהרה עם הכיתוב Google לא אימתה את האפליקציה הזו. אם זה קורה, כדי להמשיך, לוחצים על האפשרות מתקדם ואז על מעבר אל שם הפרויקט (לא בטוח). מידע נוסף זמין במאמר Google לא אימתה את האפליקציה הזו.
6. במסך Grant Project Name permission (מתן הרשאה לגישה לשם הפרויקט), לוחצים על Allow (אישור) כדי לתת לפרויקט הרשאה לגשת לחשבון Google.
7. במסך אישור הבחירות שלך, מוודאים שההרשאות שרוצים לתת מסומנות ולוחצים על אישור.

8. תופנו אוטומטית אל https://www.google.com. קוד ההרשאה מוחזר כפרמטר code בכתובת ה-URL, שצריכה להיות בפורמט הבא:

   https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service
   

9. מעתיקים את קוד ההרשאה.

קבלת טוקן גישה

משתמשים בקוד ההרשאה כדי לאחזר טוקן גישה, שבו אפשר להשתמש כדי להפעיל את SDM API.

1. פותחים טרמינל ומריצים את הפקודה הבאה של curl, ומחליפים את:

   1. ‫oauth2-client-id ו-oauth2-client-secret עם מזהה הלקוח והסוד של הלקוח ב-OAuth2 מפרטי הכניסה שלך ב-Google Cloud
   2. ‫authorization-code בקוד שקיבלתם בשלב הקודם

   curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&code=authorization-code&grant_type=authorization_code&redirect_uri=https://www.google.com'

2. מערכת Google OAuth מחזירה שני טוקנים: טוקן גישה וטוקן רענון.

   {
     "access_token": "access-token",
     "expires_in": 3599,
     "refresh_token": "refresh-token",
     "scope": "https://www.googleapis.com/auth/sdm.service",
     "token_type": "Bearer"
   }

   מעתיקים את שני הערכים האלה. אסימון הגישה משמש לקריאה ל-SDM API, ואסימון הרענון משמש לקבלת אסימון גישה חדש.

איך מתקשרים מרשימת המכשירים

ההרשאה לא תושלם עד שתבצעו את השיחה הראשונה עם אסימון הגישה החדש שלכם. השיחה הראשונה הזו מסיימת את תהליך ההרשאה ומאפשרת אירועים אם כבר הגדרתם מינוי ל-Pub/Sub.devices.list

כדי להתקשר באמצעות curl לנקודת הקצה devices:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

שיחה מוצלחת מחזירה רשימה של מכשירים שמקושרים לפרויקט Device Access. לכל מכשיר יש רשימה ייחודית משלו של תכונות זמינות:

{
  "devices": [
    {
      "name": "enterprises/project-id/devices/device-id",
      "type": "sdm.devices.types.device-type",
      "traits": { ... },
      "parentRelations": [
        {
          "parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
          "displayName": "device-room-name"
        }
      ]
    }
  ]
}

איך משתמשים באסימון רענון

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

הפקודה דומה לפקודה של אסימון הגישה, אבל משתמשים בgrant_type שונה.

1. פותחים טרמינל ומריצים את הפקודה curl הבאה, ומחליפים את:

   1. ‫oauth2-client-id ו-oauth2-client-secret עם מזהה הלקוח והסוד של הלקוח ב-OAuth2 מפרטי הכניסה שלך ב-Google Cloud
   2. ‫refresh-token עם הקוד שקיבלתם כשקיבלתם את אסימון הגישה בפעם הראשונה.

   curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&refresh_token=refresh-token&grant_type=refresh_token'

2. מערכת Google OAuth מחזירה אסימון גישה חדש.

   {
     "access_token": "new-access-token",
     "expires_in": 3599,
     "scope": "https://www.googleapis.com/auth/sdm.service",
     "token_type": "Bearer"
   }

פתרון בעיות

מידע נוסף על Google OAuth מופיע במאמר בנושא שימוש ב-OAuth 2.0 כדי לגשת אל Google APIs.

התוקף של טוקן הרענון פג כל הזמן

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

הגישה נדחתה

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

שגיאה ב-Partner Connections Manager‏ (PCM)

אם נתקלתם בשגיאות כשניסיתם לגשת ל-PCM, תוכלו לעיין בהפניה לשגיאות ב-Partner Connections Manager (PCM).

‫Google לא אימתה את האפליקציה הזו

ממשק SDM API משתמש בהיקף מוגבל, כלומר כל האפליקציות שמשתמשות בהיקף הזה במהלך ההרשאה יוגדרו כ'לא מאומתות' אלא אם יושלם אימות של OAuth API. כשמשתמשים ב- Device Access לשימוש אישי, לא נדרש אימות של OAuth API.

יכול להיות שבמהלך תהליך ההרשאה יוצג המסך 'Google לא אימתה את האפליקציה הזו'. המסך הזה מופיע אם ההיקף sdm.service לא מוגדר במסך ההסכמה ל-OAuth ב-Google Cloud. כדי לדלג על המסך הזה, לוחצים על האפשרות מתקדם ואז על מעבר אל שם הפרויקט (לא בטוח).

מידע נוסף זמין במאמר בנושא מסך של אפליקציה לא מאומתת.

לקוח לא חוקי

כשמנסים לקבל אסימון גישה או אסימון רענון, מוצגת השגיאה 'לקוח לא תקין' אם מספקים סוד לקוח שגוי של OAuth 2.0. חשוב לוודא שהערך client_secret שבו אתם משתמשים בקריאות לאסימון גישה ולאסימון רענון הוא הערך של מזהה הלקוח של OAuth 2.0 שבו אתם משתמשים, כפי שמופיע בדף Google Cloud Credentials.

בקשה לא חוקית, חסר היקף הרשאות נדרש

אחרי שנותנים הרשאות ב-PCM, יכול להיות שתופיע השגיאה 'בקשה לא חוקית' עם ההודעה 'חסר פרמטר נדרש: היקף'. חשוב לוודא שהערך scope שבו אתם משתמשים בקריאות הרשאה זהה לערך שהגדרתם ללקוח OAuth 2.0, כפי שמופיע בדף פרטי הכניסה ב-Google Cloud.

חוסר התאמה ב-URI של ההפניה לכתובת אחרת

במהלך ההרשאה, יכול להיות שתיתקלו בשגיאה 'כתובת ה-URI להפניה אוטומטית לא תואמת'. חשוב לוודא שהערך redirect_uri שבו אתם משתמשים בקריאות להרשאה זהה לערך שהגדרתם ללקוח OAuth 2.0, כפי שמופיע בדף פרטי הכניסה ב-Google Cloud.

שינוי הרשאות בחשבון

כדי לשנות את ההרשאות שניתנו לפרויקט Device Access או לנתק אותו לגמרי, עוברים אל PCM:

https://nestservices.google.com/partnerconnections

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

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

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

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

הסבר מהיר

אפשר להשתמש בהפניה הזו כדי ליישם במהירות את השלבים לאישורuser וקישור חשבון Google.

כדי להשתמש במדריך הזה, צריך לערוך כל משתנה placeholder בדוגמאות הקוד עם הערכים של השילוב הספציפי שלכם, ולהעתיק ולהדביק לפי הצורך:

https://nestservices.google.com/partnerconnections/project-id/auth?redirect_uri=https://www.google.com&access_type=offline&prompt=consent&client_id=oauth2-client-id&response_type=code&scope=https://www.googleapis.com/auth/sdm.service

https://www.google.com?code=authorization-code&scope=https://www.googleapis.com/auth/sdm.service

curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&code=authorization-code&grant_type=authorization_code&redirect_uri=https://www.google.com'

{
  "access_token": "access-token",
  "expires_in": 3599,
  "refresh_token": "refresh-token",
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?client_id=oauth2-client-id&client_secret=oauth2-client-secret&refresh_token=refresh-token&grant_type=refresh_token'

{
  "access_token": "new-access-token",
  "expires_in": 3599,
  "scope": "https://www.googleapis.com/auth/sdm.service",
  "token_type": "Bearer"
}