Guida all’automazione REST API

Le automazioni REST API ti consentono di esportare automaticamente i tuoi dati sanitari a qualsiasi servizio web che accetta richieste HTTP POST. Questo è ideale per integrare con backend personalizzati, API di terze parti o webhook.

Panoramica

Le automazioni REST API inviano i tuoi dati sanitari a un endpoint URL specificato utilizzando richieste HTTP POST. L'automazione può inviare dati in formato JSON o CSV, con intestazioni configurabili per l'autenticazione e metadati personalizzati.

Casi d'uso:

• Integrazione con servizi backend personalizzati
• Invio di dati a webhook
• Sincronizzazione con API di terze parti
• Creazione di dashboard personalizzati o piattaforme di analisi

Caratteristiche principali:

• Supporta sia formati JSON che CSV
• Intestazioni HTTP personalizzate per l'autenticazione
• Timeout richiesta configurabile
• Esportazione manuale di dati storici

Limitazioni:

• Accesso ai dati sanitari: Le app non possono accedere ai dati sanitari mentre l’iPhone è bloccato. Le automazioni vengono eseguite solo quando il dispositivo è sbloccato. È una limitazione imposta da Apple che non può essere aggirata. Maggiori informazioni

• Elaborazione in background: iOS limita l’elaborazione in background per preservare la batteria. Le automazioni dipendono dall’aggiornamento in background dell’app e potrebbero non essere eseguite subito se:

  • L’aggiornamento in background è disattivato per l’app
  • Il dispositivo è in modalità Risparmio energetico
  • Il dispositivo è rimasto inattivo per periodi prolungati
  • Le risorse di sistema sono limitate
  • Più app competono per il tempo di esecuzione in background

Prestazioni

Tieni presente che iOS è ottimizzato per attività di breve durazione su un dispositivo mobile con vincoli di prestazioni molto rigidi. Le attività in background devono in genere completarsi entro 30 secondi e sono limitate nella memoria utilizzabile. Health Auto Export offre un alto grado di flessibilità e personalizzazione, il che richiede tempo per capire come alcune configurazioni influenzano le prestazioni dell’app e i risultati.

• Configurazione: Le automazioni che producono grandi quantità di dati possono far terminare il processo da parte del sistema e impedire l’esecuzione in background. Le seguenti configurazioni possono produrre grandi quantità di dati:
  • Automazioni configurate per esportare tutte le metriche sanitarie.
    • Raccomandazione: seleziona solo le metriche sanitarie che hanno dati salvati in Apple Health e solo i dati che prevedi di usare. Anche i tipi di dati vuoti hanno un impatto sulle prestazioni. Puoi anche dividere le metriche selezionate in più automazioni, rendendo più facile il lavoro per il sistema.
  • Automazioni che usano raggruppamento temporale in secondi o minuti, o con Riepiloga dati disattivato. Query così dettagliate possono richiedere molto tempo e scontrarsi con i limiti del sistema.
    • Raccomandazione: anche se può sembrare ideale avere i dati più dettagliati possibile, valuta se quel livello di dettaglio è necessario per ogni metrica o tipo di dato. Considera più automazioni con impostazioni diverse.
  • Esportando allenamenti all’aperto, come ciclismo, corsa, escursionismo, ecc. con dati di percorso, GPS e metriche sanitarie associate possono produrre payload di grandi dimensioni.
• Dimensione del payload: Soprattutto con l’esportazione REST API, tieni conto che payload grandi possono causare errori del server. Assicurati che il backend sia configurato per gestire payload di possibilmente diverse centinaia di megabyte per evitare errori.
• Frequenza di sincronizzazione: Aggiungi il widget Automazioni alla schermata Home per favorire l’esecuzione corretta delle automazioni in background (vedi Guida alla configurazione del widget Automazioni).

Prerequisiti

• Un endpoint URL valido che accetta richieste HTTP POST
• Credenziali di autenticazione (se richieste dal tuo endpoint)
• Connettività di rete per raggiungere il tuo endpoint

Configurazione

Naviga alla schermata Esportazioni automatizzate dalla navigazione principale, quindi tocca "Nuova automazione" e seleziona "REST API" come Tipo di automazione.

Nome automazione

Inserisci un nome descrittivo per la tua automazione (ad esempio, "La mia API backend", "Integrazione webhook").

Notifiche

Configura quando desideri ricevere notifiche:

• Notifica all'aggiornamento cache - Ricevi una notifica quando i dati in cache vengono aggiornati
• Notifica quando viene eseguita - Ricevi una notifica ogni volta che l'automazione viene eseguita

Configurazione URL

Inserisci l'URL completo dove desideri inviare i tuoi dati sanitari. Questo dovrebbe essere un URL completo incluso il protocollo (http:// o https://).

URL di esempio:

• https://api.example.com/health-data
• https://webhook.site/your-unique-id
• http://localhost:3000/api/health

Nota: L'URL deve essere valido e accessibile dal tuo dispositivo. URL non validi impediranno l'esecuzione dell'automazione.

Timeout richiesta

Seleziona un intervallo di timeout per le richieste HTTP. Questo determina per quanto tempo l'app attenderà una risposta prima di considerare la richiesta fallita.

Intestazioni HTTP

Aggiungi intestazioni HTTP personalizzate per l'autenticazione o i metadati. I casi d'uso comuni includono:

• Chiavi API: X-API-Key: your-api-key
• Token di autorizzazione: Authorization: Bearer your-token
• Override del tipo di contenuto: Content-Type: application/json

Per aggiungere intestazioni:

1. Tocca "Aggiungi intestazioni"
2. Inserisci la chiave dell'intestazione nel campo sinistro
3. Inserisci il valore dell'intestazione nel campo destro
4. Ripeti per intestazioni aggiuntive

Importante: Ogni chiave di intestazione deve avere un valore corrispondente. Le intestazioni vuote verranno ignorate.

Impostazioni tipo di dati

Tipo di dati

Seleziona quale tipo di dati sanitari esportare:

• Metriche sanitarie - Passi, frequenza cardiaca, sonno e altre misurazioni sanitarie
• Allenamenti - Attività di esercizio e fitness
• Sintomi - Sintomi e condizioni sanitarie
• ECG - Letture di elettrocardiogramma
• Notifiche frequenza cardiaca - Eventi di frequenza cardiaca alta/bassa
• Stato mentale - Voci di umore e stato mentale (iOS 18.0+)
• Monitoraggio ciclo - Dati del ciclo mestruale e salute riproduttiva
• Farmaci - Registri dei farmaci e aderenza (iOS 26.0+)

Configurazione metriche sanitarie

Quando Metriche sanitarie è selezionato:

Seleziona metriche sanitarie - Scegli quali metriche specifiche includere. Puoi selezionare tutte le metriche disponibili o scegliere quelle specifiche.

Suggerimento: Selezionare solo le metriche di cui hai bisogno può migliorare il tempo di elaborazione e ridurre la dimensione dei dati.

Fonti preferite - Configura quali fonti di dati hanno priorità quando più fonti forniscono la stessa metrica.

Configurazione allenamenti

Quando Allenamenti è selezionato:

Includi dati percorso - Attiva per includere percorsi per gli allenamenti che hanno dati di posizione.

Includi metriche allenamento - Attiva per includere metriche sanitarie raccolte durante gli allenamenti (frequenza cardiaca, calorie, ecc.).

Raggruppamento temporale (metriche allenamento) - Quando si utilizza Versione esportazione 2 e Includi metriche allenamento è abilitato:

• Minuti - Raggruppa le metriche degli allenamenti per minuto
• Secondi - Raggruppa le metriche degli allenamenti per secondo

Impostazioni esportazione

Formato esportazione

Seleziona il formato per i tuoi dati esportati:

• Formato JSON - Fornisce strutture di dati dettagliate con oggetti annidati. Ideale per API, database e applicazioni che necessitano di dati strutturati. Il formato JSON include informazioni più dettagliate per tipi di dati complessi come fasi del sonno e letture AFib.

• Formato CSV - Fornisce dati tabulari che possono essere facilmente importati in applicazioni di fogli di calcolo. Ideale per analisi dati semplici o quando il tuo endpoint si aspetta dati CSV.

Nota: L'intestazione Content-Type viene automaticamente impostata su application/json per le esportazioni JSON e multipart/form-data per le esportazioni CSV.

Versione esportazione

Seleziona una Versione esportazione. Il versioning consente di passare tra versioni aggiornate dell'esportazione al proprio ritmo e minimizza le modifiche che interrompono i flussi di lavoro.

• Versione 1 - Formato legacy, usalo se hai flussi di lavoro esistenti che dipendono da questo formato
• Versione 2 - Formato attuale con dati di allenamento migliorati e opzioni di metadati più dettagliate

Intervallo date

Seleziona quando i dati devono essere esportati:

• Predefinito - Sincronizza i dati per l'intera giornata precedente più i dati fino alla data e ora correnti
• Dall'ultima sincronizzazione - Ad ogni sincronizzazione, esporta tutti i dati dall'ultima volta che l'esportazione è stata eseguita fino alla data e ora correnti
• Oggi - Sincronizza tutti i dati per la data corrente fino all'ora corrente
• Ieri - Sincronizza tutti i dati per l'intera giornata precedente
• Ultimi 7 giorni - Sincronizza i dati per gli ultimi sette giorni completi

Riassumi dati

Quando si utilizza il formato JSON con il tipo di dati Metriche sanitarie, attiva o disattiva Riassumi dati.

• ATTIVO - Fornisce riepiloghi di dati aggregati
• DISATTIVO - Fornisce dati disaggregati quando possibile, mostrando singoli punti dati

Nota: Questa impostazione si applica solo al formato JSON con Metriche sanitarie. I dati sono sempre aggregati quando si utilizza il formato CSV o quando sono selezionate più metriche.

Raggruppamento temporale

Quando si utilizza il formato JSON con Riassumi dati abilitato, seleziona come i dati devono essere aggregati.

Nota: Il formato CSV aggrega sempre i dati. L'aggregazione a livello di minuto e secondo può aumentare significativamente il tempo di elaborazione e la dimensione dei dati.

Richieste batch e payload di grandi dimensioni

Con il formato JSON, attiva Richieste batch per inviare i dati in più richieste HTTP invece di un unico payload grande.

• ATTIVO — Distribuisce i dati su più richieste. Usalo quando l’endpoint ha limiti di dimensione, timeout su corpi grandi o elabori i dati in modo incrementale.
• DISATTIVO — Invia tutti i dati in una singola richiesta. Adatto a esportazioni piccole e webhook semplici.

Quando abilitare il batch:

• Molte metriche sanitarie selezionate, intervalli di date lunghi o raggruppamento temporale fine (minuti/secondi)
• Riepiloga dati è DISATTIVO ed esporti metriche sanitarie disaggregate
• Il server restituisce errori o timeout su corpi POST grandi

Note:

• Le richieste batch si applicano solo a REST API + JSON (non CSV).
• Il batch riduce la dimensione per richiesta ma non elimina il recupero sul dispositivo; le query HealthKit lente possono ancora apparire come avvisi nei registri attività. Vedi Query lente nei registri attività.

Frequenza sincronizzazione

Configura con quale frequenza l'automazione deve caricare i dati:

Seleziona un numero e un intervallo.

Test e verifica

Verifica formato dati

L'app include automaticamente queste intestazioni in ogni richiesta:

• Content-Type - Impostato in base al formato di esportazione
• automation-name - Il nome della tua automazione
• automation-id - Identificatore univoco per l'automazione
• automation-aggregation - Il raggruppamento temporale selezionato
• automation-period - L'intervallo di date selezionato
• session-id - Identificatore univoco per ogni richiesta

Risoluzione problemi

Problemi comuni

Dati non ricevuti all'endpoint

• Verifica che l'URL dell'endpoint sia corretto
• Controlla che il tuo endpoint accetti richieste POST
• Rivedi le intestazioni di autenticazione
• Controlla i log dell'endpoint per le richieste in arrivo
• Verifica la connettività di rete

Suggerimenti e best practice

1. Sincronizzazione automatica:

   • Ricarica il dispositivo e usa Duplicazione iPhone
     • Durante la ricarica, iOS impone meno restrizioni sulle prestazioni, così i dati possono sincronizzarsi più spesso
     • Con Duplicazione iPhone, il dispositivo si comporta come se fosse sbloccato. Health Auto Export può così accedere ai dati sanitari per eseguire azioni automatizzate

2. Prestazioni:

   • Usa un raggruppamento temporale appropriato per bilanciare dettaglio vs. dimensione dei dati
   • Seleziona solo le metriche di cui hai bisogno

3. Affidabilità:

   • Imposta valori di timeout appropriati in base al tempo di risposta del tuo endpoint
   • Monitora regolarmente i log attività

4. Formato dati:

   • Usa JSON per dati strutturati e API
   • Usa CSV per analisi dati semplici o integrazione con fogli di calcolo
   • Considera richieste batch per grandi set di dati o elaborazione separata

Visualizzazione registri attività

1. Tocca Visualizza registri attività nella schermata di configurazione dell’automazione.
2. Esamina le esecuzioni (raggruppate, le più recenti per prime) ed espandi gli eventi in ogni esecuzione.
3. Distingui avvisi (ad es., query lenta dei dati sanitari) da errori (errori HTTP, timeout o errori di lettura HealthKit)—vedi Panoramica automazioni — Registri attività.
4. I caricamenti REST riusciti spesso mostrano un riepilogo con formato, tipo di dati, periodo di esportazione e intervallo di date nell’esecuzione.
5. Condividi (barra degli strumenti) esporta lo ZIP diagnostico completo dei Registri eventi dell’app per l’assistenza (come Impostazioni → Avanzate).
6. Cancella rimuove solo la cronologia attività di questa automazione.