Sincronizzare i dati di Apple Health con 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 sono autorizzate ad accedere ai dati sanitari mentre l'iPhone è bloccato. Le automazioni verranno eseguite solo durante i periodi in cui il dispositivo è sbloccato. Questo può influire sulla freschezza dei dati. Consulta le istruzioni per la sincronizzazione manuale per mantenere i dati aggiornati.

• Elaborazione in background: iOS limita l'elaborazione in background per preservare la durata della batteria. Le automazioni dipendono dall'Aggiornamento app in background e potrebbero non essere eseguite immediatamente se:

  • L'Aggiornamento app in background è disabilitato per l'app
  • Il dispositivo è in Modalità risparmio energetico
  • Il dispositivo è stato inattivo per periodi prolungati
  • Le risorse di sistema sono limitate
  • Più app competono per il tempo di esecuzione in background

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

Quando si utilizza il formato JSON, attiva Richieste batch per inviare dati in batch su più richieste invece di un singolo payload.

• ATTIVO - Distribuisce i dati su più richieste per evitare payload eccessivamente grandi
• DISATTIVO - Invia tutti i dati in una singola richiesta

Frequenza sincronizzazione

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

Seleziona un numero e un intervallo.

Test e verifica

Test manuali

1. Tocca "Esportazione manuale" nella schermata di configurazione dell'automazione
2. Seleziona un intervallo di date
3. Tocca "Esporta" per inviare una richiesta di test
4. Controlla il tuo endpoint per verificare che i dati siano stati ricevuti

Visualizzazione log attività

1. Tocca "Visualizza log attività" nella schermata di configurazione dell'automazione
2. Rivedi le esecuzioni recenti dell'automazione
3. Controlla eventuali errori o avvisi
4. Verifica timestamp delle richieste e stato della risposta

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. Prestazioni:

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

2. Affidabilità:

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

3. 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