Automatisation Deep Link

Les automatisations deep link vous permettent de créer des automatisations d'API REST par programmation en utilisant des schémas d'URL. C'est idéal pour les scripts d'automatisation, la gestion de configuration ou l'intégration avec des systèmes externes qui doivent configurer des exportations de données de santé.

Vue d'ensemble

Les automatisations deep link utilisent un schéma d'URL personnalisé pour créer et configurer des automatisations d'API REST sans saisir manuellement les paramètres dans l'app. Lorsque vous ouvrez une URL deep link, l'app crée automatiquement une nouvelle automatisation avec la configuration spécifiée.

Cas d'usage :

• Configuration programmatique d'automatisations depuis des scripts ou des outils
• Configuration en masse d'automatisations
• Intégration avec des systèmes de gestion de configuration
• Configuration rapide depuis des applications ou sites web externes
• Flux de travail de test et développement

Fonctionnalités principales :

• Créer des automatisations via un schéma d'URL
• Configurer tous les paramètres d'automatisation d'API REST
• Validation de paramètres avec sécurité de type
• Messages d'erreur complets

Limitations

• Les deep links ne prennent en charge que les automatisations d'API REST (pas Dropbox, Google Drive, etc.)
• Les limites de longueur d'URL peuvent restreindre les listes de paramètres très longues
• Toutes les limitations des automatisations d'API REST s'appliquent (traitement en arrière-plan, accès aux données de santé, etc.)

Format d'URL

L'URL deep link suit cette structure :

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

URL de base : com.HealthExport://automation

Paramètres : Tous les paramètres sont optionnels sauf name et url. Les paramètres ne sont pas sensibles à la casse.

Référence des paramètres

Paramètres requis

url (requis)

• Type : String (URL valide)
• Description : L'URL du point de terminaison où les données de santé seront envoyées
• Exemple : https://api.example.com/health-data
• Note : Doit être une URL HTTP/HTTPS valide

name (requis)

• Type : String
• Description : Un nom descriptif pour l'automatisation
• Exemple : My%20Backend%20API (codé en URL : "My Backend API")
• Note : Doit être codé en URL s'il contient des espaces ou des caractères spéciaux

Configuration de base

format

• Type : Enum (json, csv)
• Par défaut : json
• Description : Format d'exportation pour les données
• Exemple : format=json ou format=csv
• Note : Le format CSV active automatiquement l'agrégation de données

enabled

• Type : Boolean (true, false, 1, 0, yes, no)
• Par défaut : false
• Description : Si l'automatisation est activée immédiatement après la création
• Exemple : enabled=true

datatype

• Type : Enum (voir Types de données ci-dessous)
• Par défaut : healthMetrics
• Description : Type de données de santé à exporter
• Exemple : datatype=workouts
• Note : Un seul type de données peut être sélectionné. La définition de ce paramètre configure automatiquement les indicateurs d'inclusion appropriés.

Types de données valides :

• healthMetrics - Métriques de santé (pas, fréquence cardiaque, sommeil, etc.)
• workouts - Activités d'exercice et de fitness
• symptoms - Symptômes et conditions de santé
• ecg - Lectures d'électrocardiogramme
• heartRateNotification - Événements de fréquence cardiaque élevée/faible
• stateOfMind - Entrées d'humeur et d'état mental (iOS 18.0+)
• cycleTracking - Données du cycle menstruel et de santé reproductive
• medications - Journaux de médicaments et adhésion (iOS 26.0+)

Paramètres d'exportation

period

• Type : Enum
• Par défaut : none
• Description : Plage de dates pour l'exportation de données
• Exemple : period=today

Valeurs valides :

• none - Par défaut (jour précédent complet plus jour actuel)
• lastsync - Depuis la dernière synchronisation
• today - Jour actuel
• yesterday - Jour précédent
• previous7days - 7 derniers jours
• realtime - Mises à jour en temps réel (nécessite un intervalle de synchronisation en secondes)

interval

• Type : Enum
• Par défaut : none
• Description : Intervalle de regroupement/agrégation temporelle (valide uniquement pour le type de données healthMetrics)
• Exemple : interval=hours

Valeurs valides :

• none - Par défaut (pas d'agrégation)
• minutes - Grouper par minute
• hours - Grouper par heure
• days - Grouper par jour
• weeks - Grouper par semaine
• months - Grouper par mois
• years - Grouper par année

Note : Ce paramètre n'est valide que lorsque datatype=healthMetrics. Le format CSV agrège toujours les données.

aggregatedata

• Type : Boolean
• Par défaut : true (pour CSV), false (pour JSON)
• Description : S'il faut agréger/résumer les données (valide uniquement pour healthMetrics avec format JSON)
• Exemple : aggregatedata=true
• Note : Défini automatiquement à true lorsque format=csv

aggregatesleep

• Type : Boolean
• Par défaut : true
• Description : S'il faut agréger les données de sommeil
• Exemple : aggregatesleep=true

exportversion

• Type : Enum (v1, v2, 1, 2)
• Par défaut : v2
• Description : Version du format d'exportation
• Exemple : exportversion=v2
• Note : La version 2 inclut des données d'entraînement améliorées et des métadonnées plus détaillées

batchrequests

• Type : Boolean
• Par défaut : false
• Description : Envoyer les données par lots sur plusieurs requêtes (valide uniquement pour l'API REST avec format JSON)
• Exemple : batchrequests=true
• Note : Valide uniquement lorsque format=json et exportDestination=restApi

Cadence de synchronisation

syncinterval

• Type : Enum
• Par défaut : minutes
• Description : Intervalle pour la cadence de synchronisation
• Exemple : syncinterval=hours

Valeurs valides :

• minutes - Synchroniser toutes les N minutes
• hours - Synchroniser toutes les N heures
• days - Synchroniser tous les N jours
• weeks - Synchroniser toutes les N semaines
• seconds - Valide uniquement lorsque period=realtime

Note : Pour les automatisations d'API REST, seuls minutes, hours, days et weeks sont valides sauf si vous utilisez l'exportation en temps réel.

syncquantity

• Type : Integer (positif)
• Par défaut : 5
• Description : Nombre d'intervalles entre les synchronisations
• Exemple : syncquantity=10 (synchroniser toutes les 10 minutes si syncinterval=minutes)
• Note : Doit être supérieur à 0

Configuration HTTP

headers

• Type : String (paires clé-valeur séparées par des virgules)
• Par défaut : Aucun
• Description : En-têtes HTTP pour l'authentification ou les métadonnées
• Exemple : headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Format : key1,value1,key2,value2,...
• Note : Les valeurs doivent être codées en URL. Chaque en-tête nécessite à la fois une clé et une valeur.

Exemples d'en-têtes :

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

requesttimeout

• Type : Integer (60-86400)
• Par défaut : 60
• Description : Délai d'expiration de la requête en secondes
• Exemple : requesttimeout=300
• Note : Doit être entre 60 et 86400 secondes (1 minute à 24 heures)

Paramètres spécifiques au type de données

Paramètres des métriques de santé

metrics

• Type : String (valeurs rawValues MetricName séparées par des virgules)
• Par défaut : Toutes les métriques disponibles
• Description : Métriques de santé spécifiques à inclure (valide uniquement pour le type de données healthMetrics)
• Exemple : metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Note : Doit utiliser les valeurs rawValues exactes de MetricName. Si non spécifié, toutes les métriques disponibles sont incluses.

Noms de métriques courants :

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

Consultez l'écran de sélection des métriques de l'app pour la liste complète des métriques disponibles.

Paramètres d'entraînement

includeroutes

• Type : Boolean
• Par défaut : true
• Description : Inclure les données d'itinéraire pour les entraînements (valide uniquement pour le type de données workouts)
• Exemple : includeroutes=true

includeworkoutmetadata

• Type : Boolean
• Par défaut : true
• Description : Inclure les métriques d'entraînement (fréquence cardiaque, calories, etc.) collectées pendant les entraînements (valide uniquement pour le type de données workouts)
• Exemple : includeworkoutmetadata=true

workoutsmetadatainterval

• Type : Enum (minutes, seconds)
• Par défaut : minutes
• Description : Regroupement temporel pour les métriques d'entraînement (valide uniquement pour le type de données workouts avec exportVersion v2)
• Exemple : workoutsmetadatainterval=seconds
• Note : Valide uniquement lorsque datatype=workouts et exportversion=v2

workouttypes

• Type : String (valeurs UInt séparées par des virgules)
• Par défaut : Vide (tous les types d'entraînement)
• Description : Types d'entraînement spécifiques à inclure (valide uniquement pour le type de données workouts)
• Exemple : workouttypes=1,2,3
• Note : Utilise les identifiants de type d'entraînement HealthKit

Notifications

notifyonupdate

• Type : Boolean
• Par défaut : true
• Description : Recevoir des notifications lorsque les données en cache sont mises à jour
• Exemple : notifyonupdate=true

notifywhenrun

• Type : Boolean
• Par défaut : true
• Description : Recevoir des notifications à chaque exécution de l'automatisation
• Exemple : notifywhenrun=false

Exemples

Automatisation d'API REST de base

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

Crée une automatisation de base qui envoie des données JSON au point de terminaison spécifié.

Avec en-têtes d'authentification

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

Crée une automatisation avec des en-têtes d'authentification personnalisés.

Métriques de santé avec métriques spécifiques

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

Crée une automatisation qui exporte uniquement les pas et la fréquence cardiaque, agrégés par heure.

Entraînements avec données d'itinéraire

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

Crée une automatisation pour les entraînements avec données d'itinéraire et métriques d'entraînement, en utilisant la version d'exportation 2.

Exemple de configuration complète

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

Un exemple complet avec tous les paramètres principaux configurés.

Exemple de format CSV

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

Crée une automatisation d'exportation CSV. Notez que le format CSV active automatiquement l'agrégation de données.

Codification d'URL

Les caractères spéciaux dans les valeurs des paramètres doivent être codés en URL. Codifications courantes :

• Espace : %20
• Virgule : %2C
• Deux-points : %3A
• Point-virgule : %3B
• Égal : %3D
• Esperluette : %26
• Plus : %2B

Exemple :

• Original : My Automation Name
• Codé : My%20Automation%20Name

Exemple d'en-têtes :

• Original : Authorization, Bearer token123
• Codé : Authorization,Bearer%20token123

La plupart des langages de programmation et outils fournissent des fonctions de codification d'URL :

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

Test des deep links

Depuis Safari (iOS)

1. Ouvrez Safari sur votre appareil iOS
2. Entrez l'URL deep link dans la barre d'adresse
3. Appuyez sur Aller
4. L'app devrait s'ouvrir et créer l'automatisation

Depuis Terminal (macOS/Simulateur iOS)

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

Depuis Xcode

Ajoutez un point d'arrêt ou utilisez la console du débogueur :

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

Depuis l'app Raccourcis

1. Créez un nouveau raccourci
2. Ajoutez l'action "Ouvrir les URL"
3. Entrez votre URL deep link
4. Exécutez le raccourci

Dépannage

Problèmes courants

"Impossible d'analyser l'URL"

• Vérifiez que le schéma d'URL est correct : com.HealthExport://automation
• Vérifiez que toutes les valeurs des paramètres sont correctement codées en URL
• Assurez-vous que les noms des paramètres sont correctement orthographiés (insensible à la casse)

"Valeur de paramètre d'URL invalide"

• Vérifiez que l'URL est une URL HTTP/HTTPS valide
• Vérifiez le codage d'URL approprié
• Assurez-vous que l'URL ne contient pas de caractères invalides

"Type de données invalide"

• Utilisez les valeurs exactes de type de données : healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Vérifiez l'orthographe et la casse (bien qu'une correspondance insensible à la casse soit prise en charge)

"Intervalle de cadence de synchronisation invalide"

• Pour l'API REST, utilisez uniquement : minutes, hours, days, weeks
• Utilisez seconds uniquement lorsque period=realtime

"Les paramètres d'agrégation ne sont valides que pour le type de données healthMetrics"

• Les paramètres aggregatedata et interval ne fonctionnent qu'avec datatype=healthMetrics
• Supprimez ces paramètres ou changez le type de données

"Les requêtes par lots ne sont valides que pour l'API REST avec format JSON"

• batchrequests ne fonctionne que lorsque format=json
• Changez le format en JSON ou supprimez le paramètre batchrequests

"Les paramètres d'entraînement ne sont valides que pour le type de données workouts"

• includeroutes, includeworkoutmetadata et workoutsmetadatainterval ne fonctionnent qu'avec datatype=workouts
• Changez le type de données en workouts ou supprimez ces paramètres

"Le paramètre metrics n'est valide que pour le type de données healthMetrics"

• Le paramètre metrics ne fonctionne qu'avec datatype=healthMetrics
• Changez le type de données ou supprimez le paramètre metrics

"Nom de métrique invalide"

• Utilisez les valeurs rawValues exactes de MetricName (par exemple, "Step Count", "Heart Rate")
• Vérifiez l'orthographe et la capitalisation
• Consultez l'écran de sélection des métriques de l'app pour les noms valides

"Délai d'expiration de requête invalide"

• Doit être entre 60 et 86400 secondes
• Utilisez une valeur dans cette plage

"Un nom est requis pour l'automatisation"

• Assurez-vous que le paramètre name est inclus
• Vérifiez que la valeur n'est pas vide après le décodage d'URL

Limitations de longueur d'URL

Les URL très longues (en particulier avec de nombreuses métriques ou en-têtes) peuvent dépasser les limites du système. Considérez :

• Utiliser moins de métriques dans le paramètre metrics
• Réduire le nombre d'en-têtes
• Utiliser des valeurs de paramètres plus courtes lorsque possible
• Diviser les configurations complexes en plusieurs automatisations plus simples

Priorité des paramètres

Lorsque plusieurs paramètres entrent en conflit :

1. La sélection du type de données (datatype) réinitialise automatiquement les indicateurs d'inclusion
2. Le format CSV (format=csv) définit automatiquement aggregatedata=true
3. La période en temps réel (period=realtime) nécessite syncinterval=seconds
4. Des erreurs de validation seront générées pour les combinaisons incompatibles

Meilleures pratiques

1. Toujours coder en URL les valeurs des paramètres contenant des caractères spéciaux
2. Tester avec des URL simples d'abord, puis ajouter de la complexité
3. Utiliser des noms descriptifs pour faciliter l'identification
4. Valider les URL avant de créer des deep links par programmation
5. Gérer les erreurs avec élégance lors de l'analyse des deep links
6. Documenter vos formats de deep link si vous créez des outils qui les génèrent
7. Considérer la longueur de l'URL lors de l'inclusion de nombreuses métriques ou en-têtes
8. Tester sur des appareils réels ainsi que sur des simulateurs

Documentation connexe

• Guide d'automatisation de l'API REST - Informations détaillées sur les automatisations d'API REST
• Vue d'ensemble des automatisations - Concepts généraux d'automatisation
• Guide d'exportation manuelle - Comment exporter des données manuellement

Support

Si vous rencontrez des problèmes non couverts dans ce guide :

1. Vérifiez le message d'erreur pour les problèmes de paramètres spécifiques
2. Vérifiez que votre codage d'URL est correct
3. Testez avec une URL minimale d'abord
4. Utilisez le bouton Support par chat dans l'app pour obtenir de l'aide