REST API 自動化ガイド

REST API自動化により、HTTP POSTリクエストを受け入れる任意のWebサービスにヘルスデータを自動的にエクスポートできます。カスタムバックエンド、サードパーティAPI、またはWebhookとの統合に最適です。

概要

REST API自動化は、HTTP POSTリクエストを使用して、指定されたURLエンドポイントにヘルスデータを送信します。自動化は、認証とカスタムメタデータ用の設定可能なヘッダーを使用して、JSONまたはCSV形式でデータを送信できます。

使用例:

• カスタムバックエンドサービスとの統合
• Webhookへのデータ送信
• サードパーティAPIとの同期
• カスタムダッシュボードまたは分析プラットフォームの構築

主な機能:

• JSONとCSVの両方の形式をサポート
• 認証用のカスタムHTTPヘッダー
• 設定可能なリクエストタイムアウト
• 履歴データの手動エクスポート

制限事項:

• 健康データへのアクセス: iPhone がロックされている間、アプリは健康データにアクセスできません。自動化はデバイスがロック解除されているときにのみ実行されます。これは Apple が課す制限であり、回避できません。詳細情報

• バックグラウンド処理: iOS はバッテリー寿命のためバックグラウンド処理を制限します。自動化はバックグラウンド App の更新に依存し、次の場合はすぐに実行されないことがあります:

  • アプリのバックグラウンド App の更新がオフになっている
  • デバイスが低電力モードである
  • デバイスが長時間非アクティブだった
  • システムリソースが不足している
  • 複数のアプリがバックグラウンド実行時間を奪い合っている

パフォーマンス

iOS は、非常に厳しいパフォーマンス制約のあるモバイルデバイスで短時間のタスク向けに最適化されていることに留意してください。バックグラウンドタスクは通常 30 秒以内に完了する必要があり、使用できるメモリにも制限があります。Health Auto Export は高い柔軟性とカスタマイズ性を提供するため、設定がアプリのパフォーマンスと結果にどう影響するかを理解することが重要です。

• 設定: 大量のデータを生成する自動化は、システムがプロセスを終了させ、バックグラウンドで自動化が実行されなくなる原因になることがあります。次の設定は大量のデータを生成する可能性があります:
  • すべての健康メトリクスをエクスポートするよう設定された自動化。
    • 推奨: Apple Health に保存されているデータがある健康メトリクスのみ、実際に使用するデータのみを選択してください。空のデータタイプでもパフォーマンスに影響します。選択した健康メトリクスを複数の自動化に分割することも検討してください。システムが処理しやすくなります。
  • 秒または分単位の時間グループ化を使用する自動化、またはデータ要約がオフの自動化。このような細かいクエリは実行に時間がかかり、システムの制限と衝突する可能性があります。
    • 推奨: 可能な限り詳細なデータが理想的に思えても、各メトリクスやデータタイプにそのレベルの詳細が必要か検討してください。設定の異なる複数の自動化を検討してください。
  • サイクリング、ランニング、ハイキングなどの屋外ワークアウトをルートデータ付きでエクスポートする場合、GPS と関連する健康メトリクスデータは大きなペイロードを生成する可能性があります。
• ペイロードサイズ: REST API エクスポートを使用する場合は特に、大きなペイロードがサーバーエラーの原因になることがあります。バックエンドが数百メガバイト規模のペイロードを処理できるよう設定されていることを確認してください。
• 同期頻度: ホーム画面に自動化ウィジェットを追加すると、バックグラウンドでの自動化実行がより確実になります（自動化のウィジェット設定を参照）。

前提条件

• HTTP POSTリクエストを受け入れる有効なURLエンドポイント
• 認証情報（エンドポイントで必要な場合）
• エンドポイントに到達するためのネットワーク接続

設定

メインナビゲーションから自動エクスポート画面に移動し、「新しい自動化」をタップして、自動化タイプとして「REST API」を選択します。

自動化名

自動化の説明名を入力します（例：「マイバックエンドAPI」、「Webhook統合」）。

通知

通知を受け取るタイミングを設定します:

• キャッシュ更新時に通知 - キャッシュされたデータが更新されたときに通知を受け取る
• 実行時に通知 - 自動化が実行されるたびに通知を受け取る

URL設定

ヘルスデータを送信する完全なURLを入力します。これは、プロトコル（http://またはhttps://）を含む完全なURLである必要があります。

URLの例:

• https://api.example.com/health-data
• https://webhook.site/your-unique-id
• http://localhost:3000/api/health

注: URLは有効で、デバイスからアクセス可能である必要があります。無効なURLは自動化の実行を妨げます。

リクエストタイムアウト

HTTPリクエストのタイムアウト間隔を選択します。これは、リクエストが失敗したと見なされる前に、アプリが応答を待つ時間を決定します。

HTTPヘッダー

認証またはメタデータ用のカスタムHTTPヘッダーを追加します。一般的な使用例には以下が含まれます:

• APIキー: X-API-Key: your-api-key
• 認証トークン: Authorization: Bearer your-token
• コンテンツタイプのオーバーライド: Content-Type: application/json

ヘッダーを追加するには:

1. 「ヘッダーを追加」をタップ
2. 左側のフィールドにヘッダーキーを入力
3. 右側のフィールドにヘッダー値を入力
4. 追加のヘッダーについて繰り返す

重要: 各ヘッダーキーには対応する値が必要です。空のヘッダーは無視されます。

データタイプ設定

データタイプ

エクスポートするヘルスデータのタイプを選択します:

• ヘルスメトリクス - 歩数、心拍数、睡眠、その他のヘルス測定値
• ワークアウト - 運動とフィットネス活動
• 症状 - ヘルス症状と状態
• 心電図 - 心電図の読み取り値
• 心拍数通知 - 高/低心拍数イベント
• 心の状態 - 気分と精神状態のエントリ（iOS 18.0+）
• サイクル追跡 - 月経周期と生殖健康データ
• 薬物 - 薬物ログと遵守（iOS 26.0+）

ヘルスメトリクス設定

ヘルスメトリクスが選択されている場合:

ヘルスメトリクスを選択 - 含める特定のメトリクスを選択します。利用可能なすべてのメトリクスを選択するか、特定のメトリクスを選択できます。

ヒント: 必要なメトリクスのみを選択すると、処理時間を改善し、データサイズを削減できます。

優先ソース - 複数のソースが同じメトリクスを提供する場合に、どのデータソースに優先順位を付けるかを設定します。

ワークアウト設定

ワークアウトが選択されている場合:

ルートデータを含める - 位置データを持つワークアウトのルートを含めるにはオンにします。

ワークアウトメトリクスを含める - ワークアウト中に収集されたヘルスメトリクス（心拍数、カロリーなど）を含めるにはオンにします。

時間グループ化（ワークアウトメトリクス） - エクスポートバージョン2を使用し、ワークアウトメトリクスを含めるが有効な場合:

• 分 - ワークアウトメトリクスを分ごとにグループ化
• 秒 - ワークアウトメトリクスを秒ごとにグループ化

エクスポート設定

エクスポート形式

エクスポートするデータの形式を選択します:

• JSON形式 - ネストされたオブジェクトを含む詳細なデータ構造を提供します。構造化データが必要なAPI、データベース、アプリケーションに最適です。JSON形式には、睡眠フェーズやAFib読み取り値などの複雑なデータタイプのより詳細な情報が含まれます。

• CSV形式 - スプレッドシートアプリケーションに簡単にインポートできる表形式のデータを提供します。簡単なデータ分析や、エンドポイントがCSVデータを期待する場合に最適です。

注: Content-Typeヘッダーは、JSONエクスポートの場合はapplication/json、CSVエクスポートの場合はmultipart/form-dataに自動的に設定されます。

エクスポートバージョン

エクスポートバージョンを選択します。バージョニングにより、エクスポートの更新されたバージョン間を自分のペースで移行でき、ワークフローを破壊する変更を最小限に抑えます。

• バージョン1 - レガシー形式、この形式に依存する既存のワークフローがある場合に使用
• バージョン2 - 強化されたワークアウトデータとより詳細なメタデータオプションを含む現在の形式

日付範囲

データをエクスポートするタイミングを選択します:

• デフォルト - 前日の完全なデータと現在の日時までのデータを同期
• 最後の同期以降 - 各同期で、エクスポートが最後に実行された時点から現在の日時までのすべてのデータをエクスポート
• 今日 - 現在の日付の現在の時刻までのすべてのデータを同期
• 昨日 - 前日の完全なすべてのデータを同期
• 過去7日間 - 過去7日間の完全なデータを同期

データを要約

ヘルスメトリクスデータタイプでJSON形式を使用する場合、データを要約をオンまたはオフにします。

• オン - 集約されたデータの要約を提供
• オフ - 可能な限り非集約データを提供し、個別のデータポイントを表示

注: この設定は、ヘルスメトリクスを含むJSON形式にのみ適用されます。CSV形式を使用する場合、または複数のメトリクスが選択されている場合、データは常に集約されます。

時間グループ化

データを要約が有効なJSON形式を使用する場合、データをどのように集約するかを選択します。

注: CSV形式は常にデータを集約します。分レベルと秒レベルの集約は、処理時間とデータサイズを大幅に増加させる可能性があります。

バッチリクエストと大きなペイロード

JSON 形式では、1 つの大きなペイロードではなく複数の HTTP リクエストでデータを送るために バッチリクエスト をオンにします。

• オン — データを複数のリクエストに分散します。エンドポイントにペイロードサイズ制限、大きなボディのタイムアウト、または段階的な処理がある場合に使用します。
• オフ — すべてのデータを 1 つのリクエストで送信します。小さなエクスポートやシンプルな Webhook に適しています。

バッチを有効にする場合:

• 多くの健康指標、長い日付範囲、細かい時間グループ化（分/秒）
• データ要約がオフで、非集計の健康指標をエクスポートする場合
• サーバーが大きな POST ボディでエラーまたはタイムアウトを返す場合

メモ:

• バッチリクエストは REST API + JSON にのみ適用されます（CSV ではありません）。
• バッチはリクエストごとのペイロードを減らしますが、デバイスでの取得は必要です。遅い HealthKit クエリは アクティビティログ に警告として表示されることがあります。アクティビティログの遅いクエリ を参照してください。

同期頻度

自動化がデータをアップロードする頻度を設定します:

数値と間隔を選択します。

テストと検証

データ形式の検証

アプリは各リクエストに自動的に次のヘッダーを含めます:

• Content-Type - エクスポート形式に基づいて設定
• automation-name - 自動化の名前
• automation-id - 自動化の一意の識別子
• automation-aggregation - 選択された時間グループ化
• automation-period - 選択された日付範囲
• session-id - 各リクエストの一意の識別子

アクティビティログの表示

1. 自動化の設定画面で アクティビティログを表示 をタップします。
2. 実行 を確認します（新しい順にグループ化）。各実行を展開してイベントを確認します。
3. 警告（例：健康データのクエリが遅い）と エラー（HTTP失敗、タイムアウト、HealthKit読み取り失敗）を区別します—自動化の概要 — アクティビティログ を参照してください。
4. 成功した REST アップロードでは、実行に 形式、データタイプ、エクスポート期間、日付範囲 を含む概要が表示されることが多いです。
5. 共有（ツールバー）はサポート用の完全なアプリイベントログ診断 ZIP をエクスポートします（設定 → 詳細と同じ）。
6. クリアはこの自動化のアクティビティ履歴のみを削除します。

トラブルシューティング

一般的な問題

エンドポイントでデータが受信されない

• エンドポイントURLが正しいことを確認
• エンドポイントがPOSTリクエストを受け入れることを確認
• 認証ヘッダーを確認
• 受信リクエストのエンドポイントログを確認
• ネットワーク接続を確認

ヒントとベストプラクティス

1. 自動同期:

   • デバイスを充電し、iPhoneミラーリングを使用する
     • 充電中は iOS がパフォーマンス制限を緩めるため、データをより頻繁に同期できます
     • iPhoneミラーリングを使うと、デバイスはロック解除時と同様に動作します。Health Auto Export が健康データにアクセスして自動化を実行できます

2. パフォーマンス:

   • 詳細とデータサイズのバランスを取るために適切な時間グループ化を使用
   • 必要なメトリクスのみを選択

3. 信頼性:

   • エンドポイントの応答時間に基づいて適切なタイムアウト値を設定
   • アクティビティログを定期的に監視

4. データ形式:

   • 構造化データとAPIにはJSONを使用
   • 簡単なデータ分析やスプレッドシート統合にはCSVを使用
   • 大きなデータセットや個別の処理にはバッチリクエストを検討