ディープリンク自動化

ディープリンク自動化では、URLスキームを使って REST API 自動化をプログラムから作成できます。自動化スクリプト、構成管理、ヘルスデータのエクスポート設定が必要な外部システムとの連携に適しています。

概要

ディープリンク自動化は、カスタム URL スキームを使って、アプリ内で手動で設定を入力せずに REST API 自動化を作成・設定します。ディープリンクの URL を開くと、アプリが指定した設定で新しい自動化を自動的に作成します。

用途の例:

• スクリプトやツールからのプログラムによる自動化のセットアップ
• 自動化の一括設定
• 構成管理システムとの連携
• 外部アプリや Web サイトからの迅速なセットアップ
• テストや開発のワークフロー

主な機能:

• 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
• 注: 有効な 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
• 注: 選択できるデータ型は 1 つだけです。設定すると、適切なインクルードフラグが自動的に構成されます。

有効なデータ型:

• 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
• 説明: 時間のグループ化／集計の間隔（healthMetrics データ型のときのみ有効）
• 例: interval=hours

有効な値:

• none — 既定（集計なし）
• minutes — 分単位でグループ化
• hours — 時間単位でグループ化
• days — 日単位でグループ化
• weeks — 週単位でグループ化
• months — 月単位でグループ化
• years — 年単位でグループ化

注: このパラメータは datatype=healthMetrics のときのみ有効です。CSV 形式では常にデータが集計されます。

aggregatedata

• 型: 真偽値
• 既定値: CSV の場合は true、JSON の場合は false
• 説明: データを集計／要約するか（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（syncinterval=minutes のときは 10 分ごとに同期）
• 注: 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 の rawValue をカンマ区切り）
• 既定値: 利用可能なすべてのメトリクス
• 説明: 含めるヘルスメトリクス（healthMetrics データ型のときのみ有効）
• 例: metrics=Step%20Count,Heart%20Rate,Active%20Energy
• 注: MetricName の rawValue を正確に指定してください。省略すると、利用可能なメトリクスがすべて含まれます。

よく使うメトリクス名:

• 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. iOS 端末で Safari を開く
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. ショートカットを実行する

トラブルシューティング

よくある問題

「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 のときのみ有効
• データ型をワークアウトにするか、これらのパラメータを削除する

「Metrics parameter is only valid for healthMetrics data type」

• metrics は datatype=healthMetrics のときのみ有効
• データ型を変更するか、metrics を削除する

「Invalid metric name」

• MetricName の rawValue を正確に指定する（例: 「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 のミラーリングを使う
     • 充電中は iOS がパフォーマンスへの制限を緩めるため、データをより頻繁に同期しやすくなります
     • iPhone のミラーリングを使うと、端末はロック解除時と同様に振る舞うため、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. アプリ内のチャットサポートから問い合わせる