Sincronizar dados do Apple Health com Home Assistant

As automações do Home Assistant permitem sincronizar automaticamente os seus dados de saúde com o Home Assistant como estados de sensores. Esta integração permite utilizar os seus dados de saúde em automações do Home Assistant, painéis e outras integrações.

Visão geral

As automações do Home Assistant enviam as suas métricas de saúde para a API REST do Home Assistant, criando ou atualizando estados de sensores que podem ser utilizados em toda a sua instância do Home Assistant. Os dados são formatados especificamente para a API /states/ do Home Assistant.

Casos de utilização:

• Exibir métricas de saúde nos painéis do Home Assistant
• Criar automações baseadas em dados de saúde
• Integrar dados de saúde com outros dispositivos de casa inteligente
• Acompanhar tendências de saúde ao longo do tempo no Home Assistant

Características principais:

• Criação automática de estados de sensores
• Apenas formato JSON (otimizado para Home Assistant)
• Apenas tipo de dados Health Metrics
• Configuração simples de URL

Limitações

• Acesso a dados de saúde: As aplicações não podem aceder a dados de saúde enquanto o iPhone está bloqueado. As automações serão executadas apenas durante os períodos em que o seu dispositivo estiver desbloqueado. Isto pode afetar a atualidade dos dados. Consulte as instruções para sincronização manual para manter os dados atualizados.

• Processamento em segundo plano: O iOS limita o processamento em segundo plano para preservar a vida útil da bateria. As automações dependem da Atualização de aplicações em segundo plano e podem não ser executadas imediatamente se:

  • A Atualização de aplicações em segundo plano estiver desativada para a aplicação
  • O dispositivo estiver em Modo de baixo consumo
  • O dispositivo estiver inativo por períodos prolongados
  • Os recursos do sistema estiverem limitados
  • Múltiplas aplicações estiverem a competir por tempo de execução em segundo plano

• Suporta apenas o tipo de dados Health Metrics

• Apenas formato JSON (não pode ser alterado)

Pré-requisitos

• Uma instância do Home Assistant em execução e acessível na sua rede
• Token de acesso à API do Home Assistant (Token de acesso de longa duração)
• Conectividade de rede à sua instância do Home Assistant
• Versão do Home Assistant que suporta a API REST

Configuração

Navegue até ao ecrã de Exportações automatizadas na navegação principal, depois toque em "Nova automação" e selecione "Home Assistant" como o Tipo de automação.

Nome da automação

Introduza um nome descritivo para a sua automação. Este nome será utilizado para gerar o ID da entidade do sensor no Home Assistant.

Nota: O nome da automação será convertido para minúsculas com espaços removidos para criar o ID da entidade. Por exemplo, "Os meus dados de saúde" torna-se hae.osmeusdadosdesaude.

Notificações

Configure quando deseja receber notificações:

• Notificar na atualização da cache - Receba uma notificação quando os dados em cache forem atualizados
• Notificar quando executar - Receba uma notificação sempre que a automação for executada

URL do Home Assistant

Introduza o URL base da sua instância do Home Assistant. Isto deve incluir o protocolo e a porta se não estiver a utilizar o padrão.

URLs de exemplo:

• http://homeassistant.local:8123
• http://192.168.1.100:8123

Nota: O URL deve ser acessível a partir do seu dispositivo. Se estiver a utilizar HTTPS, certifique-se de que o seu certificado é válido ou adicione uma exceção.

Endpoint gerado automaticamente

A aplicação gera automaticamente o endpoint completo da API com base no nome da sua automação:

{your_url}/api/states/hae.{automation_name}

Por exemplo, se o seu URL for http://homeassistant.local:8123 e o nome da sua automação for "Métricas de saúde", o endpoint será:

http://homeassistant.local:8123/api/states/hae.metricasdesaude

Este endpoint é exibido abaixo do campo URL para referência.

Tempo limite do pedido

Selecione um intervalo de tempo limite para pedidos HTTP ao Home Assistant.

Opções de tempo limite disponíveis:

• 60 segundos - Padrão, adequado para a maioria das instâncias do Home Assistant
• 300 segundos (5 minutos) - Para instâncias do Home Assistant mais lentas
• 1800 segundos (30 minutos) - Para processamento muito lento
• 3600 segundos (1 hora) - Tempo limite máximo recomendado

Cabeçalhos HTTP

Adicione cabeçalhos de autenticação para acesso à API do Home Assistant. Terá de adicionar um cabeçalho Authorization com o seu Token de acesso de longa duração.

Cabeçalho obrigatório:

• Authorization: Bearer YOUR_LONG_LIVED_ACCESS_TOKEN

Para obter um Token de acesso de longa duração:

1. Abra o Home Assistant
2. Vá ao seu perfil (clique no seu nome no canto inferior esquerdo)
3. Deslize para baixo até "Tokens de acesso de longa duração"
4. Clique em "Criar token"
5. Dê-lhe um nome (por exemplo, "Health Auto Export")
6. Copie o token e cole-o no campo de valor do cabeçalho

Cabeçalhos opcionais:
Pode adicionar cabeçalhos adicionais se necessário para a sua configuração do Home Assistant.

Para adicionar cabeçalhos:

1. Toque em "Adicionar cabeçalhos"
2. Introduza a chave do cabeçalho no campo esquerdo
3. Introduza o valor do cabeçalho no campo direito
4. Repita para cabeçalhos adicionais

Importante: Cada chave de cabeçalho deve ter um valor correspondente. Cabeçalhos vazios serão ignorados.

Configurações do tipo de dados

Tipo de dados

Nota: As automações do Home Assistant suportam apenas o tipo de dados Health Metrics. Esta configuração não pode ser alterada e é automaticamente definida como Health Metrics.

Configuração Health Metrics

Selecionar Health Metrics - Escolha quais métricas específicas incluir. Pode selecionar todas as métricas disponíveis ou escolher específicas.

Dica: Selecionar apenas as métricas de que precisa pode melhorar o tempo de processamento e reduzir o tamanho dos dados enviados ao Home Assistant.

Fontes preferidas - Configure quais fontes de dados têm prioridade quando várias fontes fornecem a mesma métrica.

Configurações de exportação

Formato de exportação

Nota: As automações do Home Assistant suportam apenas o formato JSON. Esta configuração não pode ser alterada e é automaticamente definida como JSON.

Versão de exportação

Nota: A versão de exportação não está disponível para automações do Home Assistant, pois o formato é otimizado especificamente para a API de estado do Home Assistant.

Intervalo de datas

Selecione quando os dados devem ser exportados:

• Padrão - Sincroniza dados do dia anterior completo mais dados até à data e hora atuais
• Hoje - Sincroniza todos os dados da data atual até à hora atual
• Ontem - Sincroniza todos os dados do dia anterior completo

Nota: As automações do Home Assistant não suportam as opções "Tempo real", "Desde a última sincronização" ou "Últimos 7 dias".

Resumir dados

Ative ou desative Resumir dados para Health Metrics.

• ON - Fornece resumos de dados agregados (padrão)
• OFF - Fornece dados desagregados quando possível

Nota: Esta configuração aplica-se apenas ao tipo de dados Health Metrics.

Agrupamento por tempo

Quando Resumir dados está ativado, selecione como os dados devem ser agregados:

• Padrão - Sem agregação, pontos de dados brutos
• Dias - Agrupa dados por dia (recomendado)

Frequência de sincronização

Configure com que frequência a automação deve sincronizar dados com o Home Assistant:

Selecione um número e intervalo.

Testes e verificação

Testes manuais

1. Toque em "Exportação manual" no ecrã de configuração da automação
2. Selecione um intervalo de datas
3. Toque em "Exportar" para enviar um pedido de teste
4. Verifique no Home Assistant se o estado do sensor foi criado/atualizado

Verificação no Home Assistant

1. Abra o Home Assistant
2. Vá para Ferramentas do programador > Estados
3. Procure por hae.{your_automation_name} (minúsculas, sem espaços)
4. Verifique se o estado do sensor mostra os seus dados de saúde
5. Verifique o timestamp "Última atualização" para confirmar sincronizações recentes

Visualizar registos de atividade

1. Toque em "Visualizar registos de atividade" no ecrã de configuração da automação
2. Revise as execuções recentes da automação
3. Verifique se há erros ou avisos
4. Verifique os timestamps dos pedidos e o estado da resposta

Verificação dos registos do Home Assistant

Se os dados não aparecerem no Home Assistant:

1. Abra o Home Assistant
2. Vá para Definições > Sistema > Registos
3. Procure erros relacionados com a API REST ou estados de sensores
4. Verifique erros de autenticação ou formato de dados inválido

Resolução de problemas

Problemas comuns

Erros de autenticação

• Verifique se o seu Token de acesso de longa duração está correto
• Certifique-se de que o cabeçalho Authorization está formatado como: Bearer YOUR_TOKEN
• Verifique se o token não expirou ou foi revogado
• Verifique se o token tem permissões apropriadas no Home Assistant

Sensor não aparecendo no Home Assistant

• Verifique se o nome da automação não contém caracteres especiais
• Verifique o formato do ID da entidade: hae.{automation_name} (minúsculas, sem espaços)
• Verifique os registos do Home Assistant para erros
• Certifique-se de que o pedido da API foi bem-sucedido (verifique os Registos de atividade)

Dados não atualizando

• Verifique se a automação está ativada
• Revise os Registos de atividade para erros
• Certifique-se da conectividade de rede com o Home Assistant

Tempo limite de ligação

• Verifique se o Home Assistant está em execução e acessível
• Verifique a conectividade de rede
• Aumente a configuração Tempo limite do pedido se o Home Assistant responder lentamente
• Verifique se o URL e a porta estão corretos

Mensagens de erro

A aplicação exibirá mensagens de erro se:

• O URL for inválido ou inacessível
• A autenticação falhar (verifique o cabeçalho Authorization)
• O Home Assistant retornar um código de estado de erro
• A conectividade de rede não estiver disponível

Verifique os Registos de atividade para obter informações detalhadas de erros, incluindo códigos de estado HTTP e mensagens de erro do Home Assistant.

Dicas de integração com Home Assistant

Utilizar dados de saúde em automações

Depois de os seus dados de saúde estarem sincronizados com o Home Assistant, pode utilizá-los em automações:

automation:
  - alias: "Boa qualidade do sono"
    trigger:
      - platform: numeric_state
        entity_id: sensor.hae_myhealthdata_sleep_total
        above: 7
    action:
      - service: notify.mobile_app_your_phone
        data:
          message: "Ótimo sono na noite passada!"

Criar painéis

Adicione métricas de saúde ao seu painel do Home Assistant:

1. Vá para o seu painel
2. Adicione um novo cartão
3. Selecione o tipo de cartão "Entidades" ou "Gauge"
4. Adicione as entidades de sensores hae.{your_automation_name}

Estrutura do estado do sensor

O estado do sensor no Home Assistant contém:

• state: O valor ou estado atual
• attributes: Dados adicionais incluindo:
  • Informações de timestamp
  • Estrutura de dados correspondente ao formato JSON exportado
  • Informações de unidades quando aplicável

Dicas e melhores práticas

1. Nomenclatura:

   • Evite caracteres especiais que possam causar problemas

2. Seleção de dados:

   • Selecione apenas as métricas de que precisa