ポイントインタイム リカバリ（PITR）を使用して FHIR リソースを復元する

このページでは、ポイントインタイム リカバリ（PITR）を使用して、FHIR ストア内の FHIR リソースを過去 21 日以内の状態に復元する方法について説明します。PITR を使用して、FHIR リソースが誤って削除されるなどの不要な変更から復元できます。

準備

PITR リクエストは高度なオペレーション リクエストとして分類され、それに応じて課金されます。PITR を使用する前に、高度なオペレーション リクエストの料金を確認してください。

PITR と FHIR のリソースの変更履歴

PITR は FHIR リソースの変更履歴に依存しません。FHIR ストアの disableResourceVersioning フィールドが true の場合、または FHIR リソースの過去のバージョンが削除されている場合は、引き続き PITR を使用できます。

復元ワークフロー

本番環境の復元が期待どおりに実行されるように、まずドライランを実行します。ドライランでは、復元する FHIR リソースの ID とタイプを含む 1 つ以上のファイルが出力されます。本番環境での復元を再度実行する前に、出力ファイルの正確性を確認します。

特定のリソースを復元する、またはフィルタ条件に従ってリソースを復元するには、フィルタを指定します。

ドライランを行う

本番環境で FHIR リソースを復元する前に、ドライランを行います。

次のサンプルは、fhirStores.rollback メソッドを使用してドライランを行う方法を示しています。

コンソール

FHIR ストアを以前の状態にロールバックする手順は次のとおりです。

  1. Google Cloud コンソールで、[データセット] ページに移動します。

    [データセット] に移動

  2. ロールバックする FHIR ストアを含むデータセットを選択します。
  3. [データストア] リストで、ロールバックするデータストアの [アクション] プルダウン メニューをクリックします。メニューで [ロールバック] をクリックします。
  4. 最初の手順では、FHIR ストアをロールバックする時点や、FHIR ストアで実行された特定のタイプのオペレーションをすべてロールバックするなど、より広範なスコープでロールバックをパラメータ化できます。時点パラメータは必須です。
  5. [続行] をクリックします。
  6. 2 番目の手順では、リソース関連のパラメータを必要に応じて設定できます。特定タイプ（Patient など）のすべてのリソースをロールバックするか、ロールバックするすべてのリソースのリストを識別子（Patient/123 など）で指定して（Google Cloud Storage に保存）、ロールバックするリソースの resource.meta フィールド値にフィルタを指定できます。

    resource.meta フィルタの詳細については、 API ドキュメント をご覧ください。
  7. [続行] をクリックします。
  8. 最後のステップでは、ロールバックの動作を構成できます。Google Cloud Storage でロールバックの結果の出力先を選択します（これは必須フィールドです）。また、ドライランを開始するかどうか、以前のロールバックを無視するかどうかを指定します。
    • ドライランは、ストア内のリソースに実際には影響しません。選択した Cloud Storage の宛先に出力される結果は、ロールバックが有効になった場合に何が起こるかを示します。このオプションを有効にします。
    • [以前のロールバックを無視する] が選択されている場合、このロールバックの実行時に、以前のロールバック オペレーションの影響は考慮されません。
  9. [ロールバック] をクリックします。オペレーションが初期化されます。

REST

  1. FHIR リソースを復元します。

    ドライランを行うには、force フィールドが false であることを確認します。

    リクエストのデータを使用する前に、次のように置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID
    • LOCATION: データセットの場所
    • DATASET_ID: FHIR ストアの親データセット
    • FHIR_STORE_ID: FHIR ストア ID
    • RECOVERY_TIMESTAMP: 過去 21 日以内の復元ポイント。RFC 3339 形式を使用します。2 番目の部分に時刻を指定し、タイムゾーンを加えます（例: 2015-02-07T13:28:17.239+02:00、2017-01-01T00:00:00Z）。
    • CLOUD_STORAGE_BUCKET: 出力ファイルを書き込む Cloud Storage フォルダまたはバケットの完全修飾 URI

    リクエストの本文（JSON）: 

    {
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}

    リクエストを送信するには、次のいずれかのオプションを選択します。

    curl

    リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

    cat > request.json << 'EOF'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}
EOF

    その後、次のコマンドを実行して REST リクエストを送信します。

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback"

    PowerShell

    リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

    @'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}
'@  | Out-File -FilePath request.json -Encoding utf8

    その後、次のコマンドを実行して REST リクエストを送信します。

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback" | Select-Object -Expand Content

    API Explorer

    リクエスト本文をコピーして、メソッドのリファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。

    次のとおり出力されます。レスポンスには、長時間実行オペレーション（LRO）の識別子が含まれます。長時間実行オペレーションは、メソッドの呼び出しが完了するまでに時間がかかる場合に返されます。OPERATION_IDの値をメモします。この値は次の手順で必要になります。

  2. projects.locations.datasets.operations.get メソッドを使用して、長時間実行オペレーションのステータスを取得します。

    リクエストのデータを使用する前に、次のように置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID
    • DATASET_ID: データセット ID
    • LOCATION: データセットの場所
    • OPERATION_ID: 長時間実行オペレーションから返された ID。

    リクエストを送信するには、次のいずれかのオプションを選択します。

    curl

    次のコマンドを実行します。

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

    PowerShell

    次のコマンドを実行します。

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

    API Explorer

    メソッド リファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。必須フィールドを入力して、[Execute] をクリックします。

    次のとおり出力されます。レスポンスに "done": true が含まれている場合、長時間実行オペレーションは終了しています。

ドライランの出力ファイルを表示する

各ドライランでは、復元する FHIR リソースの ID とタイプを含む 1 つ以上のファイルが出力されます。ファイルは、送信先の Cloud Storage バケットの rollback_resources フォルダ内のサブフォルダに作成されます。サブフォルダ名は、fhirStores.rollback レスポンスで返された LRO ID です。ファイルを表示して、復元が想定どおりに機能することを確認するには、オブジェクトのメタデータを表示するをご覧ください。

ファイル数は、復元された FHIR リソースの数に比例します。

ファイル名の形式は trial-NUMBER-of-TOTAL_NUMBER.txt です。ここで、NUMBER はファイル番号、TOTAL_NUMBER はファイルの合計数です。

ドライランの出力ファイル スキーマ

ドライランの復元からの出力ファイルは、次の表に示すスキーマを使用します。

RESOURCE_TYPE RESOURCE_ID TIMESTAMP
FHIR のリソースタイプ。 FHIR のリソース ID。 FHIR ストアで FHIR リソースが作成または更新された時刻。

本番環境で復元する

本番環境で復元する前にドライランを実行し、ドライランの出力ファイルを調べて本番環境での復元が想定どおりに実行されることを確認します。

次のサンプルは、fhirStores.rollback メソッドを使用して本番環境の FHIR リソースを復元する方法を示しています。

コンソール

FHIR ストアを以前の状態にロールバックする手順は次のとおりです。

  1. Google Cloud コンソールで、[データセット] ページに移動します。

    [データセット] に移動

  2. ロールバックする FHIR ストアを含むデータセットを選択します。
  3. [データストア] リストで、ロールバックするデータストアの [アクション] プルダウン メニューをクリックします。メニューで [ロールバック] をクリックします。
  4. 最初の手順では、FHIR ストアをロールバックする時点や、FHIR ストアで実行された特定のタイプのオペレーションをすべてロールバックするなど、より広範なスコープでロールバックをパラメータ化できます。時点パラメータは必須です。
  5. [続行] をクリックします。
  6. 2 番目の手順では、リソース関連のパラメータを必要に応じて設定できます。特定タイプ（Patient など）のすべてのリソースをロールバックするか、ロールバックするすべてのリソースのリストを識別子（Patient/123 など）で指定して（Google Cloud Storage に保存）、ロールバックするリソースの resource.meta フィールド値にフィルタを指定できます。

    resource.meta フィルタの詳細については、 API ドキュメント をご覧ください。
  7. [続行] をクリックします。
  8. 最後のステップでは、ロールバックの動作を構成できます。Google Cloud Storage でロールバックの結果の出力先を選択します（これは必須フィールドです）。また、ドライランを開始するかどうか、以前のロールバックを無視するかどうかを指定します。
    • ドライランは、ストア内のリソースに実際には影響しません。選択した Cloud Storage の宛先に出力される結果は、ロールバックが有効になった場合に何が起こるかを示します。このオプションを無効にします。
    • [以前のロールバックを無視する] が選択されている場合、このロールバックの実行時に、以前のロールバック オペレーションの影響は考慮されません。
  9. [ロールバック] をクリックします。オペレーションが初期化されます。

REST

  1. FHIR リソースを復元します。

    force フィールドが true であることを確認します。

    リクエストのデータを使用する前に、次のように置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID
    • LOCATION: データセットの場所
    • DATASET_ID: FHIR ストアの親データセット
    • FHIR_STORE_ID: FHIR ストア ID
    • RECOVERY_TIMESTAMP: 過去 21 日以内の復元ポイント。RFC 3339 形式を使用します。2 番目の部分に時刻を指定し、タイムゾーンを加えます（例: 2015-02-07T13:28:17.239+02:00、2017-01-01T00:00:00Z）。
    • CLOUD_STORAGE_BUCKET: 出力ファイルを書き込む Cloud Storage フォルダまたはバケットの完全修飾 URI

    リクエストの本文（JSON）: 

    {
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}

    リクエストを送信するには、次のいずれかのオプションを選択します。

    curl

    リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

    cat > request.json << 'EOF'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}
EOF

    その後、次のコマンドを実行して REST リクエストを送信します。

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback"

    PowerShell

    リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。

    @'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}
'@  | Out-File -FilePath request.json -Encoding utf8

    その後、次のコマンドを実行して REST リクエストを送信します。

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback" | Select-Object -Expand Content

    API Explorer

    リクエスト本文をコピーして、メソッドのリファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。

    次のとおり出力されます。レスポンスには、長時間実行オペレーション（LRO）の識別子が含まれます。長時間実行オペレーションは、メソッドの呼び出しが完了するまでに時間がかかる場合に返されます。OPERATION_IDの値をメモします。この値は次の手順で必要になります。

  2. projects.locations.datasets.operations.get メソッドを使用して、長時間実行オペレーションのステータスを取得します。

    リクエストのデータを使用する前に、次のように置き換えます。

    • PROJECT_ID: Google Cloud プロジェクトの ID
    • DATASET_ID: データセット ID
    • LOCATION: データセットの場所
    • OPERATION_ID: 長時間実行オペレーションから返された ID。

    リクエストを送信するには、次のいずれかのオプションを選択します。

    curl

    次のコマンドを実行します。

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

    PowerShell

    次のコマンドを実行します。

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

    API Explorer

    メソッド リファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。必須フィールドを入力して、[Execute] をクリックします。

    次のとおり出力されます。レスポンスに "done": true が含まれている場合、長時間実行オペレーションは終了しています。

本番環境の復元の出力ファイルを表示する

本番環境の復元では、次のファイルが出力されます。ファイルは、送信先の Cloud Storage バケットの rollback_resources フォルダ内のサブフォルダに作成されます。サブフォルダ名は、fhirStores.rollback レスポンスで返された LRO ID です。ファイルを表示するには、オブジェクトのメタデータを表示するをご覧ください。

  • success-NUMBER-of-TOTAL_NUMBER.txt: 正常に復元された FHIR リソースが含まれます。
  • fail-NUMBER-of-TOTAL_NUMBER.txt: 復元に失敗した FHIR リソースが含まれます。失敗していない場合でも、空のファイルが生成されます。

ファイル名では、NUMBER はファイル番号、TOTAL_NUMBER はファイルの総数です。

本番環境の出力ファイル スキーマ

本番環境の復元からの成功ファイルと失敗ファイルは、次のスキーマを使用します。エラーファイルには追加の ERROR_MESSAGE 列が含まれています。

RESOURCE_TYPE RESOURCE_ID ROLLBACK_VERSION_ID NEW_VERSION_ID ERROR_MESSAGE（エラーファイルのみ）
FHIR のリソースタイプ。 FHIR のリソース ID。 復元が開始された時点でのリソースの現在のバージョン ID。 復元後のリソースの現在のバージョン ID。disableResourceVersioning が true の場合、またはリソースを復元するとリソースが削除される場合、ROLLBACK_VERSION_ID と NEW_VERSION_ID は空になります。 エラー ファイルのみ。復元する FHIR リソースを提出する理由を説明します。

フィルタを使用して特定の FHIR リソースを復元する

以降のセクションでは、フィルタを使用して、フィルタ条件に基づいて FHIR リソースを復元する方法について説明します。フィルタは、fhirStores.rollback リクエストを送信するときに RollbackFhirResourceFilteringFields オブジェクトで指定します。

フィルタは、次のようないくつかのユースケースで組み合わせたり、個別に利用したりできます。

  • FHIR リソースを誤って削除した後、他の FHIR リソースを変更せずに、特定の FHIR リソースを復元します。
  • 特定のインポート オペレーションで特定の FHIR リソースがインポートされる前の状態に FHIR ストアを復元します。

フィルタ ファイルを使用する

デフォルトでは、PITR は FHIR ストア内のすべての FHIR リソースを復元します。特定の FHIR リソースを復元するには、リソースタイプとそのリソース ID をファイルで指定し、そのファイルを Cloud Storage にアップロードします。inputGcsObject フィールドでファイルの場所を指定します。

Cloud Storage からフィルタ ファイルを読み取るには、Cloud Healthcare サービス エージェントのサービス アカウントに権限を付与する必要があります。詳細については、Cloud Storage からフィルタ ファイルを読み取るをご覧ください。

フィルタ ファイルには任意の拡張子を使用できます。次のスキーマを使用し、1 行に 1 つの FHIR リソースを記述する必要があります。

FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID

たとえば、ID が 8f25b0ac の Patient リソースと、ID が d507417e90e と e9950d90e の 2 つの Observation リソースを復元するには、フィルタ ファイルで次のように指定します。

Patient/8f25b0ac
Observation/d507417e90e
Observation/e9950d90e

カスタム関数を使用する

Cloud Healthcare API は、次のカスタム フィルタ関数を提供します。カスタム関数と rollbackTime フィールドを組み合わせて、追加のフィルタを適用できます。

tag
詳細
関数の構文
tag("system") = "code"
説明
リソース Meta.tag 要素に基づいて FHIR リソースをフィルタします。
引数
system
string
コードシステムを参照する URL。詳しくは、リソースでのコードの使用をご覧ください。
code
string
コードシステムで定義されたコンセプトを識別する値。詳しくは、リソースでのコードの使用をご覧ください。
extension_value_ts
詳細
関数の構文
extension_value_ts("url")
説明
extension 要素の url 値に基づいて FHIR リソースをフィルタリングします。ここで、url は UNIX タイムスタンプです。次の比較演算子をサポートしています。
  • =
  • !=
  • <
  • >
  • <=
  • >=
引数
url
string
拡張機能を定義する StructureDefinition リソースの正規 URL。たとえば、次の extension 要素では、url は http://hl7.org/fhir/StructureDefinition/timezone です。
"extension" : [{
  "url" : "http://hl7.org/fhir/StructureDefinition/timezone",
  "valueCode" : "America/New_York"
}]
詳細については、拡張機能の定義をご覧ください。

FHIR リソースタイプでフィルタする

リソースタイプのみに基づいて FHIR リソースを幅広くフィルタするには、types[] 配列でリソースタイプを指定します。

オペレーション タイプでフィルタリング

CREATE、UPDATE、または DELETE のトランザクションで変更された FHIR リソースをフィルタリングするには、ChangeType 列挙型で値を指定します。

たとえば、削除された FHIR リソースのみを復元するには、DELETE 値を指定します。

CHANGE_TYPE_UNSPECIFIED または ALL を指定した場合、または値を指定しない場合は、すべての FHIR リソースが復元されます。

過去の復元を除外する

FHIR リソースの復元時に過去の復元を除外するには、excludeRollbacks フィールドを true に設定します。復元が正しく機能し、変更を上書きしない場合は、過去の復元を除外できます。タイムスタンプが重複する複数の復元を実行することもできます。

次のシナリオを考えてみます。

  1. 1:00 で、復元タイムスタンプを 0:01 に設定して復元を開始します。2:00 では、復元オペレーションにより FHIR ストアの Patient/1 と Patient/2 の Patient リソースが削除されます。復元オペレーションは 3:00 で終了します。

  2. 数日後、復元タイムスタンプを 1:00 に設定して復元オペレーションを実行します。デフォルトでは、オペレーションを実行すると次のようになります。

    • Patient/1 と Patient/2 の Patient リソースを誤って再作成しました。
    • 3:00 以降に作成または更新された FHIR リソースを正しく復元します。

Patient/1 と Patient/2 の Patient リソースを削除した初期復元オペレーションを除外し、再作成を避けるには、excludeRollbacks を true に設定します。

長時間実行オペレーション（LRO）ID を使用してフィルタする

FHIR リソースが 1 つ以上の長時間実行オペレーション（LRO）によって変更された場合は、operationIds フィールドで LRO ID を指定し、変更されたリソースを復元することができます。

Cloud Healthcare API データセット内の LRO ID の一覧表示と表示については、LRO の一覧表示をご覧ください。

本番環境で復元に失敗した FHIR リソースを再試行する

一部の FHIR リソースが本番環境の復元に失敗した場合は、復元を再試行できます。生成された本番環境の出力ファイルを使用して、失敗した FHIR リソースを見つけます。これらの FHIR リソースのタイプとその ID をフィルタ ファイルで指定し、復元を再度実行します。

復元を実行するたびに、各リクエストで同じ構成を使用し、タイムスタンプが過去 21 日以内の場合、復元はべき等になります。

制限事項

  • PITR では、FHIR ストアの disableReferentialIntegrity 設定に関係なく、参照整合性が適用されません。一部の FHIR リソースのみを復元すると、FHIR ストアが参照整合性に違反している状態のままになることがあります。

  • 復元された FHIR リソースは作成または更新時に検証されているため、PITR は FHIR プロファイル検証をスキップします。FHIR ストア プロファイルの構成が変更された場合、PITR によって FHIR ストアがプロファイル検証に違反する状態のままになることがあります。

  • rollbackTime の値が FHIR ストアで FHIR リソースが削除された時刻よりも前の場合、FHIR ストアで enableUpdateCreate が有効になっている必要があります。有効でない場合、リソースは復元されません。

  • 復元中に FHIR ストアを更新したり、データの読み取りと書き込みを行ったりできますが、復元ステージによっては予期しない結果が表示されることがあります。たとえば、読み取りリクエストは、復元された FHIR リソースと復元されていない FHIR リソースの組み合わせを返すことがあります。リソースを更新すると、復元によって更新が上書きされる可能性があります。

  • PITR は FHIR リソースの履歴を保持します。復元された各リソースには新しい現在のバージョンが割り当てられ、履歴は保持されます。