深度鏈接自動化
使用 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 獲取幫助