Utilizzare l'API

Con un token di accesso a portata di mano e la chiamata iniziale all'elenco dei dispositivi effettuata, puoi utilizzare l'API SDM per accedere al tuo dispositivo e controllarlo.

Elenco di strutture e dispositivi

Utilizza 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 al tuo 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.

Recuperare le informazioni di 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 di prima, 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 riuscita, 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 ha esito positivo, si verificano i seguenti risultati:

TERMOSTATO

Riceverai una risposta vuota e il termostato fisico cambierà la sua 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 1 ora. Se ricevi una risposta UNAUTHENTICATED, è probabile che il token sia scaduto. Utilizza il token di aggiornamento per ricevere un nuovo token di accesso.

Altri errori

Consulta la sezione Riferimento ai codici di errore per un elenco completo dei Device Access codici di errore.