使用 ETag 防止 FHIR 资源冲突

本页介绍了如何使用实体标记 (ETag) 在 Cloud Healthcare API 中针对 FHIR 资源进行并发管理。ETag 通过启用乐观并发控制和客户端缓存，有助于防止数据丢失并提升应用性能。

了解 ETag

ETag 是服务器上 FHIR 资源当前状态的唯一标识符，类似于版本号。每次创建或修改 FHIR 资源时，系统都会生成新的 ETag 值。

在以下情况下，您可以使用 ETag 来确保数据完整性并优化性能：

  • 为确保乐观并发控制：当您在修改 FHIR 资源的请求中添加 ETag 时，Cloud Healthcare API 会验证 ETag 是否与服务器上最新版本的 FHIR 资源相匹配。这有助于防止一个客户端意外覆盖另一个客户端所做的更改，这也称为写入-写入冲突或“更新丢失问题”。

  • 发送有条件的请求：借助 ETag，客户端可以仅在满足特定条件时有条件地发送请求。这有助于优化数据检索并减少不必要的网络流量。例如，您可以使用以下 HTTP 标头发送有条件的请求：

    • If-Match：只有当提供的 ETag 与服务器上的当前 ETag 匹配时，请求才会成功。这样可以确保您更新的是预期的 FHIR 资源版本。
    • If-None-Match：只有当提供的 ETag 与服务器上的当前 ETag 不匹配时，请求才会成功。这样，您就可以知道资源的本地缓存版本是否仍是最新版本，从而减少每次都从服务器提取完整资源的需要。这通常用于高效缓存。

FHIR ETag 使用弱验证，这意味着它们在不同的服务器实例中可能不完全相同，但仍能有效跟踪资源更改。

获取 ETag

以下示例展示了如何获取 FHIR 资源的 ETag。

当您获取 FHIR 资源的内容时，ETag 会包含在完整的 HTTP 响应标头中。ETag 与 FHIR 资源中的 Meta.versionId 匹配。

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

  • PROJECT_ID：您的 Google Cloud 项目的 ID
  • LOCATION：数据集位置
  • DATASET_ID：FHIR 存储区的父数据集
  • FHIR_STORE_ID：FHIR 存储区 ID
  • FHIR_RESOURCE_TYPE：FHIR 资源类型
  • FHIR_RESOURCE_ID：FHIR 资源 ID

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

权限

  • healthcare.fhirResources.get

角色

  • Healthcare FHIR Resource Reader (roles/healthcare.fhirResourceReader)

您可以要求管理员为您授予这些 Identity and Access Management 角色。如需了解如何授予角色，请参阅管理访问权限或控制对 Cloud Healthcare API 资源的访问。您也可以通过自定义角色或其他预定义角色来获取所需的权限。
curlPowerShell

使用 fhir.read 方法。-verbose 标志会在响应中返回包含 ETag 的 HTTP 标头。

curl -X GET \
    -verbose \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

响应包含以下内容：

< etag: W/"ETAG_VALUE"

使用 fhir.read 方法。-Headers 标志会在响应中返回包含 ETag 的 HTTP 标头。

$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/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Headers

响应包含以下内容：

ETag                   {W/"ETAG_VALUE"}

管理更新 FHIR 资源时的并发性

以下示例展示了如何在更新 FHIR 资源时添加 ETag。

这些示例使用 If-Match，其行为如下：

  • 如果 ETag 与服务器上 FHIR 资源的当前 ETag 匹配，则更新会成功，并且服务器会为更新后的资源生成新的 ETag。这可确保您更新的是预期版本的 FHIR 资源。

  • 如果 ETag 不匹配，更新将失败并显示 412 Precondition Failed 错误，表示自提取原始 ETag 以来，其他客户端已修改了资源。这样可以防止因意外覆盖而丢失数据。

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

  • ETAG_VALUE：FHIR 资源的 ETag 值
  • PROJECT_ID：您的 Google Cloud 项目的 ID
  • LOCATION：数据集位置
  • DATASET_ID：FHIR 存储区的父数据集
  • FHIR_STORE_ID：FHIR 存储区 ID
  • FHIR_RESOURCE_TYPE：FHIR 资源类型
  • FHIR_RESOURCE_ID：FHIR 资源 ID

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

权限

  • healthcare.fhirResources.update

角色

  • Healthcare FHIR Resource Editor (roles/healthcare.fhirResourceEditor)

您可以要求管理员为您授予这些 Identity and Access Management 角色。如需了解如何授予角色，请参阅管理访问权限或控制对 Cloud Healthcare API 资源的访问。您也可以通过自定义角色或其他预定义角色来获取所需的权限。
curlPowerShell

使用 fhir.update 方法。

curl -X PUT \
    -H "If-Match: W/\"ETAG_VALUE\"" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -d @request.json \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

响应中包含更新后的 FHIR 资源。

使用 fhir.update 方法。

$cred = gcloud auth print-access-token
$etag = W/\"ETAG_VALUE\""
$headers = @{
  "Authorization" = "Bearer $cred"
  "If-Match"      = "$etag"}

Invoke-WebRequest `
    -Method PUT `
    -Headers $headers `
    -InFile request.json `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Content

响应中包含更新后的 FHIR 资源。

实现客户端缓存

您可以使用 ETag 实现客户端缓存，从而加快数据检索速度，并为用户提供更顺畅、更快速响应的体验。

如需检索之前缓存的 FHIR 资源，您可以在 If-None-Match 标头中添加缓存的 ETag，其行为如下：

  • 如果 ETag 匹配，服务器会返回 304 Not Modified，客户端会使用其缓存的副本。这样可以节省带宽并减少服务器负载。

  • 如果 ETag 不匹配，服务器会发送更新后的 FHIR 资源及其新的 ETag，以便客户端刷新其缓存。

以下示例展示了如何使用与服务器上的 ETag 匹配的 ETag 获取 FHIR 资源的内容。

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

  • ETAG_VALUE：FHIR 资源的 ETag 值
  • PROJECT_ID：您的 Google Cloud 项目的 ID
  • LOCATION：数据集位置
  • DATASET_ID：FHIR 存储区的父数据集
  • FHIR_STORE_ID：FHIR 存储区 ID
  • FHIR_RESOURCE_TYPE：FHIR 资源类型
  • FHIR_RESOURCE_ID：FHIR 资源 ID

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

权限

  • healthcare.fhirResources.get

角色

  • Healthcare FHIR Resource Reader (roles/healthcare.fhirResourceReader)

您可以要求管理员为您授予这些 Identity and Access Management 角色。如需了解如何授予角色，请参阅管理访问权限或控制对 Cloud Healthcare API 资源的访问。您也可以通过自定义角色或其他预定义角色来获取所需的权限。
curlPowerShell

使用 fhir.read 方法。-verbose 标志会在响应中返回 HTTP 标头，否则不会返回任何响应。

curl -X GET \
    -H "If-None-Match: W/\"ETAG_VALUE\"" \
    -v \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID"

响应包含 304 Not Modified 状态代码。

使用 fhir.read 方法。-Headers 标志会在响应中返回 HTTP 标头，否则不会返回任何响应。

$cred = gcloud auth print-access-token
$etag = W/\"ETAG_VALUE\""
$headers = @{
"Authorization" = "Bearer $cred"
  "If-None-Match"      = "$etag"}

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID" | Select-Object -Expand Headers

响应包含 304 Not Modified 状态代码。