借助时间点恢复 (PITR) 来恢复 FHIR 资源

本页面介绍了如何使用时间点恢复 (PITR) 将 FHIR 存储区中的 FHIR 资源恢复为过去 21 天内的状态。您可以使用 PITR 从不需要的更改（例如意外删除 FHIR 资源）中恢复。

PITR 和 FHIR 资源版本记录

PITR 不依赖于 FHIR 资源版本历史记录。如果 FHIR 存储区中的 disableResourceVersioning 字段为 true，或 FHIR 资源的历史版本已完全清除，您仍然可以使用 PITR。

恢复工作流程

如需确保生产环境恢复按预期运行，请先执行试运行。试运行会输出一个或多个文件，其中包含要恢复的 FHIR 资源的 ID 和类型。在生产中再次运行恢复之前，请先验证输出文件的正确性。

如需恢复特定资源，或根据过滤条件恢复资源，请指定过滤条件。

执行试运行

执行此任务所需的权限

如需执行此任务，您必须已获得以下权限或 Identity and Access Management (IAM) 角色：

权限

healthcare.fhirStores.rollback

角色

Healthcare FHIR Store Administrator (roles/healthcare.fhirStoreAdmin)

在生产环境中恢复 FHIR 资源之前，请执行试运行。

以下示例展示了如何使用 fhirStores.rollback 方法执行试运行。

REST

恢复 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback"
```
PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback" | Select-Object -Expand Content
```
API Explorer

复制请求正文并打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。
输出如下所示。响应包含长时间运行的操作 (LRO) 的标识符。如果方法调用可能需要更多时间才能完成，系统就会返回长时间运行的操作。请注意 OPERATION_ID 的值。在下一步中，您需要使用此值。
响应
```
{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}
```

使用 projects.locations.datasets.operations.get 方法可获取长时间运行的操作的状态。

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的 Google Cloud 项目的 ID
DATASET_ID：数据集 ID
LOCATION：数据集位置
OPERATION_ID：从长时间运行的操作返回的 ID

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

执行以下命令：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1beta1/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/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

API Explorer

打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。填写所有必填字段，然后点击执行。

输出如下所示。如果响应包含 "done": true，则表示长时间运行的操作已完成。

响应

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.fhir.FhirStoreService.RollbackFhirResources",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT",
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.fhir.RollbackFhirResourcesResponse",
    "fhirStore": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/myfhirstore"
  }
}

查看试运行输出文件

每次试运行都会输出一个或多个文件，其中包含要恢复的 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 资源的时间。

在生产环境中恢复

执行此任务所需的权限

如需执行此任务，您必须已获得以下权限或 Identity and Access Management (IAM) 角色：

权限

healthcare.fhirStores.rollback

角色

Healthcare FHIR Store Administrator (roles/healthcare.fhirStoreAdmin)

如需将生产输出文件写入 Cloud Storage，您必须向 Cloud Healthcare Service Agent 服务帐号授予权限。有关说明，请参阅将输出文件写入 Cloud Storage。

在生产环境中恢复之前，请执行试运行并检查试运行输出文件，以确保生产环境恢复按预期运行。

以下示例展示了如何使用 fhirStores.rollback 方法恢复生产环境中的 FHIR 资源。

REST

恢复 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

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback"
```
PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:rollback" | Select-Object -Expand Content
```
API Explorer

复制请求正文并打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。将请求正文粘贴到此工具中，填写任何其他必填字段，然后点击执行。
输出如下所示。响应包含长时间运行的操作 (LRO) 的标识符。如果方法调用可能需要更多时间才能完成，系统就会返回长时间运行的操作。请注意 OPERATION_ID 的值。在下一步中，您需要使用此值。
响应
```
{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}
```

使用 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/v1beta1/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/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

API Explorer

打开方法参考页面。API Explorer 面板会在页面右侧打开。您可以与此工具进行交互以发送请求。填写所有必填字段，然后点击执行。

输出如下所示。如果响应包含 "done": true，则表示长时间运行的操作已完成。

响应

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1beta1.fhir.FhirStoreService.RollbackFhirResources",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT",
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.fhir.RollbackFhirResourcesResponse",
    "fhirStore": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/myfhirstore"
  }
}

查看生产环境恢复输出文件

生产环境恢复会输出以下文件。系统会在目标 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:00，您可以启动恢复时间戳，并将恢复时间戳设置为 0:01。在 2:00，恢复操作会删除 FHIR 存储区中的 Patient/1 和 Patient/2 患者资源。恢复操作将于 3:00 结束。
几天后，您运行恢复操作，将恢复时间戳设置为 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 天内，则恢复过程就是幂等的。

限制

无论 FHIR 存储区的 disableReferentialIntegrity 设置如何，PITR 都不会强制执行参照完整性。如果仅恢复部分 FHIR 资源，可能会使 FHIR 存储区处于违反引用完整性的状态。
PITR 会跳过 FHIR 配置文件验证，因为恢复的 FHIR 资源是在创建或更新时进行的验证。如果 FHIR 存储区配置文件配置发生更改，PITR 可能会使 FHIR 存储区处于违反配置文件验证的状态。
如果 rollbackTime 的值早于 FHIR 存储区中删除 FHIR 资源的时间，则 FHIR 存储区必须启用 enableUpdateCreate，否则该资源将无法恢复。
在恢复期间，您可以更新 FHIR 存储区或读取和写入数据，但您可能会看到意外结果，具体取决于恢复阶段。例如，读取请求可能会返回已恢复和未恢复的 FHIR 资源的组合。如果您更新资源，恢复作业可能会覆盖更新。
PITR 会保留 FHIR 资源历史记录。每个恢复的资源都会获得一个新的当前版本，并保留其历史记录。