Evitare i conflitti delle risorse FHIR utilizzando gli ETag

Questa pagina spiega come utilizzare i tag di 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 consentendo 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, 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 i tag ETag per garantire l'integrità dei dati e ottimizzare le prestazioni nelle seguenti situazioni:

• Per garantire controllo della contemporaneità ottimistico: quando includi un ETag in una richiesta di modifica di una risorsa FHIR, l'API Cloud Healthcare verifica se l'ETag corrisponde all'ultima versione della risorsa FHIR sul server. In questo modo si evita che un client sovrascriva accidentalmente le modifiche apportate da un altro client, un problema anche chiamato conflitto di scrittura o "problema di aggiornamento perso".

• Invio di richieste condizionali: i tag ETag consentono ai client di inviare richieste condizionali solo quando sono soddisfatte condizioni specifiche. In questo modo, il recupero dei dati viene ottimizzato e il traffico di rete non necessario viene ridotto. Ad esempio, puoi inviare richieste condizionali utilizzando le seguenti intestazioni HTTP:

  • If-Match: la richiesta ha esito positivo solo se l'ETag fornito corrisponde all'ETag corrente sul server. In questo modo ti assicuri di aggiornare la versione prevista della risorsa FHIR.
  • If-None-Match: La richiesta ha esito positivo 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 attuale, riducendo la necessità di recuperare ogni volta la risorsa completa dal server. Viene comunemente utilizzato per la memorizzazione nella cache efficiente.

Gli ETag FHIR utilizzano la convalida debole, il che significa che potrebbero non essere identici in diverse istanze del server, ma tengono comunque traccia in modo efficace delle modifiche alle risorse.

Recuperare un ETag

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

L'ETag è inclusa nell'intestazione della risposta HTTP completa quando recuperi 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 padre dell'archivio FHIR
• FHIR_STORE_ID: l'ID datastore FHIR
• FHIR_RESOURCE_TYPE: il tipo di risorsa FHIR
• FHIR_RESOURCE_ID: l'ID risorsa FHIR

Autorizzazioni richieste per questa attività

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 Identity and Access Management. Per istruzioni sulla concessione dei ruoli, consulta Gestire l'accesso o Controllare l'accesso alle risorse dell'API Cloud Healthcare. Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Nota: se hai creato un progetto Google Cloud per questa guida, in qualità di autore del progetto ti viene automaticamente concesso il ruolo IAM Proprietario (roles/owner), che dispone delle autorizzazioni. Non è necessario concedere altri ruoli IAM.

curl

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"

PowerShell

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 viene eseguito correttamente e il server genera una nuova 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 e viene visualizzato un errore 412 Precondition Failed, che indica che un altro client ha modificato la risorsa dopo il recupero dell'ETag originale. In questo modo si evita la perdita di dati dovuta a 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 padre dell'archivio FHIR
• FHIR_STORE_ID: l'ID datastore FHIR
• FHIR_RESOURCE_TYPE: il tipo di risorsa FHIR
• FHIR_RESOURCE_ID: l'ID risorsa FHIR

Autorizzazioni richieste per questa attività

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 Identity and Access Management. Per istruzioni sulla concessione dei ruoli, consulta Gestire l'accesso o Controllare l'accesso alle risorse dell'API Cloud Healthcare. Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Nota: se hai creato un progetto Google Cloud per questa guida, in qualità di autore del progetto ti viene automaticamente concesso il ruolo IAM Proprietario (roles/owner), che dispone delle autorizzazioni. Non è necessario concedere altri ruoli IAM.

curl

Utilizza il metodo fhir.update.

Importante: il campione include un flag -d @request.json. Prima di eseguire l'esempio, devi disporre di un file request.json valido nella directory corrente. Per esempi di cosa includere in un file request.json, vedi Aggiornamento di una risorsa 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 risposta contiene la risorsa FHIR aggiornata.

PowerShell

Utilizza il metodo fhir.update.

Importante: il campione include un flag -Infile request.json. Prima di eseguire l'esempio, devi disporre di un file request.json valido nella directory corrente. Per esempi di cosa includere in un file request.json, vedi Aggiornamento di una risorsa 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 risposta contiene la risorsa FHIR aggiornata.

Implementare la memorizzazione nella cache lato client

Puoi utilizzare i tag 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 memorizzata 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 relativo nuovo ETag, consentendo al client di aggiornare la cache.

Gli esempi riportati di seguito mostrano come recuperare una risorsa FHIR utilizzando un ETag che corrisponde all'ETag 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 padre dell'archivio FHIR
• FHIR_STORE_ID: l'ID datastore FHIR
• FHIR_RESOURCE_TYPE: il tipo di risorsa FHIR
• FHIR_RESOURCE_ID: l'ID risorsa FHIR

Autorizzazioni richieste per questa attività

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 Identity and Access Management. Per istruzioni sulla concessione dei ruoli, consulta Gestire l'accesso o Controllare l'accesso alle risorse dell'API Cloud Healthcare. Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Nota: se hai creato un progetto Google Cloud per questa guida, in qualità di autore del progetto ti viene automaticamente concesso il ruolo IAM Proprietario (roles/owner), che dispone delle autorizzazioni. Non è necessario concedere altri ruoli IAM.

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