Evitare i conflitti delle risorse FHIR utilizzando gli ETag

Questa pagina spiega come utilizzare i tag delle entità (ETag) per la gestione della concorrenza con le risorse FHIR nell'API Cloud Healthcare. Gli ETag contribuiscono a evitare la perdita di dati e a migliorare le prestazioni dell'applicazione attivando il controllo della concorrenza ottimistico e la memorizzazione nella cache lato client.

Informazioni sugli ETag

Un ETag funge da identificatore univoco per lo stato corrente di una risorsa FHIR sul server, in modo simile a un numero di versione. Ogni volta che una risorsa FHIR viene creata o modificata, viene generato un nuovo valore ETag.

Puoi utilizzare gli ETag per garantire l'integrità dei dati e ottimizzare il rendimento nelle seguenti situazioni:

  • Per garantire il controllo della concorrenza ottimistico: quando includi un ETag in una richiesta di modifica di una risorsa FHIR, l'API Cloud Healthcare verifica se l'ETag corrisponde alla versione più recente della risorsa FHIR sul server. In questo modo, un client non sovrascriverà accidentalmente le modifiche apportate da un altro client, un problema chiamato anche conflitto di scrittura o "problema di aggiornamento perso".

  • Invio di richieste condizionali: gli ETag consentono ai client di inviare richieste in modo condizionale solo quando sono soddisfatte condizioni specifiche. In questo modo, ottimizzi il recupero dei dati e riduci il traffico di rete non necessario. Ad esempio, puoi inviare richieste condizionali utilizzando le seguenti intestazioni HTTP:

    • If-Match: la richiesta va a buon fine solo se l'ETag fornito corrisponde all'ETag corrente sul server. In questo modo, avrai la certezza di aggiornare la versione prevista della risorsa FHIR.
    • If-None-Match: la richiesta va a buon fine solo se l'ETag fornito non corrisponde all'ETag corrente sul server. In questo modo puoi sapere se la versione memorizzata nella cache locale di una risorsa è ancora aggiornata, riducendo la necessità di recuperare ogni volta la risorsa completa dal server. Questo approccio viene comunemente utilizzato per una memorizzazione nella cache efficiente.

Gli ETag FHIR utilizzano la convalida debole, il che significa che potrebbero non essere identici in diverse istanze di server, ma monitorano comunque in modo efficace le modifiche alle risorse.

Ottenere un ETag

Gli esempi riportati di seguito mostrano come recuperare l'ETag di una risorsa FHIR.

L'ETag è incluso nell'intestazione completa della risposta HTTP quando ricevi i contenuti di una risorsa FHIR. L'ETag corrisponde a Meta.versionId nella risorsa FHIR.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo Google Cloud progetto
  • LOCATION: la posizione del set di dati
  • DATASET_ID: il set di dati principale dell'archivio FHIR
  • FHIR_STORE_ID: l'ID dell'archivio FHIR
  • FHIR_RESOURCE_TYPE: il tipo di risorsa FHIR
  • FHIR_RESOURCE_ID: l'ID risorsa FHIR

Per eseguire questa attività, devi disporre delle seguenti autorizzazioni o dei seguenti ruoli Identity and Access Management (IAM):

Autorizzazioni

  • healthcare.fhirResources.get

Ruoli

  • Lettore risorse FHIR Healthcare (roles/healthcare.fhirResourceReader)

Puoi chiedere all'amministratore di concederti questi ruoli di Identity and Access Management. Per istruzioni su come concedere i ruoli, consulta Gestire l'accesso o Controllare l'accesso alle risorse dell'API Cloud Healthcare. Potresti anche riuscire a ottenere le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.
curlPowerShell

Utilizza il metodo fhir.read. Il flag -verbose restituisce le intestazioni HTTP nella risposta, che contengono 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 risposta contiene quanto segue:

< etag: W/"ETAG_VALUE"

Utilizza il metodo fhir.read. Il flag -Headers restituisce le intestazioni HTTP nella risposta, che contengono 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 risposta contiene quanto segue:

ETag                   {W/"ETAG_VALUE"}

Gestire la concorrenza durante l'aggiornamento di una risorsa FHIR

Gli esempi riportati di seguito mostrano come includere un ETag durante l'aggiornamento di una risorsa FHIR.

Gli esempi utilizzano If-Match, che ha il seguente comportamento:

  • Se l'ETag corrisponde all'ETag corrente della risorsa FHIR sul server, l'aggiornamento va a buon fine e il server genera un nuovo ETag per la risorsa aggiornata. In questo modo ti assicuri di aggiornare la versione prevista della risorsa FHIR.

  • Se l'ETag non corrisponde, l'aggiornamento non riesce con un errore 412 Precondition Failed e indica che un altro client ha modificato la risorsa da quando è stato recuperato l'ETag originale. In questo modo si evita la perdita di dati a causa di sovrascritture accidentali.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • ETAG_VALUE: il valore ETag della risorsa FHIR
  • PROJECT_ID: l'ID del tuo Google Cloud progetto
  • LOCATION: la posizione del set di dati
  • DATASET_ID: il set di dati principale dell'archivio FHIR
  • FHIR_STORE_ID: l'ID dell'archivio FHIR
  • FHIR_RESOURCE_TYPE: il tipo di risorsa FHIR
  • FHIR_RESOURCE_ID: l'ID risorsa FHIR

Per eseguire questa attività, devi disporre delle seguenti autorizzazioni o dei seguenti ruoli Identity and Access Management (IAM):

Autorizzazioni

  • healthcare.fhirResources.update

Ruoli

  • Editor risorse FHIR Healthcare (roles/healthcare.fhirResourceEditor)

Puoi chiedere all'amministratore di concederti questi ruoli di Identity and Access Management. Per istruzioni su come concedere i ruoli, consulta Gestire l'accesso o Controllare l'accesso alle risorse dell'API Cloud Healthcare. Potresti anche riuscire a ottenere le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.
curlPowerShell

Utilizza il metodo 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 risposta contiene la risorsa FHIR aggiornata.

Utilizza il metodo 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 risposta contiene la risorsa FHIR aggiornata.

Implementare la memorizzazione nella cache lato client

Puoi utilizzare gli ETag per implementare la memorizzazione nella cache lato client, che accelera il recupero dei dati e contribuisce a un'esperienza utente più fluida e reattiva.

Per recuperare una risorsa FHIR memorizzata nella cache in precedenza, puoi includere l'ETag memorizzato nella cache nell'intestazione If-None-Match, che ha il seguente comportamento:

  • Se gli ETag corrispondono, il server risponde con 304 Not Modified e il client utilizza la copia memorizzata nella cache. In questo modo si risparmia larghezza di banda e si riduce il carico del server.

  • Se gli ETag non corrispondono, il server invia la risorsa FHIR aggiornata e il nuovo ETag, consentendo al client di aggiornare la cache.

Gli esempi riportati di seguito mostrano come recuperare i contenuti di una risorsa FHIR utilizzando un ETag che corrisponda a quello sul server.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • ETAG_VALUE: il valore ETag della risorsa FHIR
  • PROJECT_ID: l'ID del tuo Google Cloud progetto
  • LOCATION: la posizione del set di dati
  • DATASET_ID: il set di dati principale dell'archivio FHIR
  • FHIR_STORE_ID: l'ID dell'archivio FHIR
  • FHIR_RESOURCE_TYPE: il tipo di risorsa FHIR
  • FHIR_RESOURCE_ID: l'ID risorsa FHIR

Per eseguire questa attività, devi disporre delle seguenti autorizzazioni o dei seguenti ruoli Identity and Access Management (IAM):

Autorizzazioni

  • healthcare.fhirResources.get

Ruoli

  • Lettore risorse FHIR Healthcare (roles/healthcare.fhirResourceReader)

Puoi chiedere all'amministratore di concederti questi ruoli di Identity and Access Management. Per istruzioni su come concedere i ruoli, consulta Gestire l'accesso o Controllare l'accesso alle risorse dell'API Cloud Healthcare. Potresti anche riuscire a ottenere le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.
curlPowerShell

Utilizza il metodo fhir.read. Il flag -verbose restituisce le intestazioni HTTP nella risposta, altrimenti non viene restituita alcuna risposta.

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 risposta contiene un codice di stato 304 Not Modified.

Utilizza il metodo fhir.read. Il flag -Headers restituisce le intestazioni HTTP nella risposta, altrimenti non viene restituita alcuna risposta.

$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 risposta contiene un codice di stato 304 Not Modified.