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

本頁說明如何使用時間點復原 (PITR)，將 FHIR 存放區中的 FHIR 資源復原至過去 21 天內的狀態。您可以使用 PITR 從不想要的變更中復原，例如意外刪除 FHIR 資源。

事前準備

PITR 要求會歸類為進階作業要求，並據此計費。使用 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 資料夾或 bucket 完整 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

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

    輸出內容如下所示。回應會包含長時間執行作業 (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

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

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

查看模擬測試輸出檔案

每次試運作都會輸出一或多個檔案，其中包含要復原的 FHIR 資源 ID 和類型。檔案會建立在目標 Cloud Storage bucket 的 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 資料夾或 bucket 完整 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

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

    輸出內容如下所示。回應會包含長時間執行作業 (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

    開啟方法參考頁面。系統會在頁面右側開啟 APIs 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 服務代理程式服務帳戶權限。詳情請參閱「從 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 Patient 資源。復原作業將於 3:00結束。

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

    • 錯誤地重新建立 Patient/1 和 Patient/2 病患資源。
    • 正確復原 3:00 之後建立或更新的 FHIR 資源。

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

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

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

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

重試在正式環境中無法復原的 FHIR 資源

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

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

限制

  • 無論 FHIR 儲存庫的 disableReferentialIntegrity 設定為何，時間點復原功能都不會強制執行參照完整性。如果只還原部分 FHIR 資源，FHIR 儲存庫可能會處於違反參照完整性的狀態。

  • 由於還原的 FHIR 資源在建立或更新時已通過驗證，因此 PITR 會略過 FHIR 設定檔驗證。如果 FHIR 儲存庫設定檔設定已變更，PITR 可能會導致 FHIR 儲存庫處於違反設定檔驗證的狀態。

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

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

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