REST-API-Automatisierungsanleitung

REST API-Automatisierungen ermöglichen es Ihnen, Ihre Gesundheitsdaten automatisch an jeden Webservice zu exportieren, der HTTP POST-Anfragen akzeptiert. Dies ist ideal für die Integration mit benutzerdefinierten Backends, Drittanbieter-APIs oder Webhooks.

Übersicht

REST API-Automatisierungen senden Ihre Gesundheitsdaten an einen angegebenen URL-Endpunkt unter Verwendung von HTTP POST-Anfragen. Die Automatisierung kann Daten im JSON- oder CSV-Format senden, mit konfigurierbaren Headern für Authentifizierung und benutzerdefinierte Metadaten.

Anwendungsfälle:

• Integration mit benutzerdefinierten Backend-Services
• Senden von Daten an Webhooks
• Synchronisierung mit Drittanbieter-APIs
• Erstellen benutzerdefinierter Dashboards oder Analyseplattformen

Hauptfunktionen:

• Unterstützt sowohl JSON- als auch CSV-Formate
• Benutzerdefinierte HTTP-Header für Authentifizierung
• Konfigurierbare Anforderungs-Timeout
• Manueller Export historischer Daten

Einschränkungen:

• Zugriff auf Gesundheitsdaten: Apps dürfen nicht auf Gesundheitsdaten zugreifen, während das iPhone gesperrt ist. Automatisierungen laufen nur, wenn Ihr Gerät entsperrt ist. Das ist eine von Apple auferlegte Einschränkung, die nicht umgangen werden kann. Weitere Informationen

• Hintergrundverarbeitung: iOS begrenzt die Hintergrundverarbeitung, um die Batterie zu schonen. Automatisierungen nutzen die Hintergrundaktualisierung der App und laufen möglicherweise nicht sofort, wenn:

  • Die Hintergrundaktualisierung für die App deaktiviert ist
  • Das Gerät im Energiesparmodus ist
  • Das Gerät längere Zeit inaktiv war
  • Systemressourcen knapp sind
  • Mehrere Apps um Hintergrundausführungszeit konkurrieren

Leistung

Bedenken Sie, dass iOS für kurz laufende Aufgaben auf Mobilgeräten mit sehr engen Leistungsgrenzen optimiert ist. Hintergrundaufgaben müssen in der Regel innerhalb von 30 Sekunden abgeschlossen sein und sind in ihrem Speicherverbrauch begrenzt. Health Auto Export bietet viel Flexibilität und Anpassbarkeit — es lohnt sich daher, zu verstehen, wie bestimmte Konfigurationen die App-Leistung und Ergebnisse beeinflussen.

• Konfiguration: Automatisierungen, die große Datenmengen erzeugen, können dazu führen, dass das System den Prozess beendet und Automatisierungen im Hintergrund nicht mehr laufen. Folgende Konfigurationen können große Datenmengen erzeugen:
  • Automatisierungen, die alle Gesundheitsmetriken exportieren.
    • Empfehlung: Wählen Sie nur Gesundheitsmetriken aus, für die in Apple Health Daten gespeichert sind, und nur Daten, die Sie tatsächlich nutzen möchten. Selbst leere Datentypen wirken sich auf die Leistung aus. Sie können ausgewählte Gesundheitsmetriken auch auf mehrere Automatisierungen aufteilen — das erleichtert die Verarbeitung für das System.
  • Automatisierungen mit Zeitgruppierungen in Sekunden oder Minuten oder mit deaktivierter Datenzusammenfassung. Solche feingranularen Abfragen können lange dauern und mit Systemgrenzen kollidieren.
    • Empfehlung: Auch wenn maximale Detailtiefe verlockend ist — prüfen Sie, ob diese für jede Metrik oder jeden Datentyp nötig ist. Erwägen Sie mehrere Automatisierungen mit unterschiedlichen Einstellungen.
  • Beim Export von Outdoor-Workouts wie Radfahren, Laufen, Wandern usw. mit Routendaten können GPS- und zugehörige Gesundheitsmetrikdaten große Nutzlasten erzeugen.
• Nutzlastgröße: Besonders bei REST-API-Exporten können große Nutzlasten Serverfehler verursachen. Stellen Sie sicher, dass Ihr Backend Nutzlasten von möglicherweise mehreren hundert Megabyte verarbeiten kann.
• Synchronisierungsfrequenz: Fügen Sie das Automatisierungs-Widget zum Home-Bildschirm hinzu, damit Automatisierungen im Hintergrund zuverlässiger laufen (siehe Automatisierungs-Widget-Einrichtung).

Voraussetzungen

• Ein gültiger URL-Endpunkt, der HTTP POST-Anfragen akzeptiert
• Authentifizierungsanmeldedaten (falls von Ihrem Endpunkt erforderlich)
• Netzwerkverbindung, um Ihren Endpunkt zu erreichen

Konfiguration

Navigieren Sie zum Bildschirm Automatisierte Exporte aus der Hauptnavigation, tippen Sie dann auf "Neue Automatisierung" und wählen Sie "REST API" als Automatisierungstyp.

Automatisierungsname

Geben Sie einen beschreibenden Namen für Ihre Automatisierung ein (z. B. "Meine Backend-API", "Webhook-Integration").

Benachrichtigungen

Konfigurieren Sie, wann Sie Benachrichtigungen erhalten möchten:

• Bei Cache-Aktualisierung benachrichtigen - Erhalten Sie eine Benachrichtigung, wenn zwischengespeicherte Daten aktualisiert werden
• Bei Ausführung benachrichtigen - Erhalten Sie eine Benachrichtigung jedes Mal, wenn die Automatisierung ausgeführt wird

URL-Konfiguration

Geben Sie die vollständige URL ein, an die Sie Ihre Gesundheitsdaten senden möchten. Dies sollte eine vollständige URL sein, einschließlich des Protokolls (http:// oder https://).

Beispiel-URLs:

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

Hinweis: Die URL muss gültig und von Ihrem Gerät aus erreichbar sein. Ungültige URLs verhindern, dass die Automatisierung ausgeführt wird.

Anforderungs-Timeout

Wählen Sie ein Timeout-Intervall für HTTP-Anfragen. Dies bestimmt, wie lange die App auf eine Antwort wartet, bevor die Anfrage als fehlgeschlagen betrachtet wird.

HTTP-Header

Fügen Sie benutzerdefinierte HTTP-Header für Authentifizierung oder Metadaten hinzu. Häufige Anwendungsfälle umfassen:

• API-Schlüssel: X-API-Key: your-api-key
• Autorisierungstoken: Authorization: Bearer your-token
• Content-Type-Überschreibungen: Content-Type: application/json

So fügen Sie Header hinzu:

1. Tippen Sie auf "Header hinzufügen"
2. Geben Sie den Header-Schlüssel in das linke Feld ein
3. Geben Sie den Header-Wert in das rechte Feld ein
4. Wiederholen Sie dies für zusätzliche Header

Wichtig: Jeder Header-Schlüssel muss einen entsprechenden Wert haben. Leere Header werden ignoriert.

Datentyp-Einstellungen

Datentyp

Wählen Sie aus, welche Art von Gesundheitsdaten exportiert werden sollen:

• Gesundheitsmetriken - Schritte, Herzfrequenz, Schlaf und andere Gesundheitsmessungen
• Workouts - Trainings- und Fitnessaktivitäten
• Symptome - Gesundheitssymptome und -zustände
• EKG - Elektrokardiogramm-Messwerte
• Herzfrequenz-Benachrichtigungen - Hohe/niedrige Herzfrequenz-Ereignisse
• Gemütszustand - Stimmungs- und mentale Zustandseinträge (iOS 18.0+)
• Zyklusverfolgung - Menstruationszyklus- und reproduktive Gesundheitsdaten
• Medikamente - Medikamentenprotokolle und Einhaltung (iOS 26.0+)

Gesundheitsmetriken-Konfiguration

Wenn Gesundheitsmetriken ausgewählt ist:

Gesundheitsmetriken auswählen - Wählen Sie aus, welche spezifischen Metriken einbezogen werden sollen. Sie können alle verfügbaren Metriken auswählen oder spezifische auswählen.

Tipp: Die Auswahl nur der benötigten Metriken kann die Verarbeitungszeit verbessern und die Datengröße reduzieren.

Bevorzugte Quellen - Konfigurieren Sie, welche Datenquellen Priorität haben, wenn mehrere Quellen dieselbe Metrik bereitstellen.

Workout-Konfiguration

Wenn Workouts ausgewählt ist:

Routendaten einbeziehen - Aktivieren Sie, um Routen für Workouts einzuschließen, die Standortdaten haben.

Workout-Metriken einbeziehen - Aktivieren Sie, um Gesundheitsmetriken einzuschließen, die während der Workouts erfasst wurden (Herzfrequenz, Kalorien usw.).

Zeitgruppierung (Workout-Metriken) - Bei Verwendung von Export-Version 2 und wenn Workout-Metriken einbeziehen aktiviert ist:

• Minuten - Gruppiert Workout-Metriken nach Minute
• Sekunden - Gruppiert Workout-Metriken nach Sekunde

Export-Einstellungen

Export-Format

Wählen Sie das Format für Ihre exportierten Daten:

• JSON-Format - Bietet detaillierte Datenstrukturen mit verschachtelten Objekten. Am besten für APIs, Datenbanken und Anwendungen, die strukturierte Daten benötigen. Das JSON-Format enthält detailliertere Informationen für komplexe Datentypen wie Schlafphasen und AFib-Messwerte.

• CSV-Format - Bietet Tabellendaten, die einfach in Tabellenkalkulationsanwendungen importiert werden können. Am besten für einfache Datenanalyse oder wenn Ihr Endpunkt CSV-Daten erwartet.

Hinweis: Der Content-Type-Header wird automatisch auf application/json für JSON-Exporte und multipart/form-data für CSV-Exporte gesetzt.

Export-Version

Wählen Sie eine Export-Version. Die Versionsverwaltung ermöglicht es, in Ihrem eigenen Tempo zwischen aktualisierten Versionen des Exports zu wechseln und minimiert Änderungen, die Workflows beeinträchtigen.

• Version 1 - Legacy-Format, verwenden Sie es, wenn Sie vorhandene Workflows haben, die von diesem Format abhängen
• Version 2 - Aktuelles Format mit erweiterten Workout-Daten und detaillierteren Metadaten-Optionen

Datumsbereich

Wählen Sie aus, wann Daten exportiert werden sollen:

• Standard - Synchronisiert Daten für den vollständigen vorherigen Tag plus Daten bis zum aktuellen Datum und zur aktuellen Uhrzeit
• Seit letzter Synchronisierung - Bei jeder Synchronisierung werden alle Daten seit dem letzten Ausführen des Exports bis zum aktuellen Datum und zur aktuellen Uhrzeit exportiert
• Heute - Synchronisiert alle Daten für das aktuelle Datum bis zur aktuellen Uhrzeit
• Gestern - Synchronisiert alle Daten für den vollständigen vorherigen Tag
• Letzte 7 Tage - Synchronisiert Daten für die vollständigen letzten sieben Tage

Daten zusammenfassen

Wenn Sie das JSON-Format mit dem Datentyp Gesundheitsmetriken verwenden, aktivieren oder deaktivieren Sie Daten zusammenfassen.

• EIN - Bietet aggregierte Datenzusammenfassungen
• AUS - Bietet disaggregierte Daten, wo möglich, und zeigt individuelle Datenpunkte

Hinweis: Diese Einstellung gilt nur für das JSON-Format mit Gesundheitsmetriken. Daten werden immer aggregiert, wenn das CSV-Format verwendet wird oder wenn mehrere Metriken ausgewählt sind.

Zeitgruppierung

Wenn Sie das JSON-Format mit aktiviertem Daten zusammenfassen verwenden, wählen Sie aus, wie Daten aggregiert werden sollen.

Hinweis: Das CSV-Format aggregiert immer Daten. Die Aggregation auf Minuten- und Sekundenebene kann die Verarbeitungszeit und Datengröße erheblich erhöhen.

Batch-Anfragen und große Nutzlasten

Wenn Sie das JSON-Format verwenden, schalten Sie Batch-Anfragen EIN, um Daten in mehreren HTTP-Anfragen statt einer großen Nutzlast zu senden.

• EIN — Verteilt Daten über mehrere Anfragen. Verwenden Sie dies, wenn Ihr Endpunkt Nutzlastgrößenlimits, Timeouts bei großen Bodies hat oder Sie Daten schrittweise verarbeiten.
• AUS — Sendet alle Daten in einer einzelnen Anfrage. Geeignet für kleinere Exporte und einfache Webhooks.

Wann Batching aktivieren:

• Viele Gesundheitsmetriken ausgewählt, lange Datumsbereiche oder feine Zeitgruppierung (Minuten/Sekunden)
• Daten zusammenfassen ist AUS und Sie exportieren disaggregierte Gesundheitsmetriken
• Ihr Server gibt Fehler oder Timeouts bei großen POST-Bodies zurück

Hinweise:

• Batch-Anfragen gelten nur für REST API + JSON (nicht CSV).
• Batching reduziert die Nutzlastgröße pro Anfrage, entfernt aber nicht die Notwendigkeit, Daten auf dem Gerät abzurufen; langsame HealthKit-Abfragen können weiterhin als Warnungen in Aktivitätsprotokollen erscheinen. Siehe Langsame Abfragen in Aktivitätsprotokollen.

Synchronisierungsfrequenz

Konfigurieren Sie, wie oft die Automatisierung Daten hochladen soll:

Wählen Sie eine Zahl und ein Intervall.

Tests und Überprüfung

Datenformat überprüfen

Die App fügt automatisch diese Header in jede Anfrage ein:

• Content-Type - Basierend auf Export-Format gesetzt
• automation-name - Der Name Ihrer Automatisierung
• automation-id - Eindeutiger Bezeichner für die Automatisierung
• automation-aggregation - Die ausgewählte Zeitgruppierung
• automation-period - Der ausgewählte Datumsbereich
• session-id - Eindeutiger Bezeichner für jede Anfrage

Aktivitätsprotokolle anzeigen

1. Tippen Sie auf Aktivitätsprotokolle anzeigen im Automatisierungskonfigurationsbildschirm.
2. Überprüfen Sie Ausführungen (gruppiert, neueste zuerst) und klappen Sie Ereignisse innerhalb jeder Ausführung auf.
3. Unterscheiden Sie Warnungen (z. B. langsame Gesundheitsdatenabfrage) von Fehler (HTTP-Fehler, Zeitüberschreitungen oder HealthKit-Lesefehler)—siehe Übersicht zu Automatisierungen — Aktivitätsprotokolle.
4. Erfolgreiche REST-Uploads zeigen oft eine Zusammenfassung mit Format, Datentyp, Exportzeitraum und Datumsbereich in der Ausführung.
5. Teilen (Symbolleiste) exportiert das vollständige Diagnose-ZIP der App-Ereignisprotokolle für den Support (wie Einstellungen → Erweitert).
6. Löschen entfernt nur den Aktivitätsverlauf dieser Automatisierung.

Fehlerbehebung

Häufige Probleme

Daten nicht am Endpunkt empfangen

• Überprüfen Sie, ob die Endpunkt-URL korrekt ist
• Überprüfen Sie, ob Ihr Endpunkt POST-Anfragen akzeptiert
• Überprüfen Sie die Authentifizierungs-Header
• Überprüfen Sie die Endpunktprotokolle auf eingehende Anfragen
• Überprüfen Sie die Netzwerkverbindung

Tipps und Best Practices

1. Automatische Synchronisierung:

• Laden Sie Ihr Gerät und nutzen Sie iPhone-Spiegelung
  • Beim Laden legt iOS weniger Leistungsbeschränkungen auf, sodass Daten häufiger synchronisiert werden können
  • Mit iPhone-Spiegelung verhält sich das Gerät wie entsperrt. So kann Health Auto Export auf Gesundheitsdaten zugreifen und automatisierte Aktionen ausführen

2. Leistung:

   • Verwenden Sie eine angemessene Zeitgruppierung, um Detail vs. Datengröße auszugleichen
   • Wählen Sie nur die Metriken aus, die Sie benötigen

• Aktivieren Sie Batch-Anfragen für große JSON-Nutzlasten (siehe Batch-Anfragen und große Nutzlasten)
• Achten Sie auf Warnungen zu langsamen Abfragen in den Aktivitätsprotokollen; reduzieren Sie Metriken oder verwenden Sie gröbere Gruppierung, wenn Ausführungen langsam sind

2. Zuverlässigkeit:

   • Legen Sie angemessene Timeout-Werte basierend auf der Antwortzeit Ihres Endpunkts fest
   • Überwachen Sie Aktivitätsprotokolle regelmäßig

• Achten Sie auf Warnungen zu langsamen Abfragen in den Aktivitätsprotokollen; reduzieren Sie Metriken oder verwenden Sie gröbere Gruppierung, wenn Ausführungen langsam sind

3. Datenformat:

   • Verwenden Sie JSON für strukturierte Daten und APIs
   • Verwenden Sie CSV für einfache Datenanalyse oder Tabellenkalkulationsintegration
   • Erwägen Sie Batch-Anfragen für große Datensätze oder separate Verarbeitung