本页面介绍了如何使用实体标记 (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 项目的 IDLOCATION
:数据集位置DATASET_ID
:FHIR 存储区的父数据集FHIR_STORE_ID
:FHIR 存储区 IDFHIR_RESOURCE_TYPE
:FHIR 资源类型FHIR_RESOURCE_ID
:FHIR 资源 ID
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 项目的 IDLOCATION
:数据集位置DATASET_ID
:FHIR 存储区的父数据集FHIR_STORE_ID
:FHIR 存储区 IDFHIR_RESOURCE_TYPE
:FHIR 资源类型FHIR_RESOURCE_ID
:FHIR 资源 ID
curl
使用 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 资源。
PowerShell
使用 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 项目的 IDLOCATION
:数据集位置DATASET_ID
:FHIR 存储区的父数据集FHIR_STORE_ID
:FHIR 存储区 IDFHIR_RESOURCE_TYPE
:FHIR 资源类型FHIR_RESOURCE_ID
:FHIR 资源 ID
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
状态代码。