ポイントインタイム リカバリ(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 メソッドを使用してドライランを行う方法を示しています。

REST

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

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

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

    • PROJECT_ID: Google Cloud プロジェクトの ID
    • LOCATION: データセットの場所
    • DATASET_ID: FHIR ストアの親データセット
    • FHIR_STORE_ID: FHIR ストア ID
    • RECOVERY_TIMESTAMP: 過去 21 日以内のリカバリ ポイント。RFC 3339 形式を使用します。時刻を秒に指定し、タイムゾーンを含めます(例: 2015-02-07T13:28:17.239+02:002017-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 リソースを復元する方法を示しています。

REST

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

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

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

    • PROJECT_ID: Google Cloud プロジェクトの ID
    • LOCATION: データセットの場所
    • DATASET_ID: FHIR ストアの親データセット
    • FHIR_STORE_ID: FHIR ストア ID
    • RECOVERY_TIMESTAMP: 過去 21 日以内のリカバリ ポイント。RFC 3339 形式を使用します。時刻を秒に指定し、タイムゾーンを含めます(例: 2015-02-07T13:28:17.239+02:002017-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。disableResourceVersioningtrue の場合、またはリソースの復元でリソースが削除される場合、ROLLBACK_VERSION_IDNEW_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 が d507417e90ee9950d90e の 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 要素では、urlhttp://hl7.org/fhir/StructureDefinition/timezone です。

"extension" : [{
  "url" : "http://hl7.org/fhir/StructureDefinition/timezone",
  "valueCode" : "America/New_York"
}]
詳しくは、拡張機能の定義をご覧ください。

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

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

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

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

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

CHANGE_TYPE_UNSPECIFIEDALL を指定するか、値を指定しない場合、すべての FHIR リソースが復元されます。

過去の復元を除外する

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

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

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

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

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

長時間実行オペレーション(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 リソースの履歴を保持します。復元された各リソースは、現在の新しいバージョンを取得し、その履歴は保持されます。