Sincronizare date Apple Health cu REST API

Trimiteți date de sănătate către un endpoint REST API.

Last updated: June 9, 2026

Pe această pagină

Ghid de automatizare REST API

Automatizările REST API vă permit să exportați automat datele de sănătate către orice serviciu web care acceptă cereri HTTP POST. Este potrivit pentru integrarea cu backend-uri personalizate, API-uri terțe sau webhook-uri.

Prezentare generală

Automatizările REST API trimit datele de sănătate către un URL specificat folosind cereri HTTP POST. Automatizarea poate trimite date în format JSON sau CSV, cu antete HTTP configurabile pentru autentificare și metadate personalizate.

Cazuri de utilizare:

Integrare cu servicii backend personalizate
Trimitere de date către webhook-uri
Sincronizare cu API-uri terțe
Construirea de tablouri de bord sau platforme de analiză personalizate

Caracteristici principale:

Suportă atât formate JSON, cât și CSV
Antete HTTP personalizate pentru autentificare
Timeout configurabil pentru cereri
Export manual al datelor istorice

Limitări:

Acces la datele de sănătate: Aplicațiilor nu li se permite accesul la datele de sănătate cât timp iPhone-ul este blocat. Automatizările vor rula doar în perioadele în care dispozitivul este deblocat. Aceasta este o limitare impusă de Apple care nu poate fi ocolită. Mai multe informații
Procesare în fundal: iOS limitează procesarea în fundal pentru a economisi bateria. Automatizările se bazează pe Reîmprospătare în fundal a aplicațiilor și s-ar putea să nu ruleze imediat dacă:
- Reîmprospătarea în fundal a aplicațiilor este dezactivată pentru aplicație
- Dispozitivul este în modul de economisire a energiei
- Dispozitivul a fost inactiv perioade îndelungate
- Resursele sistemului sunt limitate
- Mai multe aplicații concurează pentru timpul de execuție în fundal

Performanță

Țineți cont că iOS este optimizat pentru sarcini de scurtă durată pe un dispozitiv mobil, cu constrângeri de performanță foarte stricte. Sarcinile din fundal trebuie de obicei finalizate în 30 de secunde și sunt limitate în consumul de memorie. Health Auto Export oferă un grad mare de flexibilitate și personalizare, ceea ce înseamnă că este important să înțelegeți cum anumite configurații afectează performanța aplicației și rezultatele.

Configurare: Automatizările care produc cantități mari de date pot determina sistemul să oprească procesul și automatizările să nu mai ruleze în fundal. Următoarele configurații pot produce cantități mari de date:
- Automatizări configurate pentru a exporta toate metricile de sănătate.
  - Recomandare: selectați doar metricile de sănătate care au date salvate în Apple Health și doar datele pe care intenționați să le folosiți efectiv. Chiar și tipurile de date goale au un impact asupra performanței. Puteți lua în considerare și împărțirea metricilor selectate în mai multe automatizări, ceea ce ușurează gestionarea pentru sistem.
- Automatizări cu grupare temporală în secunde sau minute sau cu rezumarea datelor dezactivată. Astfel de interogări foarte detaliate pot dura mult și se pot ciocni cu limitările sistemului.
  - Recomandare: deși poate părea ideal să aveți cele mai detaliate date posibile, gândiți-vă dacă acel nivel de detaliu este necesar pentru fiecare metrică sau tip de date. Luați în considerare mai multe automatizări cu setări diferite.
- La exportul antrenamentelor în aer liber, cum ar fi ciclismul, alergarea, drumețiile etc. cu date de traseu, GPS-ul și metricile de sănătate asociate pot produce sarcini mari de date.
Dimensiunea sarcinii: Mai ales la exportul REST API, rețineți că sarcinile mari pot provoca erori de server. Asigurați-vă că backend-ul este configurat să gestioneze sarcini de eventual câteva sute de megaocteți.
Frecvența de sincronizare: Adăugați widgetul Automatizări pe ecranul principal pentru a ajuta automatizările să ruleze cu succes în fundal (consultați Ghid de configurare a widgetului Automatizări).

Cerințe preliminare

Un endpoint URL valid care acceptă cereri HTTP POST
Date de autentificare (dacă sunt necesare pentru endpoint)
Conectivitate la rețea pentru a ajunge la endpoint

Configurare

Deschideți ecranul Exporturi automate din navigarea principală, apoi atingeți „Automatizare nouă” și selectați „REST API” ca tip de automatizare.

Nume automatizare

Introduceți un nume descriptiv pentru automatizare (ex.: „API backend propriu”, „Integrare webhook”).

Notificări

Configurați când doriți să primiți notificări:

Notificare la actualizarea cache-ului — primiți o notificare când datele din cache se actualizează
Notificare la rulare — primiți o notificare la fiecare execuție a automatizării

Configurare URL

Introduceți URL-ul complet unde doriți să trimiteți datele de sănătate. Trebuie să fie un URL complet, inclusiv protocolul (http:// sau https://).

Exemple de URL-uri:

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

Notă: URL-ul trebuie să fie valid și accesibil de pe dispozitiv. URL-urile invalide împiedică rularea automatizării.

Timeout cerere

Selectați un interval de timeout pentru cererile HTTP. Acesta determină cât timp așteaptă aplicația un răspuns înainte de a considera că cererea a eșuat.

Antete HTTP

Adăugați antete HTTP personalizate pentru autentificare sau metadate. Cazuri frecvente de utilizare:

chei API: X-API-Key: your-api-key
tokenuri de autorizare: Authorization: Bearer your-token
suprascrieri ale tipului de conținut: Content-Type: application/json

Pentru a adăuga antete:

Atingeți „Adăugați antete”
Introduceți cheia antetului în câmpul din stânga
Introduceți valoarea antetului în câmpul din dreapta
Repetați pentru antete suplimentare

Important: Fiecare cheie de antet trebuie să aibă o valoare corespunzătoare. Antetele goale vor fi ignorate.

Setări tip de date

Tip de date

Selectați ce tip de date de sănătate exportați:

Metrici de sănătate — pași, puls, somn și alte măsurători de sănătate
Antrenamente — activități de exercițiu și fitness
Simptome — simptome și afecțiuni de sănătate
ECG — înregistrări electrocardiografice
Notificări privind pulsul — evenimente de puls ridicat sau scăzut
Stare de spirit — intrări legate de dispoziție și stare mentală (iOS 18.0+)
Monitorizarea ciclului — date despre ciclul menstrual și sănătatea reproductivă
Medicamente — jurnale de medicamente și aderență (iOS 26.0+)

Configurare metrici de sănătate

Când este selectat Metrici de sănătate:

Selectare metrici de sănătate — alegeți ce metrici specifice includeți. Puteți selecta toate metricile disponibile sau doar anumite.

Sfat: Selectarea doar a metricilor de care aveți nevoie poate îmbunătăți timpul de procesare și reduce dimensiunea datelor.

Surse preferate — configurați ce surse de date au prioritate când mai multe surse oferă aceeași metrică.

Configurare antrenamente

Când sunt selectate Antrenamente:

Includeți date de traseu — activați pentru a include traseele antrenamentelor care au date de locație.

Includeți metrici din antrenament — activați pentru a include metrici de sănătate colectate în timpul antrenamentelor (puls, calorii etc.).

Grupare temporală (metrici antrenament) — când folosiți versiunea de export 2 și Includeți metrici din antrenament este activat:

Minute — grupează metricile antrenamentului pe minut
Secunde — grupează metricile antrenamentului pe secundă

Setări export

Format export

Selectați formatul pentru datele exportate:

Format JSON — oferă structuri de date detaliate cu obiecte imbricate. Cel mai potrivit pentru API-uri, baze de date și aplicații care au nevoie de date structurate. Formatul JSON include informații mai detaliate pentru tipuri de date complexe, cum ar fi fazele de somn și citirile AFib.
Format CSV — oferă date tabulare care pot fi importate ușor în aplicații de foi de calcul. Cel mai potrivit pentru analize simple de date sau când endpoint-ul așteaptă date CSV.

Notă: Antetul Content-Type este setat automat la application/json pentru exporturile JSON și la multipart/form-data pentru exporturile CSV.

Versiune export

Selectați o versiune de export. Versionarea permite trecerea la versiuni actualizate ale exportului în propriul ritm și reduce modificările care pot întrerupe fluxurile de lucru.

Versiunea 1 — format moștenit; folosiți dacă aveți fluxuri existente care depind de acest format
Versiunea 2 — format actual, cu date de antrenament îmbunătățite și opțiuni de metadate mai detaliate

Interval de date

Selectați când trebuie exportate datele:

Implicit — sincronizează datele pentru întreaga zi anterioară, plus date până la data și ora curente
De la ultima sincronizare — la fiecare sincronizare, exportă toate datele de la ultima rulare a exportului până la data și ora curente
Astăzi — sincronizează toate datele pentru ziua curentă până la momentul curent
Ieri — sincronizează toate datele pentru întreaga zi anterioară
Ultimele 7 zile — sincronizează datele pentru întregul interval de șapte zile anterioare

Rezumat date

Când folosiți formatul JSON cu tipul de date Metrici de sănătate, activați sau dezactivați Rezumat date.

Activat — oferă rezumate agregate ale datelor
Dezactivat — oferă date dezagregate pe cât posibil, cu puncte individuale de date

Notă: Această setare se aplică doar formatului JSON cu Metrici de sănătate. Datele sunt întotdeauna agregate când folosiți formatul CSV sau când sunt selectate mai multe metrici.

Grupare temporală

Când folosiți formatul JSON cu Rezumat date activat, selectați modul în care trebuie agregate datele.

Notă: Formatul CSV agregă întotdeauna datele. Agregarea la nivel de minut sau secundă poate crește semnificativ timpul de procesare și dimensiunea datelor.

Cereri în lot și încărcături mari

Când folosiți formatul JSON, activați Cereri în lot pentru a trimite date în mai multe cereri HTTP în loc de o singură încărcătură mare.

PORNIT — Distribuie datele pe mai multe cereri. Folosiți când endpoint-ul are limite de dimensiune, expirări pe corpuri mari sau procesați date incremental.
OPRIT — Trimite toate datele într-o singură cerere. Potrivit pentru exporturi mici și webhook-uri simple.

Când să activați lotul:

Multe metrici de sănătate selectate, intervale lungi de date sau grupare temporală fină (minute/secunde)
Rezumă datele este OPRIT și exportați metrici de sănătate dezagregate
Serverul returnează erori sau expirări pe corpuri POST mari

Note:

Cererile în lot se aplică doar la REST API + JSON (nu CSV).
Lotul reduce încărcătura per cerere, dar nu elimină preluarea pe dispozitiv; interogările HealthKit lente pot apărea în continuare ca avertismente în jurnalele de activitate. Consultați Interogări lente în jurnalele de activitate.

Testare și verificare

Verificare format date

Aplicația include automat următoarele antete în fiecare cerere:

Content-Type — setat în funcție de formatul de export
automation-name — numele automatizării dvs.
automation-id — identificator unic pentru automatizare
automation-aggregation — gruparea temporală selectată
automation-period — intervalul de date selectat
session-id — identificator unic pentru fiecare cerere

Depanare

Probleme frecvente

Datele nu sunt primite la endpoint

Verificați că URL-ul endpoint-ului este corect
Confirmați că endpoint-ul acceptă cereri POST
Revizuiți antetele de autentificare
Verificați jurnalele endpoint-ului pentru cereri primite
Verificați conectivitatea la rețea

Sfaturi și bune practici

Sincronizare automată:
- Încărcați dispozitivul și folosiți iPhone Mirroring
  - Când dispozitivul se încarcă, iOS aplică mai puține restricții asupra performanței, astfel că datele se pot sincroniza mai frecvent
  - Folosind iPhone Mirroring, dispozitivul se comportă la fel ca atunci când ar fi deblocat. Astfel, datele de sănătate sunt accesibile pentru Health Auto Export, pentru a rula acțiuni automate
Performanță:
- Folosiți o grupare temporală potrivită pentru a echilibra detaliul față de dimensiunea datelor
- Selectați doar metricile de care aveți nevoie
Fiabilitate:
- Setați valori de timeout potrivite în funcție de timpul de răspuns al endpoint-ului
- Monitorizați regulat jurnalele de activitate
Format date:
- Folosiți JSON pentru date structurate și API-uri
- Folosiți CSV pentru analize simple de date sau integrare cu foi de calcul
- Luați în calcul cereri în lot pentru seturi mari de date sau procesare separată

Vizualizarea jurnalelor de activitate

Atingeți Vizualizați jurnalele de activitate pe ecranul de configurare a automatizării.
Examinați rulări (grupate, cele mai recente primele) și extindeți evenimentele din fiecare rulare.
Distingeți avertismente (de ex., interogare lentă a datelor de sănătate) de erori (eșecuri HTTP, expirări sau eșecuri de citire HealthKit)—consultați Prezentare generală automatizări — Jurnale de activitate.
Încărcările REST reușite afișează adesea un rezumat cu format, tip de date, perioadă de export și interval de date în rulare.
Partajare (bară de instrumente) exportă ZIP-ul diagnostic complet Jurnale de evenimente ale aplicației pentru asistență (la fel ca Setări → Avansat).
Ștergere elimină doar istoricul de activitate al acestei automatizări.