このページでは、ポイントインタイム リカバリ(PITR)を使用して、FHIR ストア内の FHIR リソースを過去 21 日以内の状態に復元する方法について説明します。PITR を使用して、FHIR リソースが誤って削除されるなどの不要な変更から復元できます。
準備
PITR リクエストは高度なオペレーション リクエストとして分類され、それに応じて課金されます。PITR を使用する前に、高度なオペレーション リクエストの料金を確認してください。
PITR と FHIR のリソースの変更履歴
PITR は FHIR リソースの変更履歴に依存しません。FHIR ストアの disableResourceVersioning
フィールドが true
の場合、または FHIR リソースの過去のバージョンが削除されている場合は、引き続き PITR を使用できます。
復元ワークフロー
本番環境の復元が期待どおりに実行されるように、まずドライランを実行します。ドライランは、復元する FHIR リソースの ID とタイプを含む 1 つ以上のファイルを出力します。本番環境での復元を再度実行する前に、出力ファイルの正確性を確認します。
特定のリソースを復元する、またはフィルタ条件に従ってリソースを復元するには、フィルタを指定します。
ドライランを行う
本番環境で FHIR リソースを復元する前に、ドライランを行います。
次のサンプルは、fhirStores.rollback
メソッドを使用してドライランを行う方法を示しています。
REST
FHIR リソースを復元します。
ドライランを行うには、
force
フィールドがfalse
であることを確認します。リクエストのデータを使用する前に、次のように置き換えます。
PROJECT_ID
: Google Cloud プロジェクトの IDLOCATION
: データセットの場所DATASET_ID
: FHIR ストアの親データセットFHIR_STORE_ID
: FHIR ストア IDRECOVERY_TIMESTAMP
: 過去 21 日以内のリカバリ ポイント。RFC 3339 形式を使用します。時刻を秒に指定し、タイムゾーンを含めます(例: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 ContentAPI Explorer
リクエスト本文をコピーして、メソッド リファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。
OPERATION_ID
の値をメモします。この値は次の手順で必要になります。projects.locations.datasets.operations.get
メソッドを使用して、長時間実行オペレーションのステータスを取得します。リクエストのデータを使用する前に、次のように置き換えます。
PROJECT_ID
: Google Cloud プロジェクトの IDDATASET_ID
: データセット IDLOCATION
: データセットの場所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 ContentAPI 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
FHIR リソースを復元します。
force
フィールドがtrue
であることを確認します。リクエストのデータを使用する前に、次のように置き換えます。
PROJECT_ID
: Google Cloud プロジェクトの IDLOCATION
: データセットの場所DATASET_ID
: FHIR ストアの親データセットFHIR_STORE_ID
: FHIR ストア IDRECOVERY_TIMESTAMP
: 過去 21 日以内のリカバリ ポイント。RFC 3339 形式を使用します。時刻を秒に指定し、タイムゾーンを含めます(例: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 ContentAPI Explorer
リクエスト本文をコピーして、メソッド リファレンス ページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。このツールにリクエスト本文を貼り付け、その他の必須フィールドに入力して、[Execute] をクリックします。
OPERATION_ID
の値をメモします。この値は次の手順で必要になります。projects.locations.datasets.operations.get
メソッドを使用して、長時間実行オペレーションのステータスを取得します。リクエストのデータを使用する前に、次のように置き換えます。
PROJECT_ID
: Google Cloud プロジェクトの IDDATASET_ID
: データセット IDLOCATION
: データセットの場所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 ContentAPI 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:00
で、復元タイムスタンプを0:01
に設定して復元を開始します。2:00
では、復元オペレーションにより FHIR ストアのPatient/1
とPatient/2
の Patient リソースが削除されます。復元オペレーションは3:00
で終了します。数日後、復元タイムスタンプを
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 リソースの履歴を保持します。復元された各リソースは、現在の新しいバージョンを取得し、その履歴は保持されます。