Evita los conflictos de recursos de FHIR con ETags

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

Información sobre las ETags

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

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

• Para garantizar el control de simultaneidad optimista: Cuando incluyes una ETag en una solicitud para modificar un recurso de FHIR, la API de Cloud Healthcare verifica si la ETag coincide con la versión más reciente del recurso de FHIR en el servidor. Esto ayuda a evitar que un cliente reemplace accidentalmente los cambios realizados por otro cliente, también llamado conflicto de escritura o "problema de actualización perdida".

• Envío de solicitudes condicionales: Los ETags permiten que los clientes envíen solicitudes de forma condicional solo cuando se cumplen condiciones específicas. Esto optimiza la recuperación de datos y reduce el tráfico de red innecesario. Por ejemplo, puedes enviar solicitudes condicionales con los siguientes encabezados HTTP:

  • If-Match: La solicitud solo se realiza correctamente si la ETag proporcionada coincide con la ETag actual del servidor. Esto garantiza que actualices la versión esperada del recurso FHIR.
  • If-None-Match: La solicitud solo se realiza correctamente si la ETag proporcionada no coincide con la ETag actual del servidor. Esto te permite saber si la versión almacenada en caché local de un recurso sigue siendo actual, lo que reduce la necesidad de recuperar el recurso completo del servidor cada vez. Por lo general, se usa para el almacenamiento en caché eficiente.

Las ETags de FHIR usan validación débil, lo que significa que pueden no ser idénticas en diferentes instancias de servidor, pero aún hacen un seguimiento eficaz de los cambios en los recursos.

Cómo obtener una ETag

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

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

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

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

Permisos necesarios para esta tarea

Para realizar esta tarea, debes tener los siguientes permisos o las siguientes funciones de Administración de identidades y accesos (IAM):

Permisos

• healthcare.fhirResources.get

Funciones

• Lector de recursos FHIR de Healthcare (roles/healthcare.fhirResourceReader)

Puedes pedirle a tu administrador que te otorgue estos roles de administración de identidades y accesos. Si quieres obtener instrucciones para otorgar roles, consulta Administra el acceso o Controla el acceso a los recursos de la API de Cloud Healthcare. También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Nota: Si creaste un proyecto Google Cloud para esta guía, como creador del proyecto, se te otorga automáticamente el rol de IAM propietario (roles/owner), que tiene los permisos. No es necesario que se te otorgue ningún rol de IAM adicional.

curl

Usa el método fhir.read. La marca -verbose muestra los encabezados HTTP en la respuesta, que contienen la 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"

La respuesta contiene lo siguiente:

< etag: W/"ETAG_VALUE"

PowerShell

Usa el método fhir.read. La marca -Headers muestra los encabezados HTTP en la respuesta, que contienen la etiqueta 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

La respuesta contiene lo siguiente:

ETag                   {W/"ETAG_VALUE"}

Administra la simultaneidad cuando actualizas un recurso de FHIR

En los siguientes ejemplos, se muestra cómo incluir una ETag cuando se actualiza un recurso de FHIR.

En las muestras, se usa If-Match, que tiene el siguiente comportamiento:

• 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 ETag nuevo para el recurso actualizado. Esto garantiza que actualices la versión esperada del recurso de FHIR.

• Si la ETag no coincide, la actualización falla con un error 412 Precondition Failed, lo que indica que otro cliente modificó el recurso desde que se recuperó la ETag original. Esto evita la pérdida de datos por reemplazos accidentales.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

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

Permisos necesarios para esta tarea

Para realizar esta tarea, debes tener los siguientes permisos o las siguientes funciones de Administración de identidades y accesos (IAM):

Permisos

• healthcare.fhirResources.update

Funciones

• Editor de recursos FHIR de Healthcare (roles/healthcare.fhirResourceEditor)

Puedes pedirle a tu administrador que te otorgue estos roles de administración de identidades y accesos. Si quieres obtener instrucciones para otorgar roles, consulta Administra el acceso o Controla el acceso a los recursos de la API de Cloud Healthcare. También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Nota: Si creaste un proyecto Google Cloud para esta guía, como creador del proyecto, se te otorga automáticamente el rol de IAM propietario (roles/owner), que tiene los permisos. No es necesario que se te otorgue ningún rol de IAM adicional.

curl

Usa el método fhir.update.

Importante: La muestra incluye una marca -d @request.json. Debes tener un archivo request.json válido en tu directorio actual antes de ejecutar la muestra. Para ver ejemplos de lo que se debe incluir en un archivo request.json, consulta Cómo actualizar un recurso de 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"

La respuesta contiene el recurso de FHIR actualizado.

PowerShell

Usa el método fhir.update.

Importante: La muestra incluye una marca -Infile request.json. Debes tener un archivo request.json válido en tu directorio actual antes de ejecutar la muestra. Para ver ejemplos de lo que se debe incluir en un archivo request.json, consulta Cómo actualizar un recurso de 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

La respuesta contiene el recurso de FHIR actualizado.

Implementa el almacenamiento en caché del cliente

Puedes usar ETags para implementar el almacenamiento en caché del cliente, que acelera la recuperación de datos y contribuye a una experiencia del usuario más fluida y responsiva.

Para recuperar un recurso FHIR almacenado en caché anteriormente, puedes incluir la ETag almacenada 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é. Esto ahorra ancho de banda y reduce la carga del servidor.

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

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

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

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

Permisos necesarios para esta tarea

Para realizar esta tarea, debes tener los siguientes permisos o las siguientes funciones de Administración de identidades y accesos (IAM):

Permisos

• healthcare.fhirResources.get

Funciones

• Lector de recursos FHIR de Healthcare (roles/healthcare.fhirResourceReader)

Puedes pedirle a tu administrador que te otorgue estos roles de administración de identidades y accesos. Si quieres obtener instrucciones para otorgar roles, consulta Administra el acceso o Controla el acceso a los recursos de la API de Cloud Healthcare. También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Nota: Si creaste un proyecto Google Cloud para esta guía, como creador del proyecto, se te otorga automáticamente el rol de IAM propietario (roles/owner), que tiene los permisos. No es necesario que se te otorgue ningún rol de IAM adicional.

curl

Usa el método fhir.read. La marca -verbose muestra los encabezados HTTP en la respuesta; de lo contrario, no se muestra ninguna respuesta.

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"

La respuesta contiene un código de estado 304 Not Modified.

PowerShell

Usa el método fhir.read. La marca -Headers muestra los encabezados HTTP en la respuesta; de lo contrario, no se muestra ninguna respuesta.

$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

La respuesta contiene un código de estado 304 Not Modified.