Evitar conflictos de recursos FHIR mediante ETags

En esta página se explica cómo usar las etiquetas de entidad (ETags) para la gestión de la simultaneidad con recursos FHIR en la API Cloud Healthcare. Las etiquetas ETag ayudan a evitar la pérdida de datos y a mejorar el rendimiento de las aplicaciones al habilitar el control de concurrencia optimista y el almacenamiento en caché del lado del cliente.

Información sobre las ETags

Un ETag sirve como identificador único del estado actual de un recurso FHIR en el servidor, de forma similar a un número de versión. Cada vez que se crea o se modifica un recurso FHIR, se genera un nuevo valor de ETag.

Puede usar ETags para asegurar la integridad de los datos y optimizar el rendimiento en las siguientes situaciones:

• Para asegurar el control de concurrencia optimista, cuando incluyes un ETag en una solicitud para modificar un recurso FHIR, la API Cloud Healthcare verifica si el ETag coincide con la versión más reciente del recurso FHIR en el servidor. De esta forma, se evita que un cliente sobrescriba accidentalmente los cambios realizados por otro cliente, lo que también se conoce como conflicto de escritura-escritura o problema de actualización perdida.

• Envío de solicitudes condicionales: las etiquetas ETag permiten a los clientes enviar solicitudes condicionalmente solo cuando se cumplen condiciones específicas. De esta forma, se optimiza la recuperación de datos y se reduce el tráfico de red innecesario. Por ejemplo, puede enviar solicitudes condicionales mediante los siguientes encabezados HTTP:

  • If-Match: la solicitud solo se completa correctamente si el ETag proporcionado coincide con el ETag actual del servidor. De esta forma, te aseguras de que actualizas la versión esperada del recurso FHIR.
  • If-None-Match: la solicitud solo se completa correctamente si la ETag proporcionada no coincide con la ETag actual del servidor. De esta forma, sabrás si la versión de un recurso almacenada en la caché local sigue siendo actual, lo que reduce la necesidad de obtener el recurso completo del servidor cada vez. Se suele usar para mejorar la eficiencia del almacenamiento en caché.

Los ETags de FHIR usan la validación débil, lo que significa que puede que no sean idénticos en diferentes instancias del servidor, pero siguen registrando los cambios de los recursos de forma eficaz.

Obtener un ETag

En los siguientes ejemplos se muestra cómo obtener el ETag de un recurso FHIR.

El ETag se incluye en el encabezado de respuesta HTTP completo cuando obtienes el contenido de un recurso FHIR. El ETag coincide con el Meta.versionId del recurso FHIR.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• PROJECT_ID: el ID de tu Google Cloud proyecto
• LOCATION: la ubicación del conjunto de datos
• DATASET_ID: el conjunto de datos superior del almacén FHIR
• FHIR_STORE_ID: el ID del almacén FHIR
• FHIR_RESOURCE_TYPE: el tipo de recurso FHIR
• FHIR_RESOURCE_ID: el ID del recurso FHIR

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"

$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"}

Gestionar la simultaneidad al actualizar un recurso FHIR

En los siguientes ejemplos se muestra cómo incluir un ETag al actualizar un recurso FHIR.

En los ejemplos se usa If-Match, que se comporta de la siguiente manera:

• Si el ETag coincide con el ETag actual del recurso FHIR en el servidor, la actualización se realiza correctamente y el servidor genera un nuevo ETag para el recurso actualizado. De esta forma, te aseguras de que actualizas la versión esperada del recurso FHIR.

• Si la ETag no coincide, la actualización falla y se devuelve un error 412 Precondition Failed que indica que otro cliente ha modificado el recurso desde que se obtuvo la ETag original. De esta forma, se evitan las pérdidas de datos por sobrescrituras accidentales.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• ETAG_VALUE: el valor de ETag del recurso FHIR
• PROJECT_ID: el ID de tu Google Cloud proyecto
• LOCATION: la ubicación del conjunto de datos
• DATASET_ID: el conjunto de datos superior del almacén FHIR
• FHIR_STORE_ID: el ID del almacén FHIR
• FHIR_RESOURCE_TYPE: el tipo de recurso FHIR
• FHIR_RESOURCE_ID: el ID del recurso 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"

$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

Implementar el almacenamiento en caché del lado del cliente

Puede usar ETags para implementar el almacenamiento en caché del lado del cliente, lo que acelera la recuperación de datos y contribuye a que la experiencia de usuario sea más fluida y rápida.

Para recuperar un recurso FHIR almacenado en caché anteriormente, puedes incluir el ETag almacenado en caché en el encabezado If-None-Match, que tiene el siguiente comportamiento:

• Si las ETags coinciden, el servidor responde con 304 Not Modified y el cliente usa su copia almacenada en caché. De esta forma, se ahorra ancho de banda y se reduce la carga del servidor.

• Si los ETag no coinciden, el servidor envía el recurso FHIR actualizado y su nuevo ETag, lo que permite al cliente actualizar su caché.

En los siguientes ejemplos se muestra cómo obtener el contenido de un recurso FHIR mediante una ETag que coincida con la ETag del servidor.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• ETAG_VALUE: el valor de ETag del recurso FHIR
• PROJECT_ID: el ID de tu Google Cloud proyecto
• LOCATION: la ubicación del conjunto de datos
• DATASET_ID: el conjunto de datos superior del almacén FHIR
• FHIR_STORE_ID: el ID del almacén FHIR
• FHIR_RESOURCE_TYPE: el tipo de recurso FHIR
• FHIR_RESOURCE_ID: el ID del recurso FHIR

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"

$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