Éviter les conflits de ressources FHIR à l'aide d'ETags

Cette page explique comment utiliser les tags d'entité (ETags) pour la gestion de la simultanéité avec les ressources FHIR dans l'API Cloud Healthcare. Les ETag permettent d'éviter la perte de données et d'améliorer les performances des applications en activant le contrôle de simultanéité optimiste et la mise en cache côté client.

Comprendre les ETags

Une balise ETag sert d'identifiant unique pour l'état actuel d'une ressource FHIR sur le serveur, comme un numéro de version. Chaque fois qu'une ressource FHIR est créée ou modifiée, une nouvelle valeur ETag est générée.

Vous pouvez utiliser les ETags pour garantir l'intégrité des données et optimiser les performances dans les situations suivantes :

  • Pour assurer le contrôle de la concurrence optimiste : lorsque vous incluez un ETag dans une requête visant à modifier une ressource FHIR, l'API Cloud Healthcare vérifie si l'ETag correspond à la dernière version de la ressource FHIR sur le serveur. Cela permet d'éviter qu'un client n'écrase accidentellement les modifications apportées par un autre client, ce qui est également appelé conflit d'écriture ou problème de mise à jour perdue.

  • Envoi de requêtes conditionnelles : les ETag permettent aux clients d'envoyer des requêtes conditionnelles uniquement lorsque des conditions spécifiques sont remplies. Cela permet d'optimiser la récupération des données et de réduire le trafic réseau inutile. Par exemple, vous pouvez envoyer des requêtes conditionnelles à l'aide des en-têtes HTTP suivants :

    • If-Match : la requête n'aboutit que si l'ETag fourni correspond à l'ETag actuel sur le serveur. Cela vous permet de mettre à jour la version attendue de la ressource FHIR.
    • If-None-Match : la requête n'aboutit que si l'ETag fourni ne correspond pas à l'ETag actuel sur le serveur. Cela vous permet de savoir si la version mise en cache localement d'une ressource est toujours à jour, ce qui réduit la nécessité de récupérer la ressource complète à chaque fois depuis le serveur. Cette méthode est couramment utilisée pour une mise en cache efficace.

Les ETags FHIR utilisent une validation faible, ce qui signifie qu'ils peuvent ne pas être identiques sur différentes instances de serveur, mais qu'ils suivent toujours efficacement les modifications apportées aux ressources.

Obtenir un ETag

Les exemples suivants montrent comment obtenir l'ETag d'une ressource FHIR.

L'ETag est inclus dans l'en-tête de réponse HTTP complet lorsque vous obtenez le contenu d'une ressource FHIR. L'ETag correspond à Meta.versionId dans la ressource FHIR.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : emplacement de l'ensemble de données
  • DATASET_ID : ensemble de données parent du magasin FHIR.
  • FHIR_STORE_ID : ID du magasin FHIR.
  • FHIR_RESOURCE_TYPE : type de la ressource FHIR
  • FHIR_RESOURCE_ID : ID de la ressource FHIR

curl

Utilisez la méthode fhir.read. L'indicateur -verbose renvoie les en-têtes HTTP dans la réponse, qui contiennent l'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 réponse contient les éléments suivants :

< etag: W/"ETAG_VALUE"

PowerShell

Utilisez la méthode fhir.read. L'indicateur -Headers renvoie les en-têtes HTTP dans la réponse, qui contiennent l'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 réponse contient les éléments suivants :

ETag                   {W/"ETAG_VALUE"}

Gérer la simultanéité lors de la mise à jour d'une ressource FHIR

Les exemples suivants montrent comment inclure un ETag lors de la mise à jour d'une ressource FHIR.

Les exemples utilisent If-Match, qui présente le comportement suivant :

  • Si l'ETag correspond à l'ETag actuel de la ressource FHIR sur le serveur, la mise à jour réussit et le serveur génère un nouvel ETag pour la ressource mise à jour. Vous êtes ainsi sûr de mettre à jour la version attendue de la ressource FHIR.

  • Si l'ETag ne correspond pas, la mise à jour échoue avec une erreur 412 Precondition Failed, indiquant qu'un autre client a modifié la ressource depuis la récupération de l'ETag d'origine. Cela permet d'éviter la perte de données en cas d'écrasement accidentel.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • ETAG_VALUE : valeur ETag de la ressource FHIR
  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : emplacement de l'ensemble de données
  • DATASET_ID : ensemble de données parent du magasin FHIR.
  • FHIR_STORE_ID : ID du magasin FHIR.
  • FHIR_RESOURCE_TYPE : type de la ressource FHIR
  • FHIR_RESOURCE_ID : ID de la ressource FHIR

curl

Utilisez la méthode 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"

La réponse contient la ressource FHIR mise à jour.

PowerShell

Utilisez la méthode 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

La réponse contient la ressource FHIR mise à jour.

Implémenter la mise en cache côté client

Vous pouvez utiliser les ETags pour implémenter la mise en cache côté client, ce qui accélère la récupération des données et contribue à une expérience utilisateur plus fluide et plus réactive.

Pour récupérer une ressource FHIR précédemment mise en cache, vous pouvez inclure l'ETag mis en cache dans l'en-tête If-None-Match, qui présente le comportement suivant :

  • Si les ETag correspondent, le serveur répond avec 304 Not Modified et le client utilise sa copie mise en cache. Cela permet d'économiser de la bande passante et de réduire la charge du serveur.

  • Si les ETags ne correspondent pas, le serveur envoie la ressource FHIR mise à jour et sa nouvelle ETag, ce qui permet au client d'actualiser son cache.

Les exemples suivants montrent comment obtenir le contenu d'une ressource FHIR à l'aide d'un ETag correspondant à celui du serveur.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

  • ETAG_VALUE : valeur ETag de la ressource FHIR
  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : emplacement de l'ensemble de données
  • DATASET_ID : ensemble de données parent du magasin FHIR.
  • FHIR_STORE_ID : ID du magasin FHIR.
  • FHIR_RESOURCE_TYPE : type de la ressource FHIR
  • FHIR_RESOURCE_ID : ID de la ressource FHIR

curl

Utilisez la méthode fhir.read. L'indicateur -verbose renvoie les en-têtes HTTP dans la réponse. Sinon, aucune réponse n'est renvoyée.

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 réponse contient un code d'état 304 Not Modified.

PowerShell

Utilisez la méthode fhir.read. L'indicateur -Headers renvoie les en-têtes HTTP dans la réponse. Sinon, aucune réponse n'est renvoyée.

$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 réponse contient un code d'état 304 Not Modified.