APIエンドポイント

APIエンドポイントは、Health.mdのデータを独自のサーバー、Webhook、データベース、ダッシュボード、または自動処理へ送信したいユーザー向けのエクスポート先です。Apple Healthの読み取りは引き続きiPhoneで行われますが、ファイルへ書き込む代わりに、設定したエンドポイントへJSONをPOSTします。

プライバシーに関する注意

この出力先を使用すると、選択したヘルスデータが入力したURLへ意図的に送信されます。ご自身が管理または信頼するエンドポイントを使用し、HTTPSを優先して、サービスが実際に必要とする指標だけに限定してください。

出力先を設定する

1. iPhoneでHealth.mdを開きます。
2. エクスポートに移動します。
3. エクスポート先でAPIエンドポイントを選択します。
4. https://api.example.com/healthmd/ingestのようなURLを入力します。
5. 任意でBearerトークンを入力します。Health.mdはトークンをキーチェーンに保存します。
6. 完了をタップし、日付範囲と指標を選択してからエクスポートをタップします。

通常のトークンを入力した場合、Health.mdはAuthorization: Bearer <token>として送信します。値がすでにBearer またはBasic で始まっている場合は、入力どおりに送信します。

ペイロードの構造

Health.mdは、エクスポート操作ごとに1回POSTします。本文は、独立してバージョン管理されたhealthmd.api_exportエンベロープで、公開スキーマv8のhealthmd.health_data日次レコードを含みます。APIエンベロープv1は日次レコードを格納します。v2では、日次レコードのスキーマを変更せずに、プロバイダのサイドカーも追加できます。

records

リクエストした範囲について保持された、完全な日次スキーマv8オブジェクトです。クエリマニフェストがエビデンスとなる、完全だが空のレコードも含みます。

failed_date_details

日次ドキュメントを保持できる前に処理が失敗した日付です。

daily_record_schema_version

records内の日次スキーマのバージョンです。APIエンベロープのバージョンとは独立して更新されます。

プロバイダサイドカー

接続済みプロバイダが有効な場合に含まれる、独自のスキーマと識別規則を持つ条件付きのv2外部レコードです。

本番環境で生成された完全なAPI v1エンベロープとAPI v2プロバイダサイドカーエンベロープを確認できます。APIとCLIのコントラクトには、すべてのフィールド、バージョン境界、受け入れ規則が記載されています。

エンドポイントの要件

メソッド

POSTを受け入れます。

コンテンツタイプ

application/jsonを受け入れます。

成功

ペイロードを安全に受け入れた後、いずれかの2xxステータスを返します。

失敗

リクエストを拒否する場合は4xxまたは5xxを返します。利用可能な場合、Health.mdはレスポンスの短いプレビューを表示します。

確実に取り込めるよう、エンドポイントを日付単位で冪等にしてください。指標を変更した後やサーバーエラーを修正した後に、ユーザーが同じエクスポート範囲を再実行することがあります。

ヒント

• 長期間のバックフィルをアップロードする前に、1日分でテストしてください。
• ソースの完全性が重要な場合は「ロスレスヘルスレコード」を有効にしたままにしてください。経路、臨床文書、心電図、添付ファイルが多い場合は日付範囲を短くします。
• ペイロードを保存する前に、サーバー側でトークンを検証してください。
• 日単位の主キーにはrecords[].dateを使用してください。
• 簡潔なエラー本文を返してください。Health.mdが表示するのは短いプレビューだけです。

トラブルシューティング

問題	通常考えられる原因	対処方法
API出力先を使用できない	URLが空か無効	APIエンドポイントの設定を開き直し、有効なHTTP(S) URLを入力します。
HTTP 401または403	トークンがないか拒否された	トークンまたはサーバーの認証規則を更新します。
HTTP 404	URLパスが誤っている	サーバー上のルートを確認します。
HTTP 413	ペイロードが大きすぎる	エクスポートする日数を減らします。受信側が正規ソースレコードを必要としない場合に限り、サマリーのみの出力を使用します。
一部の日付がない	その日付について有効なHealthKitデータがない	failed_date_detailsと指標の選択を確認します。

関連ページ

ソースエクスポート — 出力先と日付範囲を選択し、手動エクスポートを実行します。 スキーマAPIとCLIのリファレンス — 正確なエンベロープ、バージョン、失敗時の動作、生成済みの例を確認します。 出力形式のカスタマイズ — JSON、CSV、Markdown、単位、フィールドを設定します。