Smart Device Management API

SDM API 是一种 REST API，提供各种方法来查看 trait 并执行 trait 命令，以便管理 Google Nest 设备。在每次 API 调用中使用授权流程中授予的访问令牌。

trait

SDM API 使用基于 trait 的模型来处理设备信息和功能。请查看各个设备指南，了解相应设备支持哪些 trait：

方法

如需详细了解 SDM API 提供的所有方法，请参阅 API 参考文档。

executeCommand

向已获授权的设备执行命令。

使用 POST 调用执行命令。例如，如需更改温控器模式，请执行以下操作：

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatMode.SetMode",
  "params" : {
    "mode" : "HEAT"
  }
}

您可以在每个 trait 参考页面中找到更多命令示例。如需了解详情，请参阅完整的特征列表。

get

获取已获授权的结构或设备的相关信息。

GET 调用会返回一个响应，其中包含已授权的结构体或设备可用的所有 trait 的当前字段和值，以及一个“parentRelations”对象，该对象表示当前资源（结构体或房间）的父级资源。 user

例如，Nest Thermostat 可能会返回以下内容：

GET /enterprises/project-id/devices/device-id
{
  "name" : "enterprises/project-id/devices/device-id",
  "type" : "sdm.devices.types.THERMOSTAT",
  "assignee" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "traits" : {
    "sdm.devices.traits.Connectivity" : {
      "status" : "ONLINE"
    },
    "sdm.devices.traits.Fan" : {
      "timerMode" : "ON",
      "timerTimeout" : "2019-05-10T03:22:54Z"
    },
    "sdm.devices.traits.Humidity" : {
      "ambientHumidityPercent" : 35.0
    },
    "sdm.devices.traits.Info" : {
      "customName" : "My device"
    },
    "sdm.devices.traits.Settings" : {
      "temperatureScale" : "CELSIUS"
    },
    "sdm.devices.traits.Temperature" : {
      "ambientTemperatureCelsius" : 23.0
    },
    "sdm.devices.traits.ThermostatEco" : {
      "availableModes" : ["MANUAL_ECO", "OFF"],
      "mode" : "MANUAL_ECO",
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    },
    "sdm.devices.traits.ThermostatHvac" : {
      "status" : "HEATING"
    },
    "sdm.devices.traits.ThermostatMode" : {
      "availableModes" : ["HEAT", "COOL", "HEATCOOL", "OFF"],
      "mode" : "COOL"
    },
    "sdm.devices.traits.ThermostatTemperatureSetpoint" : {
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    }
  },
  "parentRelations" : [
    {
      "parent" : "enterprises/project-id/structures/structure-id/rooms/room-id",
      "displayName" : "Lobby"
    }
  ]
}

list

列出已获授权的结构、房间或设备。

如需列出使用单个访问令牌授权的所有结构、房间或设备，请对相应的资源端点进行 GET 调用：

GET /enterprises/project-id/structures
GET /enterprises/project-id/structures/structure-id/rooms
GET /enterprises/project-id/devices

Google 助理集成

设备获得 SDM 授权后，Google 会在 Home Graph 中感知到该设备，并直接管理其状态。如果您的商业产品/服务中包含 Google 助理集成：

错误

如需查看 API 错误代码的完整列表，请参阅 API 错误代码参考文档。