REST API-automatiseringsgids

REST API-automatiseringen stellen u in staat om uw gezondheidsgegevens automatisch te exporteren naar elke webservice die HTTP POST-verzoeken accepteert. Dit is ideaal voor integratie met aangepaste backends, API's van derden of webhooks.

Overzicht

REST API-automatiseringen sturen uw gezondheidsgegevens naar een opgegeven URL-endpoint met behulp van HTTP POST-verzoeken. De automatisering kan gegevens verzenden in JSON- of CSV-formaat, met configureerbare headers voor authenticatie en aangepaste metadata.

Gebruikssituaties:

• Integratie met aangepaste backend-services
• Gegevens verzenden naar webhooks
• Synchronisatie met API's van derden
• Aangepaste dashboards of analyseplatforms bouwen

Belangrijkste functies:

• Ondersteunt zowel JSON- als CSV-formaten
• Aangepaste HTTP-headers voor authenticatie
• Configureerbare verzoek-timeout
• Handmatige export van historische gegevens

Beperkingen:

• Toegang tot gezondheidsgegevens: Apps mogen geen gezondheidsgegevens lezen terwijl de iPhone vergrendeld is. Automatiseringen draaien alleen wanneer uw apparaat ontgrendeld is. Dit is een door Apple opgelegde beperking die niet te omzeilen is. Meer informatie

• Achtergrondverwerking: iOS beperkt achtergrondverwerking om de batterij te sparen. Automatiseringen zijn afhankelijk van Achtergrond-app verversen en draaien mogelijk niet meteen als:

  • Achtergrond-app verversen is uitgeschakeld voor de app
  • Het apparaat in de energiebesparingsmodus staat
  • Het apparaat lang inactief is geweest
  • Systeembronnen beperkt zijn
  • Meerdere apps om achtergronduitvoeringstijd concurreren

Prestaties

Houd er rekening mee dat iOS is geoptimaliseerd voor kortlopende taken op een mobiel apparaat met zeer strakke prestatiebeperkingen. Achtergrondtaken moeten doorgaans binnen 30 seconden worden voltooid en zijn beperkt in hoeveel geheugen ze kunnen gebruiken. Health Auto Export biedt veel flexibiliteit en aanpasbaarheid, en dat vereist dat u begrijpt hoe bepaalde configuraties de app-prestaties en resultaten beïnvloeden.

• Configuratie: Automatiseringen die grote hoeveelheden gegevens produceren, kunnen ervoor zorgen dat het systeem het proces beëindigt en automatiseringen niet meer op de achtergrond draaien. De volgende configuraties kunnen grote hoeveelheden gegevens produceren:
  • Automatiseringen die zijn geconfigureerd om alle gezondheidsmetrieken te exporteren.
    • Aanbeveling: selecteer alleen gezondheidsmetrieken waarvoor gegevens in Apple Health zijn opgeslagen en alleen gegevens die u daadwerkelijk wilt gebruiken. Zelfs lege gegevenstypen hebben invloed op de prestaties. U kunt geselecteerde gezondheidsmetrieken ook over meerdere automatiseringen verdelen, wat het voor het systeem makkelijker maakt om ze te verwerken.
  • Automatiseringen met tijdgroepering in seconden of minuten, of met Gegevens samenvatten uitgeschakeld. Zulke gedetailleerde queries kunnen lang duren en botsen met systeembeperkingen.
    • Aanbeveling: hoewel het ideaal lijkt om de meest gedetailleerde gegevens te hebben, overweeg of dat detailniveau nodig is voor elke metriek of elk gegevenstype. Overweeg meerdere automatiseringen met verschillende instellingen.
  • Bij het exporteren van outdoor-workouts, zoals fietsen, hardlopen, wandelen enz. met routedata, kunnen GPS en bijbehorende gezondheidsmetriekgegevens grote payloads opleveren.
• Payloadgrootte: Vooral bij REST API-export: grote payloads kunnen serverfouten veroorzaken. Zorg dat uw backend is geconfigureerd om payloads van mogelijk enkele honderden megabytes aan te kunnen om fouten te voorkomen.
• Synchronisatiefrequentie: Voeg de Automatiseringen-widget toe aan uw startscherm om te helpen ervoor te zorgen dat automatiseringen succesvol op de achtergrond draaien (zie Gids voor het instellen van de automatiseringen-widget).

Vereisten

• Een geldig URL-endpoint dat HTTP POST-verzoeken accepteert
• Authenticatiegegevens (indien vereist door uw endpoint)
• Netwerkverbinding om uw endpoint te bereiken

Configuratie

Navigeer naar het scherm Geautomatiseerde exports vanuit de hoofdnavigatie, tik vervolgens op "Nieuwe automatisering" en selecteer "REST API" als Automatiseringstype.

Automatiseringsnaam

Voer een beschrijvende naam in voor uw automatisering (bijvoorbeeld "Mijn Backend API", "Webhook-integratie").

Meldingen

Configureer wanneer u meldingen wilt ontvangen:

• Melden bij cache-update - Ontvang een melding wanneer gecachte gegevens worden bijgewerkt
• Melden bij uitvoering - Ontvang een melding telkens wanneer de automatisering wordt uitgevoerd

URL-configuratie

Voer de volledige URL in waar u uw gezondheidsgegevens naartoe wilt sturen. Dit moet een volledige URL zijn inclusief het protocol (http:// of https://).

Voorbeeld-URL's:

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

Opmerking: De URL moet geldig zijn en toegankelijk vanaf uw apparaat. Ongeldige URL's voorkomen dat de automatisering wordt uitgevoerd.

Verzoek-timeout

Selecteer een timeout-interval voor HTTP-verzoeken. Dit bepaalt hoe lang de app wacht op een antwoord voordat het verzoek als mislukt wordt beschouwd.

HTTP-headers

Voeg aangepaste HTTP-headers toe voor authenticatie of metadata. Veelvoorkomende gebruikssituaties zijn:

• API-sleutels: X-API-Key: your-api-key
• Autorisatietokens: Authorization: Bearer your-token
• Content-type overschrijvingen: Content-Type: application/json

Om headers toe te voegen:

1. Tik op "Headers toevoegen"
2. Voer de header-sleutel in het linkerveld in
3. Voer de header-waarde in het rechterveld in
4. Herhaal voor aanvullende headers

Belangrijk: Elke header-sleutel moet een bijbehorende waarde hebben. Lege headers worden genegeerd.

Gegevenstype-instellingen

Gegevenstype

Selecteer welk type gezondheidsgegevens u wilt exporteren:

• Gezondheidsmetrieken - Stappen, hartslag, slaap en andere gezondheidsmetingen
• Trainingen - Oefen- en fitnessactiviteiten
• Symptomen - Gezondheidssymptomen en -aandoeningen
• ECG - Elektrocardiogrammetingen
• Hartslagmeldingen - Hoge/lage hartslaggebeurtenissen
• Gemoedstoestand - Stemmings- en mentale toestandsinvoeren (iOS 18.0+)
• Cyclusvolging - Menstruatiecyclus- en reproductieve gezondheidsgegevens
• Medicijnen - Medicijnlogboeken en naleving (iOS 26.0+)

Configuratie gezondheidsmetrieken

Wanneer Gezondheidsmetrieken is geselecteerd:

Selecteer gezondheidsmetrieken - Kies welke specifieke metrieken u wilt opnemen. U kunt alle beschikbare metrieken selecteren of specifieke kiezen.

Tip: Alleen de metrieken selecteren die u nodig heeft, kan de verwerkingstijd verbeteren en de gegevensgrootte verminderen.

Voorkeursbronnen - Configureer welke gegevensbronnen prioriteit hebben wanneer meerdere bronnen dezelfde metriek leveren.

Configuratie trainingen

Wanneer Trainingen is geselecteerd:

Routegegevens opnemen - Schakel AAN om routes op te nemen voor trainingen die locatiegegevens hebben.

Trainingsmetrieken opnemen - Schakel AAN om gezondheidsmetrieken op te nemen die tijdens trainingen zijn verzameld (hartslag, calorieën, enz.).

Tijdsgroepering (trainingsmetrieken) - Bij gebruik van Exportversie 2 en wanneer Trainingsmetrieken opnemen is ingeschakeld:

• Minuten - Groepeert trainingsmetrieken per minuut
• Seconden - Groepeert trainingsmetrieken per seconde

Exportinstellingen

Exportformaat

Selecteer het formaat voor uw geëxporteerde gegevens:

• JSON-formaat - Biedt gedetailleerde gegevensstructuren met geneste objecten. Het beste voor API's, databases en applicaties die gestructureerde gegevens nodig hebben. JSON-formaat bevat meer gedetailleerde informatie voor complexe gegevenstypen zoals slaapfasen en AFib-metingen.

• CSV-formaat - Biedt tabelgegevens die eenvoudig kunnen worden geïmporteerd in spreadsheetapplicaties. Het beste voor eenvoudige gegevensanalyse of wanneer uw endpoint CSV-gegevens verwacht.

Opmerking: De Content-Type-header wordt automatisch ingesteld op application/json voor JSON-exports en multipart/form-data voor CSV-exports.

Exportversie

Selecteer een Exportversie. Versiebeheer maakt het mogelijk om in uw eigen tempo over te schakelen tussen bijgewerkte versies van de export en minimaliseert wijzigingen die workflows verstoren.

• Versie 1 - Legacy-formaat, gebruik dit als u bestaande workflows heeft die afhankelijk zijn van dit formaat
• Versie 2 - Huidig formaat met verbeterde trainingsgegevens en meer gedetailleerde metadata-opties

Datumbereik

Selecteer wanneer gegevens moeten worden geëxporteerd:

• Standaard - Synchroniseert gegevens voor de volledige vorige dag plus gegevens tot de huidige datum en tijd
• Sinds laatste synchronisatie - Bij elke synchronisatie worden alle gegevens geëxporteerd sinds de laatste keer dat de export werd uitgevoerd tot de huidige datum en tijd
• Vandaag - Synchroniseert alle gegevens voor de huidige datum tot de huidige tijd
• Gisteren - Synchroniseert alle gegevens voor de volledige vorige dag
• Afgelopen 7 dagen - Synchroniseert gegevens voor de volledige afgelopen zeven dagen

Gegevens samenvatten

Bij gebruik van JSON-formaat met gegevenstype Gezondheidsmetrieken, schakel Gegevens samenvatten AAN of UIT.

• AAN - Biedt geaggregeerde gegevenssamenvattingen
• UIT - Biedt gedisaggregeerde gegevens waar mogelijk, met individuele gegevenspunten

Opmerking: Deze instelling is alleen van toepassing op JSON-formaat met Gezondheidsmetrieken. Gegevens worden altijd geaggregeerd bij gebruik van CSV-formaat of wanneer meerdere metrieken zijn geselecteerd.

Tijdsgroepering

Bij gebruik van JSON-formaat met Gegevens samenvatten ingeschakeld, selecteer hoe gegevens moeten worden geaggregeerd.

Opmerking: CSV-formaat aggregeert altijd gegevens. Aggregatie op minuut- en seconde-niveau kan de verwerkingstijd en gegevensgrootte aanzienlijk verhogen.

Batchverzoeken en grote payloads

Bij JSON-formaat schakelt u Batchverzoeken IN om gegevens in meerdere HTTP-verzoeken te sturen in plaats van één grote payload.

• AAN — Spreidt gegevens over meerdere verzoeken. Gebruik wanneer uw endpoint payloadlimieten, timeouts op grote bodies heeft of gegevens incrementeel verwerkt.
• UIT — Stuurt alle gegevens in één verzoek. Geschikt voor kleinere exports en eenvoudige webhooks.

Wanneer batching inschakelen:

• Veel gezondheidsmetrieken geselecteerd, lange datumbereiken of fijne tijdgroepering (minuten/seconden)
• Gegevens samenvatten staat UIT en u exporteert gedesaggregeerde gezondheidsmetrieken
• Uw server retourneert fouten of timeouts op grote POST-bodies

Opmerkingen:

• Batchverzoeken gelden alleen voor REST API + JSON (niet CSV).
• Batching verkleint de payload per verzoek maar verwijdert niet het ophalen op het apparaat; trage HealthKit-query’s kunnen nog steeds als waarschuwingen in activiteitslogboeken verschijnen. Zie Trage query’s in activiteitslogboeken.

Synchronisatiefrequentie

Configureer hoe vaak de automatisering gegevens moet uploaden:

Selecteer een getal en interval.

Testen en verificatie

Gegevensformaat verifiëren

De app voegt automatisch deze headers toe aan elk verzoek:

• Content-Type - Ingesteld op basis van exportformaat
• automation-name - De naam van uw automatisering
• automation-id - Unieke identifier voor de automatisering
• automation-aggregation - De geselecteerde tijdsgroepering
• automation-period - Het geselecteerde datumbereik
• session-id - Unieke identifier voor elk verzoek

Problemen oplossen

Veelvoorkomende problemen

Gegevens niet ontvangen bij endpoint

• Verifieer dat de endpoint-URL correct is
• Controleer of uw endpoint POST-verzoeken accepteert
• Controleer authenticatieheaders
• Controleer endpoint-logboeken op inkomende verzoeken
• Verifieer netwerkverbinding

Tips en best practices

1. Automatische synchronisatie:

   • Laad uw apparaat op en gebruik iPhone-spiegeling
     • Tijdens het opladen legt iOS minder prestatiebeperkingen op, zodat gegevens vaker kunnen worden gesynchroniseerd
     • Met iPhone-spiegeling gedraagt het apparaat zich alsof het ontgrendeld is. Zo kan Health Auto Export gezondheidsgegevens gebruiken voor geautomatiseerde acties

2. Prestaties:

   • Gebruik passende tijdsgroepering om detail vs. gegevensgrootte in balans te brengen
   • Selecteer alleen de metrieken die u nodig heeft

3. Betrouwbaarheid:

   • Stel passende timeout-waarden in op basis van de responstijd van uw endpoint
   • Monitor activiteitenlogboeken regelmatig

4. Gegevensformaat:

   • Gebruik JSON voor gestructureerde gegevens en API's
   • Gebruik CSV voor eenvoudige gegevensanalyse of spreadsheetintegratie
   • Overweeg batch-verzoeken voor grote datasets of gescheiden verwerking

Activiteitenlogboeken bekijken

1. Tik op Activiteitenlogboeken bekijken op het configuratiescherm van de automatisering.
2. Bekijk runs (gegroepeerd, nieuwste eerst) en vouw gebeurtenissen binnen elke run uit.
3. Onderscheid waarschuwingen (bijv. trage gezondheidsdataquery) van fouten (HTTP-fouten, time-outs of HealthKit-leesfouten)—zie Overzicht automatiseringen — Activiteitenlogboeken.
4. Geslaagde REST-uploads tonen vaak een samenvatting met formaat, gegevenstype, exportperiode en datumbereik in de run.
5. Deel (werkbalk) exporteert de volledige diagnostische ZIP van App-gebeurtenislogboeken voor ondersteuning (zelfde als Instellingen → Geavanceerd).
6. Wissen verwijdert alleen de activiteitengeschiedenis van deze automatisering.