Автоматизація глибоких посилань

Автоматизація глибоких посилань дозволяє програмно створювати автоматизації REST API за допомогою схем URL-адрес. Це ідеально підходить для сценаріїв автоматизації, керування конфігурацією або інтеграції із зовнішніми системами, яким потрібно налаштувати експорт даних про здоров’я.

Огляд

Автоматизація посилань на глибину використовує спеціальну схему URL-адреси для створення та налаштування автоматизації REST API без ручного введення налаштувань у програмі. Коли ви відкриваєте URL-адресу глибокого посилання, програма автоматично створює нову автоматизацію з указаною конфігурацією.

Випадки використання:

• Програмне налаштування автоматизації за допомогою сценаріїв або інструментів
• Конфігурація масової автоматизації
• Інтеграція з системами управління конфігурацією
• Швидке налаштування із зовнішніх програм або веб-сайтів
• Робочі процеси тестування та розробки

Ключові характеристики:

• Створення автоматизації за допомогою схеми URL
• Налаштуйте всі параметри автоматизації REST API
• Типобезпечна перевірка параметрів
• Вичерпні повідомлення про помилки

Обмеження

• Глибинні посилання підтримують лише автоматизацію REST API (не Dropbox, Google Drive тощо)
• Обмеження довжини URL-адреси можуть обмежувати дуже довгі списки параметрів
• Застосовуються всі обмеження автоматизації REST API (фонова обробка, доступ до даних про здоров’я тощо).

Формат URL-адреси

URL-адреса глибокого посилання має таку структуру:

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

Базова URL-адреса: com.HealthExport://automation

Параметри: Усі параметри є необов’язковими, крім name і url. Параметри нечутливі до регістру.

Довідник параметрів

Необхідні параметри

url (обов'язково)

• Тип: Рядок (дійсна URL-адреса)
• Опис: URL-адреса кінцевої точки, куди надсилатимуться дані про стан здоров’я
• Приклад: https://api.example.com/health-data
• Примітка. Має бути дійсна URL-адреса HTTP/HTTPS

name (обов'язково)

• Тип: рядок
• Опис: Описова назва для автоматизації
• Приклад: My%20Backend%20API (URL-кодування: My Backend API»)
• Примітка. Повинен бути закодований URL-адресою, якщо містить пробіли або спеціальні символи

Базова конфігурація

format

• Тип: Enum (json, csv)
• За замовчуванням: json
• Опис: Формат експорту даних
• Приклад: format=json або format=csv
• Примітка. Формат CSV автоматично вмикає агрегацію даних

enabled

• Тип: Логічний (true, false, 1, 0, yes, no)
• За замовчуванням: false
• Опис: Чи ввімкнено автоматизацію одразу після створення
• Приклад: enabled=true

datatype

• Тип: Enum (див. Типи даних нижче)
• За замовчуванням: healthMetrics
• Опис: Тип даних про здоров’я для експорту
• Приклад: datatype=workouts
• Примітка. Можна вибрати лише один тип даних. Встановлення цього параметра автоматично налаштовує відповідні прапорці включення.

Дійсні типи даних:

• healthMetrics - показники здоров'я (кроки, пульс, сон тощо)
• workouts - Заняття спортом і фітнесом
• symptoms – Симптоми та стани здоров’я
• ecg - показання електрокардіограми
• heartRateNotification - події високого/низького пульсу
• stateOfMind - записи про настрій і психічний стан (iOS 18.0+)
• cycleTracking - дані про менструальний цикл і репродуктивне здоров'я
• medications - Журнали прийому ліків і дотримання (iOS 26.0+)

Налаштування експорту

period

• Тип: Enum
• За замовчуванням: none
• Опис: Діапазон дат для експорту даних
• Приклад: period=today

Дійсні значення:

• none - за замовчуванням (повний попередній день плюс поточний день)
• lastsync - З часу останньої синхронізації
• today - поточний день
• yesterday - Попередній день
• previous7days - Попередні 7 днів
• realtime - Оновлення в реальному часі (потрібний інтервал синхронізації в секундах)

interval

• Тип: Enum
• За замовчуванням: none
• Опис: Групування за часом/інтервал агрегації (дійсно лише для типу даних HealthMetrics)
• Приклад: interval=hours

Дійсні значення:

• none - за замовчуванням (без агрегації)
• minutes - Групування за хвилинами
• hours - Групування за годинами
• days - Групувати за днями
• weeks - Групування за тижнем
• months - Групувати за місяцями
• years - Групування за роками

Примітка: Цей параметр дійсний лише для datatype=healthMetrics. Формат CSV завжди агрегує дані.

aggregatedata

• Тип: Boolean
• За замовчуванням: true (для CSV), false (для JSON)
• Опис: Чи агрегувати/узагальнювати дані (дійсно лише для HealthMetrics із форматом JSON)
• Приклад: aggregatedata=true
• Примітка. Автоматично встановлюється на true, коли format=csv

aggregatesleep

• Тип: Boolean
• За замовчуванням: true
• Опис: Чи зводити дані про сон
• Приклад: aggregatesleep=true

exportversion

• Тип: Enum (v1, v2, 1, 2)
• За замовчуванням: v2
• Опис: Версія формату експорту
• Приклад: exportversion=v2
• Примітка. Версія 2 містить розширені дані про тренування та більш детальні метадані

batchrequests

• Тип: Boolean
• За замовчуванням: false
• Опис: надсилати дані пакетами через кілька запитів (дійсно лише для REST API із форматом JSON)
• Приклад: batchrequests=true
• Примітка: Діє лише для format=json і exportDestination=restApi

Синхронізація каденції

syncinterval

• Тип: Enum
• За замовчуванням: minutes
• Опис: Інтервал для частоти синхронізації
• Приклад: syncinterval=hours

Дійсні значення:

• minutes - синхронізація кожні N хвилин
• hours - синхронізація кожні N годин
• days - синхронізація кожні N днів
• weeks - синхронізація кожні N тижнів
• seconds – дійсний лише коли period=realtime

Примітка. Для автоматизації REST API дійсні лише minutes, hours, days і weeks, якщо не використовується експорт у реальному часі.

syncquantity

• Тип: Ціле (позитивне)
• За замовчуванням: 5
• Опис: Кількість інтервалів між синхронізаціями
• Приклад: syncquantity=10 (синхронізувати кожні 10 хвилин, якщо syncinterval=хвилини)
• Примітка. Має бути більше 0

Конфігурація HTTP

headers

• Тип: Рядок (пари ключ-значення, розділені комами)
• За замовчуванням: Немає
• Опис: HTTP-заголовки для автентифікації або метаданих
• Приклад: headers=Authorization,Bearer%20token123,X-API-Key,abc123
• Формат: key1,value1,key2,value2,...
• Примітка. Значення мають бути закодовані в URL-адресі. Кожен заголовок потребує як ключа, так і значення.

Приклади заголовків:

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

requesttimeout

• Тип: Ціле число (60-86400)
• За замовчуванням: 60
• Опис: Час очікування запиту в секундах
• Приклад: requesttimeout=300
• Примітка. Має бути від 60 до 86400 секунд (від 1 хвилини до 24 годин)

Спеціальні налаштування типу даних

Налаштування показників здоров'я

metrics

• Тип: Рядок (розділені комами MetricName rawValues)
• За замовчуванням: усі доступні показники
• Опис: Конкретні показники здоров’я, які слід включити (дійсно лише для типу даних healthMetrics)
• Приклад: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• Примітка. Необхідно використовувати точні RawValues ​​MetricName. Якщо не вказано, усі доступні показники включені.

Загальні назви показників:

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

Повний список доступних показників див. на екрані вибору показників програми.

Налаштування тренування

includeroutes

• Тип: Boolean
• За замовчуванням: true
• Опис: Включити дані маршруту для тренувань (дійсно лише для типу даних тренувань)
• Приклад: includeroutes=true

includeworkoutmetadata

• Тип: Boolean
• За замовчуванням: true
• Опис: включає показники тренувань (частота серцевих скорочень, калорії тощо), зібрані під час тренувань (дійсно лише для типу даних тренувань)
• Приклад: includeworkoutmetadata=true

workoutsmetadatainterval

• Тип: Enum (minutes, seconds)
• За замовчуванням: minutes
• Опис: Групування часу для показників тренувань (дійсно лише для типу даних тренувань із версією exportVersion v2)
• Приклад: workoutsmetadatainterval=seconds
• Примітка: Діє лише для datatype=workouts і exportversion=v2

workouttypes

• Тип: Рядок (значення UInt, розділені комами)
• За замовчуванням: Порожньо (усі типи тренувань)
• Опис: Конкретні типи тренувань для включення (дійсно лише для типу даних тренувань)
• Приклад: workouttypes=1,2,3
• Примітка. Використовує ідентифікатори типу тренування HealthKit

Сповіщення

notifyonupdate

• Тип: Boolean
• За замовчуванням: true
• Опис: Отримуйте сповіщення, коли кешовані дані оновлюються
• Приклад: notifyonupdate=true

notifywhenrun

• Тип: Boolean
• За замовчуванням: true
• Опис: Отримуйте сповіщення кожного разу, коли виконується автоматизація
• Приклад: notifywhenrun=false

Приклади

Основна автоматизація REST API

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

Створює базову автоматизацію, яка надсилає дані JSON до вказаної кінцевої точки.

З заголовками автентифікації

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

Створює автоматизацію з власними заголовками автентифікації.

Показники здоров’я з конкретними показниками

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

Створює автоматизацію, яка експортує лише кількість кроків і частоту серцевих скорочень, узагальнених за годинами.

Тренування з даними маршруту

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

Створює автоматизацію для тренувань із даними маршруту та показниками тренувань, використовуючи експорт версії 2.

Приклад повної конфігурації

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

Вичерпний приклад із усіма налаштованими основними параметрами.

Приклад формату CSV

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

Створює автоматизований експорт CSV. Зауважте, що формат CSV автоматично вмикає агрегацію даних.

Кодування URL

Спеціальні символи в значеннях параметрів мають бути закодовані URL-адресою. Поширені кодування:

• Пробіл: %20
• Кома: %2C
• Двокрапка: %3A
• Крапка з комою: %3B
• Дорівнює: %3D
• Амперсанд: %26
• Плюс: %2B

Приклад:

• Оригінал: My Automation Name
• Закодовано: My%20Automation%20Name

Приклад заголовків:

• Оригінал: Authorization, Bearer token123
• Закодовано: Authorization,Bearer%20token123

Більшість мов програмування та інструментів надають функції кодування URL:

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

Тестування глибинних посилань

З Safari (iOS)

1. Відкрийте Safari на пристрої iOS
2. Введіть URL-адресу глибокого посилання в адресний рядок
3. Натисніть Перейти
4. Додаток має відкритися та створити автоматизацію

З терміналу (симулятор macOS/iOS)

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

З Xcode

Додайте точку зупину або скористайтеся консоллю налагоджувача:

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

З програми «Ярлики».

1. Створіть новий ярлик
2. Додайте дію «Відкрити URL-адреси».
3. Введіть URL-адресу глибокого посилання
4. Запустіть ярлик

Усунення несправностей

Загальні питання

"Не вдалося проаналізувати URL"

• Переконайтеся, що схема URL-адреси правильна: com.HealthExport://automation
• Переконайтеся, що всі значення параметрів правильно закодовані URL-адресою
• Переконайтеся, що назви параметрів написані правильно (незалежно від регістру)

"Недійсне значення параметра URL"

• Переконайтеся, що URL-адреса є дійсною URL-адресою HTTP/HTTPS
• Перевірте правильність кодування URL-адреси
• Переконайтеся, що URL-адреса не містить неприпустимих символів

"Недійсний тип даних"

• Використовуйте точні значення типу даних: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
• Перевірка орфографії та регістру (хоча підтримка регістру не залежить від регістру)

"Недійсний інтервал синхронізації"

• Для REST API використовуйте лише: minutes, hours, days, weeks
• Використовуйте seconds лише тоді, коли period=realtime

"Налаштування агрегації дійсні лише для типу даних healthMetrics"

• Параметри aggregatedata і interval працюють лише з datatype=healthMetrics
• Видаліть ці параметри або змініть тип даних

"Пакетні запити дійсні лише для REST API із форматом JSON"

• batchrequests працює лише з format=json
• Змініть формат на JSON або видаліть параметр batchrequests

"Параметри тренувань дійсні лише для типу даних тренувань"

• includeroutes, includeworkoutmetadata і workoutsmetadatainterval працюють лише з datatype=workouts
• Змініть тип даних на тренування або видаліть ці параметри

"Параметр Metrics дійсний лише для типу даних healthMetrics"

• Параметр metrics працює лише з datatype=healthMetrics
• Змініть тип даних або видаліть параметр метрики

"Недійсна назва показника"

• Використовуйте точні RawValues ​​MetricName (наприклад, «Кількість кроків», «Часота серцевих скорочень»)
• Перевірте правопис і великі літери
• Перегляньте дійсні назви на екрані вибору показників програми

"Недійсний час очікування запиту"

• Має бути від 60 до 86400 секунд
• Використовуйте значення в межах цього діапазону

"Для автоматизації потрібна назва"

• Переконайтеся, що включено параметр name
• Переконайтеся, що значення не пусте після декодування URL-адреси

Обмеження довжини URL

Дуже довгі URL-адреси (особливо з великою кількістю показників або заголовків) можуть перевищувати системні обмеження. Розглянемо:

• Використання меншої кількості показників у параметрі metrics
• Зменшення кількості заголовків
• За можливості використовуйте коротші значення параметрів
• Розбиття складних конфігурацій на кілька простіших систем автоматизації

Пріоритет параметра

Коли кілька параметрів конфліктують:

1. Вибір типу даних (datatype) автоматично скидає позначки включення
2. Формат CSV (format=csv) автоматично встановлює aggregatedata=true
3. Період реального часу (period=realtime) вимагає syncinterval=seconds
4. Для несумісних комбінацій будуть видані помилки підтвердження

Найкращі практики

1. Автоматична синхронізація (коли автоматизації запускаються через глибокі посилання):

   • Заряджайте свій пристрій і використовуйте iPhone Mirroring
     • Коли ваш пристрій заряджається, iOS накладає менше обмежень на продуктивність пристрою, тому дані можуть синхронізуватися частіше
     • За допомогою iPhone Mirroring ваш пристрій поводиться так само, як якщо б його було розблоковано. Це означає, що дані про здоров’я доступні за допомогою Health Auto Export для виконання автоматизованих дій

2. Завжди URL-кодування значень параметрів, що містять спеціальні символи

3. Спочатку перевірте прості URL-адреси, а потім додайте складності

4. Використовуйте описові назви для легшої ідентифікації

5. Перевірте URL-адреси перед створенням глибоких посилань програмним шляхом

6. Витончено обробляйте помилки під час аналізу глибоких посилань

7. Документуйте свої формати глибоких посилань, якщо створюєте інструменти, які їх створюють

8. Враховуйте довжину URL-адреси, додаючи багато показників або заголовків

9. Тестуйте на реальних пристроях, а також на симуляторах

Пов'язана документація

• Посібник з автоматизації REST API - Докладна інформація про автоматизацію REST API
• Огляд автоматизації - Загальні концепції автоматизації
• Посібник з експорту вручну - Як експортувати дані вручну

Підтримка

Якщо ви зіткнулися з проблемами, не розглянутими в цьому посібнику:

1. Перевірте повідомлення про помилку щодо певних проблем із параметрами
2. Перевірте правильність кодування URL-адреси
3. Спочатку протестуйте з мінімальною URL-адресою
4. Скористайтеся кнопкою підтримки в чаті в додатку, щоб отримати допомогу