
Estruturas de ninho representam estruturas físicas no mundo real. Normalmente a casa de um usuário, eles servem como um ponto de organização para dispositivos e armazenam dados que se aplicam a toda a casa.
A API Nest fornece acesso aos seguintes dados em nível de estrutura, dependendo do nível de permissões concedidas:
- Nome da estrutura e dispositivo "onde nome" (localização na casa)
- A lista de dispositivos em casa
- Status do evento de energia ( hora de pico de energia )
- Estado ausente
- ETA do usuário
- Estado de segurança
- CEP ou código postal
Alguns recursos de nível de estrutura são abordados em guias de API mais detalhados e separados:
- Ausente e ETA - estado ausente , ETA do usuário
- Energia - Status do evento de energia
- Segurança - segurança e dissuasão
Permissões de estrutura
Para acesso a ... | Selecione ... |
---|---|
A maioria dos valores de dados no objeto de structures | Permissões de Ausente , ETA , Energia ou Código Postal |
O valor dos dados do name no objeto de structures | Estrutura de permissão de leitura / gravação |
Veja como as permissões funcionam na Referência da API interativa .
Identificadores de estrutura
Nome
O nome da estrutura é padronizado como "Home", mas pode ser qualquer string que o usuário escolher. Quando você escolhe a permissão de leitura / gravação da estrutura, pode alterar o name
da estrutura.
Onde está a
wheres
é um objeto definido em uma estrutura, contendo identificadores where_id
( where_id
e name
). Use o wheres
para criar nomes where personalizados ou nomes onde padrão de acesso.
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 o
name
-
where_id
é somente leitura e é criado automaticamente na chamada para criar umname
where personalizado
name
- O nome de exibição do dispositivo; pode ser qualquer nome de sala de uma lista que fornecemos ou um nome personalizado
- Para criar um personalizado, onde
name
, fazer uma chamada POST para escrever um novo, costume, ondename
; owhere_id
é retornado na chamada - Considerações
-
name
não pode ser editado ou excluído após a criação -
name
deve ser único dentro da estrutura - Se um dispositivo estiver emparelhado com uma estrutura, o
name
personalizado onde oname
associado ao dispositivo pode ser acessado em/structures/
path - Para mover um dispositivo com um
name
onde personalizado para uma estrutura diferente, desemparelhe o dispositivo e volte a emparelhar o dispositivo com o nome desejado
-
Saiba mais sobre os nomes dos termostatosNest ,Nest Protects e Nest Cams .
Outros metadados
Todos os valores de dados são somente leitura, a menos que especificado de outra forma.
Valor de Dados | Descrição |
---|---|
structure_id | Uma string que representa com exclusividade 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 | CEP ou código postal, dependendo do país |
time_zone | Uma string de fuso horário da IANA que mapeia para o fuso horário da estrutura |
Recursos de estrutura
Estados de alarme de fumaça e CO
Quando você escolhe a permissão de leitura Smoke + CO , pode acessar smoke_alarm_state
e co_alarm_state
no objeto de 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 Smoke + CO para obter mais informações sobre esses estados.
Restrições relacionadas à estrutura
Muitos valores de dados trabalham juntos para determinar como os dispositivos se comportam em uma estrutura.
- Quando um estado de estrutura
away
é definido comoaway
a palavra "ECO" é exibida no Nest Thermostat, no idioma de preferência do usuário - Quando um estado de estrutura
away
é definido comoaway
, você pode:- definir
fan_timer_active
- alterar
target_temperature_f
outarget_temperature_c
- definir
- Quando um estado de estrutura
away
é definido comohome
, você pode:- fazer uma chamada ETA (definir id de viagem e janela de chegada)
- Quando o desligamento de emergência está ativo, você não pode definir
fan_timer_active
- Quando o aquecimento de emergência está ativado, você não pode definir a estrutura para
away
Estruturas múltiplas
É possível que um usuário tenha mais de uma estrutura anexada à conta Nest, então seu produto deve oferecer um meio para o usuário escolher entre as estruturas disponíveis (um seletor de estrutura).

Por exemplo, ao configurar o ETA, é importante que o usuário possa escolher uma estrutura para o destino do ETA. De maneira semelhante, um usuário poderia ter dois detectores de fumaça na "sala de estar" de duas casas diferentes. Se você precisar fazer a correlação de estrutura com seu próprio conceito de casa, recomendamos que faça isso durante o processo de autorização.
Aprenda como os usuários gerenciam dispositivos em várias estruturas .
Máximo do dispositivo
Existem limites para a quantidade de dispositivos que o Nest suporta em uma estrutura.
Tipo de dispositivo | Máx por estrutura |
---|---|
Nest Thermostat | 20 |
Câmeras Nest | 10 |
Nest Protect | 18 |
Mensagens de erro
Para obter informações sobre o que significam os erros de chamada de API e como lidar com eles, consulte Mensagens de erro .