Panoramica delle Dataverse Healthcare API

  • Articolo

Le Dataverse Healthcare API sono un'offerta di prodotti completa di Microsoft Cloud for Healthcare che ti consente di interagire con Dataverse utilizzando lo standard FHIR (Fast Health Interoperability Resources). Le API usano i mapping di Data Integration Toolkit per trasformare le aggregazioni tra FHIR e Dataverse.

Queste API sono implementate come API Dataverse progettate per accettare aggregazioni FHIR come parametri di input. Le API gestiscono il mapping e la trasformazione di singole risorse FHIR e pubblicano i record risultanti in Dataverse. Puoi eseguire l'autenticazione in questi endpoint e proteggerli come faresti con lo API Dataverse standard.

Nota

Per saperne di più sulle API Dataverse standard, vai a Creare e utilizzare API personalizzate.

Le Dataverse Healthcare API possono essere utilizzate per:

  • Pubblicare dati basati su FHIR direttamente in Dataverse.
  • Sincronizzare Dataverse con servizi FHIR esterni come i Servizi per i dati sanitari di Azure.

Queste API, combinate con App per la logica di Azure, costituiscono la sostituzione dello strumento Agente di sincronizzazione FHIR, ormai in disuso, con Microsoft Cloud for Healthcare

Per utilizzare le Dataverse Healthcare API non è necessario utilizzare l'app per la logica fornita. Puoi creare la tua app per la logica, utilizzare Power Automate o sviluppare il tuo codice personalizzato. Non è inoltre necessario sincronizzare i dati con un servizio FHIR esterno. Puoi eseguire la sincronizzazione con gli endpoint FHIR di Servizi per i dati sanitari di Azure o pubblicare i dati direttamente nelle API. Le Dataverse Healthcare API sono pensate come componente flessibile che può essere usato per progettare soluzioni per il settore sanitario in Microsoft Cloud for Healthcare.

Sezione Sommario
Dataverse Healthcare API Riassume le informazioni sulle API attualmente disponibili come parte di Dataverse Healthcare API.
Panoramica del writeback per le Dataverse Healthcare API Descrive il processo di writeback per le Dataverse Healthcare API.
Configurare le Dataverse Healthcare API Contiene i passaggi per la configurazione delle Dataverse Healthcare API.
Configurare un'app per la logica di Azure con un trigger HTTP Contiene una guida dettagliata per creare la tua app per la logica in grado di inserire dati FHIR in Dataverse Healthcare API, Servizi per i dati sanitari di Azure o entrambi.
Utilizzare Modello pipeline dati assistenza sanitaria per distribuire app per la logica di Azure Fornisce una guida dettagliata per l'uso di un modello per distribuire un gruppo di app per la logica che orchestrano l'inserimento di aggregazioni FHIR nelle Dataverse Healthcare API e nei Servizi per i dati sanitari di Azure.
Usare le Dataverse Healthcare API Riassume come richiamare e utilizzare Dataverse Healthcare API, con esempi e scenari di utilizzo comuni.
Esaminare i registri delle Dataverse Healthcare API Spiega come esaminare i registri delle transazioni per le attività delle Dataverse Healthcare API.

Dataverse Healthcare API

Le seguenti API sono attualmente disponibili come parte delle Dataverse Healthcare API:

  • API di aggregazione upsert
  • API di recupero aggregazione

API di aggregazione upsert

L'API di aggregazione upsert abilita l'invio di aggregazioni FHIR a Dataverse e li trasforma in record Dataverse.

L'API attualmente supporta le seguenti funzionalità:

  • L'inserimento di aggregazioni di risorse sia singole che miste. Una singola aggregazione di risorse contiene un solo tipo di risorsa, mentre un'aggregazione mista contiene diversi tipi di risorsa.
  • L'inserimento di tipi di aggregazione batch. Per maggiori informazioni, vedi Tipi di bundle supportati.
  • Inserimento di aggregazioni con riferimenti URN (Uniform Resource Name).
  • Integrità referenziale delle aggregazioni FHIR: una risorsa verrebbe creata in Dataverse solo se tutti i relativi riferimenti fossero risolti.
  • La creazione di record espansi per ogni risorsa FHIR in Dataverse.
  • La creazione di concetti codificabili quando mancano in Dataverse.
  • Risposte dettagliate e localizzate.

L'API (msind_UpsertBundle) ha due parametri di richiesta definiti come segue:

Parametro di richiesta Descrzione
msind_JSON L'aggregazione FHIR che deve essere inserita (valore obbligatorio).
msind_BundleTag Un tag che aiuta a identificare le aggregazioni durante l'analisi dei registri in Dataverse (valore facoltativo).

Per informazioni su come richiamare l'API ed esaminare alcuni scenari di utilizzo comuni, vedi Richiamare l'API di aggregazione upsert dall'API Web.

Dopo la chiamata dell'API, puoi aspettarti i seguenti elementi nella risposta JSON:

Parametro di risposta Descrizione
msind_Status Un valore booleano che indica se l'aggregazione è stata elaborata correttamente e se tutte le risorse valide sono state sottoposte a upsert in Dataverse.
msind_StatusDetail Fornisce informazioni dettagliate sul valore msind_Status.
msind_fhirresourceid L'ID FHIR della risorsa nell'aggregazione. Se una voce nel risultato riguarda un record espanso, il valore è l'ID FHIR della risorsa radice.
msind_fhirresourcetype Il tipo di risorsa FHIR della risorsa nell'aggregazione. Se una voce nel risultato riguarda un record espanso, il valore è il tipo di risorsa FHIR della risorsa radice.
msind_resultingrecordid L'ID Dataverse dopo il record viene sottoposto a upsert. Se una voce nel risultato riguarda un record espanso, il valore è l'ID Dataverse della risorsa radice.
msind_resultingrecordtype Il nome dell'entità Dataverse in cui è stato eseguito l'upsert del record. Se una voce nel risultato riguarda un record espanso, il valore è il nome dell'entità Dataverse del record espanso.
msind_requestactionperformed Il tipo di azione eseguita. Per visualizzare i valori previsti e la relativa descrizione, vedi Tipi di azioni di richiesta eseguite.
msind_requeststatus Stato della richiesta. Per visualizzare i valori previsti e la relativa descrizione, vedi Tipi di stato di richieste.
msind_requeststatusdetail Informazioni dettagliate sul valore msind_requeststatus.

Tipi di azioni di richiesta eseguite

Nella tabella seguente sono elencati i valori previsti per il parametro di risposta msind_requestactionperformed:

valore Descrzione
935000000 Viene creata una risorsa radice.
935000001 Una risorsa radice già esistente in Dataverse viene aggiornata.
935000002 L'azione è stata eseguita su un'entità espansa.

Tipi di stato della richiesta

Nella tabella seguente sono elencati i valori previsti per il parametro di risposta msind_requeststatus:

valore Descrizione
935000000 L'upsert delle risorse è stato completato.
935000001 L'upsert delle risorse ha restituito un avviso.
935000002 L'upsert delle risorse ha restituito un errore.

Tipi di aggregazioni supportate

L'API di aggregazione upsert supporta attualmente aggregazioni di tipo batch e batch-response. Per inserire le aggregazioni di tipi non supportati, devi prima modificare il tipo di aggregazione che stai inviando. Se desideri modificare il tipo di aggregazione in batch prima di eseguire la registrazione nelle API, puoi usare l'azione di sostituzione dell'app per la logica incorporata per modificare il tipo di aggregazione. Questo passaggio elabora l'aggregazione come gruppo di azioni indipendenti.

Quando modifichi il tipo di aggregazione in batch, è importante considerare l'effetto che potrebbe avere sui singoli scenari. La modifica di un'aggregazione transazionale in batch potrebbe avere effetti indesiderati sui dati che stai tentando di importare in Dataverse. Per ulteriori informazioni sulle regole per l'utilizzo di queste aggregazioni, vai a HL7 FHIR - Usare le aggregazioni.

Se invii un aggregazione di tipo batch-response, la Dataverse Healthcare API registra le risorse di tipo OperationOutcome con valore di gravità error nei registri. Questa azione ti consente di pubblicare l'aggregazione in un server FHIR e reindirizzare la risposta dal server FHIR alla Dataverse Healthcare API. Di conseguenza, puoi acquisire tutti gli errori in un'unica posizione.

API di recupero aggregazione

L'API di recupero aggregazione ti consente di eseguire query Dataverse per una singola risorsa FHIR utilizzando l'ID FHIR. L'API trasforma la richiesta e utilizza i mapping di Data Integration Toolkit per rispondere con una risorsa standardizzata FHIR.

L'API attualmente supporta le seguenti funzionalità:

  • Esecuzione di query per un singolo record utilizzando l'ID FHIR.
  • Registrazione dettagliata e localizzata.

L'API (msind_RetrieveBundle) ha un parametro di richiesta definito come segue:

Parametro di richiesta Descrzione
msind_FHIRQuery La query FHIR da eseguire (valore obbligatorio).

Query FHIR supportate

Query Descrzione
FHIRResource/FHIRID La query restituisce l'intera risorsa insieme alle entità espanse.
FHIRResource/FHIRId?_elements=element_1,element_2,...,element_n La query restituisce gli elementi specificati nella query insieme a tutti gli elementi contrassegnati come obbligatorio FHIR nel mapping attributi.

Per ulteriori informazioni, vai a Ricerca dell'elemento FHIR.

Per informazioni su come richiamare l'API ed esaminare alcuni scenari di utilizzo comuni, vedi Richiamare l'API di recupero aggregazione dall'API Web.

Dopo la chiamata, puoi vedere una risposta contenente lo stato della richiesta completa e lo stato dettagliato di ogni risorsa e dei relativi elementi espansi.

Parametro di risposta Descrizione
msind_Status Valore booleano che indica se l'azione è stata elaborata correttamente.
msind_StatusDetail Fornisce informazioni dettagliate sul valore msind_Status.
msind_JSON Rappresentazione di JSON FHIR.