深度链接自动化
使用 URL 方案以编程方式创建自动化。
Last updated: April 5, 2026
本页目录
深度链接自动化可通过 URL 方案以编程方式创建 REST API 自动化。适合自动化脚本、配置管理，或需要配置健康数据导出的外部系统。
概述
深度链接自动化使用自定义 URL 方案，无需在应用中手动逐项输入即可创建并配置 REST API 自动化。打开深度链接 URL 时，应用会自动按指定配置创建新自动化。
适用场景：
- 通过脚本或工具以编程方式设置自动化
- 批量配置自动化
- 与配置管理系统集成
- 从外部应用或网站快速设置
- 测试与开发流程
主要功能：
- 通过 URL 方案创建自动化
- 配置全部 REST API 自动化选项
- 类型安全的参数校验
- 详细的错误信息
限制
- 深度链接仅支持 REST API 自动化（不支持 Dropbox、Google Drive 等）
- URL 长度限制可能影响很长的参数列表
- 适用 REST API 自动化的全部限制（后台处理、健康数据访问等）
URL 格式
深度链接 URL 结构如下：
com.HealthExport://automation?parameter1=value1¶meter2=value2&...
基础 URL： com.HealthExport://automation
参数： 除 name 与 url 外均为可选。参数名不区分大小写。
参数说明
必填参数
url（必填）
- 类型： 字符串（有效 URL）
- 说明： 接收健康数据的端点 URL
- 示例：
https://api.example.com/health-data - 注意： 须为有效 HTTP/HTTPS URL
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— 实时更新（需秒级同步间隔）
interval
- 类型： 枚举
- 默认：
none - 说明： 时间分组/汇总间隔（仅当
datatype=healthMetrics时有效） - 示例：
interval=hours
有效值：
none— 默认（不汇总）minutes— 按分钟分组hours— 按小时分组days— 按日分组weeks— 按周分组months— 按月分组years— 按年分组
注意： 仅在 datatype=healthMetrics 时有效。CSV 格式始终汇总数据。
aggregatedata
- 类型： 布尔
- 默认： CSV 为
true，JSON 为false - 说明： 是否汇总数据（仅 JSON 且
healthMetrics时有效） - 示例：
aggregatedata=true - 注意：
format=csv时自动为true
aggregatesleep
- 类型： 布尔
- 默认：
true - 说明： 是否汇总睡眠数据
- 示例：
aggregatesleep=true
exportversion
- 类型： 枚举（
v1、v2、1、2） - 默认：
v2 - 说明： 导出格式版本
- 示例：
exportversion=v2 - 注意： 版本 2 包含更丰富的运动数据与元数据
batchrequests
- 类型： 布尔
- 默认：
false - 说明： 分多次请求批量发送数据（仅 JSON 且 REST API 时有效）
- 示例：
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（若syncinterval=minutes则为每 10 分钟） - 注意： 必须大于 0
HTTP 配置
headers
- 类型： 字符串（逗号分隔的键值对）
- 默认： 无
- 说明： 用于身份验证或元数据的 HTTP 标头
- 示例：
headers=Authorization,Bearer%20token123,X-API-Key,abc123 - 格式：
key1,value1,key2,value2,... - 注意： 值需 URL 编码。每个标头需同时提供键和值。
标头示例：
Authorization, Bearer your-tokenX-API-Key, your-api-keyContent-Type, application/json
requesttimeout
- 类型： 整数（60–86400）
- 默认：
60 - 说明： 请求超时（秒）
- 示例：
requesttimeout=300 - 注意： 须在 60 至 86400 秒之间（1 分钟至 24 小时）
按数据类型的设置
Health Metrics 设置
metrics
- 类型： 字符串（逗号分隔的 MetricName 原始值）
- 默认： 全部可用指标
- 说明： 要包含的具体健康指标（仅
healthMetrics） - 示例：
metrics=Step%20Count,Heart%20Rate,Active%20Energy - 注意： 须使用准确的 MetricName 原始值。未指定则包含全部。
常见指标名称：
Step CountHeart RateActive EnergyApple Exercise TimeSleep AnalysisWalking + Running Distance
完整列表见应用内的指标选择界面。
Workout 设置
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
创建带自定义身份验证标头的自动化。
指定指标的 Health Metrics
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
仅导出步数与心率，按小时汇总。
含路线数据的 Workouts
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¬ifyonupdate=true¬ifywhenrun=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）
- 在 iOS 设备上打开 Safari
- 在地址栏输入深度链接 URL
- 轻点前往
- 应用应打开并创建自动化
在终端中（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)
在“快捷指令”中
- 新建快捷指令
- 添加“打开 URL”操作
- 输入深度链接 URL
- 运行快捷指令
故障排除
常见问题
“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 - 仅在
period=realtime时使用seconds
“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 或删除该参数
“Workout settings are only valid for workouts data type”
includeroutes、includeworkoutmetadata、workoutsmetadatainterval仅在datatype=workouts时有效- 更改数据类型或删除这些参数
“Metrics parameter is only valid for healthMetrics data type”
metrics仅在datatype=healthMetrics时有效- 更改数据类型或删除该参数
“Invalid metric name”
- 使用准确的 MetricName 原始值（如 “Step Count”、“Heart Rate”）
- 检查拼写与大小写
- 在应用的指标选择界面查看有效名称
“Invalid request timeout”
- 须在 60 至 86400 秒之间
“A name is required for the automation”
- 必须包含
name参数 - URL 解码后值不能为空
URL 长度限制
极长的 URL（尤其包含大量指标或标头）可能超过系统限制。可考虑：
- 在
metrics中减少指标数量 - 减少标头数量
- 在可能的情况下缩短参数值
- 将复杂配置拆成多个较简单的自动化
参数优先级
当多个参数冲突时：
- 数据类型选择（
datatype）会重置包含项 - CSV 格式（
format=csv）会自动设置aggregatedata=true - 实时周期（
period=realtime）需要syncinterval=seconds - 不兼容的组合会触发校验错误
最佳实践
自动同步（通过深度链接触发自动化时）：
- 为设备充电并使用 iPhone 镜像
- 充电时 iOS 对性能限制较少，数据可更频繁同步
- 使用镜像时设备行为类似已解锁，Health Auto Export 可访问健康数据以执行自动化
- 为设备充电并使用 iPhone 镜像
含特殊字符的值务必进行 URL 编码
先使用简单 URL 测试，再逐步增加复杂度
使用便于识别的名称
以编程方式生成链接前先验证 URL
解析深度链接时妥善处理错误
若开发生成链接的工具，请文档化格式
包含大量指标或标头时注意 URL 长度
除模拟器外也在真机上测试
相关文档
- REST API 自动化指南 — REST API 自动化详解
- 自动化概览 — 通用概念
- 手动导出指南 — 如何手动导出数据
支持
若遇到本指南未涵盖的问题：
- 根据错误信息排查具体参数
- 确认 URL 编码正确
- 先使用最短 URL 测试
- 使用应用内的 Chat Support 获取帮助