Estructura

Las estructuras de Nest representan estructuras físicas en el mundo real. Por lo general, la casa de un usuario sirve como punto de organización para los dispositivos y almacena datos que se aplican a toda la casa.

La API de Nest proporciona acceso a los siguientes datos a nivel de la estructura, según el nivel de permisos otorgados:

• Nombre de la estructura y el dispositivo "where name" (ubicación de la casa)
• La lista de dispositivos del hogar
• Estado del evento de energía (hora pico de energía)
• Estado Ausente
• ETA del usuario
• Estado de seguridad
• Código postal

Algunas funciones a nivel de estructura se tratan en guías de API independientes y más detalladas:

• Ausente y ETA: estado Ausente y ETA
• Energía: estado de eventos de energía
• Seguridad: Disuasión y seguridad

Permisos de estructura

Para acceder a...	Selecciona…
La mayoría de los valores de datos del objeto structures	Permisos Ausente, ETA, Energía o Código postal
El valor de datos name en el objeto structures	Permiso de estructura de lectura y escritura

Consulta el funcionamiento de los permisos en la referencia interactiva de la API.

Identificadores de la estructura

Nombre

El nombre predeterminado de la estructura es "Home", pero puede ser cualquier string que elija el usuario. Cuando eliges el permiso Estructura de lectura y escritura, puedes cambiar la estructura name.

Dónde

wheres es un objeto establecido en una estructura, que contiene los identificadores de ubicación (where_id y name). Usa wheres para crear nombres personalizados de nombres o accede a esos nombres estándar.

El acceso al objeto wheres requiere permisos de Cámara, Alarma de humo + CO o Termostato.

where_id

• Un identificador único generado por Nest que representa a name
• where_id es de solo lectura y se crea de forma automática en la llamada para crear una instancia personalizada. name

name

• El nombre visible del dispositivo; puede ser cualquier nombre de habitación de la lista que proporcionamos, o un nombre personalizado
• Para crear un personalizado en el que name, realiza una llamada POST a fin de escribir uno nuevo, en el que name se muestra where_id en la llamada
• Consideraciones
  • No se puede editar ni borrar name después de crearlo
  • name debe ser único en la estructura
  • Si un dispositivo está vinculado a una estructura, el personalizado en el que se puede acceder al name asociado con el dispositivo desde la ruta de acceso /structures/
  • Para mover un dispositivo con una ubicación personalizada en el que name a una estructura diferente, desvincula el dispositivo y, luego, vuelve a sincronizar el dispositivo con el nombre que quieras.

Obtén más información sobre los nombres de los termostatos Nest, los Nest Protects y las Nest Cams.

Otros metadatos

Todos los valores de datos son de solo lectura, a menos que se especifique lo contrario.

Valor de los datos	Descripción
structure_id	Es una string que representa de forma única esta estructura. Cada desarrollador verá un ID diferente para la misma estructura, pero varios productos del mismo desarrollador verán el mismo ID.
country_code	Un código de país ISO 3166-1 alpha-2 que se asigna a la ubicación registrada de la estructura
postal_code	Código postal, según el país
time_zone	Una string de zona horaria de IANA que se asigna a la zona horaria de la estructura

Características de la estructura

Estados de la alarma de humo y monóxido de carbono

Cuando eliges Permiso de lectura de humo y monóxido de carbono, puedes acceder a smoke_alarm_state y co_alarm_state en el objeto structures. Estos mismos valores de datos también están disponibles en el objeto del dispositivo (devices/smoke_co_alarms).

Consulta la guía de la alarma de humo/monóxido de carbono para obtener más información sobre estos estados.

Restricciones relacionadas con la estructura

Muchos valores de datos trabajan juntos para determinar el comportamiento de los dispositivos en una estructura.

• Cuando se establece un estado away de estructura en away, se muestra la palabra "ECO" en el Nest Thermostat, en el idioma preferido del usuario.
• Cuando un estado de estructura away se establece en away, puedes hacer lo siguiente:
  • establecer fan_timer_active
  • cambiar target_temperature_f o target_temperature_c
• Cuando un estado de estructura away se establece en home, puedes hacer lo siguiente:
  • hacer una llamada de ETA (establecer ID de viaje y período de llegada)
• Cuando el Corte de emergencia está activo, no puedes establecer fan_timer_active.
• Cuando está habilitada la opción Calefactor de emergencia, no puedes establecer la estructura en away

Varias estructuras

Es posible que un usuario tenga más de una estructura adjunta a su cuenta de Nest, por lo que tu producto debe ofrecer un medio para que el usuario elija una de las estructuras disponibles (un selector de estructura).

Por ejemplo, cuando se configura el ETA, es importante que el usuario pueda elegir una estructura para el destino del ETA. De manera similar, un usuario podría tener dos detectores de humo en la "sala de estar" de dos casas diferentes. Si necesitas correlacionar la estructura con tu concepto de casa, te recomendamos que lo hagas durante el proceso de autorización.

Obtén más información sobre cómo los usuarios administran los dispositivos en varias estructuras.

Máximos de dispositivos

Existen límites para la cantidad de dispositivos que admite Nest en una estructura.

Tipo de dispositivo	Máximo por estructura
Nest Thermostat	20
Cámaras Nest	10
Nest Protect	18

Mensajes de error

Para obtener más información sobre qué significan los errores de llamada a la API y cómo manejarlos, consulta Mensajes de error.