Cómo usar la API

Con un token de acceso en la mano y la llamada inicial de la lista de dispositivos, ya puedes usar la API de SDM para acceder y controlar tu dispositivo.

Enumerar estructuras y dispositivos

Usa curl para hacer una llamada GET simple al extremo structures:

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

Una llamada exitosa muestra una lista de estructuras para las cuentas vinculadas a tu proyectoDevice Access :

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

Si aún no lo hiciste, realiza una llamada GET al extremo devices para obtener una lista de dispositivos:

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

Una llamada exitosa muestra una lista de los dispositivos vinculados a tu proyecto de Device Access. Cada dispositivo tiene su propia lista única de características disponibles:

{
  "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 el device-id de cada dispositivo, ya que lo necesitarás para otras llamadas a la API.

Cómo obtener información de un dispositivo

Para obtener información sobre un dispositivo específico, realiza una llamada GET al extremo 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 respuesta debería ser similar a la anterior, pero solo para el dispositivo específico:

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

Ejecutar un comando

Después de validar tu acceso con una llamada a GET exitosa, intenta ejecutar un comando según el tipo de dispositivo que hayas autorizado:

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

CÁMARA

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

Si la llamada se realiza correctamente, se producirán los siguientes resultados:

TERMOSTATO

Recibes una respuesta vacía y el termostato físico cambia su modo actual al modo especificado en los parámetros de comando.

{}

CÁMARA

Recibes una URL de transmisión en vivo y tokens relacionados.

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

Solución de problemas

Sin autenticar

Los tokens de acceso para la API de SDM solo son válidos durante 1 hora. Si recibes una respuesta SIN AUTENTICACIÓN, es probable que el token haya vencido. Usa el token de actualización para obtener un token de acceso nuevo.

Otros errores

Consulta la referencia de códigos de error para ver la lista completa de los Device Access códigos de error.