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

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

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

במדריך הזה, אתם גם 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, ואסימון הרענון משמש לקבלת אסימון גישה חדש.

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

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

כדי להתקשר באמצעות 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 ימים לא קשור לאישורים מסחריים או לאישורים של ארגז חול. כדי להאריך את משך החיים של האסימון, צריך לקבל אישור למזהה הלקוח ב-OAuth 2.0 של חשבון שירות או חשבון משתמש ולהעביר אותו לסביבת הייצור. מידע נוסף זמין במאמר בנושא תפוגה של אסימון רענון.

הגישה נדחתה

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

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

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

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

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

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

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

לקוח לא חוקי

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

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

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

חוסר התאמה ב-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 בדוגמאות הקוד עם הערכים של השילוב הספציפי שלכם, ולהעתיק ולהדביק לפי הצורך:

‫1 PCM

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

  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 קוד אימות

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

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

‫3 טוקן גישה

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

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

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

‫Google OAuth מחזיר שני אסימונים: אסימון גישה ואסימון רענון.

בקשה

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"
}

‫4 קריאות ל-API

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

חובה להשתמש באחת מקריאות ה-API שמפורטות להיקף ההרשאות שצוין כדי להשלים את ההרשאה.

sdm.service

מכשירים

מידע נוסף זמין במאמר בנושא devices.list הפניית API.

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

‫5 Refresh Token

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

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

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

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

בקשה

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"
}
הקודם
1. תחילת העבודה
הבא
3. שימוש ב-API