Estrutura

As estruturas do Nest representam estruturas físicas no mundo real. Normalmente, a casa de um usuário serve como um ponto de organização para os dispositivos e armazena dados aplicáveis a toda a casa.

A API Nest fornece acesso aos seguintes dados no nível da estrutura, dependendo do nível de permissões concedidas:

• Nome da estrutura e do dispositivo "onde nome" (local na casa)
• Lista de dispositivos na casa
• Status do evento de energia (hora de pico de energia)
• Estado "Ausente"
• HEC do usuário
• Estado de segurança
• Código postal ou CEP

Alguns recursos no nível da estrutura são abordados em guias de API separados e mais detalhados:

• Ausente e HEC: estado "Ausente", HEC do usuário
• Energy: status de evento de energia
• Segurança: segurança e impedimento

Permissões da estrutura

Para acessar...	Selecionar...
A maioria dos valores de dados no objeto structures	Permissões Ausente, ETA, Energia ou Código postal
O valor de dados name no objeto structures	Permissão de leitura/gravação da estrutura

Veja como as permissões funcionam na Referência da API interativa.

Identificadores da estrutura

Nome

O nome da estrutura assume como padrão "Home", mas pode ser qualquer string escolhida pelo usuário. Ao escolher a permissão Estruturar leitura/gravação, você pode alterar a estrutura name.

Onde

wheres é um objeto definido em uma estrutura que contém identificadores de localização (where_id e name). Use wheres para criar nomes de locais personalizados ou acessar nomes de locais padrão.

O acesso ao objeto wheres requer as permissões Camera, Smoke+CO Alarm ou Thermostat.

where_id

• Um identificador exclusivo gerado pelo Nest que representa name.
• where_id é somente leitura e é criado automaticamente na chamada para criar um personalizado em que name.

name

• O nome de exibição do dispositivo. Pode ser qualquer nome de ambiente de uma lista fornecida ou um nome personalizado.
• Para criar um personalizado em que name, faça uma chamada POST para escrever um novo e personalizado em que name. O where_id é retornado na chamada
• Considerações
  • Não é possível editar ou excluir name após a criação
  • name precisa ser exclusivo na estrutura
  • Se um dispositivo estiver pareado com uma estrutura, o personalizado em que name associado ao dispositivo vai poder ser acessado pelo caminho /structures/
  • Para mover um dispositivo com um personalizado em que name para uma estrutura diferente, pareie o dispositivo e pareie novamente com o nome desejado.

Saiba mais sobre os nomes da Nest Thermostats, Nest Protects e Nest Cams.

Outros metadados

Todos os valores de dados são somente leitura, a menos que seja especificado de outra forma.

Valor dos dados	Descrição
structure_id	Uma string que representa exclusivamente essa estrutura. Todos os desenvolvedores verão um ID diferente para a mesma estrutura, mas vários produtos do mesmo desenvolvedor verão o mesmo código.
country_code	Um código de país ISO 3166-1 alfa-2 que mapeia para o local registrado da estrutura
postal_code	CEP ou código postal, dependendo do país
time_zone	Uma string de fuso horário da IANA (em inglês) que é mapeada para o fuso horário da estrutura.

Recursos de estrutura

Estados de alarme de fumaça e monóxido de carbono

Ao escolher a permissão de leitura do Smoke+CO, é possível acessar smoke_alarm_state e co_alarm_state no objeto structures. Esses mesmos valores de dados também estão disponíveis no objeto de dispositivo (devices/smoke_co_alarms).

Consulte o guia de alarme do Smoke+CO para saber mais sobre esses estados.

Restrições relacionadas à estrutura

Muitos valores de dados funcionam juntos para determinar como os dispositivos se comportam em uma estrutura.

• Quando um estado away da estrutura estiver definido como away, a palavra "ECO" será exibida no Nest Thermostat no idioma preferido do usuário
• Quando um estado away da estrutura é definido como away, é possível:
  • Definir fan_timer_active
  • mudar target_temperature_f ou target_temperature_c
• Quando um estado away da estrutura é definido como home, é possível:
  • Fazer uma chamada de HEC (definir o ID da viagem e o horário de chegada)
• Quando a desativação de emergência está ativa, não é possível definir fan_timer_active.
• Quando o aquecimento de emergência está ativado, não é possível definir a estrutura como away

Várias estruturas

É possível que um usuário tenha mais de uma estrutura anexada à conta do Nest. Por isso, o produto precisa oferecer um meio para o usuário escolher entre as estruturas disponíveis (um seletor de estrutura).

Por exemplo, ao definir o ETA, é importante que o usuário possa escolher uma estrutura para o destino do ETA. De maneira semelhante, um usuário pode ter dois detectores de fumaça na "sala de estar" de duas casas diferentes. Se você precisar fazer correlação de estrutura com seu próprio conceito de casa, recomendamos que faça isso durante o processo de autorização.

Saiba como os usuários gerenciam dispositivos em várias estruturas.

Máximo de dispositivos

Há limites para quantos dispositivos o Nest oferece suporte em uma estrutura.

Tipo de dispositivo	Máximo por estrutura
Nest Thermostat	20
Câmeras Nest	10
Nest Protect	18

Mensagens de erro

Para mais informações sobre o que significam erros de chamada de API e como lidar com eles, consulte Mensagens de erro.