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

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

כדי להציג מבנים ומכשירים, צריך לקשר חשבון 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, שבו Project Name הוא שם הפרויקט ב-Google Cloud, בוחרים את חשבון Google שרוצים להעניק לו הרשאה ל-SDM API. משתמשים באותו חשבון Google כמו קודם.
  5. אחרי שבוחרים חשבון, יכול להיות שיופיע מסך אזהרה עם הכיתוב Google לא אימתה את האפליקציה הזו. במקרה כזה, כדי להמשיך, לוחצים על האפשרות מתקדם ואז על כניסה אל שם הפרויקט (לא בטוח). למידע נוסף, ראו Google לא אימתה את האפליקציה הזו.
  6. במסך Grant Project Name permission (מתן הרשאה ל-Project Name), לוחצים על Allow (אישור) כדי לתת לפרויקט הרשאה לגשת לחשבון Google.
  7. במסך Confirm your choices, מוודאים שההרשאות שרוצים להעניק מסומנות ולוחצים על Allow כדי לאשר.

  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.

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

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 וסוג המשתמש מוגדר כחיצוני, תופיע הודעת השגיאה 'Access denied' (הרשאת הגישה נדחתה) אם תנסו לקשר חשבון עם חשבון Google שלא מופיע כמשתמש לבדיקה באפליקציה. חשוב להוסיף את חשבון Google לקטע משתמשים לבדיקה במסך ההסכמה של OAuth.

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

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

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

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

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

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

לקוח לא חוקי

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

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

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

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

מכשירים

מידע נוסף זמין במסמכי העזרה של API devices.list.

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

5 טוקן רענון

אסימוני הגישה ל-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