使用時間點復原 (PITR) 功能復原 FHIR 資源

本頁說明如何使用時間點復原 (PITR) 功能，將 FHIR 商店中的 FHIR 資源復原至過去 21 天內的狀態。您可以使用 PITR 復原不必要的變更，例如誤刪 FHIR 資源。

事前準備

PITR 要求會歸類為進階作業要求，並依據此類型收費。使用 PITR 前，請先查看進階作業要求的定價。

時間點復原和 FHIR 資源版本記錄

PITR 不依賴 FHIR 資源版本記錄。如果 FHIR 儲存庫中的 disableResourceVersioning 欄位為 true，或是 FHIR 資源的歷史版本已遭到清除，您仍可使用 PITR。

復原工作流程

為確保正式版復原作業能正常運作，請先執行模擬測試。模擬執行作業會輸出一個或多個檔案，其中包含要復原的 FHIR 資源 ID 和類型。請先確認輸出檔案是否正確，再於實際工作環境中再次執行復原作業。

如要復原特定資源，或根據篩選條件復原資源，請指定篩選器。

執行模擬測試

在正式環境中復原 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: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

    APIs Explorer

    複製要求主體並開啟方法參考頁面。系統會在頁面右側開啟 API Explorer 面板。 您可以使用這項工具來傳送要求。將要求主體貼到這項工具中，並填妥其他必填欄位，然後按一下「執行」。

    輸出內容如下。回應會包含長時間執行作業 (LRO) 的 ID。如果方法呼叫可能需要額外時間才能完成，系統就會傳回長時間執行的作業。請記下 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

    APIs Explorer

    開啟方法參考頁面。系統會在頁面右側開啟 API Explorer 面板。 您可以使用這項工具來傳送要求。完成所有必填欄位，然後按一下「執行」。

    輸出內容如下。如果回應包含 "done": true，表示長時間執行作業已完成。

查看模擬測試輸出檔案

每個模擬執行作業都會輸出一個或多個檔案，其中包含要復原的 FHIR 資源 ID 和類型。檔案會建立在目的地 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: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

    APIs Explorer

    複製要求主體並開啟方法參考頁面。系統會在頁面右側開啟 API Explorer 面板。 您可以使用這項工具來傳送要求。將要求主體貼到這項工具中，並填妥其他必填欄位，然後按一下「執行」。

    輸出內容如下。回應會包含長時間執行作業 (LRO) 的 ID。如果方法呼叫可能需要額外時間才能完成，系統就會傳回長時間執行的作業。請記下 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

    APIs Explorer

    開啟方法參考頁面。系統會在頁面右側開啟 API Explorer 面板。 您可以使用這項工具來傳送要求。完成所有必填欄位，然後按一下「執行」。

    輸出內容如下。如果回應包含 "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 資源。如要復原特定 FHIR 資源，請在檔案中指定資源類型及其資源 ID，然後將檔案上傳至 Cloud Storage。在 inputGcsObject 欄位中指定檔案的位置。

如要從 Cloud Storage 讀取篩選器檔案，您必須將權限授予 Cloud Healthcare Service Agent 服務帳戶。詳情請參閱「從 Cloud Storage 讀取篩選器檔案」。

篩選器檔案可以有任何副檔名。必須使用下列結構定義，每行一個 FHIR 資源：

FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID

舉例來說，如要復原 ID 為 8f25b0ac 的 Patient 資源，以及 ID 為 d507417e90e 和 e9950d90e 的兩個 Observation 資源，請在篩選器檔案中指定下列內容：

Patient/8f25b0ac
Observation/d507417e90e
Observation/e9950d90e

使用自訂函式

Cloud Healthcare API 提供下列自訂篩選函式。您可以將自訂函式與 rollbackTime 欄合併，以便套用其他篩選器。

tag
詳細資料
函式語法
tag("system") = "code"
說明
根據資源 Meta.tag 元素篩選 FHIR 資源。
引數
system
string
參照程式碼系統的網址。詳情請參閱「在資源中使用程式碼」。
code
string
用於識別概念的值，由程式碼系統定義。詳情請參閱「在資源中使用代碼」。
extension_value_ts
詳細資料
函式語法
extension_value_ts("url")
說明
根據 extension 元素中的 url 值篩選 FHIR 資源，其中 url 是 Unix 時間戳記。支援下列比較運算子：
  • =
  • !=
  • <
  • >
  • <=
  • >=
引數
url
string
定義擴充功能的 StructureDefinition 資源的標準網址。例如，在以下 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 病患資源。還原作業會在 3:00 結束。

  2. 幾天後，您執行復原作業，並將復原時間戳記設為 1:00。根據預設，執行作業會導致下列結果：

    • 不正確重建 Patient/1 和 Patient/2 Patient 資源。
    • 正確復原在 3:00 之後建立或更新的 FHIR 資源。

如要排除刪除 Patient/1 和 Patient/2 病患資源的初始復原作業，並避免重新建立這些資源，請將 excludeRollbacks 設為 true。

使用長時間執行作業 (LRO) ID 進行篩選

如果 FHIR 資源遭到一或多個長時間執行作業 (LROs) 修改，您可以在 operationIds 欄位中指定 LRO ID，以便復原已修改的資源。

如要瞭解如何在 Cloud Healthcare API 資料集中列出及查看 LRO ID，請參閱「列出 LRO」。

重試在實際環境中無法復原的 FHIR 資源

如果部分 FHIR 資源無法在實際環境中復原，您可以重試復原作業。使用產生的正式版輸出檔案，找出失敗的 FHIR 資源。在篩選器檔案中指定這些 FHIR 資源的類型和 ID，然後再次執行復原作業。

每次執行復原作業時，如果您在每個要求中使用相同的設定，且時間戳記在過去 21 天內，復原作業就會是冪等的。

限制

  • 無論 FHIR 儲存庫的 disableReferentialIntegrity 設定為何，PITR 都不會強制執行參照完整性。僅還原部分 FHIR 資源，可能會導致 FHIR 儲存庫處於違反參照完整性的狀態。

  • PITR 會略過 FHIR 設定檔驗證，因為已還原的 FHIR 資源在建立或更新時已完成驗證。如果 FHIR 儲存庫設定檔設定有所變更，PITR 可能會讓 FHIR 儲存庫處於違反設定檔驗證的狀態。

  • 如果 rollbackTime 的值早於 FHIR 資源在 FHIR 儲存庫中刪除的時間，則 FHIR 儲存庫必須啟用 enableUpdateCreate，否則無法復原資源。

  • 您可以在復原期間更新 FHIR 儲存庫或讀取及寫入資料，但視復原階段而定，您可能會看到意外的結果。舉例來說，讀取要求可能會傳回已復原和未復原的 FHIR 資源組合。如果您更新資源，復原作業可能會覆寫更新內容。

  • 時間點復原功能會保留 FHIR 資源記錄。每個還原的資源都會取得新的目前版本，並保留其記錄。