Sprievodca automatizáciou REST API

Automatizácie REST API umožňujú automaticky exportovať zdravotné údaje na ľubovoľnú webovú službu, ktorá prijíma požiadavky HTTP POST. Hodí sa na integráciu s vlastnými backendmi, API tretích strán alebo webhookmi.

Prehľad

Automatizácie REST API posielajú zdravotné údaje na zadanú URL pomocou požiadaviek HTTP POST. Automatizácia môže posielať dáta vo formáte JSON alebo CSV, s konfigurovateľnými hlavičkami na autentifikáciu a vlastné metadáta.

Prípady použitia:

• Integrácia s vlastnými backendovými službami
• Odosielanie údajov na webhooky
• Synchronizácia s API tretích strán
• Vlastné dashboardy alebo analytické platformy

Hlavné funkcie:

• Podporuje formáty JSON aj CSV
• Vlastné HTTP hlavičky na autentifikáciu
• Nastaviteľný časový limit požiadavky
• Manuálny export historických údajov

Obmedzenia:

• Prístup k zdravotným údajom: Aplikácie nemajú povolený prístup k zdravotným údajom, keď je iPhone uzamknutý. Automatizácie sa spustia len v obdobiach, keď je zariadenie odomknuté. Ide o obmedzenie spoločnosti Apple, ktoré nemožno obísť. Viac informácií

• Spracovanie na pozadí: iOS obmedzuje spracovanie na pozadí, aby šetril batériu. Automatizácie sa spoliehajú na Obnovenie aplikácií na pozadí a nemusia sa spustiť okamžite, ak:

  • je pre aplikáciu vypnuté Obnovenie aplikácií na pozadí
  • je zariadenie v režime nízkej spotreby
  • bolo zariadenie dlhší čas neaktívne
  • sú obmedzené systémové zdroje
  • viac aplikácií súperí o čas behu na pozadí

Výkon

Majte na pamäti, že iOS je optimalizovaný pre krátkodobé úlohy na mobilnom zariadení s veľmi prísnymi výkonnostnými obmedzeniami. Úlohy na pozadí zvyčajne musia byť dokončené do 30 sekúnd a majú obmedzenú spotrebu pamäte. Health Auto Export ponúka veľkú flexibilitu a prispôsobiteľnosť, a preto je dôležité pochopiť, ako určité konfigurácie ovplyvnia výkon aplikácie a výsledky.

• Konfigurácia: Automatizácie, ktoré generujú veľké množstvá údajov, môžu spôsobiť ukončenie procesu systémom a automatizácie potom nebežia na pozadí. Nasledujúce konfigurácie môžu generovať veľké množstvá údajov:
  • Automatizácie nastavené na export všetkých zdravotných metrík.
    • Odporúčanie: vyberte len zdravotné metriky, ktoré majú v Apple Health uložené údaje, a len údaje, ktoré skutočne plánujete používať. Aj prázdne typy údajov majú dopad na výkon. Môžete tiež zvážiť rozdelenie vybraných zdravotných metrík do viacerých automatizácií, čo systému uľahčí spracovanie.
  • Automatizácie s časovým zoskupením v sekundách alebo minútach alebo s vypnutou sumarizáciou údajov. Takto jemne granulované dotazy môžu dlho trvať a naraziť na systémové obmedzenia.
    • Odporúčanie: aj keď sa môže zdať ideálne mať čo najpodrobnejšie údaje, zvážte, či je taká úroveň detailu nutná pre každú metriku alebo typ údajov. Zvážte viac automatizácií s rôznym nastavením.
  • Pri exporte outdoorových tréningov, ako je cyklistika, beh, turistika atď. s údajmi trasy, môžu GPS a súvisiace zdravotné metriky vytvoriť veľké dátové balíky.
• Veľkosť dátového balíka: Najmä pri exporte cez REST API majte na pamäti, že veľké dátové balíky môžu spôsobiť chyby servera. Uistite sa, že váš backend je nakonfigurovaný na spracovanie balíkov o veľkosti prípadne niekoľkých stoviek megabajtov.
• Frekvencia synchronizácie: Pridajte widget automatizácií na Domovskú obrazovku, aby automatizácie spoľahlivejšie bežali na pozadí (pozri Sprievodca nastavením widgetu automatizácií).

Predpoklady

• Platný koncový bod URL, ktorý prijíma požiadavky HTTP POST
• Prihlasovacie údaje (ak ich váš koncový bod vyžaduje)
• Sieťové pripojenie na dosiahnutie koncového bodu

Konfigurácia

Prejdite na obrazovku Automatizované exporty v hlavnej navigácii, potom klepnite na „Nová automatizácia“ a ako typ automatizácie vyberte „REST API“.

Názov automatizácie

Zadajte výstižný názov automatizácie (napr. „Môj backend API“, „Integrácia webhooku“).

Upozornenia

Nastavte, kedy chcete dostávať upozornenia:

• Upozorniť pri aktualizácii vyrovnávacej pamäte — upozornenie pri aktualizácii dát vo vyrovnávacej pamäti
• Upozorniť pri spustení — upozornenie pri každom spustení automatizácie

Konfigurácia URL

Zadajte úplnú URL, na ktorú chcete posielať zdravotné údaje. Malo by ísť o úplnú URL vrátane protokolu (http:// alebo https://).

Príklady URL:

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

Poznámka: URL musí byť platná a dostupná zo zariadenia. Neplatné URL zabránia spusteniu automatizácie.

Časový limit požiadavky

Vyberte interval časového limitu pre HTTP požiadavky. Určuje, ako dlho aplikácia čaká na odpoveď, kým považuje požiadavku za neúspešnú.

HTTP hlavičky

Pridajte vlastné HTTP hlavičky na autentifikáciu alebo metadáta. Bežné prípady:

• Kľúče API: X-API-Key: your-api-key
• Autorizačné tokeny: Authorization: Bearer your-token
• Prepísanie typu obsahu: Content-Type: application/json

Pridanie hlavičiek:

1. Klepnite na „Pridať hlavičky“
2. Zadajte kľúč hlavičky do ľavého poľa
3. Zadajte hodnotu hlavičky do pravého poľa
4. Opakujte pre ďalšie hlavičky

Dôležité: Každý kľúč hlavičky musí mať zodpovedajúcu hodnotu. Prázdne hlavičky sa ignorujú.

Nastavenia typu údajov

Typ údajov

Vyberte, ktorý typ zdravotných údajov exportovať:

• Zdravotné metriky — kroky, srdcová frekvencia, spánok a ďalšie zdravotné merania
• Tréningy — cvičenia a športové aktivity
• Príznaky — zdravotné príznaky a stavy
• EKG — záznamy elektrokardiogramu
• Upozornenia na srdcovú frekvenciu — udalosti vysokej alebo nízkej srdcovej frekvencie
• Stav mysle — záznamy nálady a duševného stavu (iOS 18.0+)
• Sledovanie cyklu — menštruačný cyklus a reprodukčné zdravotné údaje
• Lieky — záznamy liekov a adherencia (iOS 26.0+)

Konfigurácia zdravotných metrík

Pri výbere Zdravotné metriky:

Vybrať zdravotné metriky — vyberte konkrétne metriky na zahrnutie. Môžete vybrať všetky dostupné metriky alebo len vybrané.

Tip: Výber len potrebných metrík môže skrátiť čas spracovania a znížiť veľkosť dát.

Preferované zdroje — nastavte, ktoré zdroje údajov majú prednosť, keď viac zdrojov poskytuje rovnakú metriku.

Konfigurácia tréningov

Pri výbere Tréningy:

Zahrnúť údaje o trase — zapnite, ak chcete zahrnúť trasy pre tréningy, ktoré majú údaje o polohe.

Zahrnúť metriky tréningu — zapnite, ak chcete zahrnúť zdravotné metriky zozbierané počas tréningov (srdcová frekvencia, kalórie atď.).

Časové zoskupenie (metriky tréningu) — pri použití exportnej verzie 2 a zapnutom zahrnutí metrík tréningu:

• Minúty — zoskupuje metriky tréningu po minútach
• Sekundy — zoskupuje metriky tréningu po sekundách

Nastavenia exportu

Formát exportu

Vyberte formát exportovaných údajov:

• Formát JSON — poskytuje podrobné dátové štruktúry s vnorenými objektmi. Najvhodnejší pre API, databázy a aplikácie, ktoré potrebujú štruktúrované dáta. Formát JSON obsahuje podrobnejšie informácie pre zložité typy údajov, napr. fázy spánka a čítania AFib.

• Formát CSV — poskytuje tabuľkové dáta, ktoré sa dajú jednoducho importovať do tabuľkových aplikácií. Najvhodnejší na jednoduchú analýzu údajov alebo keď váš koncový bod očakáva dáta CSV.

Poznámka: Hlavička Content-Type sa automaticky nastaví na application/json pre export JSON a na multipart/form-data pre export CSV.

Verzia exportu

Vyberte verziu exportu. Verziovanie umožňuje prechádzať medzi aktualizovanými verziami exportu vlastným tempom a minimalizuje narušenie existujúcich postupov.

• Verzia 1 — starší formát; použite, ak máte existujúce postupy závislé na tomto formáte
• Verzia 2 — aktuálny formát s rozšírenými údajmi o tréningoch a podrobnejšími možnosťami metadát

Časové rozpätie

Vyberte, kedy sa majú údaje exportovať:

• Predvolené — synchronizuje údaje za celý predchádzajúci deň plus údaje do aktuálneho dátumu a času
• Od poslednej synchronizácie — pri každej synchronizácii exportuje všetky údaje od posledného spustenia exportu až do aktuálneho dátumu a času
• Dnes — synchronizuje všetky údaje za aktuálny deň do aktuálneho času
• Včera — synchronizuje všetky údaje za celý predchádzajúci deň
• Predchádzajúcich 7 dní — synchronizuje údaje za celých predchádzajúcich sedem dní

Zhrnúť údaje

Pri formáte JSON a type údajov Zdravotné metriky zapnite alebo vypnite zhrnutie údajov.

• Zapnuté — poskytuje agregované súhrny údajov
• Vypnuté — kde je to možné, poskytuje neagregované údaje s jednotlivými bodmi

Poznámka: Toto nastavenie platí len pre formát JSON so zdravotnými metrikami. Pri formáte CSV alebo pri výbere viacerých metrík sa údaje vždy agregujú.

Časové zoskupenie

Pri formáte JSON so zapnutým zhrnutím údajov vyberte, ako sa majú údaje agregovať.

Poznámka: Formát CSV vždy agreguje údaje. Agregácia na úrovni minút alebo sekúnd môže výrazne zvýšiť čas spracovania a veľkosť dát.

Dávkové požiadavky a veľké dátové časti

Pri formáte JSON zapnite Dávkové požiadavky, aby ste odoslali údaje vo viacerých HTTP požiadavkách namiesto jednej veľkej časti.

• ZAPNUTÉ — Rozloží údaje do viacerých požiadaviek. Použite, keď má koncový bod limity veľkosti, časové limity veľkých telies alebo údaje spracovávate postupne.
• VYPNUTÉ — Odošle všetky údaje v jednej požiadavke. Vhodné pre menšie exporty a jednoduché webhooky.

Kedy zapnúť dávkovanie:

• Je vybraných veľa zdravotných metrík, dlhé rozsahy dátumov alebo jemné časové zoskupenie (minúty/sekundy)
• Zhrnutie údajov je vypnuté a exportujete nesúhrnné zdravotné metriky
• Server vracia chyby alebo časové limity pri veľkých POST telách

Poznámky:

• Dávkové požiadavky platia len pre REST API + JSON (nie CSV).
• Dávkovanie znižuje veľkosť časti na požiadavku, ale neodstraňuje načítanie na zariadení; pomalé dotazy HealthKit sa môžu stále zobrazovať ako varovania v protokoloch aktivít. Pozrite Pomalé dotazy v protokoloch aktivít.

Frekvencia synchronizácie

Nastavte, ako často má automatizácia nahrávať údaje:

Vyberte číslo a interval.

Testovanie a overenie

Overenie formátu dát

Aplikácia automaticky pridáva do každej požiadavky tieto hlavičky:

• Content-Type — nastavené podľa formátu exportu
• automation-name — názov vašej automatizácie
• automation-id — jedinečný identifikátor automatizácie
• automation-aggregation — zvolené časové zoskupenie
• automation-period — zvolené časové rozpätie
• session-id — jedinečný identifikátor každej požiadavky

Riešenie problémov

Bežné problémy

Koncový bod nedostáva údaje

• Overte, či je URL koncového bodu správna
• Skontrolujte, či koncový bod prijíma požiadavky POST
• Skontrolujte autentifikačné hlavičky
• Pozrite logy koncového bodu pre prichádzajúce požiadavky
• Overte sieťové pripojenie

Tipy a osvedčené postupy

1. Automatická synchronizácia:

   • Nabíjajte zariadenie a používajte zrkadlenie iPhonu
     • Pri nabíjaní iOS menej obmedzuje výkon zariadenia, takže sa údaje môžu synchronizovať častejšie
     • Pri zrkadlení iPhonu sa zariadenie správa rovnako ako pri odomknutí. Zdravotné údaje sú tak pre Health Auto Export dostupné na spúšťanie automatizovaných akcií

2. Výkon:

   • Používajte vhodné časové zoskupenie na vyváženie detailu a veľkosti dát
   • Vyberte len metriky, ktoré potrebujete

3. Spoľahlivosť:

   • Nastavte vhodné hodnoty časového limitu podľa odozvy koncového bodu
   • Pravidelne sledujte denníky aktivít

4. Formát dát:

   • JSON pre štruktúrované dáta a API
   • CSV pre jednoduchú analýzu údajov alebo integráciu s tabuľkami
   • Pri veľkých súboroch údajov alebo samostatnom spracovaní zvážte dávkové požiadavky

Zobrazenie protokolov aktivít

1. Klepnite na Zobraziť protokoly aktivít na obrazovke konfigurácie automatizácie.
2. Skontrolujte behy (zoskupené, najnovšie prvé) a rozbaliť udalosti v rámci každého behu.
3. Rozlište varovania (napr. pomalý dotaz na zdravotné údaje) od chyby (chyby HTTP, časové limity alebo zlyhania čítania HealthKit)—pozrite Prehľad automatizácií — Protokoly aktivít.
4. Úspešné REST nahrávania často zobrazujú súhrn s formátom, typom údajov, obdobím exportu a rozsahom dátumov v behu.
5. Zdieľať (panel nástrojov) exportuje úplné diagnostické ZIP Protokoly udalostí aplikácie pre podporu (rovnaké ako Nastavenia → Pokročilé).
6. Vymazať odstráni iba históriu aktivít tejto automatizácie.