Automação Deep Link

As automações deep link permitem criar automações de API REST mediante programação usando esquemas de URL. Isto é ideal para scripts de automação, gestão de configuração ou integração com sistemas externos que precisam configurar exportações de dados de saúde.

Visão Geral

As automações deep link usam um esquema de URL personalizado para criar e configurar automações de API REST sem inserir manualmente as configurações na aplicação. Quando abre uma URL deep link, a aplicação cria automaticamente uma nova automação com a configuração especificada.

Casos de Uso:

• Configuração programática de automações a partir de scripts ou ferramentas
• Configuração em massa de automações
• Integração com sistemas de gestão de configuração
• Configuração rápida a partir de aplicaçãos ou sites externos
• Fluxos de trabalho de teste e desenvolvimento

Recursos Principais:

• Criar automações via esquema de URL
• Configurar todas as configurações de automação de API REST
• Validação de parâmetros com segurança de tipos
• Mensagens de erro completas

Limitações

• Os deep links suportam apenas automações de API REST (não Dropbox, Google Drive, etc.)
• Os limites de comprimento de URL podem restringir listas de parâmetros muito longas
• Todas as limitações das automações de API REST se aplicam (processamento em segundo plano, acesso a dados de saúde, etc.)

Formato de URL

A URL deep link segue esta estrutura:

com.HealthExport://automation?parameter1=value1&parameter2=value2&...

URL Base: com.HealthExport://automation

Parâmetros: Todos os parâmetros são opcionais, exceto name e url. Os parâmetros não diferenciam maiúsculas de minúsculas.

Referência de Parâmetros

Parâmetros Obrigatórios

url (obrigatório)

• Tipo: String (URL válida)
• Descrição: A URL do endpoint onde os dados de saúde serão enviados
• Exemplo: https://api.example.com/health-data
• Nota: Deve ser uma URL HTTP/HTTPS válida

name (obrigatório)

• Tipo: String
• Descrição: Um nome descritivo para a automação
• Exemplo: My%20Backend%20API (codificado em URL: "My Backend API")
• Nota: Deve ser codificado em URL se contiver espaços ou caracteres especiais

Configuração Básica

format

• Tipo: Enum (json, csv)
• Padrão: json
• Descrição: Formato de exportação para os dados
• Exemplo: format=json ou format=csv
• Nota: O formato CSV habilita automaticamente a agregação de dados

enabled

• Tipo: Boolean (true, false, 1, 0, yes, no)
• Padrão: false
• Descrição: Se a automação está habilitada imediatamente após a criação
• Exemplo: enabled=true

datatype

• Tipo: Enum (veja Tipos de Dados abaixo)
• Padrão: healthMetrics
• Descrição: Tipo de dados de saúde a exportar
• Exemplo: datatype=workouts
• Nota: Apenas um tipo de dados pode ser selecionado. Definir isso configura automaticamente os sinalizadores de inclusão apropriados.

Tipos de Dados Válidos:

• healthMetrics - Métricas de saúde (passos, frequência cardíaca, sono, etc.)
• workouts - Atividades de exercício e fitness
• symptoms - Sintomas e condições de saúde
• ecg - Leituras de eletrocardiograma
• heartRateNotification - Eventos de frequência cardíaca alta/baixa
• stateOfMind - Entradas de humor e estado mental (iOS 18.0+)
• cycleTracking - Dados do ciclo menstrual e saúde reprodutiva
• medications - Registros de medicamentos e aderência (iOS 26.0+)

Configurações de Exportação

period

• Tipo: Enum
• Padrão: none
• Descrição: Intervalo de datas para exportação de dados
• Exemplo: period=today

Valores Válidos:

• none - Padrão (dia anterior completo mais dia atual)
• lastsync - Desde a última sincronização
• today - Dia atual
• yesterday - Dia anterior
• previous7days - Últimos 7 dias
• realtime - Atualizações em tempo real (requer intervalo de sincronização em segundos)

interval

• Tipo: Enum
• Padrão: none
• Descrição: Intervalo de agrupamento/agregação de tempo (válido apenas para o tipo de dados healthMetrics)
• Exemplo: interval=hours

Valores Válidos:

• none - Padrão (sem agregação)
• minutes - Agrupar por minuto
• hours - Agrupar por hora
• days - Agrupar por dia
• weeks - Agrupar por semana
• months - Agrupar por mês
• years - Agrupar por ano

Nota: Este parâmetro é válido apenas quando datatype=healthMetrics. O formato CSV sempre agrega dados.

aggregatedata

• Tipo: Boolean
• Padrão: true (para CSV), false (para JSON)
• Descrição: Se deve agregar/resumir dados (válido apenas para healthMetrics com formato JSON)
• Exemplo: aggregatedata=true
• Nota: Definido automaticamente como true quando format=csv

aggregatesleep

• Tipo: Boolean
• Padrão: true
• Descrição: Se deve agregar dados de sono
• Exemplo: aggregatesleep=true

exportversion

• Tipo: Enum (v1, v2, 1, 2)
• Padrão: v2
• Descrição: Versão do formato de exportação
• Exemplo: exportversion=v2
• Nota: A versão 2 inclui dados de treino aprimorados e metadados mais detalhados

batchrequests

• Tipo: Boolean
• Padrão: false
• Descrição: Enviar dados em lotes em várias solicitações (válido apenas para API REST com formato JSON)
• Exemplo: batchrequests=true
• Nota: Válido apenas quando format=json e exportDestination=restApi

Cadência de Sincronização

syncinterval

• Tipo: Enum
• Padrão: minutes
• Descrição: Intervalo para a cadência de sincronização
• Exemplo: syncinterval=hours

Valores Válidos:

• minutes - Sincronizar a cada N minutos
• hours - Sincronizar a cada N horas
• days - Sincronizar a cada N dias
• weeks - Sincronizar a cada N semanas
• seconds - Válido apenas quando period=realtime

Nota: Para automações de API REST, apenas minutes, hours, days e weeks são válidos, a menos que seja usado exportação em tempo real.

syncquantity

• Tipo: Integer (positivo)
• Padrão: 5
• Descrição: Número de intervalos entre sincronizações
• Exemplo: syncquantity=10 (sincronizar a cada 10 minutos se syncinterval=minutes)
• Nota: Deve ser maior que 0

Configuração HTTP

headers

• Tipo: String (pares chave-valor separados por vírgula)
• Padrão: Nenhum
• Descrição: Cabeçalhos HTTP para autenticação ou metadados
• Exemplo: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Formato: key1,value1,key2,value2,...
• Nota: Os valores devem ser codificados em URL. Cada cabeçalho requer tanto uma chave quanto um valor.

Exemplos de Cabeçalhos:

• Authorization, Bearer your-token
• X-API-Key, your-api-key
• Content-Type, application/json

requesttimeout

• Tipo: Integer (60-86400)
• Padrão: 60
• Descrição: Timeout da solicitação em segundos
• Exemplo: requesttimeout=300
• Nota: Deve estar entre 60 e 86400 segundos (1 minuto a 24 horas)

Configurações Específicas do Tipo de Dados

Configurações de Métricas de Saúde

metrics

• Tipo: String (valores rawValues MetricName separados por vírgula)
• Padrão: Todas as métricas disponíveis
• Descrição: Métricas de saúde específicas a incluir (válido apenas para o tipo de dados healthMetrics)
• Exemplo: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Nota: Deve usar valores rawValues exatos de MetricName. Se não especificado, todas as métricas disponíveis são incluídas.

Nomes de Métricas Comuns:

• Step Count
• Heart Rate
• Active Energy
• Apple Exercise Time
• Sleep Analysis
• Walking + Running Distance

Consulte o ecrã de seleção de métricas da aplicação para a lista completa de métricas disponíveis.

Configurações de Treinos

includeroutes

• Tipo: Boolean
• Padrão: true
• Descrição: Incluir dados de rota para treinos (válido apenas para o tipo de dados workouts)
• Exemplo: includeroutes=true

includeworkoutmetadata

• Tipo: Boolean
• Padrão: true
• Descrição: Incluir métricas de treino (frequência cardíaca, calorias, etc.) coletadas durante os treinos (válido apenas para o tipo de dados workouts)
• Exemplo: includeworkoutmetadata=true

workoutsmetadatainterval

• Tipo: Enum (minutes, seconds)
• Padrão: minutes
• Descrição: Agrupamento de tempo para métricas de treino (válido apenas para o tipo de dados workouts com exportVersion v2)
• Exemplo: workoutsmetadatainterval=seconds
• Nota: Válido apenas quando datatype=workouts e exportversion=v2

workouttypes

• Tipo: String (valores UInt separados por vírgula)
• Padrão: Vazio (todos os tipos de treino)
• Descrição: Tipos de treino específicos a incluir (válido apenas para o tipo de dados workouts)
• Exemplo: workouttypes=1,2,3
• Nota: Usa identificadores de tipo de treino do HealthKit

Notificações

notifyonupdate

• Tipo: Boolean
• Padrão: true
• Descrição: Receber notificações quando os dados em cache forem atualizados
• Exemplo: notifyonupdate=true

notifywhenrun

• Tipo: Boolean
• Padrão: true
• Descrição: Receber notificações sempre que a automação for executada
• Exemplo: notifywhenrun=false

Exemplos

Automação Básica de API REST

com.HealthExport://automation?url=https://api.example.com/health&name=My%20Automation&format=json&enabled=true

Cria uma automação básica que envia dados JSON para o endpoint especificado.

Com Cabeçalhos de Autenticação

com.HealthExport://automation?url=https://api.example.com/health&name=Authenticated%20API&format=json&headers=Authorization,Bearer%20your-token-here,X-API-Key,abc123&enabled=true

Cria uma automação com cabeçalhos de autenticação personalizados.

Métricas de Saúde com Métricas Específicas

com.HealthExport://automation?url=https://api.example.com/metrics&name=Steps%20and%20Heart%20Rate&format=json&datatype=healthMetrics&metrics=Step%20Count,Heart%20Rate&aggregatedata=true&interval=hours&enabled=true

Cria uma automação que exporta apenas passos e frequência cardíaca, agregados por hora.

Treinos com Dados de Rota

com.HealthExport://automation?url=https://api.example.com/workouts&name=Workout%20Export&format=json&datatype=workouts&includeroutes=true&includeworkoutmetadata=true&exportversion=v2&workoutsmetadatainterval=minutes&enabled=true

Cria uma automação para treinos com dados de rota e métricas de treino, usando a versão de exportação 2.

Exemplo de Configuração Completa

com.HealthExport://automation?url=https://api.example.com/health-data&name=Complete%20Configuration&format=json&datatype=healthMetrics&period=today&interval=hours&aggregatedata=true&aggregatesleep=true&exportversion=v2&syncinterval=hours&syncquantity=2&headers=Authorization,Bearer%20token123&requesttimeout=300&batchrequests=true&notifyonupdate=true&notifywhenrun=false&enabled=true

Um exemplo abrangente com todos os principais parâmetros configurados.

Exemplo de Formato CSV

com.HealthExport://automation?url=https://api.example.com/csv&name=CSV%20Export&format=csv&datatype=healthMetrics&period=yesterday&enabled=true

Cria uma automação de exportação CSV. Observe que o formato CSV habilita automaticamente a agregação de dados.

Codificação de URL

Caracteres especiais nos valores dos parâmetros devem ser codificados em URL. Codificações comuns:

• Espaço: %20
• Vírgula: %2C
• Dois pontos: %3A
• Ponto e vírgula: %3B
• Igual: %3D
• E comercial: %26
• Mais: %2B

Exemplo:

• Original: My Automation Name
• Codificado: My%20Automation%20Name

Exemplo de Cabeçalhos:

• Original: Authorization, Bearer token123
• Codificado: Authorization,Bearer%20token123

A maioria das linguagens de programação e ferramentas fornece funções de codificação de URL:

• Swift: addingPercentEncoding(withAllowedCharacters:)
• JavaScript: encodeURIComponent()
• Python: urllib.parse.quote()

Testando Deep Links

Do Safari (iOS)

1. Abra o Safari no seu dispositivo iOS
2. Introduza a URL deep link na barra de endereços
3. Toque em Ir
4. A aplicação deve abrir e criar a automação

Do Terminal (macOS/Simulador iOS)

xcrun simctl openurl booted "com.HealthExport://automation?url=https://api.example.com/health&name=Test&enabled=true"

Do Xcode

Adicione um ponto de interrupção ou use o console do depurador:

let url = URL(string: "com.HealthExport://automation?url=https://api.example.com/health&name=Test&enabled=true")!
try DataModel.shared.handleAPIDeepLink(url)

Da Aplicação Atalhos

1. Crie um novo atalho
2. Adicione a ação "Abrir URLs"
3. Introduza a sua URL deep link
4. Execute o atalho

Solução de Problemas

Problemas Comuns

"Não foi possível analisar a URL"

• Verifique se o esquema de URL está correto: com.HealthExport://automation
• Verifique se todos os valores dos parâmetros estão corretamente codificados em URL
• Certifique-se de que os nomes dos parâmetros estão escritos corretamente (não diferencia maiúsculas de minúsculas)

"Valor de parâmetro de URL inválido"

• Verifique se a URL é uma URL HTTP/HTTPS válida
• Verifique a codificação de URL adequada
• Certifique-se de que a URL não contém caracteres inválidos

"Tipo de dados inválido"

• Use valores exatos do tipo de dados: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Verifique a ortografia e maiúsculas/minúsculas (embora a correspondência sem diferenciação de maiúsculas e minúsculas seja suportada)

"Intervalo de cadência de sincronização inválido"

• Para API REST, use apenas: minutes, hours, days, weeks
• Use seconds apenas quando period=realtime

"As configurações de agregação são válidas apenas para o tipo de dados healthMetrics"

• Os parâmetros aggregatedata e interval funcionam apenas com datatype=healthMetrics
• Remova esses parâmetros ou altere o tipo de dados

"Solicitações em lote são válidas apenas para API REST com formato JSON"

• batchrequests funciona apenas quando format=json
• Altere o formato para JSON ou remova o parâmetro batchrequests

"As configurações de treino são válidas apenas para o tipo de dados workouts"

• includeroutes, includeworkoutmetadata e workoutsmetadatainterval funcionam apenas com datatype=workouts
• Altere o tipo de dados para workouts ou remova esses parâmetros

"O parâmetro metrics é válido apenas para o tipo de dados healthMetrics"

• O parâmetro metrics funciona apenas com datatype=healthMetrics
• Altere o tipo de dados ou remova o parâmetro metrics

"Nome de métrica inválido"

• Use valores rawValues exatos de MetricName (por exemplo, "Step Count", "Heart Rate")
• Verifique a ortografia e capitalização
• Consulte o ecrã de seleção de métricas da aplicação para nomes válidos

"Timeout de solicitação inválido"

• Deve estar entre 60 e 86400 segundos
• Use um valor dentro desse intervalo

"Um nome é obrigatório para a automação"

• Certifique-se de que o parâmetro name está incluído
• Verifique se o valor não está vazio após a decodificação da URL

Limitações de Comprimento de URL

URLs muito longas (especialmente com muitas métricas ou cabeçalhos) podem exceder os limites do sistema. Considere:

• Usar menos métricas no parâmetro metrics
• Reduzir o número de cabeçalhos
• Usar valores de parâmetros mais curtos quando possível
• Dividir configurações complexas em várias automações mais simples

Precedência de Parâmetros

Quando vários parâmetros entram em conflito:

1. A seleção do tipo de dados (datatype) redefine automaticamente os sinalizadores de inclusão
2. O formato CSV (format=csv) define automaticamente aggregatedata=true
3. O período em tempo real (period=realtime) requer syncinterval=seconds
4. Erros de validação serão lançados para combinações incompatíveis

Melhores Práticas

1. Sempre codifique em URL os valores dos parâmetros que contenham caracteres especiais
2. Teste com URLs simples primeiro, depois adicione complexidade
3. Use nomes descritivos para facilitar a identificação
4. Valide URLs antes de criar deep links mediante programação
5. Trate erros com elegância ao analisar deep links
6. Documente seus formatos de deep link se estiver criando ferramentas que os geram
7. Considere o comprimento da URL ao incluir muitas métricas ou cabeçalhos
8. Teste em dispositivos reais além de simuladores

Documentação Relacionada

• Guia de Automação de API REST - Informações detalhadas sobre automações de API REST
• Visão Geral de Automações - Conceitos gerais de automação
• Guia de Exportação Manual - Como exportar dados manualmente

Suporte

Se você encontrar problemas não cobertos neste guia:

1. Verifique a mensagem de erro para problemas específicos de parâmetros
2. Verifique se sua codificação de URL está correta
3. Teste com uma URL mínima primeiro
4. Use o botão Suporte por Chat na aplicação para obter ajuda