Vodič za REST API automatizaciju

REST API automatizacije omogućuju automatski izvoz zdravstvenih podataka na bilo koji web servis koji prihvaća HTTP POST zahtjeve. To je prikladno za integraciju s prilagođenim backendovima, API-jima trećih strana ili webhookovima.

Pregled

REST API automatizacije šalju zdravstvene podatke na određeni URL krajnju točku HTTP POST zahtjevima. Automatizacija može slati podatke u JSON ili CSV formatu, s prilagodljivim zaglavljima za autentifikaciju i prilagođene metapodatke.

Primjene:

• Integracija s prilagođenim backend servisima
• Slanje podataka na webhookove
• Sinkronizacija s API-jima trećih strana
• Izgradnja prilagođenih nadzornih ploča ili analitičkih platformi

Ključne značajke:

• Podržava JSON i CSV formate
• Prilagođena HTTP zaglavlja za autentifikaciju
• Prilagodljiv istek zahtjeva (timeout)
• Ručni izvoz povijesnih podataka

Ograničenja:

• Pristup zdravstvenim podacima: Aplikacijama nije dopušten pristup zdravstvenim podacima dok je iPhone zaključan. Automatizacije će se pokretati samo dok je uređaj otključan. To je ograničenje Applea koje se ne može zaobići. Više informacija

• Obrada u pozadini: iOS ograničava obradu u pozadini radi štednje baterije. Automatizacije ovise o Osvježavanju aplikacija u pozadini i možda se neće pokrenuti odmah ako:

  • je Osvježavanje aplikacija u pozadini isključeno za aplikaciju
  • je uređaj u načinu rada niske potrošnje energije
  • je uređaj bio neaktivan dulje vrijeme
  • su ograničeni resursi sustava
  • više aplikacija natječe se za vrijeme izvršavanja u pozadini

Performanse

Imajte na umu da je iOS optimiziran za kratkotrajne zadatke na mobilnom uređaju s vrlo strogim ograničenjima performansi. Zadaci u pozadini obično moraju biti dovršeni unutar 30 sekundi i ograničeni su u potrošnji memorije. Health Auto Export nudi veliku fleksibilnost i prilagodljivost, pa je važno razumjeti kako određene konfiguracije utječu na performanse aplikacije i ishode.

• Konfiguracija: Automatizacije koje proizvode velike količine podataka mogu uzrokovati da sustav prekine proces i da automatizacije ne rade u pozadini. Sljedeće konfiguracije mogu proizvesti velike količine podataka:
  • Automatizacije konfigurirane za izvoz svih zdravstvenih metrika.
    • Preporuka: odaberite samo zdravstvene metrike koje imaju spremljene podatke u Apple Healthu i samo podatke koje stvarno planirate koristiti. Čak i prazni tipovi podataka utječu na performanse. Možete razmotriti i podjelu odabranih zdravstvenih metrika na više automatizacija, što sustavu olakšava obradu.
  • Automatizacije s grupiranjem po vremenu u sekundama ili minutama ili s isključenim sažimanjem podataka. Takvi fino granularni upiti mogu dugo trajati i sukobiti se sa sustavnim ograničenjima.
    • Preporuka: iako se može činiti idealnim imati najdetaljnije podatke, razmislite je li ta razina detalja potrebna za svaku metriku ili tip podataka. Razmislite o više automatizacija s različitim postavkama.
  • Pri izvozu treninga na otvorenom, poput biciklizma, trčanja, planinarenja itd. s podacima rute, GPS i povezani zdravstveni podaci mogu stvoriti velike količine podataka.
• Veličina podataka: Posebno pri REST API izvozu imajte na umu da velike količine podataka mogu uzrokovati pogreške poslužitelja. Provjerite je li vaš backend konfiguriran za obradu količina podataka od eventualno nekoliko stotina megabajta.
• Učestalost sinkronizacije: Dodajte widget Automatizacije na početni zaslon kako biste osigurali pouzdanije pokretanje automatizacija u pozadini (pogledajte Vodič za postavljanje widgeta Automatizacije).

Preduvjeti

• Valjani URL krajnje točke koji prihvaća HTTP POST zahtjeve
• Vjerodajnice za autentifikaciju (ako ih krajnja točka zahtijeva)
• Mrežna povezanost do krajnje točke

Konfiguracija

U glavnoj navigaciji otvorite zaslon Automatskih izvoza, zatim dodirnite „New Automation” i odaberite „REST API” kao vrstu automatizacije.

Naziv automatizacije

Unesite opisni naziv automatizacije (npr. „My Backend API”, „Webhook Integration”).

Obavijesti

Postavite kada želite primati obavijesti:

• Notify on Cache Update — obavijest kad se ažuriraju predmemorirani podaci
• Notify When Run — obavijest pri svakom izvršavanju automatizacije

Konfiguracija URL-a

Unesite puni URL na koji želite slati zdravstvene podatke. To mora biti potpuni URL uključujući protokol (http:// ili https://).

Primjeri URL-ova:

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

Napomena: URL mora biti valjan i dostupan s vašeg uređaja. Nevažeći URL-ovi sprječavaju rad automatizacije.

Istek zahtjeva (Request Timeout)

Odaberite interval isteka za HTTP zahtjeve. Određuje koliko dugo aplikacija čeka odgovor prije nego što smatra zahtjev neuspjelim.

HTTP zaglavlja

Dodajte prilagođena HTTP zaglavlja za autentifikaciju ili metapodatke. Uobičajeni slučajevi:

• API ključevi: X-API-Key: your-api-key
• Tokeni autorizacije: Authorization: Bearer your-token
• Nadjačavanje vrste sadržaja: Content-Type: application/json

Dodavanje zaglavlja:

1. Dodirnite „Add Headers”
2. Unesite ključ zaglavlja u lijevo polje
3. Unesite vrijednost zaglavlja u desno polje
4. Ponovite za dodatna zaglavlja

Važno: Svaki ključ zaglavlja mora imati odgovarajuću vrijednost. Prazna zaglavlja bit će zanemarena.

Postavke vrste podataka

Vrsta podataka

Odaberite koji tip zdravstvenih podataka izvesti:

• Health Metrics — koraci, otkucaji srca, san i druga mjerenja
• Workouts — aktivnosti vježbanja i fitnessa
• Symptoms — simptomi i stanja
• ECG — elektrokardiogramska snimanja
• Heart Rate Notifications — događaji visokih/niskih otkucaja srca
• State of Mind — unosi raspoloženja i mentalnog stanja (iOS 18.0+)
• Cycle Tracking — menstrualni ciklus i reproduktivno zdravlje
• Medications — evidencija lijekova i uzimanja (iOS 26.0+)

Konfiguracija zdravstvenih metrika

Kad je odabrano Health Metrics:

Select Health Metrics — odaberite koje metrike uključiti. Možete odabrati sve dostupne ili pojedinačne.

Savjet: Odabirom samo potrebnih metrika možete poboljšati vrijeme obrade i smanjiti veličinu podataka.

Preferred Sources — postavite koji izvori imaju prednost kad više izvora daje istu metriku.

Konfiguracija treninga

Kad je odabrano Workouts:

Include Route Data — uključite da biste dodali rute za treninge s lokacijskim podacima.

Include Workout Metrics — uključite metrike prikupljene tijekom treninga (otkucaji srca, kalorije itd.).

Time Grouping (Workout Metrics) — kad se koristi Export Version 2 i uključena je opcija Include Workout Metrics:

• Minutes — grupira metrike treninga po minuti
• Seconds — grupira metrike treninga po sekundi

Postavke izvoza

Format izvoza

Odaberite format izvezenih podataka:

• JSON format — detaljne strukture s ugniježđenim objektima. Najbolje za API-je, baze i aplikacije koje trebaju strukturirane podatke. JSON uključuje više detalja za složene tipove poput faza sna i AFib očitanja.

• CSV format — tablični podaci za uvoz u proračunske tablice. Najbolje za jednostavnu analizu ili kad krajnja točka očekuje CSV.

Napomena: Zaglavlje Content-Type automatski se postavlja na application/json za JSON izvoz i multipart/form-data za CSV izvoz.

Verzija izvoza

Odaberite verziju izvoza. Verzioniranje omogućuje prijelaz na ažurirane verzije vlastitim tempom i smanjuje lomljenje tijekova rada.

• Version 1 — stariji format; koristite ako postojeći tijekovi ovise o njemu
• Version 2 — trenutačni format s poboljšanim trening podacima i detaljnijim metapodacima

Raspon datuma

Odaberite kada izvesti podatke:

• Default — sinkronizira podatke za cijeli prethodni dan plus podatke do trenutnog datuma i vremena
• Since Last Sync — pri svakoj sinkronizaciji izvozi sve podatke od zadnjeg pokretanja izvoza do trenutnog datuma i vremena
• Today — sinkronizira sve podatke za tekući dan do trenutnog vremena
• Yesterday — sinkronizira sve podatke za cijeli prethodni dan
• Previous 7 Days — sinkronizira podatke za cijelih prethodnih sedam dana

Summarize Data

Kad koristite JSON format s vrstom Health Metrics, uključite ili isključite Summarize Data.

• ON — agregirani sažeci
• OFF — gdje je moguće, pojedinačne točke podataka

Napomena: Postavka vrijedi samo za JSON s Health Metrics. Pri CSV formatu ili više odabranih metrika podaci su uvijek agregirani.

Vremensko grupiranje

Kad koristite JSON format s uključenim Summarize Data, odaberite kako agregirati podatke.

Napomena: CSV format uvijek agregira podatke. Agregacija na razini minute ili sekunde može značajno povećati vrijeme obrade i veličinu podataka.

Skupni zahtjevi i veliki tereti

Kod formata JSON uključite Skupne zahtjeve za slanje podataka u više HTTP zahtjeva umjesto jednog velikog tereta.

• UKLJUČENO — Raspodjeljuje podatke na više zahtjeva. Koristite kad krajnja točka ima ograničenja veličine, istjeke na velikim tijelima ili obrađujete podatke postupno.
• ISKLJUČENO — Šalje sve podatke u jednom zahtjevu. Pogodno za manje izvoz i jednostavne webhookove.

Kada uključiti skupno slanje:

• Odabrano mnogo zdravstvenih metrika, dugi rasponi datuma ili fina vremenska grupacija (minute/sekunde)
• Sažmi podatke je ISKLJUČENO i izvozite nesagrupirane metrike
• Poslužitelj vraća pogreške ili istjeke na velikim POST tijelima

Napomene:

• Skupni zahtjevi vrijede samo za REST API + JSON (ne CSV).
• Skupno slanje smanjuje teret po zahtjevu, ali ne uklanja dohvat na uređaju; spori HealthKit upiti mogu se i dalje prikazati kao upozorenja u zapisnicima aktivnosti. Pogledajte Spori upiti u zapisnicima aktivnosti.

Učestalost sinkronizacije

Postavite koliko često automatizacija treba učitavati podatke:

Odaberite broj i interval.

Testiranje i provjera

Provjera formata podataka

Aplikacija automatski uključuje ova zaglavlja u svaki zahtjev:

• Content-Type — postavlja se prema formatu izvoza
• automation-name — naziv automatizacije
• automation-id — jedinstveni identifikator automatizacije
• automation-aggregation — odabrano vremensko grupiranje
• automation-period — odabrani raspon datuma
• session-id — jedinstveni identifikator za svaki zahtjev

Rješavanje problema

Uobičajeni problemi

Podaci ne stižu na krajnju točku

• Provjerite je li URL krajnje točke točan
• Provjerite prihvaća li krajnja točku POST zahtjeve
• Pregledajte zaglavlja autentifikacije
• Pogledajte logove krajnje točke za dolazne zahtjeve
• Provjerite mrežnu povezanost

Savjeti i najbolje prakse

1. Automatska sinkronizacija:

   • Punite uređaj i koristite iPhone Mirroring
     • Kad se uređaj puni, iOS manje ograničava performanse pa se podaci mogu češće sinkronizirati
     • iPhone Mirroring ponaša se kao da je uređaj otključan, pa Health Auto Export može pristupiti zdravstvenim podacima za automatizirane radnje

2. Performanse:

   • Koristite prikladno vremensko grupiranje radi ravnoteže detalja i veličine podataka
   • Odaberite samo metrike koje trebate

3. Pouzdanost:

   • Postavite prikladne vrijednosti isteka prema vremenu odgovora krajnje točke
   • Redovito pratite Activity Logs

4. Format podataka:

   • JSON za strukturirane podatke i API-je
   • CSV za jednostavnu analizu ili integraciju s tablicama
   • Razmotrite batch zahtjeve za velike skupove podataka ili odvojenu obradu

Pregled zapisnika aktivnosti

1. Dodirnite Prikaži zapisnike aktivnosti na zaslonu konfiguracije automatizacije.
2. Pregledajte pokretanja (grupirano, najnovije prvo) i proširite događaje unutar svakog pokretanja.
3. Razlikujte upozorenja (npr. spori upit zdravstvenih podataka) od greške (HTTP greške, isteci vremena ili greške čitanja HealthKit-a)—pogledajte Pregled automatizacija — Zapisnici aktivnosti.
4. Uspješna REST učitavanja često prikazuju sažetak s formatom, vrstom podataka, razdobljem izvoza i rasponom datuma u pokretanju.
5. Podijeli (alatna traka) izvozi potpuni dijagnostički ZIP Zapisnici događaja aplikacije za podršku (isto kao Postavke → Napredno).
6. Očisti uklanja samo povijest aktivnosti ove automatizacije.