Prévenir les conflits de ressources FHIR à l'aide d'ETags

Cette page explique comment utiliser des balises d'entité (ETags) pour la gestion de la concurrence avec les ressources FHIR dans l'API Cloud Healthcare. Les ETags 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

Un 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 des ETags pour garantir l'intégrité des données et optimiser les performances dans les situations suivantes :

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

• Envoi de requêtes conditionnelles: les ETag permettent aux clients d'envoyer uniquement lorsque des conditions spécifiques sont remplies. Cela optimise les données et réduit 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 au l'ETag actuel sur le serveur. Vous êtes ainsi sûr de mettre à jour la version attendue de la ressource FHIR.
  • If-None-Match: la requête n'aboutit que si l'ETag fourni n'aboutit pas. correspond à l'ETag actuel sur le serveur. Cela vous permet de savoir si votre version mise en cache localement d'une ressource est toujours à jour, ce qui réduit le besoin d'extraire chaque fois la ressource complète du 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 ne sont pas nécessairement identiques entre les différentes instances de serveur, mais qu'ils permettent tout de même de suivre efficacement les modifications des 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 obtenir 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

Autorisations requises pour cette tâche

Pour effectuer cette tâche, vous devez disposer des autorisations suivantes ou aux rôles Identity and Access Management (IAM) suivants:

Autorisations

• healthcare.fhirResources.get

Rôles

• Lecteur de ressources FHIR Healthcare (roles/healthcare.fhirResourceReader)

Vous pouvez demander à votre administrateur de vous accorder ces rôles Identity and Access Management. Pour obtenir des instructions sur l'attribution de rôles, consultez Gérer les accès ou Contrôler l'accès aux ressources de l'API Cloud Healthcare. Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Remarque: Si vous avez créé un projet Google Cloud pour ce guide, en tant que créateur du projet, le rôle IAM Propriétaire (roles/owner) vous est automatiquement attribué, qui dispose des autorisations nécessaires. Vous n'avez pas besoin d'être attribué de rôles IAM supplémentaires.

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'option -Headers renvoie les en-têtes HTTP dans la réponse, qui contiennent les informations 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 aboutit 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 et renvoie l'erreur 412 Precondition Failed. indiquant qu'un autre client a modifié la ressource depuis l'original ETag a été récupéré. 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

Autorisations requises pour cette tâche

Pour effectuer cette tâche, vous devez disposer des autorisations suivantes ou aux rôles Identity and Access Management (IAM) suivants:

Autorisations

• healthcare.fhirResources.update

Rôles

• Éditeur de ressources FHIR Healthcare (roles/healthcare.fhirResourceEditor)

Vous pouvez demander à votre administrateur de vous accorder ces rôles Identity and Access Management. Pour obtenir des instructions sur l'attribution de rôles, consultez Gérer les accès ou Contrôler l'accès aux ressources de l'API Cloud Healthcare. Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Remarque : Si vous avez créé un projet Google Cloud pour ce guide, vous disposez automatiquement du rôle IAM Propriétaire (roles/owner), qui dispose des autorisations nécessaires. Vous n'avez pas besoin d'obtenir des rôles IAM supplémentaires.

curl

Utilisez la méthode fhir.update.

Important :L'exemple inclut un indicateur -d @request.json. Vous devez disposer d'un fichier request.json valide dans votre répertoire actuel avant d'exécuter l'exemple. Par exemple, des éléments à inclure dans un fichier request.json, consultez Mettre à jour une ressource 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 réponse contient la ressource FHIR mise à jour.

PowerShell

Utilisez la méthode fhir.update.

Important : L'exemple inclut un indicateur -Infile request.json. Vous devez disposer d'un fichier request.json valide dans votre répertoire actuel avant d'exécuter l'échantillon. Pour obtenir des exemples d'éléments à inclure dans un fichier request.json, consultez la section Mettre à jour une ressource 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 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 les 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 ETags correspondent, le serveur répond avec 304 Not Modified et le client utilise sa copie mise en cache. Cela permet d'économiser 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 son nouvel 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

Autorisations requises pour cette tâche

Pour effectuer cette tâche, vous devez disposer des autorisations suivantes ou des rôles Identity and Access Management (IAM) suivants :

Autorisations

• healthcare.fhirResources.get

Rôles

• Lecteur de ressources FHIR Healthcare (roles/healthcare.fhirResourceReader)

Vous pouvez demander à votre administrateur de vous accorder ces rôles Identity and Access Management. Pour obtenir des instructions sur l'attribution de rôles, consultez Gérer les accès ou Contrôler l'accès aux ressources de l'API Cloud Healthcare. Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Remarque: Si vous avez créé un projet Google Cloud pour ce guide, en tant que créateur du projet, le rôle IAM Propriétaire (roles/owner) vous est automatiquement attribué, qui dispose des autorisations nécessaires. Vous n'avez pas besoin d'obtenir des rôles IAM supplémentaires.

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'option -Headers renvoie les en-têtes HTTP dans la réponse, sinon aucune réponse est renvoyé.

$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.