使用 API

有了存取權權杖，並發出初始裝置清單呼叫後，您就可以使用 SDM API 存取及控制裝置。

列出結構體和裝置

使用 curl 對 structures 端點發出簡單的 GET 呼叫：

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

如果您尚未這麼做，請對 devices 端點發出 GET 呼叫，取得裝置清單：

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 呼叫。

取得裝置資訊

如要取得特定裝置的資訊，請對 device-id 端點提出 GET 呼叫：

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" : {}
  }'

如果呼叫成功，系統會產生以下結果：

溫度控制器

您會收到空白回應，實體溫度控制器也會將目前模式變更為指令參數中指定的模式。

{}

相機

你會收到直播網址和相關符記。

{
  "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 的存取權杖有效期限只有 1 小時。如果您收到「UNAUTHENTICATED」回應，表示權杖可能已過期。使用重新整理權杖取得新的存取權杖。

其他錯誤

如需 Device Access 錯誤代碼的完整清單，請參閱「錯誤代碼參考資料」。