Syvälinkkiautomaatio

Syvälinkki-automaatiot antavat sinun luoda REST API -automaatioita ohjelmallisesti URL-skeemojen avulla. Tämä sopii automaatioskripteille, määritysten hallinnalle tai ulkoisiin järjestelmiin integroitumiseen, joiden täytyy määrittää terveysdatan vientiä.

Yleiskatsaus

Syvälinkki-automaatiot käyttävät mukautettua URL-skeemaa REST API -automaatioiden luomiseen ja määritykseen ilman, että asetukset syötetään käsin sovelluksessa. Kun avaat syvälinkin URL-osoitteen, sovellus luo automaattisesti uuden automaation annetulla määrityksellä.

Käyttötapaukset:

• Automaation ohjelmallinen määritys skripteillä tai työkaluilla
• Automaatioiden massamääritys
• Integraatio määritysten hallintajärjestelmiin
• Nopea määritys ulkoisista sovelluksista tai verkkosivuilta
• Testaus- ja kehitystyönkulut

Keskeiset ominaisuudet:

• Automaatioiden luonti URL-skeeman kautta
• Kaikkien REST API -automaatioasetusten määritys
• Tyhjentävä parametrien validointi
• Kattavat virheilmoitukset

Rajoitukset

• Syvälinkit tukevat vain REST API -automaatioita (ei Dropboxia, Google Drivea jne.)
• URL:n pituusrajoitukset voivat rajoittaa hyvin pitkiä parametrilistoja
• Kaikki REST API -automaatioiden rajoitukset pätevät (taustakäsittely, terveysdatan käyttö jne.)

URL-muoto

Syvälinkin URL noudattaa tätä rakennetta:

com.HealthExport://automation?parameter1=value1&parameter2=value2&...

Perus-URL: com.HealthExport://automation

Parametrit: Kaikki parametrit paitsi name ja url ovat valinnaisia. Parametrien kirjainkoolla ei ole merkitystä.

Parametrireferenssi

Pakolliset parametrit

url (pakollinen)

• Tyyppi: Merkkijono (kelvollinen URL)
• Kuvaus: Päätepiste-URL, johon terveysdata lähetetään
• Esimerkki: https://api.example.com/health-data
• Huom: Oltava kelvollinen HTTP- tai HTTPS-URL

name (pakollinen)

• Tyyppi: Merkkijono
• Kuvaus: Kuvaava nimi automaatiolle
• Esimerkki: My%20Backend%20API (URL-koodattuna: My Backend API)
• Huom: URL-koodattava, jos nimessä on välilyöntejä tai erikoismerkkejä

Perusmääritys

format

• Tyyppi: Enum (json, csv)
• Oletus: json
• Kuvaus: Datan vientimuoto
• Esimerkki: format=json tai format=csv
• Huom: CSV-muoto ottaa automaattisesti käyttöön datan koostamisen

enabled

• Tyyppi: Totuusarvo (true, false, 1, 0, yes, no)
• Oletus: false
• Kuvaus: Onko automaatio käytössä heti luonnin jälkeen
• Esimerkki: enabled=true

datatype

• Tyyppi: Enum (katso datatyypit alapuolelta)
• Oletus: healthMetrics
• Kuvaus: Vietävän terveysdatan tyyppi
• Esimerkki: datatype=workouts
• Huom: Vain yksi datatyyppi voidaan valita. Tämä asettaa automaattisesti vastaavat sisällytysliput.

Kelvolliset datatyypit:

• healthMetrics – Terveysmittaukset (askeleet, syke, uni jne.)
• workouts – Liikunta- ja kuntoaktiviteetit
• symptoms – Terveysoireet ja tilat
• ecg – EKG-mittaukset
• heartRateNotification – Korkea/matala syke -tapahtumat
• stateOfMind – Mielialan ja mielentilan merkinnät (iOS 18.0+)
• cycleTracking – Kuukautiskierto ja lisääntymisterveysdata
• medications – Lääkkeiden kirjaukset ja noudattaminen (iOS 26.0+)

Viennin asetukset

period

• Tyyppi: Enum
• Oletus: none
• Kuvaus: Aikaväli datan viennille
• Esimerkki: period=today

Kelvolliset arvot:

• none – Oletus (koko edellinen päivä plus kuluva päivä)
• lastsync – Edellisestä synkronoinnista
• today – Kuluva päivä
• yesterday – Edellinen päivä
• previous7days – Edelliset 7 päivää
• realtime – Reaaliaikaiset päivitykset (vaatii sekuntitason synkronointivälin)

interval

• Tyyppi: Enum
• Oletus: none
• Kuvaus: Aikaryhmittely/koostamisväli (vain kelvollinen healthMetrics-datatyypille)
• Esimerkki: interval=hours

Kelvolliset arvot:

• none – Oletus (ei koostamista)
• minutes – Ryhmittele minuuteittain
• hours – Ryhmittele tunneittain
• days – Ryhmittele päivittäin
• weeks – Ryhmittele viikoittain
• months – Ryhmittele kuukausittain
• years – Ryhmittele vuosittain

Huom: Tämä parametri on kelvollinen vain, kun datatype=healthMetrics. CSV-muoto koostaa datan aina.

aggregatedata

• Tyyppi: Totuusarvo
• Oletus: true (CSV), false (JSON)
• Kuvaus: Koostetaanko/yhteenvetäänkö data (vain kelvollinen healthMetrics + JSON-muoto)
• Esimerkki: aggregatedata=true
• Huom: Asetetaan automaattisesti true, kun format=csv

aggregatesleep

• Tyyppi: Totuusarvo
• Oletus: true
• Kuvaus: Koostetaanko unidata
• Esimerkki: aggregatesleep=true

exportversion

• Tyyppi: Enum (v1, v2, 1, 2)
• Oletus: v2
• Kuvaus: Viennin muotoversio
• Esimerkki: exportversion=v2
• Huom: Versio 2 sisältää laajennetun harjoitusdatan ja yksityiskohtaisempaa metatietoa

batchrequests

• Tyyppi: Totuusarvo
• Oletus: false
• Kuvaus: Lähetä data erissä useissa pyynnöissä (vain kelvollinen REST API + JSON-muoto)
• Esimerkki: batchrequests=true
• Huom: Kelvollinen vain, kun format=json ja exportDestination=restApi

Synkronoinnin tiheys

syncinterval

• Tyyppi: Enum
• Oletus: minutes
• Kuvaus: Synkronoinnin tiheyden väli
• Esimerkki: syncinterval=hours

Kelvolliset arvot:

• minutes – Synkronoi N minuutin välein
• hours – Synkronoi N tunnin välein
• days – Synkronoi N päivän välein
• weeks – Synkronoi N viikon välein
• seconds – Kelvollinen vain, kun period=realtime

Huom: REST API -automaatioissa vain minutes, hours, days ja weeks ovat kelvollisia, ellei käytetä reaaliaikaista vientiä.

syncquantity

• Tyyppi: Kokonaisluku (positiivinen)
• Oletus: 5
• Kuvaus: Intervallien lukumäärä synkronointien välillä
• Esimerkki: syncquantity=10 (synkronoi 10 minuutin välein, jos syncinterval=minutes)
• Huom: Oltava suurempi kuin 0

HTTP-määritys

headers

• Tyyppi: Merkkijono (pilkulla erotetut avain-arvo-parit)
• Oletus: Ei mitään
• Kuvaus: HTTP-otsikot todennusta tai metatietoja varten
• Esimerkki: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Muoto: key1,value1,key2,value2,...
• Huom: Arvot tulisi URL-koodata. Jokainen otsikko vaatii sekä avaimen että arvon.

Esimerkkiotsikoita:

• Authorization, Bearer your-token
• X-API-Key, your-api-key
• Content-Type, application/json

requesttimeout

• Tyyppi: Kokonaisluku (60–86400)
• Oletus: 60
• Kuvaus: Pyynnön aikakatkaisu sekunteina
• Esimerkki: requesttimeout=300
• Huom: Oltava 60–86400 sekunnin välillä (1 minuutista 24 tuntiin)

Datatyypin kohtaiset asetukset

Health Metrics -asetukset

metrics

• Tyyppi: Merkkijono (pilkulla erotetut MetricName rawValues -arvot)
• Oletus: Kaikki saatavilla olevat mittarit
• Kuvaus: Mitkä terveysmittarit sisällytetään (vain kelvollinen healthMetrics-datatyypille)
• Esimerkki: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Huom: Käytä täsmälleen MetricName rawValues -arvoja. Jos ei määritetä, kaikki saatavilla olevat mittarit sisältyvät.

Yleisiä mittarinimiä:

• Step Count
• Heart Rate
• Active Energy
• Apple Exercise Time
• Sleep Analysis
• Walking + Running Distance

Katso sovelluksen mittarinvalinnan näytöstä täydellinen luettelo saatavilla olevista mittareista.

Workout-asetukset

includeroutes

• Tyyppi: Totuusarvo
• Oletus: true
• Kuvaus: Sisällytä reittidata harjoituksiin (vain kelvollinen workouts-datatyypille)
• Esimerkki: includeroutes=true

includeworkoutmetadata

• Tyyppi: Totuusarvo
• Oletus: true
• Kuvaus: Sisällytä harjoitusmittarit (syke, kalorit jne.) harjoituksen aikana kerättynä (vain kelvollinen workouts-datatyypille)
• Esimerkki: includeworkoutmetadata=true

workoutsmetadatainterval

• Tyyppi: Enum (minutes, seconds)
• Oletus: minutes
• Kuvaus: Aikaryhmittely harjoitusmittareille (vain kelvollinen workouts + exportVersion v2)
• Esimerkki: workoutsmetadatainterval=seconds
• Huom: Kelvollinen vain, kun datatype=workouts ja exportversion=v2

workouttypes

• Tyyppi: Merkkijono (pilkulla erotetut UInt-arvot)
• Oletus: Tyhjä (kaikki harjoitustyypit)
• Kuvaus: Mitkä harjoitustyypit sisällytetään (vain kelvollinen workouts-datatyypille)
• Esimerkki: workouttypes=1,2,3
• Huom: Käyttää HealthKitin harjoitustyyppitunnisteita

Ilmoitukset

notifyonupdate

• Tyyppi: Totuusarvo
• Oletus: true
• Kuvaus: Ilmoitus, kun välimuistidata päivittyy
• Esimerkki: notifyonupdate=true

notifywhenrun

• Tyyppi: Totuusarvo
• Oletus: true
• Kuvaus: Ilmoitus joka kerta, kun automaatio suoritetaan
• Esimerkki: notifywhenrun=false

Esimerkit

Perus REST API -automaatio

com.HealthExport://automation?url=https://api.example.com/health&name=My%20Automation&format=json&enabled=true

Luo perusautomaation, joka lähettää JSON-dataa määritettyyn päätepisteeseen.

Todennusotsikoilla

com.HealthExport://automation?url=https://api.example.com/health&name=Authenticated%20API&format=json&headers=Authorization,Bearer%20your-token-here,X-API-Key,abc123&enabled=true

Luo automaation mukautetuilla todennusotsikoilla.

Health Metrics tietyillä mittareilla

com.HealthExport://automation?url=https://api.example.com/metrics&name=Steps%20and%20Heart%20Rate&format=json&datatype=healthMetrics&metrics=Step%20Count,Heart%20Rate&aggregatedata=true&interval=hours&enabled=true

Luo automaation, joka vie vain askeleet ja sykkeen, koostettuna tunneittain.

Harjoitukset reittidatalla

com.HealthExport://automation?url=https://api.example.com/workouts&name=Workout%20Export&format=json&datatype=workouts&includeroutes=true&includeworkoutmetadata=true&exportversion=v2&workoutsmetadatainterval=minutes&enabled=true

Luo harjoitusautomaation reittidatalla ja harjoitusmittareilla, viennin versio 2.

Täydellinen määritysesimerkki

com.HealthExport://automation?url=https://api.example.com/health-data&name=Complete%20Configuration&format=json&datatype=healthMetrics&period=today&interval=hours&aggregatedata=true&aggregatesleep=true&exportversion=v2&syncinterval=hours&syncquantity=2&headers=Authorization,Bearer%20token123&requesttimeout=300&batchrequests=true&notifyonupdate=true&notifywhenrun=false&enabled=true

Kattava esimerkki, jossa kaikki keskeiset parametrit on määritetty.

CSV-muodon esimerkki

com.HealthExport://automation?url=https://api.example.com/csv&name=CSV%20Export&format=csv&datatype=healthMetrics&period=yesterday&enabled=true

Luo CSV-vientiautomaation. Huomaa, että CSV-muoto ottaa automaattisesti käyttöön datan koostamisen.

URL-koodaus

Parametriarvojen erikoismerkit on URL-koodattava. Yleisiä koodeja:

• Välilyönti: %20
• Pilkku: %2C
• Kaksoispiste: %3A
• Puolipiste: %3B
• Yhtäläisyysmerkki: %3D
• &-merkki: %26
• Plus: %2B

Esimerkki:

• Alkuperäinen: My Automation Name
• Koodattu: My%20Automation%20Name

Otsikoiden esimerkki:

• Alkuperäinen: Authorization, Bearer token123
• Koodattu: Authorization,Bearer%20token123

Useimmat ohjelmointikielet ja työkalut tarjoavat URL-koodausfunktioita:

• Swift: addingPercentEncoding(withAllowedCharacters:)
• JavaScript: encodeURIComponent()
• Python: urllib.parse.quote()

Syvälinkkien testaus

Safarista (iOS)

1. Avaa Safari iOS-laitteellasi
2. Kirjoita syvälinkin URL osoitepalkkiin
3. Napauta Siirry
4. Sovelluksen pitäisi avautua ja luoda automaatio

Terminaalista (macOS/iOS Simulator)

xcrun simctl openurl booted "com.HealthExport://automation?url=https://api.example.com/health&name=Test&enabled=true"

Xcodesta

Lisää katkaisupiste tai käytä debugger-konsolia:

let url = URL(string: "com.HealthExport://automation?url=https://api.example.com/health&name=Test&enabled=true")!
try DataModel.shared.handleAPIDeepLink(url)

Oikopolut-sovelluksesta (Shortcuts)

1. Luo uusi oikopolku
2. Lisää Avaa URL-osoitteet -toiminto
3. Syötä syvälinkin URL
4. Suorita oikopolku

Ongelmanratkaisu

Yleisiä ongelmia

"Could not parse the URL"

• Varmista, että URL-skeema on oikein: com.HealthExport://automation
• Tarkista, että kaikki parametriarvot on URL-koodattu oikein
• Varmista, että parametrien nimet on kirjoitettu oikein (kirjainkoolla ei merkitystä)

"Invalid URL parameter value"

• Varmista, että URL on kelvollinen HTTP/HTTPS-URL
• Tarkista URL-koodaus
• Varmista, että URL ei sisällä virheellisiä merkkejä

"Invalid data type"

• Käytä täsmälleen näitä datatyyppiarvoja: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Tarkista kirjoitusasu (kirjainkoolla ei silti merkitystä)

"Invalid sync cadence interval"

• REST API:lle käytä vain: minutes, hours, days, weeks
• Käytä seconds vain, kun period=realtime

"Aggregation settings are only valid for healthMetrics data type"

• Parametrit aggregatedata ja interval toimivat vain datatype=healthMetrics -tilanteessa
• Poista nämä parametrit tai vaihda datatyyppiä

"Batch requests are only valid for REST API with JSON format"

• batchrequests toimii vain, kun format=json
• Vaihda muodoksi JSON tai poista batchrequests

"Workout settings are only valid for workouts data type"

• includeroutes, includeworkoutmetadata ja workoutsmetadatainterval toimivat vain datatype=workouts -tilanteessa
• Vaihda datatyypiksi workouts tai poista nämä parametrit

"Metrics parameter is only valid for healthMetrics data type"

• metrics toimii vain datatype=healthMetrics -tilanteessa
• Vaihda datatyyppiä tai poista metrics

"Invalid metric name"

• Käytä täsmälleen MetricName rawValues -arvoja (esim. "Step Count", "Heart Rate")
• Tarkista kirjoitusasu ja isot kirjaimet
• Katso kelvolliset nimet sovelluksen mittarinvalinnan näytöstä

"Invalid request timeout"

• Oltava 60–86400 sekunnin välillä
• Käytä arvoa tältä väliltä

"A name is required for the automation"

• Varmista, että name-parametri on mukana
• Tarkista, että arvo ei ole tyhjä URL-dekoodauksen jälkeen

URL:n pituusrajoitukset

Hyvin pitkät URL-osoitteet (erityisesti monilla mittareilla tai otsikoilla) voivat ylittää järjestelmärajoituksia. Harkitse:

• Vähemmän mittareita metrics-parametrissa
• Vähemmän otsikoita
• Lyhyempiä parametriarvoja mahdollisuuksien mukaan
• Monimutkaisten määritysten jakamista useampaan yksinkertaisempaan automaatioon

Parametrien etusijajärjestys

Kun parametrit ovat ristiriidassa:

1. Datatyypin valinta (datatype) nollaa sisällytysliput automaattisesti
2. CSV-muoto (format=csv) asettaa automaattisesti aggregatedata=true
3. Reaaliaikainen jakso (period=realtime) vaatii syncinterval=seconds
4. Yhteensopimattomista yhdistelmistä tulee validointivirheitä

Parhaat käytännöt

1. Automaattinen synkronointi (kun automaatiot käynnistetään syvälinkeillä):

   • 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. URL-koodaa aina parametriarvot, jotka sisältävät erikoismerkkejä

3. Testaa ensin yksinkertaisilla URL-osoitteilla, lisää sitten monimutkaisuutta

4. Käytä kuvaavia nimiä helpompaa tunnistamista varten

5. Validoi URL-osoitteet ennen syvälinkkien ohjelmallista luontia

6. Käsittele virheet hallitusti syvälinkkejä jäsennettäessä

7. Dokumentoi syvälinkkimuotosi, jos rakennat työkaluja, jotka generoivat niitä

8. Huomioi URL:n pituus, kun mukana on paljon mittareita tai otsikoita

9. Testaa oikeilla laitteilla simulaattoreiden lisäksi

Liittyvä dokumentaatio

• REST API -automaatio – Tarkemmin REST API -automaatioista
• Automaatiot – yleiskatsaus – Yleiset automaatiokäsitteet
• Manuaalinen vienti – Datan manuaalinen vienti

Tuki

Jos kohtaat ongelmia, joita ei käsitellä tässä oppaassa:

1. Tarkista virheilmoitus parametrikohtaisia ongelmia varten
2. Varmista URL-koodauksesi oikeellisuus
3. Testaa ensin mahdollisimman lyhyellä URL-osoitteella
4. Käytä sovelluksen Chat Support -painiketta avun saamiseksi