REST API automatizálási útmutató

A REST API automatizálásokkal automatikusan exportálhatod egészségügyi adataidat bármely olyan webszolgáltatáshoz, amely HTTP POST kéréseket fogad. Ideális egyedi háttérrendszerekhez, harmadik féltől származó API-khoz vagy webhookokhoz.

Áttekintés

A REST API automatizálások HTTP POST kéréssel küldik az egészségügyi adataidat egy megadott URL-végpontra. Az automatizálás JSON vagy CSV formátumban küldhet adatot, beállítható fejlécekkel hitelesítéshez és egyedi metaadatokhoz.

Használati esetek:

• Integráció egyedi háttérszolgáltatásokkal
• Adatküldés webhookokra
• Szinkronizálás harmadik féltől származó API-kkal
• Egyedi irányítópultok vagy elemző platformok építése

Fő jellemzők:

• JSON és CSV formátum támogatása
• Egyedi HTTP-fejlécek hitelesítéshez
• Beállítható kérés időtúllépése
• Korábbi adatok kézi exportja

Korlátok:

• Egészségügyi adatok elérése: Az alkalmazások nem férnek hozzá egészségügyi adatokhoz, amíg az iPhone zárolva van. Az automatizálások csak akkor futnak, amikor az eszköz fel van oldva. Ezt az Apple korlátozása nem kerülhető meg. További információ

• Háttérfeldolgozás: Az iOS korlátozza a háttérben futó feldolgozást az akkumulátor védelme érdekében. Az automatizálások a háttérben futó alkalmazás-frissítésre támaszkodnak, és nem feltétlenül futnak le azonnal, ha:

  • A háttérben futó alkalmazás-frissítés ki van kapcsolva az alkalmazásnál
  • Az eszköz alacsony töltöttségi módban van
  • Az eszköz hosszú ideje inaktív
  • A rendszer erőforrásai szűkösek
  • Több alkalmazás verseng a háttérben futásért

Teljesítmény

Tartsd szem előtt, hogy az iOS rövid ideig futó feladatokra van optimalizálva mobil eszközön, nagyon szigorú teljesítménykorlátokkal. A háttérfeladatoknak általában 30 másodpercen belül be kell fejeződniük, és korlátozott a memóriahasználatuk. A Health Auto Export nagyfokú rugalmasságot és testreszabhatóságot kínál, ezért érdemes megérteni, hogyan befolyásolják az egyes beállítások az alkalmazás teljesítményét és az eredményeket.

• Beállítás: A nagy mennyiségű adatot előállító automatizálások miatt a rendszer leállíthatja a folyamatot, és az automatizálások nem futnak a háttérben. A következő beállítások nagy mennyiségű adatot állíthatnak elő:
  • Az összes egészségügyi metrika exportjára beállított automatizálások.
    • Ajánlás: csak olyan egészségügyi metrikákat válassz, amelyekhez van mentett adat az Apple Healthben, és csak olyan adatokat, amelyeket ténylegesen használni fogsz. Az üres adattípusok is befolyásolják a teljesítményt. Fontold meg a kiválasztott metrikák több automatizálásra osztását is — így a rendszer könnyebben kezeli őket.
  • Másodperces vagy perces időcsoportosítású automatizálások, vagy kikapcsolt adatösszegzéssel. Az ilyen finom részletességű lekérdezések sokáig futhatnak, és ütközhetnek a rendszer korlátaival.
    • Ajánlás: bár csábító a lehető legrészletesebb adat, gondold át, szükséges-e ez minden metrikához vagy adattípushoz. Fontold meg több automatizálást különböző beállításokkal.
  • Szabadtéri edzések, például kerékpározás, futás, túrázás stb. útvonaladatokkal történő exportálásakor a GPS és a kapcsolódó egészségügyi metrikák nagy adatmennyiséget eredményezhetnek.
• Adatmennyiség mérete: Különösen REST API exportnál vedd figyelembe, hogy a nagy adatmennyiségek szerverhibákat okozhatnak. Győződj meg róla, hogy a háttérrendszered képes kezelni akár több száz megabájtos adatmennyiségeket is.
• Szinkrongyakoriság: Add hozzá az Automatizálások widgetet a Kezdőképernyőhöz, hogy az automatizálások megbízhatóbban fussanak a háttérben (lásd: Automatizálások widget beállítási útmutató).

Előfeltételek

• Érvényes URL-végpont, amely HTTP POST kéréseket fogad
• Hitelesítő adatok, ha a végpont megköveteli
• Hálózati kapcsolat a végpont eléréséhez

Konfiguráció

Lépj az Automatizált exportok képernyőre a fő navigációból, majd koppints az „Új automatizálás” lehetőségre, és válaszd a „REST API” automatizálástípust.

Automatizálás neve

Adj leíró nevet az automatizálásnak (pl. „Saját háttér API”, „Webhook integráció”).

Értesítések

Állítsd be, mikor szeretnél értesítést kapni:

• Értesítés gyorsítótár-frissítéskor – Értesítés, ha a gyorsítótárazott adat frissül
• Értesítés futtatáskor – Értesítés minden alkalommal, amikor az automatizálás lefut

URL-konfiguráció

Add meg a teljes URL-t, ahová az egészségügyi adatokat küldeni szeretnéd. Teljes URL legyen, protokollal együtt (http:// vagy https://).

Példa URL-ek:

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

Megjegyzés: Az URL-nek érvényesnek és az eszközödről elérhetőnek kell lennie. Érvénytelen URL esetén az automatizálás nem fut le.

Kérés időtúllépése

Válassz időtúllépést a HTTP-kérésekhez. Ez határozza meg, meddig vár az alkalmazás válaszra, mielőtt sikertelennek tekinti a kérést.

HTTP-fejlécek

Adj hozzá egyedi HTTP-fejléceket hitelesítéshez vagy metaadatokhoz. Gyakori esetek:

• API-kulcsok: X-API-Key: your-api-key
• Engedélyezési tokenek: Authorization: Bearer your-token
• Tartalomtípus felülírás: Content-Type: application/json

Fejlécek hozzáadása:

1. Koppints a „Fejlécek hozzáadása” lehetőségre
2. Írd be a fejléc kulcsát a bal mezőbe
3. Írd be a fejléc értékét a jobb mezőbe
4. Ismeld további fejlécekhez

Fontos: Minden fejléc-kulcshoz tartoznia kell értéknek. Az üres fejlécek figyelmen kívül maradnak.

Adattípus-beállítások

Adattípus

Válaszd ki, milyen típusú egészségügyi adatot exportálj:

• Egészségügyi metrikák – Lépések, pulzus, alvás és egyéb mérések
• Edzések – Mozgásformák és fitnesztevékenységek
• Tünetek – Egészségügyi tünetek és állapotok
• EKG – Elektrokardiogram felvételek
• Pulzusértesítések – Magas/alacsony pulzus események
• Lelkiállapot – Hangulat és mentális állapot bejegyzések (iOS 18.0+)
• Cikluskövetés – Menstruációs ciklus és reprodukciós adatok
• Gyógyszerek – Gyógyszerbejegyzések és adherencia (iOS 26.0+)

Egészségügyi metrikák konfigurációja

Ha az Egészségügyi metrikák van kiválasztva:

Egészségügyi metrikák kiválasztása – Válaszd ki, mely konkrét metrikák kerüljenek bele. Kiválaszthatod az összes elérhető metrikát vagy csak bizonyosakat.

Tipp: Ha csak a szükséges metrikákat választod, javulhat a feldolgozási idő és csökkenhet az adatméret.

Preferált források – Állítsd be, mely adatforrások kapjanak prioritást, ha több forrás ugyanazt a metrikát szolgáltatja.

Edzés konfigurációja

Ha az Edzések van kiválasztva:

Útvonaladatok belefoglalása – Kapcsold BE, ha az edzés útvonalait is szeretnéd helyadattal rendelkező edzésekhez.

Edzésmetrikák belefoglalása – Kapcsold BE, ha az edzés alatt gyűjtött egészségügyi metrikákat (pulzus, kalória stb.) is szeretnéd.

Időcsoportosítás (edzésmetrikák) – Export 2-es verzió és bekapcsolt edzésmetrikák esetén:

• Perc – edzésmetrikák percenkénti csoportosítása
• Másodperc – edzésmetrikák másodpercenkénti csoportosítása

Exportbeállítások

Exportformátum

Válaszd ki az exportált adat formátumát:

• JSON-formátum – Részletes, beágyazott objektumokkal. API-khoz, adatbázisokhoz és strukturált adatot váró alkalmazásokhoz. Összetett adattípusokhoz (alvásfázisok, AFib) több részletet tartalmaz.

• CSV-formátum – Táblázatos adat, könnyen importálható táblázatkezelőkbe. Egyszerű elemzéshez vagy ha a végpont CSV-t vár.

Megjegyzés: A Content-Type fejléc automatikusan application/json JSON exportnál és multipart/form-data CSV exportnál.

Export verzió

Válassz exportverziót. A verziózás lehetővé teszi a saját tempódban történő átállást, és csökkenti a munkafolyamatok megszakítását.

• 1-es verzió – Régi formátum; használd, ha a meglévő munkafolyamataid ettől függnek
• 2-es verzió – Aktuális formátum bővített edzésadatokkal és részletesebb metaadat-opciókkal

Dátumtartomány

Válaszd ki, mikor kerüljenek exportálásra az adatok:

• Alapértelmezés – Szinkronizálja az előző teljes nap adatait, valamint az aktuális dátum és időig terjedő adatokat
• Az utolsó szinkron óta – Minden szinkronkor exportálja az utolsó futás óta az aktuális dátum és időig terjedő összes adatot
• Ma – Szinkronizálja a mai nap összes adatát az aktuális időpontig
• Tegnap – Szinkronizálja a teljes előző nap adatait
• Előző 7 nap – Szinkronizálja az előző hét teljes napjainak adatait

Adatok összefoglalása

JSON formátum és Egészségügyi metrikák adattípus esetén kapcsold BE vagy KI az „Adatok összefoglalása” beállítást.

• BE – összesített adatösszefoglalók
• KI – ahol lehetséges, szétbontott adat, egyedi adatpontokkal

Megjegyzés: Ez a beállítás csak JSON + Egészségügyi metrikák esetén érvényes. CSV-nél vagy több kiválasztott metrikánál az adatok mindig összesítve vannak.

Időcsoportosítás

JSON formátum és bekapcsolt adatösszefoglalás esetén válaszd ki, hogyan legyenek az adatok összesítve.

Megjegyzés: CSV formátum mindig összesít. A perc- és másodperc szintű összesítés jelentősen megnövelheti a feldolgozási időt és az adatméretet.

Kötegelt kérések és nagy adatterhek

JSON formátum használatakor kapcsolja be a Kötegelt kéréseket, hogy az adatokat több HTTP-kérésben küldje egy nagy adatterhek helyett.

• BE — Több kérésre osztja az adatokat. Használja, ha a végpontnak méretkorlátai, nagy törzsek időkorlátjai vannak, vagy lépésenként dolgozza fel az adatokat.
• KI — Minden adatot egy kérésben küld. Kisebb exportokhoz és egyszerű webhookokhoz alkalmas.

Mikor engedélyezze a kötegelést:

• Sok egészségügyi metrika, hosszú dátumtartományok vagy finom időcsoportosítás (perc/másodperc)
• Az adatok összegzése KI van kapcsolva és szétbontott metrikákat exportál
• A szerver hibákat vagy időtúllépéseket ad nagy POST törzsekre

Megjegyzések:

• A kötegelt kérések csak REST API + JSON esetén érvényesek (nem CSV).
• A kötegelés csökkenti a kérési terhet, de nem szünteti meg az eszközön történő lekérést; a lassú HealthKit-lekérdezések továbbra is figyelmeztetésként jelenhetnek meg az tevékenységnaplókban. Lásd: Lassú lekérdezések a tevékenységnaplókban.

Tesztelés és ellenőrzés

Adatformátum ellenőrzése

Az alkalmazás automatikusan belefoglalja ezeket a fejléceket minden kérésbe:

• Content-Type – az exportformátum alapján beállítva
• automation-name – az automatizálás neve
• automation-id – az automatizálás egyedi azonosítója
• automation-aggregation – a kiválasztott időcsoportosítás
• automation-period – a kiválasztott dátumtartomány
• session-id – minden kérés egyedi azonosítója

Hibaelhárítás

Gyakori problémák

Nem érkeznek meg adatok a végpontra

• Ellenőrizd, hogy helyes-e a végpont URL-je
• Győződj meg róla, hogy a végpont POST kéréseket fogad
• Nézd át a hitelesítési fejléceket
• Ellenőrizd a végpont naplóit a bejövő kérésekért
• Ellenőrizd a hálózati kapcsolatot

Tippek és ajánlott gyakorlat

1. Automatikus szinkronizálás:

   • Töltse az eszközt és használja az iPhone-tükrözést
     • Töltés közben az iOS kevesebb teljesítménykorlátozást alkalmaz, így az adatok gyakrabban szinkronizálhatók
     • Az iPhone-tükrözéssel az eszköz úgy viselkedik, mintha fel lenne oldva. Így a Health Auto Export hozzáfér az egészségadatokhoz az automatizált műveletekhez

2. Automatikus szinkron:

   • Töltsd az eszközt, és használd az iPhone tükrözést
     • Töltés közben az iOS kevésbé korlátozza a teljesítményt
     • Az iPhone tükrözéssel az eszköz úgy viselkedik, mintha fel lenne oldva

3. Teljesítmény:

   • Használj megfelelő időcsoportosítást a részletesség és az adatméret egyensúlyához
   • Csak a szükséges metrikákat válaszd

4. Megbízhatóság:

   • Állíts be megfelelő időtúllépést a végpont válaszideje alapján
   • Rendszeresen nézd át a tevékenységnaplót

5. Adatformátum:

   • JSON strukturált adatokhoz és API-khoz
   • CSV egyszerű elemzéshez vagy táblázatintegrációhoz
   • Nagy adathalmazoknál fontold meg a kötegelt kéréseket vagy a külön feldolgozást

Tevékenységnaplók megtekintése

1. Koppintson a Tevékenységnaplók megtekintése elemre az automatizálás konfigurációs képernyőjén.
2. Tekintse át a futtatások elemeket (csoportosítva, legújabb elöl), és bontsa ki az eseményeket minden futtatáson belül.
3. Különböztesse meg a figyelmeztetések (pl. lassú egészségadat-lekérdezés) és a hibák (HTTP-hibák, időtúllépések vagy HealthKit-olvasási hibák) típusokat—lásd: Automatizálások áttekintése — Tevékenységnaplók.
4. A sikeres REST feltöltések gyakran összefoglalót mutatnak formátum, adattípus, export időszak és dátumtartomány mezőkkel a futtatásban.
5. Megosztás (eszköztár) exportálja a teljes Alkalmazásesemény-naplók diagnosztikai ZIP-et támogatáshoz (ugyanaz, mint Beállítások → Speciális).
6. Törlés csak ennek az automatizálásnak a tevékenységtörténetét távolítja el.