HealthKit Medications APIの紹介

こんにちは Ericです HealthチームのiOSデベロッパです 今日は HealthKitに 新たに追加された Medications APIを紹介します iOS、iPadOS、visionOSで エキサイティングな体験を実現します こんにちは Srishti Guptaです 同じくHealthチームのエンジニアです 今日お見せするアプリは 私が開発したもので このあとEricが紹介する 新しいAPIを使用しています

まず 新しいHealthKit APIを見ていきます このAPIでは薬のデータを 読み込むことができます 次に そのデータがヘルスケアアプリに どのように表示されるかをお見せします その後 このAPIを使用した サンプルアプリをSrishtiより紹介します

さらに アンカー付き オブジェクトクエリについて説明し 最後は 新たに追加された薬の 許可をアプリで管理する際に ヘルスケアがどう役立つかについてです 新しいAPIについて詳しく説明する前に 投薬データがHealthKitに 追加される流れを見ていきましょう

iOS 15では ヘルスケアアプリに 服薬トラッキングが追加されました 服薬トラッキングは タブにあります まず をタップします ビューに移動します 薬を追加したことがなければ をタップして 最初の薬を追加できます 薬を追加するときは 最初に検索します 同じ名前の薬も 多々ありますが 強さや形状は それぞれ異なります 特定の薬を選択したら 飲み忘れを防ぐために リマインダーも設定できます さらに 薬に関する詳細を追加して パーソナライズすることもできます をタップすると 一覧に薬が追加されます

服薬データはいつでも記録できます 記録のたびに 服用した量と 時刻を選択できます 服薬の記録について 通知を受けた時には またはを選択したり 10分後に再通知するよう 指定したりできます 薬を追加する場合でも 服用を記録する場合でも データはHealthKitに安全に保存されます 現在 アプリがHealthKitから 取得できるデータは拡大しています ここで追加するのは 薬や服用イベントを読み取る機能です 薬を表すオブジェクトが HKUserAnnotatedMedicationです HKMedicationDoseEventは 新しい種類のHKSampleで 服用の記録を表します アプリではクエリ記述子と HKQueryを使用して HealthKitからデータを取得します このたび 薬に関するデータを 取得するための 新しいクエリ記述子と HKQueryを導入します HKUserAnnotatedMedicationQueryDescriptorと HKUserAnnotatedMedicationQueryです まず この2つの オブジェクトに焦点を当てます それぞれ薬剤と服用を表します HKUserAnnotatedMedicationは 特定の薬剤と そのカスタマイズの情報を表します 4つのプロパティで構成されます isArchivedは 服薬が終わっていて 現在はもう 服用していないことを示すフラグです このフラグが設定されている薬は 服薬歴セクションに入れられ 服用中の薬の一覧には表示されません hasScheduleは 薬にリマインダーが 設定されているかどうかを示します リマインダーがあると 定期的に 服用の記録を促す 通知が届くようになります nicknameは 薬に正式名称以外の名称を設定し 覚えやすくするためのものです ニックネームを設定すれば 服薬管理がもっと 身近に感じられるようになります 最後のmedicationは 実際の薬剤を表します HKMedicationConceptは 具体的な薬を表したものです 「薬剤コンセプト」と呼んでいる理由は これが処方記録ではなく あくまでも 薬の概念を示したものであるからです 薬剤コンセプトのIDは一意です そのため 使用するデバイスや 時間の経過にかかわらず アプリは常に同じ薬剤を特定できます displayTextは薬の名称です generalFormは 薬の物理的な形状を表します カプセル、錠剤、液体などがあります 剤形によって投与方法が 異なる場合もあります 最後のrelatedCodingsには その薬に関連する 一連の臨床コードが入ります このコードは RxNormのような 標準化された用語に由来しています 他の医療システムとの 相互運用が可能になるほか 薬の識別と分類にも役立ちます DoseEventは薬を服用する時刻や 実際に服用した時刻を表します 新しい種類のHKSampleであり medicationConceptIdentifierによって 常に特定の薬が 関連付けられています また 服用やスキップなどの ステータスを表す logStatusも含まれます 服用予定時間に ユーザーが再通知を指定する場合や まったく反応しない場合もあります このように服用が省略された場合の ステータスも用意されています 服用ごとに その用量も記録されます 服用スケジュールが設定されている場合は 予定日と予定用量のデータもあります scheduledQuantityとdoseQuantityに 差がある場合は 予定の服用量と実際の服用量との間に 差があったことがわかります 繰り返しになりますが 薬とその服用は相互に結びついています medicationConceptIdentifierは HKMedicationConceptの identifierプロパティと同じです アプリがHealthKitから取得するのは HKUserAnnotatedMedicationです アプリがクエリを実行すると ヘルスケアのカスタマイズの 現在の状態が取得されます では ヘルスケアに追加された 薬について説明しましょう 詳細やカスタマイズを 確認できる場所をお見せします 例えば アモキシシリンを 追加したとしましょう 感染症の治療のために しばらく服用しようという場面です アプリが薬に関するクエリを実行すると アモキシシリンを表すオブジェクトと カスタマイズ可能な プロパティが返されます 現時点では この薬のスケジュールは 設定されておらず になっています ニックネームは「抗生剤」です この薬は抗生物質だからです アモキシシリンは 薬剤コンセプトで表現されます 一意の識別子があり 名称は「Amoxicillin Trihydrate 500mg Oral Tablet」です 剤形はタブレットで 該当するコードが1つだけあります RxNormコード308192です アプリではこの HKUserAnnotatedMedicationを使用して ヘルスケアアプリのような エクスペリエンスを作成できます これには 薬に関する詳細と カスタマイズ可能な コンポーネントが入っています アプリでクエリを実行して 薬の情報を取得しました 薬の記録に基づいて エクスペリエンスを強化するには 服用イベントも取得する必要があります ここからは 服用イベントの記録の例を使って 各プロパティに想定される値を 見ていきましょう 抗生物質は 一定の間隔で 服用する必要があるので スケジュールを設定します 服用のリマインダーが届いたものの これをスキップしたとします リマインダーをスキップしたので HealthKitにイベントが保存されました アプリが服用イベントのクエリを実行すると 結果ハンドラにサンプルが返されます イベントのステータスはskippedです 薬を服用していないので doseQuantityは0になっています サンプルのstartDateは ログ記録時に選択した時刻です この服用イベントは スケジュールが 設定されているイベントの記録です scheduledDateとscheduledQuantityは このイベントに対応しています 日付は このイベントに設定した日時です 用量は 服用するはずだった量です 服用イベントは スケジュールを設定した タイミングのたびに保存されます 最後に この服用イベントは medicationConceptIdentifierにより 薬剤コンセプトに関連付けられています アプリは HKMedicationDoseEventsを使用して ユーザーの服薬記録に 基づく体験を作成できます そこから 記録の文脈と 詳細がわかるからです アプリで服薬データを使用するための2つの オブジェクトを紹介したので 次は これらのデータを実際に 取得するクエリを紹介しましょう アプリで薬の一覧を取得するには 新しいクエリ記述子を使用します これにより 服用中の薬や服用歴のある 薬の一覧をHealthKitから取得できます このクエリ記述子には 新しいプレディケートが2つあります isArchivedとhasScheduleです 制約を指定することもできます クエリ記述子に プレディケートが設定されていると アプリには プレディケートに一致する 薬のデータのみが返されます この例では 服薬歴に 移動されているピロキシカムは アプリに表示されません 服用イベントはHKSampleなので サンプル型ベースの 既存のクエリを使って取得できます サンプルクエリ、 アンカー付きオブジェクトクエリ、 オブザーバクエリなどです このようなクエリを設定する場合は 新しいサンプル型の HKMedicationDoseEventを使います また 服用イベントに関する新しい クエリプレディケートも各種導入しました 取得する服用イベントを検討する際は 薬またはログステータスに 基づいて取得するのが最も便利です

APIの概要とデータの例の紹介が済んだので Srishtiに代わってもらいましょう Srishtiは 薬と服用イベントを HealthKitから 取り込むアプリを開発しました 開発したアプリについて 話を聞かせてもらえるでしょうか Medications APIをどのように 活用しているかも ぜひ知りたいです よろしくお願いします わかりました 私が開発したアプリでは 服用イベントを確認したり 薬の副作用を記録したりできます 実際の動作をお見せしましょう このセッションの 説明ページにあるリンクから サンプルアプリを ダウンロードすることもできます アプリを開くと 既に許可されている 薬の一覧が表示されます いずれも ヘルスケアアプリに 追加されている薬です 薬をタップすると 今日 最後に服用した時刻が表示されます この薬は 今朝ヘルスケアアプリで 服用を記録済みです また 起こる可能性のある 副作用の一覧も確認できます 副作用はいずれも この薬に関連付けられたものです 私はひどい頭痛が起こったので その症状を選択して 症状が重い旨を記録します 症状の重さは絵文字で指定します ボタンをタップすると データが保存されます ここまでは私のアプリを 簡単に紹介してきました 次は その中身について 詳しく見ていきましょう まず ユーザーから データの読み取りと共有に関して 許可を得る必要があります このアプリでは 薬剤データの 読み取りを要求する際 HealthKitのオブジェクトごとの Authorization APIを使用します 薬はサンプルでなくオブジェクトだからです このリクエストは SwiftUIの ビューに埋め込まれています 次に healthStoreと 新しいオブジェクト型である userAnnotatedMedicationTypeを 使ってリクエストを設定しました また 許可プロンプトの タイミングの指定には State変数を使用しました このState変数がtrueに変わると ヘルスケアアプリに追加されている 薬の一覧が表示されます アプリと共有する薬を トグルボタンで選択したら をタップします 許可が確認されると Completionハンドラが呼び出されます エラーを適切に処理できるよう このような形にしました 薬の服用に関しては 読み取りに 別途許可を求める必要はありません ユーザーが薬の共有を許可すると 薬と服用の両方について 自動で読み取りが許可されます このアプリでは 吐き気や頭痛など 症状サンプルの読み取りと共有も 別途リクエストしています 健康データへのアクセス要求でも 同様のAPI呼び出しを使用します ただし ここでは 1つのオブジェクト型ではなく み取り／共有の対象となる サンプル型のリストを提供します State変数がtrueに変更されると 許可リクエストが開始され 読み取りと共有を許可するデータ型を 選択するためのシートが表示されます ユーザーは 症状を選択して をタップします この許可リクエストの完了は 同じような方法で処理する必要があります これは 許可が失敗した場合に アプリで適切にエラーを処理するためです 許可が確定した後は 許可済みの薬のリストを HealthKitから クエリで取得することになります そのため このアプリでは HKUserAnnotatedMedicationの配列を返す 非同期関数を使用します この関数ではまず 許可済みの薬のリストを取得する クエリ記述子を設定しています ユーザーがヘルスケアアプリに 追加した薬です このクエリでは 現在服用中の薬と 服用を終えた薬の両方とも データを取得したいので プレディケートや制約は不要です 次に healthStoreへの参照を使って クエリ記述子からの結果を待ちます この関数を実装するクラスは 複数のクエリを担当します そのため インスタンス変数として healthStoreへの 参照を維持しています アプリには ユーザーが許可した 薬だけが表示されます クエリの結果が得られた場合には 関数から薬のリストを取得して アプリのメインビューの 入力に使用します ユーザーが薬をタップしたら また別のクエリの実行が必要です 詳細ビューに表示する 服用イベントを取得するクエリです 今回のクエリでは 今日記録された服用イベントを 取得する必要があります では 最新の服用イベントを取得するための クエリ記述子の設定をお見せしましょう 最新の服用イベントを取得するため HKMedicationConceptを受け取って HKMedicationDoseEventを返す 関数を記述しました 当日の服用記録がない場合は その薬の服用イベントが nilになります ここでは 結果を限定するための 複合プレディケートを設定しています これは 今回必要なのが 指定された薬に関して 今日記録され ステータスが服用済みの 服用イベントだからです この例のプレディケートの 設定方法について詳しくは サンプルアプリでご確認ください サンプルのクエリ記述子の残りの部分は このような設定にしました あとは 結果の最初のオブジェクトを 返すようにしています sortDescriptorsと制約は プレディケートの条件を満たし かつ 最後に記録された服用だけを 結果として取得するためのものです 今日の服用イベントを取得したら その開始日を使用して タイルを設定します 当日の服用記録がなければ 何も表示されません

さて アプリでHealthKitから 薬とその服用イベントを 正常に取得できました 今度は それぞれの薬に 関連する副作用の一覧を 表示してみたいと思います そこで それぞれの薬に どのような副作用があるかを 少し調べてみました

どんな薬であっても 副作用が出る可能性はあります HealthKitには 頭痛や吐き気などの症状を 反映したカテゴリタイプがあります 調査の結果 RxNormというシステムのコードを 症状名とカテゴリタイプIDが セットになった症状モデルに 関連付けることにしました RxNormは 臨床薬を 個々のコンセプトを表す 一意のIDでコード化したものです そこで私は 調査で知ったコードを アプリの静的構造体に落とし込みました ここからは 私がRxNormコードを どのように使って 薬とその副作用とを 関連付けたかを説明します まずは 先ほどEricが紹介してくれた 図を見てみましょう 私が使用したのは HKMedicationConceptの relatedCodingsプロパティです これには この薬を表す 一連の臨床コードが含まれています 臨床コードとは システム内で 文脈が与えられたコードです アレルギーや病態など 特定の医学的概念を表すもので 今回の例では薬を表しています システムは 正規のFHIR規格に従って 識別されます 今回のRxNormシステムであれば こちらのURLで一意に識別されます このようなコードのモデル化の 詳しい方法については デベロッパ向けドキュメントをご覧ください 次は 私がアプリでRxNormを どのように使用しているかをお見せします このアプリでは SideEffects構造体で 既知の副作用と個別の薬剤とを 対応させることにしました まず RxNormシステムの定数を追加しました 次に HKMedicationConcept向けに 症状タイプを取得する関数を導入しました この関数は 薬のRxNormコードと 症状モデルとを対応させるもので 私の静的ディクショナリの データを使用しています 薬に関連付けられている 症状の取得には 静的関数SideEffectsを使用しました その上で 取得した症状を 薬の詳細ビューに表示しました これで 薬による症状を アプリに表示できました 次は 症状を記録する機能の実装です 症状の程度を記録する方法として 私が好きなのが絵文字です そこでまず 絵文字を5つ選びました 無症状から非常に重い症状まで 5段階になるような絵文字です 次に 新しい列挙型の SymptomIntensityを作成しました この症状の重さをカテゴリサンプルに変換し HealthKitに保存したいと思います そこで 症状の重さをそれぞれ 対応するカテゴリ値に関連付けました そして カテゴリタイプと症状の重さに 対応したサンプルを作成する関数を作成し 全部を結びつけました サンプルの保存には healthStoreの saveメソッドを使います このように 症状の種類をタップすると 絵文字の選択画面が表示されます 症状の重さに応じた絵文字を選ぶと それがHealthKitに保存されます 以上が現時点の私のアプリです アプリの操作方法に加え アプリがデータの取得に 使用する様々なクエリも すべてお見せしました 症状を関連付けて アプリで表示するために RxNormシステムを どのように活用しているかも紹介しました 今後の予定としては 薬の服用記録を確認できるグラフを 追加したいと思っています そこでEric 私が検討していたのは アンカー付きオブジェクトクエリで データを確認 取得し グラフに入力するという方法なのですが これはどう思いますか？ すばらしいお話をありがとうございました そのようなグラフを作るなら アンカー付きオブジェクトクエリが 最適だと思います HealthKitに服用が保存されるたびに グラフをシームレスに更新できます

アンカー付きオブジェクトクエリで 服用イベントのデータを 取得する際は注意が必要です 記録された数日分の服用イベントが削除され その後 編集で復元される場合もあれば リマインダーとして 保存されているだけの場合もあります 正しく処理しないとデータに 一貫性がないように見えかねません ここでアンカー付きオブジェクトクエリと そのベストプラクティスについて 復習しましょう アンカー付きオブジェクトクエリを 実行したアプリは 既存のサンプルの スナップショットを受け取ります 何か更新が発生すると アプリに追加の結果が届きます この結果には アプリで既に処理済みの サンプルの削除が含まれる場合があります アンカー付きオブジェクトクエリは 様々な方法で利用できます 例えば HealthKitに追加された データをアプリで効率的に取得できます アンカー付きオブジェクトクエリは 指定されたクエリアンカーに応じた データを取得するのに便利です アンカー付きオブジェクトクエリから 既にデータを取得している場合 返されたクエリアンカーを使用して アプリが同じデータを 処理しないようにしましょう アプリで最初からクエリを やり直す場合は クエリアンカーにnilを指定します アプリには 最新の服用イベントの データを反映させる必要があります 服用イベントには インタラクティブな記録動作が 反映されるため アプリに古いデータが 表示される可能性もあります そこで アプリで常に ヘルスケアアプリと同じ 最新のデータが表示されるよう アンカー付きクエリを使用しましょう アンカー付きオブジェクトクエリは一般に オブザーバクエリとサンプルクエリの ペアを使うより効率的です また アンカー付きオブジェクトクエリには Swiftの非同期インターフェイスがあります このインターフェイスは Swiftのasync/awaitで使える 結果のストリームを提供します アンカー付きオブジェクトクエリの 使用経験のない方や 詳しい情報や例にご興味がある方は デベロッパドキュメントをご覧ください WWDCの「Getting started with HealthKit」も参考になるかと思います

次に アンカー付きオブジェクトクエリを 使って グラフ用のデータを 取得する方法を説明します Srishti このクエリの 実装方法を教えてもらえますか？

はい 喜んで 私が書こうとしているクエリは ある薬について記録されている 服用のうち グラフの日付範囲に 該当するものだけを取得するクエリです データが更新されている場合は それも 追跡できるようにしたいと考えています このクエリの設定にあたっては 先ほど作成したサンプルクエリに似た クエリをベースにすることにします プレディケートは 薬とログステータスに基づいて 服用データを取得する点は同じですが 今日の分のデータを取得するのではなく グラフの日付範囲に該当する服用だけを 取得するように変えてあります このプレディケートの 設定方法について詳しくは サンプルアプリでご確認ください アンカーにはnilを指定します 記録されたすべての服用イベントを 最初から取得するためです また バックグラウンドスレッドでクエリを 実行するため Swiftの 非同期インターフェイスを使用します クエリの結果を取得したら それを別の関数で処理し アプリのデータモデルを更新します そのために使用するのが handleResultという新しい関数です まずは 結果から削除された オブジェクトを取得して 削除されたデータを消去する必要があります その上で グラフの点を 追加されたサンプルで 更新する処理が必要です グラフの点をどのように 管理したかについて詳しくは サンプルアプリでご確認ください では UIを見てみましょう 新しいデータが保存された場合に グラフがどう更新されるかもお見せします こちらがグラフです X軸は日付を表しており Y軸は薬の服用回数を 表しています 薬の選択は水平スクロールビューで行います ここで スマートウォッチのアプリから 薬の服用を記録するとします アンカー付きオブジェクトクエリを使って 最新データを定期的に確認しているので グラフが自動的に更新され 私が記録した新しいデータが反映されます このようなグラフができたことには とても感動しています HealthKitに保存された 最新のデータが表示されるのは 薬の日々の服用記録を 確認する上で非常に便利です ところで ヘルスケアアプリに 薬を追加するとどうなるのでしょうか？ いい質問です ここまでの内容は ヘルスケアアプリに追加されている すべての薬について アプリが許可を得ている前提でした

ここで アプリがインストールされ 薬のデータへのアクセスが 許可されたとしましょう 今 アプリを使用しているユーザーが 一覧に新しい薬を追加しようとしています 新しい薬は 現在服用中の薬と 一緒に表示したいとします 薬を追加するには ヘルスケアアプリに戻ります 追加したい薬を探して カスタマイズを済ませたら 一覧に追加する前の 最後のステップが待っています アプリでは薬のデータへの アクセス要求が済んでいるので 薬のデータを共有するかどうかを選べる スイッチが表示されるのです これは 許可を求めているようなもので ヘルスケアアプリでの操作を除き 何か追加の操作をする必要はありません サンプルのアプリを選択すると 薬がヘルスケアアプリに保存されます アプリに戻ると 追加した薬が表示されます ユーザーにとっても アプリにとっても 許可を簡単に 管理できるようになります Medications APIの説明は以上です パーソナライズから 服用履歴の管理まで 薬のデータに関して 優れた体験を生み出すための すべてが揃っています 薬剤コンセプトで あらゆるものがつながっているので 他の臨床データに関連付けることもできます 人々が服用中の薬と 各自の健康を 適切に管理できるようにするための 機能の実現にお役立てください このAPIを 皆さんのアプリでも 活用していただけるのを願っています

さて さよならの前に いくつかお知らせです ここで紹介したのは サンプルアプリのごく一部です 皆さんの参考になる点は 他にもたくさんあります 独自のアプリを開発する前に ぜひサンプルアプリを ダウンロードして コードをご確認ください また HKMedicationConcept APIを さらに活用するには RxNormのような 臨床コードについて理解を深めてください 薬の分類や特定のほか 薬を副作用や教育コンテンツなどの 優れたデータと関連付けるのに役立ちます それから デベロッパ向けドキュメントです 様々なログステータスの意味や 各種のクエリプレディケート さらに HKMedicationDoseEventの その他の機能について 学べるので ぜひご覧ください 最後に デベロッパ向けセッション 「Meet workouts on iOS」もご覧ください 本セッションをご覧いただき ありがとうございました 皆さんの作品を楽しみにしています 新しいAPIについてのご意見は フィードバックアシスタントから お送りください ご視聴ありがとうございました