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 per i dati sanitari 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 per i dati sanitari 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à Esportazione bulk consente l'esportazione dei 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 la configurazione delle impostazioni di esportazione e la creazione di un 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 $export comando per esportare i dati dal servizio. I dati vengono archiviati nell'account di archiviazione specificato durante la configurazione dell'esportazione. Per informazioni su come richiamare il $export comando nel server FHIR, leggere la documentazione nella specifica $export HL7 FHIR.
Processi bloccati in uno stato non valido
In alcune situazioni, un processo potrebbe rimanere bloccato in uno stato non valido. Questo problema può verificarsi se le autorizzazioni dell'account di archiviazione non sono state configurate correttamente. Un modo per convalidare un'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 i 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>>
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 seguono 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 le limitazioni seguenti:
- Gli utenti non possono sfruttare gli spazi dei nomi gerarchici. Non esiste un modo per impostare come destinazione un'esportazione in una sottodirectory specifica all'interno di un contenitore. È possibile scegliere come destinazione solo un contenitore specifico (in cui viene creata una nuova cartella per ogni esportazione).
- Una volta completata l'esportazione, non viene mai esportato di nuovo in tale cartella. Le esportazioni successive nello stesso contenitore si troveranno all'interno di una cartella appena creata.
Impostazioni e parametri
Intestazioni
Esistono due parametri di intestazione obbligatori che devono essere impostati per $export i processi. 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. |
| _poiché | 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 vengono esportati in una cartella in tale contenitore. Se il contenitore non è specificato, i dati vengono esportati in un nuovo contenitore. |
| _dissodare | 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 eliminate, l'esportazione garantisce una visualizzazione snapshot vera. 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 le risorse della cronologia (non più recenti). 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. Nota: 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 $export che potrebbe comportare 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 o in una posizione diversa 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. Nota: 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 Storage Gen2.
Nel menu a sinistra selezionare Rete.
Selezionare Abilitato da reti virtuali e 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.
Area di 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 West US 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 il $export comando . Successivamente, per informazioni su come esportare i dati non identificati, vedere
Nota
FHIR® è un marchio registrato di HL7 ed è usato con l'autorizzazione di HL7.