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

Articolo
03/10/2023

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

Attualmente l'endpoint $convert-data personalizzato supporta four i tipi di conversione dei dati:

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

Nota

$convert-data l'endpoint può essere usato come componente all'interno di una pipeline ETL per la conversione di dati sanitari non elaborati da formati legacy in 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 per preparare i dati FHIR da rendere persistenti nel server FHIR. Il flusso di lavoro può includere: lettura e inserimento dei dati, convalida dei dati, esecuzione di chiamate API $convert-dati, pre/post-elaborazione dei dati, arricchimento dei dati e deduplicazione dei dati.

Usare l'endpoint $convert-data

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

Risorsa parametro

$convert-data accetta una risorsa Parameter 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 di immagine OCI in Registro Azure Container (Registro Azure Container). Si tratta dell'immagine contenente i 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. Vedere di seguito per informazioni sulla personalizzazione dei modelli, sull'hosting di tali modelli nel Registro Azure Container e sulla registrazione nel servizio FHIR.	Per i modelli predefiniti/di esempio : 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 i 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_A27", "ADT_A27", "ADT_A27"", "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_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": NOME risorsa STU3, ad esempio "Paziente", "Osservazione", "Organizzazione".

Nota

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

Nota

I modelli JSON sono modelli di esempio da usare, non modelli "predefiniti" che rispettano qualsiasi tipo di messaggio JSON predefinito. JSON non ha tipi di messaggio standardizzati, a differenza dei messaggi HL7v2 o dei documenti C-CDA. Pertanto, invece dei modelli predefiniti, vengono forniti alcuni modelli di esempio che è possibile usare come guida iniziale per i modelli personalizzati.

Avviso

I modelli predefiniti vengono rilasciati con licenza MIT e non sono supportati da supporto tecnico Microsoft.

I modelli predefiniti vengono forniti solo per facilitare l'avvio rapido. Possono essere aggiornati quando si aggiornano le versioni dell'API di Azure per FHIR. È quindi necessario verificare il comportamento di conversione e ospitare la propria copia dei modelli in un Registro Azure Container, registrare tali modelli nell'API di Azure per FHIR e usarli nelle chiamate API per avere un comportamento coerente di conversione dei dati tra le diverse versioni 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 FHIR Converter per Visual Studio Code per personalizzare i modelli in base alle esigenze. L'estensione offre un'esperienza di modifica interattiva e semplifica il download di modelli e dati di esempio pubblicati da Microsoft. Per altri dettagli, vedere la documentazione nell'estensione.

Nota

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

Ospitare e usare modelli

È consigliabile ospitare la propria copia dei modelli in Registro Azure Container. Esistono quattro passaggi necessari per ospitare la propria copia di 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 del Registro Azure Container all'API di Azure per L'identità gestita 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 dei modelli in Registro Azure Container

Dopo aver creato un'istanza di Registro Azure Container, è possibile usare il comando FHIR Converter: Push Templatesnell'estensione FHIR Converter per eseguire il push dei modelli personalizzati nel Registro Azure Container. In alternativa, è possibile usare lo strumento dell'interfaccia della riga di comando di Gestione modelli a questo scopo.

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 su Sì per abilitare l'identità gestita nell'API di Azure per FHIR.

Fornire l'accesso del 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 dei ruoli nella portale di Azure, vedere Ruoli predefiniti di Azure.

Registrare i server ACR nell'API di Azure per FHIR

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

Registrazione del server ACR tramite portale di Azure

Passare al pannello Artefatti in Trasformazione dati nell'API di Azure per l'istanza di FHIR. Verrà visualizzato l'elenco dei server ACR attualmente registrati. Selezionare Aggiungi e quindi selezionare il server del Registro di sistema dal menu a discesa. Sarà necessario selezionare Salva per l'effetto della registrazione. Potrebbe richiedere alcuni minuti per applicare la modifica e riavviare l'istanza.

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

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

Installare l'interfaccia della riga di comando di Azure Health Data Services da Azure PowerShell se necessario:

az extension add -n healthcareapis

Registrare i server acr nell'API di Azure per FHIR seguendo gli esempi seguenti:

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 Rete dell'account di archiviazione di Azure dal portale.

Immagine dello schermo del Registro contenitori.

Selezionare Reti selezionate.

Nella sezione Firewall specificare l'indirizzo IP nella casella Intervallo indirizzi. Aggiungere 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 eseguito 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 descritti nel documento Come esportare i dati FHIR. Per altre informazioni, vedere Esportazione sicura in Archiviazione di Azure

Verifica

Eseguire una chiamata all'API $convert-dati specificando il 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 sui progetti GitHub correlati per l'API di Azure per FHIR, vedere

Progetti GitHub correlati per l'API di Azure per FHIR

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

Share via

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 dei modelli in Registro Azure Container

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

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

Registrare i server ACR nell'API di Azure per FHIR

Registrazione del server ACR tramite 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

Verifica

Passaggi successivi

Risorse aggiuntive