Previeni 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 delle applicazioni 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 attuale di una risorsa FHIR sul server, simile a un numero di versione. Ogni volta che una risorsa FHIR viene creata o modificata, viene generato un nuovo valore ETag.

Puoi usare gli ETag per garantire l'integrità dei dati e ottimizzare le prestazioni situazioni seguenti:

  • 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. Ciò aiuta a prevenire a un client dalla sovrascrittura accidentale di modifiche apportate da un altro client, chiamato conflitto tra scrittura e scrittura o il "problema di aggiornamento perso".

  • Invio di richieste condizionali: gli ETag consentono ai client di inviare in modo condizionale delle richieste solo quando sono soddisfatte determinate condizioni. Questo ottimizza i dati recupero e riduce il traffico di rete non necessario. Ad esempio, puoi inviare richieste condizionali utilizzando le seguenti intestazioni HTTP:

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

Gli ETag FHIR utilizzano una convalida debole, il che significa che potrebbero non essere identiche tra istanze del server diverse, continuano a tenere traccia in modo efficace delle modifiche alle risorse.

Ottieni 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 progetto Google Cloud
  • LOCATION: la posizione del set di dati
  • DATASET_ID: il set di dati principale dell'archivio FHIR
  • FHIR_STORE_ID: l'ID del datastore FHIR
  • FHIR_RESOURCE_TYPE: il tipo di risorsa FHIR
  • FHIR_RESOURCE_ID: l'ID risorsa FHIR

curl

Utilizza il metodo fhir.read. Il flag -verbose restituisce il valore 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"

PowerShell

Utilizza il metodo fhir.read. Il flag -Headers restituisce le intestazioni HTTP nella risposta, che contengono il carattere 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 che 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 dovuta a sovrascritture accidentali.

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

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

curl

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.

PowerShell

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.

Implementa la memorizzazione nella cache lato client

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

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

  • Se gli ETag corrispondono, il server risponde con 304 Not Modified e del client utilizza la propria 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 corrispondente 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 progetto Google Cloud
  • LOCATION: la posizione del set di dati
  • DATASET_ID: il set di dati principale dell'archivio FHIR
  • FHIR_STORE_ID: l'ID del datastore FHIR
  • FHIR_RESOURCE_TYPE: il tipo di risorsa FHIR
  • FHIR_RESOURCE_ID: l'ID risorsa FHIR

curl

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.

PowerShell

Utilizza la 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.