שימוש ב-API

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

הצגת רשימה של מבנים ומכשירים

משתמשים ב-curl כדי לבצע קריאת GET פשוטה לנקודת הקצה structures:

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

קריאה מוצלחת מחזירה רשימה של מבנים של חשבונות שמקושרים לפרויקטDevice Access :

{
  "structures": [
    {
      "name": "enterprises/project-id/structures/structure-id",
      "traits": {
        "sdm.structures.traits.Info": {
          "customName": "structure-name"
        }
      }
    }
  ]
}

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

מעתיקים את device-id לכל מכשיר. תצטרכו את הערך הזה בקריאות API אחרות.

אחזור מידע על מכשיר

כדי לקבל מידע על מכשיר ספציפי, שולחים קריאת GET לנקודת הקצה device-id:

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

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

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

ביצוע פקודה

אחרי אימות הגישה באמצעות קריאת GET מוצלחת, נסו להריץ פקודה בהתאם לסוג המכשיר שאישרתם:

תרמוסטט

curl -X POST \
  'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices/device-id:executeCommand' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer access-token' \
  --data-raw '{
    "command" : "sdm.devices.commands.ThermostatMode.SetMode",
    "params" : {
      "mode" : "HEAT"
    }
  }'

מצלמה

curl -X POST \
  'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices/device-id:executeCommand' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer access-token' \
  --data-raw '{
    "command" : "sdm.devices.commands.CameraLiveStream.GenerateRtspStream",
    "params" : {}
  }'

אם הקריאה תתבצע בהצלחה, התוצאות הבאות יתקבלו:

תרמוסטט

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

{}

מצלמה

תקבלו כתובת URL של שידור חי ואסימונים קשורים.

{
  "results" : {
    "streamUrls" : {
      "rtspUrl" : "rtsps://someurl.com/CjY5Y3VKaTZwR3o4Y19YbTVfMF...?auth=g.0.streamingToken"
    },
    "streamExtensionToken" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
    "streamToken" : "g.0.streamingToken",
    "expiresAt" : "2018-01-04T18:30:00.000Z"
  }
}

פתרון בעיות

לא מאומת

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

שגיאות אחרות

בחומר העזר בנושא קודי שגיאה מופיעה רשימה מלאה של Device Access קודי השגיאה.