Estrutura

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

A API Nest fornece acesso aos dados no nível da estrutura a seguir, que dependem do nível de permissões concedidas:

• Estrutura do nome e do dispositivo: nome da empresa (local na casa)
• A lista de dispositivos da casa
• Status de evento de energia (hora de pico da 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 &ETA: estado "Ausente", ETA do usuário
• Energia: status de evento de energia
• Segurança: segurança e impedimento

Permissões de estrutura

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

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

Identificadores de estrutura

Nome

Por padrão, o nome da estrutura é ""Home", mas pode ser qualquer string escolhida pelo usuário. Ao escolher a permissão Estruturar leitura/gravação, é possível alterar a estrutura name.

Onde

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

O acesso ao objeto wheres requer permissões de câmera, alarme de fumaça+CO ou termostato.

where_id

• Um identificador exclusivo gerado pelo Nest que representa name.
• where_id é somente leitura e criado automaticamente na chamada para criar um personalizado onde 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 onde name, faça uma chamada POST para gravar um novo personalizado em que name. O where_id é retornado na chamada
• Considerações
  • Não é possível editar ou excluir o domínio name após a criação
  • A name precisa ser exclusiva na estrutura
  • Se um dispositivo estiver pareado com uma estrutura, o personalizado onde o name associado ao dispositivo será acessível pelo caminho /structures/
  • Para mover um dispositivo com um name personalizado para uma estrutura diferente, pareie o dispositivo e depois faça o pareamento novamente com o nome escolhido.

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

Outros metadados

Todos os valores de dados são somente leitura, salvo especificação em contrário.

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

Recursos da estrutura

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

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

Consulte o guia de alarme do Smoke+CO para ver mais informações 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 é definido como away, a palavra "ECO" é exibida no Nest Thermostat, no idioma preferencial do usuário.
• Quando um estado away da estrutura é definido como away, você pode:
  • Definir fan_timer_active
  • mudar target_temperature_f ou target_temperature_c
• Quando um estado away da estrutura é definido como home, você pode:
  • Fazer uma chamada de HEC (definir o ID da viagem e a janela de chegada)
• Quando a desligamento de emergência estiver ativa, não será 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 vinculada à conta Nest. Portanto, seu produto precisa oferecer uma forma de o usuário escolher entre as estruturas disponíveis (seletor de estrutura).

Por exemplo, ao definir o HEC, é importante que o usuário escolha uma estrutura para o destino do HEC. Da mesma forma, 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 os dispositivos em várias estruturas.

Máximo de dispositivos

Há limites para o número de dispositivos compatíveis com o Nest em uma estrutura.

Tipo de dispositivo	Máximo por estrutura
Termostato Nest	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.