使用 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 资源的访问权限。 您也可以通过自定义角色或其他预定义角色来获取所需的权限。

注意：如果您为此指南创建了 Google Cloud 项目，那么作为项目创建者，您会自动获得 Owner (roles/owner) IAM 角色，该角色具有相应权限。您无需被授予任何额外的 IAM 角色。

curl

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

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"

PowerShell

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

$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 资源的访问权限。 您也可以通过自定义角色或其他预定义角色来获取所需的权限。

注意：如果您为此指南创建了 Google Cloud 项目，那么作为项目创建者，您会自动获得 Owner (roles/owner) IAM 角色，该角色具有相应权限。您无需被授予任何额外的 IAM 角色。

curl

使用 fhir.update 方法。

重要提示： 此示例包含 -d @request.json 标志。在运行示例之前，您必须在当前目录中拥有有效的 request.json 文件。如需查看 request.json 文件中应包含哪些内容的示例，请参阅更新 FHIR 资源。

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 资源。

PowerShell

使用 fhir.update 方法。

重要提示： 此示例包含 -Infile request.json 标志。在运行示例之前，您必须在当前目录中拥有有效的 request.json 文件。如需查看 request.json 文件中应包含哪些内容的示例，请参阅更新 FHIR 资源。

$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 资源的访问权限。 您也可以通过自定义角色或其他预定义角色来获取所需的权限。

注意：如果您为此指南创建了 Google Cloud 项目，那么作为项目创建者，您会自动获得 Owner (roles/owner) IAM 角色，该角色具有相应权限。您无需被授予任何额外的 IAM 角色。

curl

使用 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 状态代码。

PowerShell

使用 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 状态代码。