HealthyApps Help Center

Автоматизация по диплинку

Создание автоматизаций программно с помощью URL-схем.

Last updated: April 5, 2026

На этой странице

Диплинки позволяют программно создавать автоматизации REST API через URL-схемы. Это удобно для сценариев автоматизации, управления конфигурацией и интеграции с внешними системами, которым нужно настроить экспорт данных о здоровье.

Обзор

Диплинки используют пользовательскую URL-схему для создания и настройки автоматизаций REST API без ручного ввода параметров в приложении. При открытии URL диплинка приложение автоматически создаёт новую автоматизацию с заданной конфигурацией.

Сценарии использования:

  • программная настройка автоматизаций из скриптов или утилит;
  • массовая настройка автоматизаций;
  • интеграция с системами управления конфигурацией;
  • быстрая настройка из внешних приложений или веб-сайтов;
  • сценарии тестирования и разработки.

Основные возможности:

  • создание автоматизаций через URL-схему;
  • настройка всех параметров автоматизации REST API;
  • проверка типов параметров с учётом безопасности типов;
  • подробные сообщения об ошибках.

Ограничения

  • диплинки поддерживают только автоматизации REST API (не Dropbox, Google Drive и т. д.);
  • ограничение длины URL может мешать очень длинным спискам параметров;
  • действуют все ограничения автоматизаций REST API (фоновая обработка, доступ к данным о здоровье и т. д.).

Формат 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

  • Тип: перечисление (json, csv)
  • По умолчанию: json
  • Описание: формат экспорта данных
  • Пример: format=json или format=csv
  • Примечание: для формата CSV агрегация данных включается автоматически

enabled

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

datatype

  • Тип: перечисление (см. типы данных ниже)
  • По умолчанию: healthMetrics
  • Описание: тип данных о здоровье для экспорта
  • Пример: datatype=workouts
  • Примечание: можно выбрать только один тип данных. При установке этого параметра автоматически настраиваются соответствующие флаги включения.

Допустимые типы данных:

  • healthMetrics — показатели здоровья (шаги, пульс, сон и т. д.)
  • workouts — упражнения и фитнес-активности
  • symptoms — симптомы и состояния здоровья
  • ecg — записи электрокардиограммы
  • heartRateNotification — события высокого/низкого пульса
  • stateOfMind — настроение и психическое состояние (iOS 18.0+)
  • cycleTracking — менструальный цикл и репродуктивное здоровье
  • medications — приём лекарств и соблюдение режима (iOS 26.0+)

Настройки экспорта

period

  • Тип: перечисление
  • По умолчанию: none
  • Описание: диапазон дат для экспорта данных
  • Пример: period=today

Допустимые значения:

  • none — по умолчанию (полный предыдущий день плюс текущий день)
  • lastsync — с момента последней синхронизации
  • today — текущие сутки
  • yesterday — предыдущие сутки
  • previous7days — предыдущие 7 дней
  • realtime — обновления в реальном времени (нужен интервал синхронизации seconds)

interval

  • Тип: перечисление
  • По умолчанию: none
  • Описание: интервал группировки/агрегации по времени (действителен только для типа данных healthMetrics)
  • Пример: interval=hours

Допустимые значения:

  • none — по умолчанию (без агрегации)
  • minutes — группировка по минутам
  • hours — по часам
  • days — по дням
  • weeks — по неделям
  • months — по месяцам
  • years — по годам

Примечание: параметр действителен только при datatype=healthMetrics. Формат CSV всегда агрегирует данные.

aggregatedata

  • Тип: логическое
  • По умолчанию: true (для CSV), false (для JSON)
  • Описание: агрегировать ли / суммировать данные (действительно только для healthMetrics в формате JSON)
  • Пример: aggregatedata=true
  • Примечание: при format=csv принудительно устанавливается true

aggregatesleep

  • Тип: логическое
  • По умолчанию: true
  • Описание: агрегировать ли данные о сне
  • Пример: aggregatesleep=true

exportversion

  • Тип: перечисление (v1, v2, 1, 2)
  • По умолчанию: v2
  • Описание: версия формата экспорта
  • Пример: exportversion=v2
  • Примечание: версия 2 включает расширенные данные тренировок и более подробные метаданные

batchrequests

  • Тип: логическое
  • По умолчанию: false
  • Описание: отправлять данные пакетами в нескольких запросах (действительно только для REST API в формате JSON)
  • Пример: batchrequests=true
  • Примечание: действительно только при format=json и exportDestination=restApi

Периодичность синхронизации

syncinterval

  • Тип: перечисление
  • По умолчанию: 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=minutes)
  • Примечание: значение должно быть больше 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
  • Тип: строка (список rawValue имён MetricName через запятую)
  • По умолчанию: все доступные метрики
  • Описание: какие показатели здоровья включать (действительно только для healthMetrics)
  • Пример: metrics=Step%20Count,Heart%20Rate,Active%20Energy
  • Примечание: нужно использовать точные rawValue имён MetricName. Если параметр не задан, включаются все доступные метрики.

Часто используемые имена метрик:

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

Полный список доступных метрик см. на экране выбора метрик в приложении.

Настройки тренировок

includeroutes
  • Тип: логическое
  • По умолчанию: true
  • Описание: включать данные маршрута для тренировок (действительно только для workouts)
  • Пример: includeroutes=true
includeworkoutmetadata
  • Тип: логическое
  • По умолчанию: true
  • Описание: включать метрики тренировки (пульс, калории и т. д.), собранные во время тренировки (действительно только для workouts)
  • Пример: includeworkoutmetadata=true
workoutsmetadatainterval
  • Тип: перечисление (minutes, seconds)
  • По умолчанию: minutes
  • Описание: группировка по времени для метрик тренировки (действительно только для workouts с версией экспорта v2)
  • Пример: workoutsmetadatainterval=seconds
  • Примечание: действительно только при datatype=workouts и exportversion=v2
workouttypes
  • Тип: строка (значения UInt через запятую)
  • По умолчанию: пусто (все типы тренировок)
  • Описание: какие типы тренировок включать (действительно только для workouts)
  • Пример: workouttypes=1,2,3
  • Примечание: используются идентификаторы типов тренировок HealthKit

Уведомления

notifyonupdate

  • Тип: логическое
  • По умолчанию: true
  • Описание: получать уведомления при обновлении кэшированных данных
  • Пример: notifyonupdate=true

notifywhenrun

  • Тип: логическое
  • По умолчанию: 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. Приложение должно открыться и создать автоматизацию

Устранение неполадок

Частые проблемы

"Could not parse the URL"

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

"Invalid URL parameter value"

  • URL должен быть действительным HTTP/HTTPS
  • проверьте URL-кодирование
  • в URL не должно быть недопустимых символов

"Invalid data type"

  • используйте точные значения типов: healthMetrics, workouts, symptoms, ecg, heartRateNotification, stateOfMind, cycleTracking, medications
  • проверьте написание; сопоставление без учёта регистра поддерживается

"Invalid sync cadence interval"

  • для REST API используйте только: minutes, hours, days, weeks
  • seconds — только при period=realtime

"Aggregation settings are only valid for healthMetrics data type"

  • параметры aggregatedata и interval работают только с datatype=healthMetrics
  • удалите эти параметры или смените тип данных

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

  • batchrequests работает только при format=json
  • переключите формат на JSON или удалите параметр batchrequests

"Workout settings are only valid for workouts data type"

  • includeroutes, includeworkoutmetadata и workoutsmetadatainterval работают только при datatype=workouts
  • смените тип данных на workouts или удалите эти параметры

"Metrics parameter is only valid for healthMetrics data type"

  • параметр metrics работает только при datatype=healthMetrics
  • смените тип данных или удалите параметр metrics

"Invalid metric name"

  • используйте точные rawValue MetricName (например «Step Count», «Heart Rate»)
  • проверьте написание и регистр
  • допустимые имена см. на экране выбора метрик в приложении

"Invalid request timeout"

  • значение от 60 до 86400 секунд
  • используйте значение из этого диапазона

"A name is required for the automation"

  • параметр name должен быть указан
  • значение после декодирования URL не должно быть пустым

Ограничения длины URL

Очень длинные URL (особенно со многими метриками или заголовками) могут превышать системные ограничения. Рекомендации:

  • указывайте меньше метрик в параметре metrics
  • сокращайте число заголовков
  • по возможности используйте более короткие значения параметров
  • разбивайте сложную конфигурацию на несколько более простых автоматизаций

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

При конфликте параметров:

  1. выбор типа данных (datatype) автоматически сбрасывает связанные флаги включения
  2. формат CSV (format=csv) автоматически задаёт aggregatedata=true
  3. режим реального времени (period=realtime) требует syncinterval=seconds
  4. несовместимые комбинации вызывают ошибки валидации

Лучшие практики

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

    • заряжайте устройство и используйте Трансляцию iPhone на Mac (iPhone Mirroring)
      • при зарядке iOS меньше ограничивает производительность устройства, поэтому данные могут синхронизироваться чаще
      • при трансляции iPhone на Mac устройство ведёт себя как при разблокированном экране: данные о здоровье доступны Health Auto Export для автоматических действий

  2. Всегда URL-кодируйте значения параметров со спецсимволами

  3. Сначала проверьте простые URL, затем усложняйте конфигурацию

  4. Используйте понятные имена для удобной идентификации

  5. Проверяйте URL перед программной генерацией диплинков

  6. Корректно обрабатывайте ошибки при разборе диплинков

  7. Документируйте форматы диплинков, если создаёте инструменты, которые их генерируют

  8. Учитывайте длину URL при большом числе метрик или заголовков

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

См. также

Поддержка

Если вы столкнулись с проблемой, которая не описана в этом руководстве:

  1. прочитайте сообщение об ошибке — в нём могут быть указаны проблемные параметры
  2. проверьте корректность URL-кодирования
  3. сначала протестируйте минимальный URL
  4. для помощи используйте кнопку чата поддержки в приложении