Esportare i dati FHIR nell'API di Azure per FHIR
Importante
L'API di Azure per FHIR verrà ritirata il 30 settembre 2026. Seguire le strategie di migrazione per passare al servizio FHIR di Servizi dati di integrità di Azure entro tale data. A causa del ritiro dell'API di Azure per FHIR, le nuove distribuzioni non saranno consentite a partire dal 1° aprile 2025. Il servizio FHIR di Servizi dati di Integrità di Azure è la versione evoluta dell'API di Azure per FHIR che consente ai clienti di gestire i servizi FHIR, DICOM e MedTech con integrazioni in altri servizi di Azure.
La funzionalità "Bulk Export" (Esportazione in blocco) consente di esportare i dati dal server FHIR in base alla specifica FHIR.
Prima di usare $export, assicurarsi che l'API di Azure per FHIR sia configurata per usarla. Per configurare le impostazioni di esportazione e la creazione dell'account di archiviazione di Azure, vedere la pagina configurare i dati di esportazione.
Nota
Solo gli account di archiviazione nella stessa sottoscrizione di quella per l'API di Azure per FHIR possono essere registrati come destinazione per le operazioni di $export.
Uso del comando $export
Dopo aver configurato l'API di Azure per FHIR per l'esportazione, è possibile usare il comando $export per esportare i dati dal servizio. I dati verranno archiviati nell'account di archiviazione specificato durante la configurazione dell'esportazione. Per informazioni su come richiamare $export comando nel server FHIR, leggere la documentazione sulla specifica $export HL7 FHIR.
Processi bloccati in uno stato non valido
In alcune situazioni, è possibile che un processo sia bloccato in uno stato non valido. Ciò può verificarsi soprattutto se le autorizzazioni dell'account di archiviazione non sono state configurate correttamente. Un modo per convalidare l'esportazione consiste nel controllare l'account di archiviazione per verificare se sono presenti i file del contenitore corrispondente ( ndjsonovvero ) . Se non sono presenti e non sono in esecuzione altri processi di esportazione, è possibile che il processo corrente sia bloccato in uno stato non valido. È consigliabile annullare il processo di esportazione inviando una richiesta di annullamento e ritentare la coda del processo. Il tempo di esecuzione predefinito per un'esportazione in stato non valido è di 10 minuti prima che venga arrestato e spostato in un nuovo processo o ritentare l'esportazione.
L'API di Azure per FHIR supporta $export ai livelli seguenti:
- Sistema:
GET https://<<FHIR service base URL>>/$export>> - Paziente:
GET https://<<FHIR service base URL>>/Patient/$export>> - Gruppo di pazienti* - L'API di Azure per FHIR esporta tutte le risorse correlate, ma non esporta le caratteristiche del gruppo:
GET https://<<FHIR service base URL>>/Group/[ID]/$export>>
Con l'esportazione, i dati vengono esportati in più file ognuno contenente risorse di un solo tipo. Il numero di risorse in un singolo file sarà limitato. Il numero massimo di risorse è basato sulle prestazioni del sistema. Attualmente è impostato su 5.000, ma può cambiare. Il risultato è che è possibile ottenere più file per un tipo di risorsa. I nomi dei file seguiranno il formato 'resourceName-number-number.ndjson'. L'ordine dei file non è garantito che corrisponda ad alcun ordinamento delle risorse nel database.
Nota
Patient/$export e possono esportare Group/[ID]/$export risorse duplicate se la risorsa si trova in un raggruppamento di più risorse o si trova in più gruppi.
Inoltre, il controllo dello stato di esportazione tramite l'URL restituito dall'intestazione della posizione durante l'accodamento è supportato insieme all'annullamento del processo di esportazione effettivo.
Esportazione dei dati FHIR in ADLS Gen2
Attualmente è supportato $export per gli account di archiviazione abilitati per ADLS Gen2, con la limitazione seguente:
- L'utente non può sfruttare i vantaggi degli spazi dei nomi gerarchici, ma non esiste un modo per impostare come destinazione l'esportazione in una sottodirectory specifica all'interno del contenitore. È possibile specificare come destinazione un contenitore specifico (in cui viene creata una nuova cartella per ogni esportazione).
- Al termine di un'esportazione, non verrà mai esportata alcuna cartella, poiché le esportazioni successive nello stesso contenitore si troveranno all'interno di una nuova cartella creata.
Impostazioni e parametri
Intestazioni
Esistono due parametri di intestazione obbligatori che devono essere impostati per i processi di $export. I valori sono definiti dalla specifica $export corrente.
- Accept - application/fhir+json
- Preferenza : respond-async
Parametri di query
L'API di Azure per FHIR supporta i parametri di query seguenti. Tutti questi parametri sono facoltativi:
| Query parameter (Parametro di query) | Definito dalla specifica FHIR? | Descrizione |
|---|---|---|
| _outputFormat | Sì | Attualmente supporta tre valori da allineare alla specifica FHIR: application/fhir+ndjson, application/ndjson o ndjson. Tutti i processi di esportazione restituiscono ndjson e il valore passato non ha alcun effetto sul comportamento del codice. |
| _Dal | Sì | Consente di esportare solo le risorse modificate dall'ora specificata |
| _type | Sì | Consente di specificare quali tipi di risorse verranno inclusi. Ad esempio, _type=Patient restituirà solo le risorse dei pazienti |
| _typefilter | Sì | Per richiedere filtri più granulari, è possibile usare _typefilter insieme al parametro _type. Il valore del parametro _typeFilter è un elenco delimitato da virgole di query FHIR che limitano ulteriormente i risultati |
| _Contenitore | No | Specifica il contenitore all'interno dell'account di archiviazione configurato in cui devono essere esportati i dati. Se si specifica un contenitore, i dati verranno esportati in una cartella in tale contenitore. Se il contenitore non è specificato, i dati verranno esportati in un nuovo contenitore. |
| _Fino | No | Consente di esportare solo le risorse modificate fino al momento specificato. Questo parametro è applicabile solo all'esportazione a livello di sistema. In questo caso, se le versioni cronologiche non sono state disabilitate o rimosse, l'esportazione garantisce la visualizzazione snapshot vera o, in altre parole, consente il viaggio nel tempo. |
| includeAssociatedData | No | Consente di esportare la cronologia e le risorse eliminate soft. Questo filtro non funziona con il parametro di query '_typeFilter'. Includere il valore come "_history" per esportare la cronologia o le risorse non più recenti con versione. Includere il valore come "_deleted" per esportare le risorse eliminate soft. |
| _isparallel | No | Il parametro di query "_isparallel" può essere aggiunto all'operazione di esportazione per migliorarne la velocità effettiva. Il valore deve essere impostato su true per abilitare la parallelizzazione. È importante notare che l'uso di questo parametro può comportare un aumento del consumo delle unità richiesta nel corso della durata dell'esportazione. |
Nota
Si è verificato un problema noto con l'operazione di $export che potrebbe causare esportazioni incomplete con esito positivo dello stato. Il problema si verifica quando è stato usato il flag is_parallel. I processi di esportazione eseguiti con _isparallel parametro di query a partire dal 13 febbraio 2024 sono interessati da questo problema.
Esportazione sicura in Archiviazione di Azure
L'API di Azure per FHIR supporta un'operazione di esportazione sicura. Scegliere una delle due opzioni seguenti:
Consentire all'API di Azure per FHIR di accedere all'account di archiviazione di Azure come servizio attendibile Microsoft.
Consentire a indirizzi IP specifici associati all'API di Azure per FHIR di accedere all'account di archiviazione di Azure. Questa opzione offre due configurazioni diverse a seconda che l'account di archiviazione si trova nella stessa posizione di o si trova in una posizione diversa da quella dell'API di Azure per FHIR.
Consentire l'API di Azure per FHIR come servizio attendibile Microsoft
Selezionare un account di archiviazione nel portale di Azure e quindi selezionare il pannello Rete. Selezionare Reti selezionate nella scheda Firewall e reti virtuali.
Importante
Assicurarsi di aver concesso l'autorizzazione di accesso all'account di archiviazione per l'API di Azure per FHIR usando la relativa identità gestita. Per altre informazioni, vedere Configurare l'impostazione di esportazione e configurare l'account di archiviazione.
Nella sezione Eccezioni selezionare la casella Consenti alle servizi Microsoft attendibili di accedere a questo account di archiviazione e salvare l'impostazione.
È ora possibile esportare i dati FHIR nell'account di archiviazione in modo sicuro. Si noti che l'account di archiviazione si trova nelle reti selezionate e non è accessibile pubblicamente. Per accedere ai file, è possibile abilitare e usare endpoint privati per l'account di archiviazione oppure abilitare tutte le reti per l'account di archiviazione per un breve periodo di tempo.
Importante
L'interfaccia utente verrà aggiornata in un secondo momento per consentire di selezionare il tipo di risorsa per l'API di Azure per FHIR e un'istanza del servizio specifica.
Consentire a indirizzi IP specifici di accedere all'account di archiviazione di Azure da altre aree di Azure
Nella portale di Azure passare all'account Azure Data Lake Archiviazione Gen2.
Nel menu a sinistra selezionare Rete.
Selezionare Abilitato nelle reti virtuali e dagli indirizzi IP selezionati.
Nella sezione Firewall specificare l'indirizzo IP nella casella Intervallo di indirizzi. Aggiungere gli intervalli IP per consentire l'accesso da Internet o dalle reti locali. È possibile trovare l'indirizzo IP nella tabella seguente per l'area di Azure in cui viene effettuato il provisioning del servizio FHIR.
Regione Azure Indirizzo IP pubblico Australia orientale 20.53.44.80 Canada centrale 20.48.192.84 Stati Uniti centrali 52.182.208.31 Stati Uniti orientali 20.62.128.148 Stati Uniti orientali 2 20.49.102.228 Stati Uniti orientali 2 (EUAP) 20.39.26.254 Germania settentrionale 51.116.51.33 Germania centro-occidentale 51.116.146.216 Giappone orientale 20.191.160.26 Corea centrale 20.41.69.51 Stati Uniti centro-settentrionali 20.49.114.188 Europa settentrionale 52.146.131.52 Sudafrica settentrionale 102.133.220.197 Stati Uniti centro-meridionali 13.73.254.220 Asia sud-orientale 23.98.108.42 Svizzera settentrionale 51.107.60.95 Regno Unito meridionale 51.104.30.170 Regno Unito occidentale 51.137.164.94 Stati Uniti centro-occidentali 52.150.156.44 Europa occidentale 20.61.98.66 Stati Uniti occidentali 2 40.64.135.77
Consentire a indirizzi IP specifici di accedere all'account di archiviazione di Azure nella stessa area
Il processo di configurazione per gli indirizzi IP nella stessa area è simile alla procedura precedente, ad eccezione del fatto che si usa un intervallo di indirizzi IP specifico nel formato CIDR (Classless Inter-Domain Routing), ovvero 100.64.0.0/10. È necessario specificare l'intervallo di indirizzi IP (da 100.64.0.0 a 100.127.255.255) perché un indirizzo IP per il servizio FHIR viene allocato ogni volta che si effettua una richiesta di operazione.
Nota
È possibile usare un indirizzo IP privato compreso nell'intervallo di 10.0.2.0/24, ma non esiste alcuna garanzia che l'operazione abbia esito positivo in questo caso. È possibile riprovare se la richiesta di operazione ha esito negativo, ma fino a quando non si usa un indirizzo IP compreso nell'intervallo di 100.64.0.0/10, la richiesta non avrà esito positivo.
Questo comportamento di rete per gli intervalli di indirizzi IP è progettato. L'alternativa consiste nel configurare l'account di archiviazione in un'area diversa.
Passaggi successivi
In questo articolo si è appreso come esportare le risorse FHIR usando $export comando. Successivamente, per informazioni su come esportare i dati non identificati, vedere
FHIR® è un marchio registrato di HL7 e viene usato con l'autorizzazione di HL7.