Eseguire aggiornamenti in blocco sui dati FHIR

L'operazione $bulk-update consente di aggiornare più risorse FHIR in massa utilizzando l'elaborazione asincrona. Supporta:

• Aggiornamenti a livello di sistema in tutti i tipi di risorse
• Aggiornamenti limitati a singoli tipi di risorse
• Operazioni su più risorse in una singola richiesta

L'operazione $bulk-update utilizza i tipi di patch supportati elencati nella sezione seguente per eseguire aggiornamenti.

• replace: Sostituire un valore esistente. Utilizza la semantica della patch replace FHIR, che garantisce che gli aggiornamenti rimangano idempotenti.
• upsert: Aggiungi un valore se non esiste, o sostituiscilo se esiste.

Prerequisiti per l'operazione di aggiornamento in blocco

Ruoli richiesti

Per eseguire un aggiornamento in massa, assegnare all'applicazione o all'utente uno dei seguenti ruoli:

• Operatore dati in massa FHIR: consente l'accesso alle operazioni in massa nel servizio FHIR.
• Contributore Dati FHIR: Fornisce accesso amministrativo al servizio FHIR.

Intestazioni obbligatorie

Richiesta

Usa i parametri di ricerca FHIR nella richiesta. L'operazione di aggiornamento in blocco supporta filtri di ricerca standard, come address:contains=Meadow o Patient.birthdate=1987-02-20. Puoi anche usare _include, _revinclude, e _not-referenced per estendere i criteri di ricerca. Usare _meta-history per configurare il comportamento della gestione delle versioni per gli aggiornamenti dei soli metadati.

Esempi di richiesta

1. Aggiornamento bulk a livello di sistema: quando esegui l'operazione a livello di sistema, puoi aggiornare le risorse FHIR su tutti i tipi di risorse sul server FHIR.

   PATCH https://{FHIR-SERVICE-HOST}/$bulk-update
   

2. Aggiornamenti limitati al singolo tipo di risorsa: Quando esegui l'operazione per i singoli tipi di risorsa, puoi aggiornare le risorse FHIR che corrispondono al tipo di risorsa specificato nell'URL.

   PATCH https://{FHIR-SERVICE-HOST}/[ResourceType]/$bulk-update
   

3. Esecuzione di query sulle risorse da aggiornare in base ai parametri di ricerca. In questo esempio, si usa _include e _revinclude. Aggiorna tutte le risorse per i pazienti aggiornate l'ultima volta prima del 18-12-2021 e tutte le risorse che vi fanno riferimento:

   PATCH {FHIR-SERVICE-HOST}/Patient/$bulk-update?_lastUpdated=lt2021-12-18&_revinclude=*
   

   PATCH {FHIR-SERVICE-HOST}/DiagnosticReport/$bulk-update?_lastUpdated=lt2021-12-12&_include=DiagnosticReport:based-on:ServiceRequest&_include:iterate=ServiceRequest:encounter
   

4. Aggiornamenti dei soli metadati con il parametro di query _meta-history: quando i criteri di controllo delle versioni del server FHIR sono impostati su versioned o version-update, il parametro _meta-history controlla se le modifiche ai soli metadati di una risorsa creano una nuova versione cronologica della risorsa. Per impostazione predefinita, qualsiasi modifica apportata a una risorsa, incluse le modifiche solo ai metadati, crea una nuova versione e salva la versione precedente come record cronologico. Quando imposti il _meta-history parametro su falso, le modifiche basate solo sui metadati non creano una nuova versione, e la versione precedente non viene salvata come record storico. Usa questa opzione quando i metadati cambiano frequentemente e vuoi evitare molte versioni della cronologia che differiscono solo nei metadati. Per altre informazioni ed esempi, vedere Gestione dei criteri di controllo delle versioni e della cronologia di FHIR.

   PATCH https://{FHIR-SERVICE-HOST}/$bulk-update?_meta-history=false
   

Quando usi l'aggiornamento in blocco con parametri di ricerca FHIR, considera di usare prima la stessa query in una ricerca FHIR, così da poter verificare i dati che intendi aggiornare.

Corpo della richiesta di esempio:

{ 
  "resourceType": "Parameters", 
  "parameter": [ 
    { 
      "name": "operation", 
      "part": [ 
        { 
          "name": "type", 
          "valueCode": "upsert" 
        }, 

        { 
          "name": "path", 
          "valueString": "Resource.meta" 
        }, 

        { 
          "name": "name", 
          "valueString": "security" 
        }, 

        { 
          "name": "value", 
          "valueCoding": { 
            "system": "http://example.org/security-system", 
            "code": "SECURITY_TAG_CODE", 
            "display": "Updated Security Tag Display" 
          } 
        } 
      ] 
    } 
  ] 
}

Punti chiave

• Ogni percorso della patch deve iniziare con la ResourceType radice ( ad esempio , Patient.meta.tag) per distinguere chiaramente tra gli aggiornamenti del meta-livello e degli elementi. Puoi correggere le proprietà comuni usando la radice Resource. Puoi effettuare un aggiornamento in massa a livello di sistema, per un singolo tipo di risorsa o per più tipi di risorse. Se devi aggiornare campi diversi per tipi di risorse differenti, specifica le mappature campo-valore in operazioni separate.
• Se la tua ricerca restituisce più tipi di risorse, la patch viene applicata solo alle risorse il cui tipo corrisponde al ResourceType prefisso nel percorso della patch. L'operazione ignora altri tipi.
• SearchParameter e StructureDefinition sono considerati fuori ambito per gli aggiornamenti in blocco. Eseguire un lavoro di aggiornamento in blocco per tipo di risorsa su SearchParameter o StructureDefinition comporta anche un errore di 400 Richieste Negative. Se una query di aggiornamento in blocco a livello di sistema o di tipo risorsa restituisce risorse di tipo SearchParameter o StructureDefinition, l'operazione ignora queste risorse. Solo altri tipi di risorse vengono aggiornati.

Risposta

Quando invii un'operazione di aggiornamento in massa, il server restituisce una risposta nel seguente formato. La risposta include un'intestazione Content-Location che punta all'endpoint del sondaggio.

Content-Location: https://{hostname}/_operations/bulk-update/{job-id}

Risultati dell'endpoint di polling

Le richieste all'endpoint di polling restituiscono uno di quattro esiti, a seconda dello stato del processo di aggiornamento in blocco. La risposta FHIR include l'esito all'interno di OperationOutcome.

La risposta a un'operazione di aggiornamento in blocco include quattro componenti chiave:

1. ResourceUpdatedCount: mostra il numero di risorse aggiornate correttamente, raggruppate per tipo di risorsa.
2. ResourceIgnoredCount: indica il numero di risorse ignorate durante l'aggiornamento bulk in base al tipo di risorsa. L'operazione ignora le risorse se non c'è una richiesta di patch corrispondente per il loro tipo, o se sono tipi esclusi come SearchParameter o StructureDefinition.
3. ResourcepatchFailedCount: Mostra il numero di risorse in cui l'operazione di patch è fallita, per tipo di risorsa. Ad esempio, se provi a sostituire un valore che non esiste, l'operazione di patch fallisce e viene conteggiata qui. Il processo è considerato un "errore leggero" se alcune risorse hanno esito negativo, ma altre hanno esito positivo. La Issues sezione fornisce un messaggio generale che raccomanda di utilizzare l'operazione FHIR PATCH su singole risorse per ottenere informazioni dettagliate sugli errori.
4. Problemi: fornisce informazioni dettagliate su eventuali errori di processo o motivi per gli aggiornamenti non riusciti.

Corpo della risposta di esempio:

{ 

  "resourceType": "Parameters", 

  "parameter": [ 
    { 
      "name": "ResourceUpdatedCount", 
      "part": [ 
        { "name": "Practitioner", "valueInteger64": 10 }, 
        { "name": "Specimen", "valueInteger64": 7 }, 
        { "name": "Device", "valueInteger64": 3 } 
      ] 
    }, 

    { 
      "name": "ResourceIgnoredCount", 
      "part": [ 
        { "name": "StructureDefinition", "valueInteger64": 9 }, 
        { "name": "SearchParameter", "valueInteger64": 8 } 
      ] 
    } 
  ] 
}

Gestione degli errori di risposta

Annullare un processo di aggiornamento in blocco

Inviare una richiesta DELETE all'endpoint di polling del processo come indicato di seguito.

DELETE https://{FHIR-SERVICE-HOST}/_operations/bulk-update/{job-id}

Registri di audit

Quando la registrazione dell'audit è abilitata, puoi consultare i log di audit da MicrosoftHealthcareApisAuditLogs:

• Filtrare in base a ResourceId.
• Cerca le voci: Processo avviato, Processo completato correttamente ed errori di applicazione delle patch.

Per ulteriori informazioni, consulta i registri diagnostici del servizio FHIR.

Domande frequenti

Perché i conteggi aggiornati delle risorse non corrispondono alle aspettative?

• Meno risorse: Un altro processo ha modificato le risorse prima che questo processo venisse eseguito.
• Più risorse: Un nuovo processo di importazione ha inserito risorse dopo che è stato avviato l'aggiornamento massivo.

Quali sono i passaggi per la risoluzione se l'attività di aggiornamento massivo sembra essere bloccata? Per verificare se un lavoro di aggiornamento in blocco è bloccato, esegui una ricerca FHIR con gli stessi parametri del lavoro di aggiornamento in massa. Aggiungi la condizione operativa appropriata nella query e imposta _summary=count. Se il numero di risorse sta diminuendo, il lavoro funziona correttamente. È anche possibile annullare il processo di aggiornamento in blocco e riprovare.

Qual è l'impatto sulle chiamate API REST quando viene eseguito simultaneamente un processo di operazione di aggiornamento bulk? Quando si esegue un'operazione di aggiornamento in blocco, è possibile che venga visualizzata una maggiore latenza nelle chiamate simultanee al servizio. Per evitare un aumento di latenza, annulla il lavoro di aggiornamento in massa e poi rieseguilo durante un periodo di traffico più basso.

È possibile ripristinare le modifiche? Usa con attenzione la capacità di aggiornamento in massa. Ad esempio, se il versioning è abilitato, prendi le versioni storiche e utilizzala PUT per ripristinarle, oppure ripristina da un backup. I dati vengono conservati per 7–30 giorni a seconda della configurazione.

Cos'è ResourcePatchFailedCount? Questo conteggio monitora le risorse che hanno fallito durante l'operazione PATCH . Le cause potrebbero includere:

• Sostituzione di un elemento inesistente
• Tentativo di aggiornare un campo non modificabile

Controlla il registro di audit o invia singolarmente una richiesta PATCH per i dettagli sugli errori.

Passo successivo