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

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

אפשר להשתמש ב-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 וסוג המשתמש הוא חיצוני, אם תנסו לקשר חשבון Google לחשבון 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. כדי לעקוף את המסך הזה, לוחצים על האפשרות Advanced ואז על Go to Project Name (לא בטוח).

למידע נוסף, ראו מסך של אפליקציות לא מאומתות.

לקוח לא חוקי

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

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

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

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

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

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

כדי לשנות את ההרשאות שהוענקו לפרויקט Device Access או לנתק אותו לחלוטין, צריך להיכנס ל-PPC:

https://nestservices.google.com/partnerconnections

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

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

כדי לנתק לחלוטין שירות מורשה, לוחצים על Unlink your Google Account (ביטול הקישור של חשבון 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 אסימון רענון

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