Utilizzare l'API

Una volta ottenuto un token di accesso e effettuata la chiamata iniziale all'elenco di dispositivi, puoi iniziare a utilizzare l'API SDM per accedere e controllare il tuo dispositivo.

Elenco di strutture e dispositivi

Usa curl per effettuare una semplice chiamata GET all'endpoint structures:

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

Una chiamata riuscita restituisce un elenco di strutture per gli account collegati al tuo Device Access progetto:

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

Se non l'hai ancora fatto, effettua una chiamata GET all'endpoint devices per ottenere un elenco di dispositivi:

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

Una chiamata riuscita restituisce un elenco di dispositivi collegati a Device Access progetto. Ogni dispositivo ha il proprio elenco univoco di trait disponibili:

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

Copia il valore device-id per ogni dispositivo, ti servirà per le altre chiamate API.

Ottenere informazioni su un dispositivo

Per ottenere informazioni su un dispositivo specifico, effettua una chiamata GET all'endpoint 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'

La risposta dovrebbe essere simile a quella precedente, ma solo per il dispositivo specifico:

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

Esegui un comando

Dopo aver convalidato l'accesso con una chiamata GET andata a buon fine, prova a eseguire un comando in base al tipo di dispositivo che hai autorizzato:

TERMOSTATO

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

FOTOCAMERA

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

Se la chiamata va a buon fine, si verificano i seguenti risultati:

TERMOSTATO

Riceverai una risposta vuota e il termostato fisico cambierà la modalità corrente in quella specificata nei parametri del comando.

{}

FOTOCAMERA

Riceverai un URL del live streaming e i token correlati.

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

Risoluzione dei problemi

Non autenticato

I token di accesso per l'API SDM sono validi solo per un'ora. Se ricevi una risposta NON AUTENTICATA, è probabile che il token sia scaduto. Utilizza il token di aggiornamento per ricevere un nuovo token di accesso.

Altri errori

Consulta la pagina Riferimento al codice di errore per l'elenco completo dei Device Access codici di errore.