REST API-automaatio-opas

REST API -automaatiot vievät terveysdatasi automaattisesti mille tahansa verkkopalvelulle, joka hyväksyy HTTP POST -pyyntöjä. Tämä sopii integraatioihin mukautettuihin taustajärjestelmiin, kolmannen osapuolen API:in tai webhookkeihin.

Yleiskatsaus

REST API -automaatiot lähettävät terveysdatasi valittuun URL-päätepisteeseen HTTP POST -pyynnöillä. Automaatio voi lähettää datan JSON- tai CSV-muodossa, ja otsikoita voi määrittää todennusta ja metatietoja varten.

Käyttötapaukset:

• Integraatio mukautettuihin taustapalveluihin
• Datan lähetys webhookkeihin
• Synkronointi kolmannen osapuolen API:in kanssa
• Mukautettujen koontinäyttöjen tai analytiikka-alustojen rakentaminen

Keskeiset ominaisuudet:

• Tukee sekä JSON- että CSV-muotoa
• Mukautetut HTTP-otsikot todennusta varten
• Säädettävä pyynnön aikakatkaisu
• Historiadatan manuaalinen vienti

Rajoitukset:

• Pääsy terveystietoihin: Sovellukset eivät saa käyttää terveystietoja, kun iPhone on lukittu. Automaatiot toimivat vain, kun laitteesi on avattu. Tämä on Applen asettama rajoitus, jota ei voi kiertää. Lisätietoja

• Taustakäsittely: iOS rajoittaa taustakäsittelyä akun säästämiseksi. Automaatiot käyttävät Sovellusten taustapäivitystä, eivätkä välttämättä käynnisty heti, jos:

  • Sovellusten taustapäivitys on poissa käytöstä sovellukselle
  • Laite on vähävirransäästötilassa
  • Laite on ollut pitkään käyttämättömänä
  • Järjestelmäresurssit ovat rajalliset
  • Useat sovellukset kilpailevat taustasuoritusajasta

Suorituskyky

Muista, että iOS on optimoitu lyhytaikaisille tehtäville mobiililaitteella, jolla on hyvin tiukat suorituskykyrajoitukset. Taustatehtävien on yleensä valmistuttava 30 sekunnissa, ja niiden muistinkäyttö on rajattu. Health Auto Export tarjoaa paljon joustavuutta ja muokattavuutta, joten on tärkeää ymmärtää, miten tietyt asetukset vaikuttavat sovelluksen suorituskykyyn ja tuloksiin.

• Asetukset: Automaatiot, jotka tuottavat suuria datamääriä, voivat saada järjestelmän lopettamaan prosessin, jolloin automaatiot eivät käynnisty taustalla. Seuraavat asetukset voivat tuottaa suuria datamääriä:
  • Automaatiot, jotka on määritetty viemään kaikki terveysmittarit.
    • Suositus: valitse vain terveysmittarit, joille on tallennettu data Apple Healthissa, ja vain data, jota todella aiot käyttää. Myös tyhjät datatyypit vaikuttavat suorituskykyyn. Voit myös jakaa valitut terveysmittarit useisiin automaatioihin, mikä helpottaa järjestelmän käsittelyä.
  • Automaatiot, joissa aikaryhmittely on sekunteina tai minuutteina tai datan yhteenveto on pois päältä. Näin hienojakoiset kyselyt voivat kestää kauan ja törmätä järjestelmän rajoituksiin.
    • Suositus: vaikka mahdollisimman yksityiskohtainen data vaikuttaa ihanteelliselta, harkitse, tarvitaanko kyseinen tarkkuus jokaiselle mittarille tai datatyypille. Harkitse useita automaatioita eri asetuksilla.
  • Kun viet ulkoliikuntaharjoituksia, kuten pyöräilyä, juoksua, vaellusta jne. reittidatan kanssa, GPS ja siihen liittyvät terveysmittarit voivat tuottaa suuria hyötykuormia.
• Hyötykuorman koko: Erityisesti REST API -vientiä käytettäessä suuret hyötykuormat voivat aiheuttaa palvelinvirheitä. Varmista, että taustajärjestelmäsi pystyy käsittelemään mahdollisesti usean sadan megatavun hyötykuormia.
• Synkronointitiheys: Lisää Automaatiot-widget kotinäytölle auttaaksesi varmistamaan, että automaatiot käynnistyvät onnistuneesti taustalla (katso Aseta automaatiowidget).

Edellytykset

• Kelvollinen URL-päätepiste, joka hyväksyy HTTP POST -pyyntöjä
• Todennustiedot (jos päätepiste vaatii)
• Verkkoyhteys päätepisteeseen

Määritys

Siirry päävalikosta automaattisten vientien näyttöön, napauta Uusi automaatio ja valitse automaation tyypiksi REST API.

Automaation nimi

Anna automaatiolle kuvaava nimi (esim. ”My Backend API”, ”Webhook Integration”).

Ilmoitukset

Määritä, milloin haluat ilmoituksia:

• Notify on Cache Update – Ilmoitus, kun välimuistidata päivittyy
• Notify When Run – Ilmoitus joka kerta, kun automaatio suoritetaan

URL-määritys

Anna täydellinen URL-osoite, johon haluat lähettää terveysdatasi. Osoitteessa on oltava protokolla (http:// tai https://).

Esimerkki-URL-osoitteita:

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

Huom: URL:n on oltava kelvollinen ja laitteesi saavutettavissa. Virheelliset URL:t estävät automaation suorituksen.

Pyynnön aikakatkaisu

Valitse HTTP-pyyntöjen aikakatkaisu. Määrittää, kuinka kauan sovellus odottaa vastausta ennen kuin pyyntö katsotaan epäonnistuneeksi.

HTTP-otsikot

Lisää mukautettuja HTTP-otsikoita todennusta tai metatietoja varten. Yleisiä tapauksia:

• API-avaimet: X-API-Key: your-api-key
• Todennustokenit: Authorization: Bearer your-token
• Content-Type -ylikirjoitukset: Content-Type: application/json

Otsikoiden lisääminen:

1. Napauta Add Headers
2. Kirjoita otsikon avain vasempaan kenttään
3. Kirjoita otsikon arvo oikeaan kenttään
4. Toista tarvittaessa

Tärkeää: Jokaisella otsikkoavaimella on oltava vastaava arvo. Tyhjät otsikot ohitetaan.

Datatyypin asetukset

Datatyyppi

Valitse, minkä terveysdatan tyyppiä viedään:

• Health Metrics – Askeleet, syke, uni ja muut terveysmittaukset
• Workouts – Liikunta- ja kuntoaktiviteetit
• Symptoms – Terveysoireet ja tilat
• ECG – EKG-mittaukset
• Heart Rate Notifications – Korkea/matala syke -tapahtumat
• State of Mind – Mielialan ja mielentilan merkinnät (iOS 18.0+)
• Cycle Tracking – Kuukautiskierto ja lisääntymisterveysdata
• Medications – Lääkkeiden kirjaukset ja noudattaminen (iOS 26.0+)

Health Metrics -asetukset

Kun on valittu Health Metrics:

Select Health Metrics – Valitse, mitkä mittarit sisällytetään. Voit valita kaikki saatavilla olevat tai tiettyjä.

Vinkki: Vain tarvitsemiesi mittareiden valinta voi nopeuttaa käsittelyä ja pienentää datamäärää.

Preferred Sources – Määritä, mitkä datalähteet ovat etusijalla, kun sama mittari tulee useasta lähteestä.

Workout-asetukset

Kun on valittu Workouts:

Include Route Data – Ota käyttöön, jotta mukaan tulee reitit harjoituksille, joissa on sijaintidataa.

Include Workout Metrics – Ota käyttöön, jotta mukaan tulee harjoituksen aikana kerätyt terveysmittarit (syke, kalorit jne.).

Aikaryhmittely (harjoitusmittarit) – Kun käytössä on Export Version 2 ja Sisällytä harjoitusmittarit on päällä:

• Minutes – Ryhmittelee harjoitusmittarit minuuteittain
• Seconds – Ryhmittelee harjoitusmittarit sekunteittain

Viennin asetukset

Viennin muoto

Valitse vietävän datan muoto:

• JSON-muoto – Yksityiskohtaiset rakenteet sisäkkäisine olioineen. Paras API:lle, tietokannoille ja sovelluksille, jotka tarvitsevat rakenteisen datan. JSON sisältää enemmän yksityiskohtia monimutkaisille datatyypeille, kuten univaiheille ja AFib-lukemille.

• CSV-muoto – Taulukkomuotoinen data, jonka voi tuoda helposti taulukko-ohjelmiin. Paras yksinkertaiseen analyysiin tai kun päätepiste odottaa CSV-dataa.

Huom: Content-Type-otsikko asetetaan automaattisesti arvoon application/json JSON-vienneille ja multipart/form-data CSV-vienneille.

Viennin versio

Valitse Export Version. Versionumerointi mahdollistaa siirtymisen päivitettyihin vientimuotoihin omaan tahtiisi ja vähentää työnkulkujen rikkoutumista.

• Version 1 – Vanha muoto; käytä, jos nykyiset työnkulut riippuvat tästä
• Version 2 – Nykyinen muoto, laajennettu harjoitusdata ja yksityiskohtaisemmat metatietovaihtoehdot

Aikaväli

Valitse, milloin data viedään:

• Default – Synkronoi datan koko edelliseltä päivältä sekä kuluvaan päivään ja -aikaan asti
• Since Last Sync – Jokaisella synkronoinnilla vie kaiken datan edellisen viennin jälkeen kuluvaan päivään ja -aikaan asti
• Today – Synkronoi kaiken kuluvan päivän datan kuluvaan hetkeen asti
• Yesterday – Synkronoi koko edellisen päivän data
• Previous 7 Days – Synkronoi edellisten seitsemän päivän data

Yhteenveto datasta

Kun käytät JSON-muotoa Health Metrics -datatyypin kanssa, kytke Summarize Data päälle tai pois.

• Päällä – Tarjoaa koostetut yhteenvedot
• Poissa – Tarjoaa mahdollisuuksien mukaan erittelemätön datan, yksittäiset datapisteet näkyvissä

Huom: Tämä asetus koskee vain JSON-muotoa Health Metrics -datatyypin kanssa. Data koostetaan aina CSV-muodossa tai kun useita mittareita on valittu.

Aikaryhmittely

Kun käytät JSON-muotoa ja Summarize Data on päällä, valitse, miten data koostetaan.

Huom: CSV-muoto koostaa datan aina. Minuutti- ja sekuntitason koostaminen voi kasvattaa merkittävästi käsittelyaikaa ja datamäärää.

Eräpyynnöt ja suuret hyötykuormat

Kun käytät JSON-muotoa, ota Eräpyynnöt käyttöön lähettääksesi tiedot useissa HTTP-pyynnöissä yhden suuren hyötykuorman sijaan.

• PÄÄLLÄ — Jakaa tiedot useisiin pyyntöihin. Käytä, kun päätepisteellä on kokorajoituksia, aikakatkaisuja suurille rungoille tai käsittelet tietoja vaiheittain.
• POIS — Lähettää kaikki tiedot yhdessä pyynnössä. Sopii pienempiin vienteihin ja yksinkertaisiin webhookeihin.

Milloin ottaa erät käyttöön:

• Monta terveysmittaria valittuna, pitkät aikavälit tai hienojakoinen aikaryhmittely (minuutit/sekunnit)
• Yhteenveto tiedoista on POIS ja viet hajautettuja terveysmittareita
• Palvelin palauttaa virheitä tai aikakatkaisuja suurille POST-runoille

Huomautuksia:

• Eräpyynnöt koskevat vain REST API + JSON (ei CSV).
• Erät pienentävät hyötykuorman kokoa pyyntöä kohti, mutta eivät poista tarvetta hakea tietoja laitteella; hitaat HealthKit-kyselyt voivat silti näkyä varoituksina aktiviteettilokeissa. Katso Hitaat kyselyt aktiviteettilokeissa.

Synkronoinnin tiheys

Määritä, kuinka usein automaation tulisi lähettää dataa:

Valitse luku ja aikaväli.

Testaus ja varmistus

Datan muodon tarkistus

Sovellus lisää automaattisesti nämä otsikot jokaiseen pyyntöön:

• Content-Type – Asetetaan viennin muodon mukaan
• automation-name – Automaation nimi
• automation-id – Automaation yksilöllinen tunniste
• automation-aggregation – Valittu aikaryhmittely
• automation-period – Valittu aikaväli
• session-id – Kunkin pyynnön yksilöllinen tunniste

Ongelmanratkaisu

Yleisiä ongelmia

Data ei saavu päätepisteeseen

• Varmista, että päätepisteen URL on oikein
• Tarkista, että päätepiste hyväksyy POST-pyyntöjä
• Tarkista todennusotsikot
• Tarkista päätepisteen lokit saapuvista pyynnöistä
• Varmista verkkoyhteys

Vinkkejä ja hyviä käytäntöjä

1. Automaattinen synkronointi:

   • Lataa laitetta ja käytä iPhonen peilausta (iPhone Mirroring)
     • Latauksen aikana iOS rajoittaa laitteen suorituskykyä vähemmän, jolloin data voi synkronoitua useammin
     • Peilauksella laite käyttäytyy kuin lukitsemattomana, jolloin Health Auto Export voi käyttää terveysdataa automaattisten toimintojen suorittamiseen

2. Suorituskyky:

   • Käytä sopivaa aikaryhmittelyä tasapainottaaksesi yksityiskohtia ja datamäärää
   • Valitse vain tarvitsemasi mittarit

3. Luotettavuus:

   • Aseta sopivat aikakatkaisut päätepisteen vasteajan mukaan
   • Seuraa toimintalokeja säännöllisesti

4. Datan muoto:

   • Käytä JSONia rakenteiselle datalle ja API:lle
   • Käytä CSV:tä yksinkertaiseen analyysiin tai taulukkointegraatioon
   • Harkitse eräpyyntöjä suurille aineistoille tai erilliseen käsittelyyn

Aktiviteettilokien tarkastelu

1. Napauta Näytä aktiviteettilokit automaation määritysnäytössä.
2. Tarkista ajot (ryhmitelty, uusimmat ensin) ja laajenna tapahtumat kullekin ajolle.
3. Erottele varoitukset (esim. hidas terveysdatakysely) ja virheet (HTTP-virheet, aikakatkaisut tai HealthKit-lukuvirheet)—katso Automaatioiden yleiskatsaus — Aktiviteettilokit.
4. Onnistuneissa REST-latauksissa näkyy usein yhteenveto, jossa on muoto, datatyyppi, vientijakso ja aikaväli ajossa.
5. Jaa (työkalurivi) vie täyden Sovellustapahtumalokit-diagnostiikka-ZIPin tukea varten (sama kuin Asetukset → Lisäasetukset).
6. Tyhjennä poistaa vain tämän automaation aktiviteettihistorian.