Usare le Dataverse Healthcare API
Le Dataverse Healthcare API contengono endpoint API personalizzati che ti consentono di scambiare dati FHIR (Fast Healthcare Interoperability Resources) con Microsoft Cloud for Healthcare. Questo articolo spiega come utilizzare l'upsert per Dataverse Healthcare e le API di recupero aggregazione e descrive anche alcuni scenari di utilizzo comuni.
Per ulteriori informazioni su queste API, vedi Panoramica delle Dataverse Healthcare API.
Richiamare l'API di aggregazione upsert dall'API Web
Il nome dello schema dell'API di aggregazione upsert è msind_UpsertBundle. Ha due parametri di richiesta e può essere invocata come segue:
POST [Organization URI]/api/data/v9.1/msind_UpsertBundle
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
{
"msind_JSON": "<The FHIR bundle that needs to be inserted (required value).>",
"msind_BundleTag": "<A tag that helps in identifying the bundles when parsing the logs in Dataverse (optional value).>"
}
La risposta contiene lo stato della richiesta completa e lo stato dettagliato di ogni risorsa e dei relativi elementi espansi.
{
"msind_Status": "<A Boolean indicating whether the bundle was successfully processed and all valid resources were upserted into Dataverse.>",
"msind_StatusDetail": "<Provides information about the msind_Status value.>",
"msind_Results": [
{
"msind_fhirresourceid": "<The FHIR ID of the resource in the bundle. If an entry in the result pertains to an expanded record, the value will be the FHIR ID of the root resource.>",
"msind_fhirresourcetype": "<The FHIR resource type of the resource in the bundle. If an entry in the result pertains to an expanded record, the value will be the FHIR resource type of the root resource.>",
"msind_resultingrecordid": "<The Dataverse ID after the record has been upserted. If an entry in the result pertains to an expanded record, the value will be the Dataverse ID of the root resource.>",
"msind_resultingrecordtype": "<The name of the Dataverse entity that the record was upserted into. If an entry in the result pertains to an expanded record, the value will be the name of the Dataverse entity of the expanded record.>",
"msind_requestactionperformed": "<The type of action performed.>",
"msind_requeststatus": "<The status of the request.>",
"msind_requeststatusdetail": "<Detailed information about the msind_requeststatus value.>"
}
]
}
Per informazioni dettagliate sui parametri msind_requestactionperformed e msind_requeststatus insieme ai relativi valori previsti, vedi Tipi di azioni di richiesta eseguite e Tipi di stato di richieste.
Avvisi comuni e scenari di errore
Questa sezione elenca alcuni degli avvisi e degli errori più comuni durante l'utilizzo dell'API di aggregazione upsert.
Mapping di entità disabilitata
Per impostazione predefinita, tutti i mapping di entità distribuiti da Microsoft Cloud for Healthcare sono disabilitati. Quando tenti di inserire dati per una risorsa specifica, devi prima abilitare i mapping di entità correlati. Nel caso in cui l'aggregazione contenga risorse per le quali i mapping di entità non sono abilitati, la risposta visualizza un avviso come segue:
{
"msind_StatusDetail": "The upsert bundle transaction completed without errors. Review the related logs for additional details.",
"msind_Status": true,
"msind_Results": [
{
"msind_requeststatus": 935000001,
"msind_requeststatusdetail": "Warning: Unable to locate entity map for FHIR Resource: Patient. Ensure you have enabled the map for this resource. Once fixed, resubmit the bundle to re-process this record.",
"msind_fhirresourceid": "patient1",
"msind_fhirresourcetype": "Patient"
}
]
}
Il msind_Status è contrassegnato come vero e il msind_requestStatus in msind_Results è contrassegnato come 935000001 (Avviso). Questo comportamento si verifica perché potresti disabilitare intenzionalmente il mapping di entità per evitare di inserire risorse "Paziente", anche se sono nell'aggregazione.
Mapping non valido
I mapping attributi guidano le trasformazioni tra Dataverse e FHIR. Uno degli elementi chiave del mapping attributi alla base di questa trasformazione è il mapping degli elementi FHIR, che prevede un JPath. Se il JPath non è corretto, puoi aspettarti la seguente risposta:
{
"msind_StatusDetail": "Warning: There were records that encountered errors. Inspect the individual records error details.",
"msind_Status": false,
"msind_Results": [
{
"msind_requeststatus": 935000002,
"msind_requeststatusdetail": "Error: An error occurred while trying to transform the FHIR resource to the Dataverse record. Target table: contact. Exception detail: Unexpected end of content while loading JObject. Path 'c', line 1, position 112.
Table: contact
Attribute Map Id: f8ce8297-b4fe-ea11-a815-000d3a37def4
Column: mobilephone
Action: 440670000
FHIR Map: {'s': '$.telecom[?(@use=='mobile')].value', 'c': {'p': 'telecom[0]', 'a': [{'use': 'mobile'}, {'value': '%'}]}",
"msind_fhirresourceid": "patient1",
"msind_fhirresourcetype": "Patient"
}
}
]
}
Il msind_Status è contrassegnato come falso e il msind_requestStatus in msind_Results è contrassegnato come 935000002 (Errore). Le informazioni in msind_requeststatusdetail identificano il mapping errato.
L'integrità referenziale è persa
In ogni risorsa in un bundle FHIR, molti elementi sono riferimenti ad altre risorse. L'API di aggregazione upsert tenta di risolvere questi riferimenti quando esegue l'upsert dei record in Dataverse. Se l'API non riesce a risolvere nessuno di questi riferimenti, non esegue l'upsert del record e garantisce che l'integrità referenziale non venga persa. In tale scenario, la risposta è la seguente:
{
"msind_StatusDetail": "Warning: There were records that encountered errors. Inspect the individual records error details.",
"msind_Status": false,
"msind_Results": [
{
"msind_fhirresourceid": "careteam2",
"msind_fhirresourcetype": "CareTeam",
"msind_resultingrecordid": "",
"msind_resultingrecordtype": "",
"msind_requeststatus": 935000002,
"msind_requeststatusdetail": "Error: An error occurred while trying to upsert the record. Exception Details: A record with the specified key values does not exist in msemr_encounter entity (-2147088239)."
}
]
}
Il msind_Status è contrassegnato come falso e il msind_requestStatus in msind_Results è contrassegnato come 935000002 (Errore). Le informazioni in msind_requeststatusdetail identificano quale riferimento non è stato risolto.
Richiamare l'API di recupero aggregazione dall'API Web
L'API di recupero aggregazione (msind_RetrieveBundle) ha un parametro di richiesta e può essere invocata come segue:
POST [Organization URI]/api/data/v9.1/msind_RetrieveBundle
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
{
"msind_FHIRQuery": "<The FHIR query to execute (required value).>"
}
Per l'elenco delle query FHIR supportate, vedi Query FHIR supportate.
La risposta contiene lo stato della richiesta completa e lo stato dettagliato di ogni risorsa e dei relativi elementi espansi.
{
"msind_Status": "<A Boolean indicating whether the action was successfully processed.>",
"msind_StatusDetail": "<Provides detailed information about the msind_Status value.>",
"msind_JSON": "<FHIR JSON representation.>"
}
Avvisi comuni e scenari di errore
Questa sezione elenca alcuni degli avvisi e degli errori più comuni durante l'utilizzo dell'API di recupero aggregazione.
ID risorsa FHIR non valido
Attualmente, il parametro di richiesta di query FHIR prevede un ID FHIR. Se Dataverse non ha un record con l'ID FHIR, la risposta è la seguente:
{
"msind_StatusDetail": {
"Message": "The request failed due to the following error.",
"Error": [
{
"Message": "Resource type Patient with id <ResourceId> couldn't be found."
}
]
},
"msind_JSON": {
"resourceType": "OperationOutcome",
"id": "7ee485e2-3797-4ee3-9916-4fc4dd7a6ecd",
"meta": {
"lastUpdated": "2022-05-06T15:21:23.8078182+05:30"
},
"issue": [
{
"severity": "error",
"code": "not-found",
"diagnostics": "Resource type Patient with id <ResourceId> couldn't be found."
}
]
},
"msind_Status": false
}
Il mapping attributi è disabilitato
Se la query FHIR contiene una ricerca di elementi, l'API di recupero aggregazione utilizza i mapping di attributi abilitati per costruire un JSON FHIR. Nel caso in cui uno dei mapping attributo per gli elementi nella query sia disabilitato, la risposta è la seguente:
{
"msind_StatusDetail": {
"Message": "Request processed successfully with the following warning/information.",
"Warning": [
{
"Message": "Attribute map is disabled for attribute name: msemr_asserter."
}
]
},
"msind_JSON": "<FHIR JSON>",
"msind_Status": true
}
Eseguire il writeback su un endpoint alternativo
Puoi configurare un endpoint alternativo a cui il servizio di writeback può inviare un'aggregazione FHIR contenente la risorsa FHIR creata o aggiornata. Per informazioni su come configurare questo endpoint alternativo, vedi Impostazioni dell'endpoint in uscita alternativo.
L'aggregazione FHIR contiene una singola risorsa (per tutti gli aggiornamenti) che l'endpoint alternativo può elaborare. Questa elaborazione può includere l'aggiornamento del messaggio FHIR in uscita o l'instradamento dello stesso a un altro endpoint. Quando l'endpoint ricevente completa l'elaborazione, il servizio di writeback si aspetta un'aggregazione di ritorno contenente la risposta del servizio FHIR remoto. Questo risposta è necessaria per aggiornare il record Dataverse con il nuovo ID versione FHIR e gli ultimi valori modificati.
Se l'endpoint alternativo pubblica su un servizio FHIR, ad esempio il servizio FHIR Servizi per i dati sanitari di Azure, dovrebbe essere sufficiente restituire la risposta del servizio FHIR. In caso contrario, lo sviluppatore dell'endpoint alternativo deve creare questa risposta dell'aggregazione. Questa aggregazione deve essere del tipo batch-response e deve contenere i dettagli aggiornati delle risorse FHIR.
Di seguito è riportato un esempio di un'aggregazione contenente la risorsa Paziente FHIR in fase di aggiornamento:
{
"resourceType": "Bundle",
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "f1fdbe3a-e266-4028-aa35-9c440daeeda4",
"meta": {
"versionId": "1",
"lastUpdated": "2024-07-18T15:03:42.826+00:00",
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
]
},
"identifier": [ {
"type": {
"coding": [ {
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MR",
"display": "Medical Record Number"
}
],
"text": "Medical Record Number"
},
"system": "http://hospital.smarthealthit.org",
"value": "f1fdbe3a-e266-4028-aa35-9c440daeeda4"
}
],
"name": [ {
"use": "official",
"family": "Ambler",
"given": [ "Joseph" ],
"prefix": [ "Mr." ]
}
],
"telecom": [ {
"system": "phone",
"value": "555-795-6145",
"use": "home"
}
],
"gender": "male",
"birthDate": "1972-02-05",
"deceasedDateTime": "1989-11-04T07:41:10+00:00",
"address": [ {
"line": [ "115 Reynolds Throughway Unit 51" ],
"city": "Woburn",
"state": "MA",
"country": "US"
}
],
"maritalStatus": {
"coding": [ {
"system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus",
"code": "M",
"display": "M"
}
],
"text": "M"
},
"multipleBirthInteger": 2,
"communication": [
{
"language": {
"coding": [ {
"system": "urn:ietf:bcp:47",
"code": "en-US",
"display": "English"
}
],
"text": "English"
}
}
]
},
"request": {
"method": "PUT",
"url": "Patient?_id=f1fdbe3a-e266-4028-aa35-9c440daeeda4"
}
}
]
}
Di seguito è riportato un esempio di risposta restituito per il messaggio precedente dopo la pubblicazione nekl servizio FHIR Servizi per i dati sanitari di Azure:
{
"resourceType": "Bundle",
"type": "batch-response",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "f1fdbe3a-e266-4028-aa35-9c440daeeda4",
"meta": {
"versionId": "2",
"lastUpdated": "2024-07-18T15:08:14.343+00:00",
"profile": [
"http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
]
},
"identifier": [ {
"type": {
"coding": [ {
"system": "http://terminology.hl7.org/CodeSystem/v2-0203",
"code": "MR",
"display": "Medical Record Number"
}
],
"text": "Medical Record Number"
},
"system": "http://hospital.smarthealthit.org",
"value": "f1fdbe3a-e266-4028-aa35-9c440daeeda4"
}
],
"name": [ {
"use": "official",
"family": "Ambler",
"given": [ "Joseph" ],
"prefix": [ "Mr." ]
}
],
"telecom": [ {
"system": "phone",
"value": "555-795-6145",
"use": "home"
}
],
"gender": "male",
"birthDate": "1972-02-05",
"deceasedDateTime": "1989-11-04T07:41:10+00:00",
"address": [ {
"line": [ "115 Reynolds Throughway Unit 51" ],
"city": "Woburn",
"state": "MA",
"country": "US"
}
],
"maritalStatus": {
"coding": [ {
"system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus",
"code": "M",
"display": "M"
}
],
"text": "M"
},
"multipleBirthInteger": 2,
"communication": [
{
"language": {
"coding": [ {
"system": "urn:ietf:bcp:47",
"code": "en-US",
"display": "English"
}
],
"text": "English"
}
}
]
},
"response": {
"status": "200",
"etag": "W/\"2\"",
"lastModified": "2024-07-18T15:08:14+00:00"
}
}
]
}
Le due differenze fondamentali sono i campi versionId e lastUpdated. Questi campi sono obbligatori per aggiornare il record Dataverse al completamento.
Viene inviato un secondo messaggio in uscita contenente i dettagli del record Provenienza FHIR. Questa risorsa tiene traccia dell'attività del precedente aggiornamento del paziente. Similmente ad altri aggiornamenti, il servizio di writeback lo pubblica come aggregazione e prevede un'aggregazione di tipo batch-response per completare l'operazione.
Di seguito un esempio del post sulla provenienza e della risposta per i messaggi di writeback precedenti. In questo esempio, il servizio di writeback pubblica un nuovo record di provenienza e aggiunge i metadati corrispondenti alla risposta.
{
"resourceType": "Bundle",
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Provenance",
"agent": {
"who": {
"reference": "Device/CDSSyncAgent"
}
},
"target": {
"reference": "Patient/f1fdbe3a-e266-4028-aa35-9c440daeeda4",
"identifier": {
"system": "Microsoft Cloud for Healthcare",
"value": "{\"DataSource\":\"Microsoft Healthcare Writeback Data Source\",\"FHIRVersion\":\"2\",\"CDSETag\":\"2c27d21e-8ce5-4c0b-9f04-eecc6414b57e\",\"CDSReference\":\"contact/6ec787f4-1645-ef11-8409-000d3a8e806f\",\"SyncStatus\":\"Updated\",\"DateRecorded\":\"2024-07-18T15:08:24.1936902Z\",\"CDSContextUserId\":\"8e6fab4b-85e5-eb11-bacb-000d3a181fef\"}"
}
},
"recorded": "2024-07-18T15:08:24.1936902Z",
"activity": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-DataOperation",
"code": "UPDATE"
}
]
},
"entity": [
{
"role": "derivation",
"what": {
"reference": "FHIRCDSSyncAgent"
}
}
]
},
"request": {
"method": "POST",
"url": "Provenance"
}
}
]
}
Valore della risposta:
{
"resourceType": "Bundle",
"type": "batch-response",
"entry": [
{
"resource": {
"resourceType": "Provenance",
"id": "287371be-0f0d-4295-ba26-c2f1900e88c4",
"meta": {
"versionId": "1",
"lastUpdated": "2024-07-18T15:08:25.906+00:00"
},
"target": [
{
"reference": "Patient/f1fdbe3a-e266-4028-aa35-9c440daeeda4",
"identifier": {
"system": "Microsoft Cloud for Healthcare",
"value": "{\"DataSource\":\"Microsoft Healthcare Writeback Data Source\",\"FHIRVersion\":\"2\",\"CDSETag\":\"2c27d21e-8ce5-4c0b-9f04-eecc6414b57e\",\"CDSReference\":\"contact/6ec787f4-1645-ef11-8409-000d3a8e806f\",\"SyncStatus\":\"Updated\",\"DateRecorded\":\"2024-07-18T15:08:24.1936902Z\",\"CDSContextUserId\":\"8e6fab4b-85e5-eb11-bacb-000d3a181fef\"}"
}
}
],
"recorded": "2024-07-18T15:08:24.1936902+00:00",
"activity": {
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-DataOperation",
"code": "UPDATE"
}
]
},
"agent": [
{
"who": {
"reference": "Device/CDSSyncAgent"
}
}
],
"entity": [
{
"role": "derivation",
"what": {
"reference": "FHIRCDSSyncAgent"
}
}
]
},
"response": {
"status": "201",
"location": "https://server.fhir.azurehealthcareapis.com/Provenance/287371be-0f0d-4295-ba26-c2f1900e88c4/_history/1",
"etag": "W/\"1\"",
"lastModified": "2024-07-18T15:08:25+00:00"
}
}
]
}