API Smart Device Management

L'API SDM è un'API REST che fornisce vari metodi per visualizzare le caratteristiche ed eseguire i comandi delle caratteristiche per la gestione dei dispositivi Google Nest. Utilizza il token di accesso concesso durante la procedura di autorizzazione con ogni chiamata API.

Tratti

L'API SDM utilizza un modello basato sui tratti per le informazioni e le funzionalità del dispositivo. Consulta le guide dei singoli dispositivi per vedere quali caratteristiche sono disponibili per un dispositivo:

Metodi

Per informazioni dettagliate su tutti i metodi disponibili per l'API SDM, consulta il Riferimento API.

executeCommand

Esegue un comando su un dispositivo autorizzato.

Utilizza una chiamata POST per eseguire un comando. Ad esempio, per cambiare la modalità del termostato:

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

Altri esempi di comandi sono disponibili nelle pagine di riferimento di ogni singolo tratto. Per saperne di più, consulta l'elenco completo dei tratti.

get

Recupera informazioni su una struttura o un dispositivo autorizzato.

Una chiamata GET restituisce una singola risposta con i campi e i valori correnti per tutte le caratteristiche disponibili per una struttura o un dispositivo che user ha autorizzato e un oggetto "parentRelations", che rappresenta la risorsa principale della risorsa corrente, ovvero una struttura o una stanza.

Ad esempio, un termostato Nest potrebbe restituire i seguenti valori:

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

Elenca le strutture, le stanze o i dispositivi autorizzati.

Per elencare tutte le strutture, le stanze o i dispositivi autorizzati con un singolo token di accesso, effettua una chiamata GET all'endpoint della risorsa appropriato:

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

Integrazioni dell'Assistente Google

Una volta autorizzato un dispositivo per SDM, Google ne viene a conoscenza in Home Graph e ne gestisce direttamente lo stato. Se hai l'integrazione dell'Assistente Google nell'ambito della tua offerta commerciale:

Errori

Per l'elenco completo dei codici di errore dell'API, consulta il riferimento ai codici di errore dell'API.