使用时间点恢复 (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 文件夹或存储分区的完全限定 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

    复制请求正文并打开方法参考页面。APIs Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。 将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

    输出如下所示。响应包含长时间运行的操作 (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

    打开方法参考页面。APIs 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

    API Explorer

    复制请求正文并打开方法参考页面。APIs Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。 将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。

    输出如下所示。响应包含长时间运行的操作 (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

    打开方法参考页面。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 资源之前的状态。

使用过滤器文件

默认情况下，PITR 会恢复 FHIR 存储区中的所有 FHIR 资源。如需恢复特定的 FHIR 资源，请在文件中指定资源类型及其资源 ID，然后将该文件上传到 Cloud Storage。在 inputGcsObject 字段中指定文件的位置。

如需从 Cloud Storage 读取过滤器文件，您必须向 Cloud Healthcare Service Agent 服务账号授予权限。如需了解详情，请参阅从 Cloud Storage 读取过滤器文件。

过滤器文件可以采用任何扩展名。它必须使用以下架构，每行包含一个 FHIR 资源：

FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID

例如，如需恢复 ID 为 8f25b0ac 的患者资源以及 ID 为 d507417e90e 和 e9950d90e 的两个观察结果资源，请在过滤器文件中指定以下内容：

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 患者资源。
    • 正确恢复在 3:00 之后创建或更新的 FHIR 资源。

如需排除删除了 Patient/1 和 Patient/2 Patient 资源的初始恢复操作，并避免重新创建这些资源，请将 excludeRollbacks 设为 true。

使用长时间运行的操作 (LRO) ID 进行过滤

如果 FHIR 资源被一个或多个长时间运行的操作 (LRO) 修改，您可以在 operationIds 字段中指定 LRO ID 以恢复已修改的资源。

如需了解如何在 Cloud Healthcare API 数据集中列出和查看 LRO ID，请参阅列出 LRO。

重试在生产环境中未能恢复的 FHIR 资源

如果某些 FHIR 资源未能成功恢复到生产环境，您可以重新尝试恢复。使用生成的正式版输出文件查找失败的 FHIR 资源。在过滤器文件中指定这些 FHIR 资源的类型及其 ID，然后再次运行恢复操作。

如果您在每次请求中使用相同的配置，并且时间戳在过去 21 天内，则每次运行恢复操作时，恢复操作都是 idempotent 操作。

限制

  • 无论 FHIR 存储区上的 disableReferentialIntegrity 设置如何，PITR 都不会强制执行参照完整性。仅恢复部分 FHIR 资源可能会导致 FHIR 存储区处于违反参照完整性的状态。

  • PITR 会跳过 FHIR 配置文件验证，因为恢复的 FHIR 资源在创建或更新时已通过验证。如果 FHIR 存储区配置文件发生更改，PITR 可能会使 FHIR 存储区处于违反配置文件验证的状态。

  • 如果 rollbackTime 的值早于 FHIR 存储区中 FHIR 资源被删除的时间，则 FHIR 存储区必须启用 enableUpdateCreate，否则无法恢复该资源。

  • 您可以在恢复期间更新 FHIR 存储区或读取和写入数据，但可能会看到意外结果，具体取决于恢复阶段。例如，读取请求可能会返回已恢复和未恢复的 FHIR 资源的组合。如果您更新了资源，恢复操作可能会覆盖更新。

  • PITR 会保留 FHIR 资源历史记录。每个已恢复的资源都会获得一个新的当前版本，并且其历史记录会保留。