使用 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项目关联的设备列表。每部设备都有自己独特的可用 trait 列表：

{
  "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。

获取设备信息

如需获取特定设备的信息，请向 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 错误代码的完整列表，请参阅错误代码参考文档。