Conversione dei dati in FHIR per l'API di Azure per FHIR

Articolo
06/25/2024

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.

L'endpoint personalizzato $convert-data nel servizio FHIR® è destinato alla conversione dei dati da diversi tipi di dati a FHIR. Usa il motore modello Liquid e i modelli del progetto Convertitore FHIR come modelli predefiniti. È possibile personalizzare questi modelli di conversione in base alle esigenze.

Attualmente, l'endpoint personalizzato $convert-data supporta quattro tipi di conversione dati:

Formato dati di origine	Formato dati di destinazione
C-CDA	FHIR
HL7v2	FHIR
JSON	FHIR
FHIR STU3	FHIR R4

Nota

L'endpoint $convert-data può essere usato come componente all'interno di una pipeline di estrazione, trasformazione e caricamento (ETL) per la conversione di dati sanitari non elaborati da formati legacy a formato FHIR. Tuttavia, non è una pipeline ETL in sé. È consigliabile usare un motore ETL, ad esempio App per la logica o Azure Data Factory, per un flusso di lavoro completo nella preparazione di dati FHIR da rendere persistenti nel server FHIR. Il flusso di lavoro può includere: lettura e inserimento di dati, convalida di dati, esecuzione di chiamate API $convert-data, pre/post-elaborazione di dati, arricchimento di dati e deduplicazione di dati.

Usare l'endpoint $convert-data

L'operazione $convert-data è integrata nel servizio FHIR ed è eseguita come parte del servizio. Dopo aver abilitato $convert-data nel server, è possibile effettuare chiamate API al server per convertire i dati in FHIR usando https://<<FHIR service base URL>>/$convert-data.

Risorsa parametro

$convert-data acquisisce una risorsa Parametro nel corpo della richiesta, come descritto nella tabella seguente. Nel corpo della richiesta di chiamata API, è necessario includere i parametri seguenti:

Nome parametro	Descrizione	Valori accettati
inputData	Dati da convertire.	Per `Hl7v2`: stringa Per `Ccda`: XML Per `Json`: JSON Per `FHIR STU3`: JSON
inputDataType	Tipo di dati di input.	`HL7v2`, `Ccda`, `Json`, `Fhir`
templateCollectionReference	Riferimento a una raccolta di modelli immagine OCI in Registro Azure Container (ACR). Si tratta dell'immagine contenente modelli Liquid da usare per la conversione. Può trattarsi di un riferimento ai modelli predefiniti o a un'immagine modello personalizzata registrata all'interno del servizio FHIR. Di seguito sono fornite informazioni sulla personalizzazione dei modelli, sull'hosting di tali modelli in Registro Azure Container e sulla registrazione al servizio FHIR.	Per modelli predefiniti/campione: Modelli HL7v2 : `microsofthealth/fhirconverter:default` `microsofthealth/hl7v2templates:default` Modelli C-CDA : `microsofthealth/ccdatemplates:default` Modelli JSON : `microsofthealth/jsontemplates:default` Modelli FHIR STU3 : `microsofthealth/stu3tor4templates:default` Per modelli personalizzati: <RegistryServer>/<imageName>@<imageDigest>, <RegistryServer>/<imageName>:<imageTag>
rootTemplate	Modello radice da usare durante la trasformazione dei dati.	Per HL7v2: "ADT_A01", "ADT_A02", "ADT_A03", "ADT_A04", "ADT_A05", "ADT_A08", "ADT_A11", "ADT_A13", "ADT_A14", "ADT_A15", "ADT_A16", "ADT_A25", "ADT_A26", "ADT_A27", "ADT_A28", "ADT_A29", "ADT_A31", "ADT_A47", "ADT_A60", "OML_O21", "ORU_R01", "ORM_O01", "VXU_V04", "SIU_S12", "SIU_S13", "SIU_S14", "SIU_S15", "SIU_S16", "SIU_S17", "SIU_S26", "MDM_T01", "MDM_T02" Per C-CDA: "CCD", "ConsultationNote", "DischargeSummary", "HistoryandPhysical", "OperativeNote", "ProcedureNote", "ProgressNote", "ReferralNote", "TransferSummary" Per JSON: "ExamplePatient", "Stu3ChargeItem" FHIR STU3": Risorsa STU3, ad esempio Nome, "Paziente", "Osservazione", "Organizzazione".

Nota

I modelli da FHIR STU3 a R4 sono modelli Liquid "diff" che forniscono mapping di differenze di campo solo tra una risorsa STU3 e la relativa risorsa equivalente nello standard FHIR R4. Alcune delle risorse STU3 vengono rinominate o rimosse da R4. Vedere Differenze e limitazioni delle risorse per la conversione da STU3 a R4.

Nota

I modelli JSON sono modelli campione da usare, non modelli "predefiniti" conformi a qualsiasi tipo di messaggio JSON predefinito. A differenza dei messaggi HL7v2 o dei documenti C-CDA, JSON non ha tipi di messaggi standardizzati. Invece di modelli predefiniti, vengono forniti alcuni modelli campione che possono essere usati come guida iniziale per modelli personalizzati.

Avviso

I modelli predefiniti vengono rilasciati con Licenza MIT e non sono supportati dal supporto tecnico Microsoft.

I modelli predefiniti vengono forniti solo per aiutare l’utente a iniziare. Potrebbero essere aggiornati all’aggiornamento di versioni dell'API di Azure per FHIR. È necessario verificare il comportamento di conversione e ospitare la propria copia di modelli in un Registro Azure Container, nonché registrare tali modelli nell'API di Azure per FHIR da usare nelle chiamate API. Questa operazione è necessaria per ottenere un comportamento coerente di conversione dei dati tra versioni diverse dell'API di Azure per FHIR.

Richiesta di esempio

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputData",
            "valueString": "MSH|^~\\&|SIMHOSP|SFAC|RAPP|RFAC|20200508131015||ADT^A01|517|T|2.3|||AL||44|ASCII\nEVN|A01|20200508131015|||C005^Whittingham^Sylvia^^^Dr^^^DRNBR^D^^^ORGDR|\nPID|1|3735064194^^^SIMULATOR MRN^MRN|3735064194^^^SIMULATOR MRN^MRN~2021051528^^^NHSNBR^NHSNMBR||Kinmonth^Joanna^Chelsea^^Ms^^D||19870624000000|F|||89 Transaction House^Handmaiden Street^Wembley^^FV75 4GJ^GBR^HOME||020 3614 5541^PRN|||||||||C^White - Other^^^||||||||\nPD1|||FAMILY PRACTICE^^12345|\nPV1|1|I|OtherWard^MainRoom^Bed 183^Simulated Hospital^^BED^Main Building^4|28b|||C005^Whittingham^Sylvia^^^Dr^^^DRNBR^D^^^ORGDR|||CAR|||||||||16094728916771313876^^^^visitid||||||||||||||||||||||ARRIVED|||20200508131015||"
        },
        {
            "name": "inputDataType",
            "valueString": "Hl7v2"
        },
        {
            "name": "templateCollectionReference",
            "valueString": "microsofthealth/fhirconverter:default"
        },
        {
            "name": "rootTemplate",
            "valueString": "ADT_A01"
        }
    ]
}

Risposta di esempio

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:9d697ec3-48c3-3e17-db6a-29a1765e22c6",
      "resource": {
        "resourceType": "Patient",
        "id": "9d697ec3-48c3-3e17-db6a-29a1765e22c6",
        ...
        ...
      "request": {
        "method": "PUT",
        "url": "Location/50becdb5-ff56-56c6-40a1-6d554dca80f0"
      }
    }
  ]
}

Personalizzare i modelli

È possibile usare l'estensione Convertitore FHIR per Visual Studio Code per personalizzare i modelli in base alle proprie esigenze. L'estensione offre un'esperienza di modifica interattiva e semplifica il download di modelli e dati campione pubblicati da Microsoft. Per altri dettagli, fare riferimento alla documentazione nell'estensione.

Nota

L'estensione Convertitore FHIR per Visual Studio Code è disponibile per i modelli Liquid HL7v2, C-CDA e JSON. I modelli Liquid da FHIR STU3 a R4 non sono attualmente supportati.

Ospitare e usare modelli

È consigliabile ospitare la propria copia dei modelli in Registro Azure Container. Sono necessari quattro passaggi per ospitare la propria copia dei modelli e usarli nell'operazione $convert-data:

Eseguire il push dei modelli nel Registro Azure Container.
Abilitare l'identità gestita nell'istanza dell'API di Azure per FHIR.
Fornire l'accesso al Registro Azure Container all'identità gestita dell’API di Azure per FHIR.
Registrare i server del Registro Azure Container nell'API di Azure per FHIR.
Facoltativamente, configurare il firewall del Registro Azure Container per l'accesso sicuro.

Eseguire il push di modelli al Registro Azure Container

Dopo aver creato un'istanza di Registro Azure Container, è possibile usare il comando Convertitore FHIR: Esegui il push di templates nell’estensione Convertitore FHIR per eseguire il push dei modelli personalizzati al Registro Azure Container. In alternativa, è possibile usare lo strumento Gestione modelli dell'interfaccia della riga di comando.

Abilitare l'identità gestita nell'API di Azure per FHIR

Passare all'istanza del servizio API di Azure per FHIR nel portale di Azure e quindi selezionare il pannello Identità. Modificare lo stato a Sì per abilitare l'identità gestita nell'API di Azure per FHIR.

Fornire l'accesso al Registro Azure Container all'API di Azure per FHIR

Passare al pannello Controllo di accesso (IAM).
Selezionare Aggiungi e quindi Aggiungi assegnazione di ruolo per aprire la pagina Aggiungi assegnazione di ruolo.
Assegnare il ruolo AcrPull.

Per altre informazioni sull'assegnazione di ruoli nel portale di Azure, vedere Ruoli di Azure integrati.

Registrare i server del Registro Azure Container nell'API di Azure per FHIR

È possibile registrare il server ACR usando il portale di Azure o l'interfaccia della riga di comando.

Registrazione dell’ARC tramite il portale di Azure

Passare al pannello Artefatti in Trasformazione dati nell'istanza dell'API di Azure per FHIR. Viene visualizzato l'elenco dei server ACR attualmente registrati. Selezionare Aggiungi e quindi selezionare il proprio server del registro dal menu a discesa. È necessario selezionare Salva per rendere effettiva la registrazione. L'applicazione della modifica e il riavvio dell'istanza potrebbero richiedere alcuni minuti.

Registrazione del server ACR tramite l'interfaccia della riga di comando

È possibile registrare fino a 20 server ACR nell'API di Azure per FHIR.

Se necessario, installare l'interfaccia della riga di comando di Servizi per i dati sanitari di Azure da Azure PowerShell:

az extension add -n healthcareapis

Registrare i server ACR nell'API di Azure per FHIR seguendo questi esempi:

Registrare un singolo server ACR

az healthcareapis acr add --login-servers "fhiracr2021.azurecr.io" --resource-group fhir-test --resource-name fhirtest2021

Registrare più server ACR

az healthcareapis acr add --login-servers "fhiracr2021.azurecr.io fhiracr2020.azurecr.io" --resource-group fhir-test --resource-name fhirtest2021

Configurare il firewall del Registro Azure Container

Selezionare Reti per l'account di archiviazione di Azure dal portale.

Screenshot del registro contenitori.

Selezionare Reti selezionate.

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.

Nella tabella seguente, si troverà l'indirizzo IP per l'area di Azure in cui viene effettuato il provisioning del servizio API di Azure per FHIR.

Area di Azure	Indirizzo IP pubblico
Australia orientale	20.53.47.210
Brasile meridionale	191.238.72.227
Canada centrale	20.48.197.161
India centrale	20.192.47.66
Stati Uniti orientali	20.62.134.242, 20.62.134.244, 20.62.134.245
Stati Uniti orientali 2	20.62.60.115, 20.62.60.116, 20.62.60.117
Francia centrale	51.138.211.19
Germania settentrionale	51.116.60.240
Germania centro-occidentale	20.52.88.224
Giappone orientale	20.191.167.146
Giappone occidentale	20.189.228.225
Corea centrale	20.194.75.193
Stati Uniti centro-settentrionali	52.162.111.130, 20.51.0.209
Europa settentrionale	52.146.137.179
Qatar centrale	20.21.36.225
Sudafrica settentrionale	102.133.220.199
Stati Uniti centro-meridionali	20.65.134.83
Asia sud-orientale	20.195.67.208
Svezia centrale	51.12.28.100
Svizzera settentrionale	51.107.247.97
Regno Unito meridionale	51.143.213.211
Regno Unito occidentale	51.140.210.86
Stati Uniti centro-occidentali	13.71.199.119
Europa occidentale	20.61.103.243, 20.61.103.244
West US 2	20.51.13.80, 20.51.13.84, 20.51.13.85
Stati Uniti occidentali 3	20.150.245.165

Nota

I passaggi precedenti sono simili ai passaggi di configurazione illustrati nel documento Come esportare dati FHIR. Per altre informazioni, vedere Esportazione sicura ad Archiviazione di Azure

Verificare

Effettuare una chiamata all'API $convert-data specificando il proprio riferimento al modello nel parametro templateCollectionReference.

<RegistryServer>/<imageName>@<imageDigest>

Passaggi successivi

In questo articolo è stata illustrata la conversione dei dati per l'API di Azure per FHIR. Per altre informazioni su progetti GitHub correlati per l'API di Azure per FHIR, vedere

Progetti GitHub correlati per l'API di Azure per FHIR

Nota

FHIR® è un marchio registrato di HL7 ed è usato con l'autorizzazione di HL7.

Condividi tramite

Conversione dei dati in FHIR per l'API di Azure per FHIR

Usare l'endpoint $convert-data

Risorsa parametro

Richiesta di esempio

Risposta di esempio

Personalizzare i modelli

Ospitare e usare modelli

Eseguire il push di modelli al Registro Azure Container

Abilitare l'identità gestita nell'API di Azure per FHIR

Fornire l'accesso al Registro Azure Container all'API di Azure per FHIR

Registrare i server del Registro Azure Container nell'API di Azure per FHIR

Registrazione dell’ARC tramite il portale di Azure

Registrazione del server ACR tramite l'interfaccia della riga di comando

Registrare un singolo server ACR

Registrare più server ACR

Configurare il firewall del Registro Azure Container

Verificare

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive