Använd Dataverse Healthcare APIs
Dataverse Healthcare APIs innehåller specialbyggda API-slutpunkter som låter dig utbyta FHIR-data (Fast Healthcare Interoperability Resources) med Microsoft Cloud for Healthcare. Den här artikeln innehåller information om hur du använder Dataverse Healthcare upsert för och hämta paket-API:er och täcker även några vanliga användningsscenarier.
Mer information om dessa API:er finns i Översikt över API Dataverse Healthcare APIs.
Anropa upsert-paketet API från webb-API
API-schemanamnet för upsert-paketet är msind_UpsertBundle. Den har två begäransparametrar och kan anropas på följande sätt:
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).>"
}
Svaret innehåller statusen för den fullständiga begäran som innehåller status för den fullständiga förfrågan och detaljerad status för varje resurs och dess expanderade element.
{
"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.>"
}
]
}
Detaljerad information om och parametrar msind_requestactionperformed och msind_requeststatus tillsammans med de förväntade värdena finns i Typer av begäransåtgärder som utförs och Status för förfrågningar.
Vanliga varningar och felscenarier
Det här avsnittet innehåller några vanliga varningar och fel när du använder API för upsert-paketet.
Entitetsmappning är inaktiverad
Som standard levereras alla entitetskartor av Microsoft Cloud for Healthcare är inaktiverad. När du försöker mata in data för en specifik resurs måste de relaterade entitetsmappningarna först aktiveras. Om paketet innehåller resurser som entitetsmappningarna inte är aktiverade för visas svar en varning enligt följande:
{
"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"
}
]
}
msind_Status ska markeras som true och msind_requestStatus inom msind_Results markeras som 935000001 (Varning). Detta beror på att du avsiktligt kan inaktivera entitetsmappningen för att undvika att hämta "patientresurser", även om de finns i paketet.
Ogiltigt mappning
Attributmappningar driver omvandlingarna mellan Dataverse och FHIR. Ett av de viktigaste attributkartelementen som driver denna transformation är FHIR-elementkartan, som förväntar sig en JPath. Om JPath-programmet är felaktigt kan du förvänta dig följande svar:
{
"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"
}
}
]
}
msind_Status ska markeras som true och msind_requestStatus inom msind_Results markeras som 935000002 (fel). Informationen i msind_requeststatusdetail hjälper dig identifiera fel mappning.
Refererande integritet förloras
I varje resurs i ett FHIR-paket är många element referenser till andra resurser. Upsert paket-API försöker lösa dessa referenser när den uppdaterar eller infogar poster i Dataverse. Om API inte lyckas lösa någon av dessa referenser misslyckas posten och garanterar att den refererande integriteten inte går förlorad. I ett sådant scenario blir svaret följande:
{
"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)."
}
]
}
msind_Status ska markeras som true och msind_requestStatus inom msind_Results markeras som 935000002 (fel). Informationen i msind_requeststatusdetail hjälper dig identifiera vilken referens som inte kunde matchas.
Anropa hämta-paketet API från webb-API
Hämta-paketet API (msind_RetrieveBundle) har en begäran-parameter och kan anropas enligt följande:
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).>"
}
För listan över FHIR-frågor går du till FHIR-frågor som stöds.
Svaret innehåller statusen för den fullständiga begäran som innehåller status för den fullständiga förfrågan och detaljerad status för varje resurs och dess expanderade element.
{
"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.>"
}
Vanliga varningar och felscenarier
Det här avsnittet innehåller några vanliga varningar och fel när du använder API för hämta-paketet.
Ogiltigt FHIR-resurs-ID
För närvarande förväntar sig FHIR-frågebegäransparametern ett FHIR ID. Om Dataverse inte har en post med FHIR-ID:t blir svaret följande:
{
"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
}
Attributkarta är inaktiverad
Om FHIR-frågan innehåller en elementsökning använder API för hämtningspaketet de aktiverade attributmappningar för att skapa en FHIR JSON. Om någon av attributmprogrammen för elementen i frågan är inaktiverade blir svaret följande:
{
"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
}
Skriv tillbaka till en alternativ slutpunkt
Du kan konfigurera en alternativ slutpunkt som tillbakaskrivningstjänsten kan publicera FHIR-paket med FHIR-resursen som skapats eller uppdaterats. Information om hur du konfigurerar den alternativa slutpunkten finns i Alternativa inställningar för slutpunkt för externa slutpunkter.
FHIR-paketet innehåller en enskild resurs (för alla uppdateringar) som den alternativa slutpunkten kan bearbeta. Den här bearbetningen kan innefatta att uppdatera det externa FHIR-meddelandet eller dirigera det till en annan slutpunkt. När den mottagande slutpunkten har slutförts förväntar sig tillbakaskrivningstjänsten ett returpaket som innehåller svar från FHIR-fjärrtjänsten. Det svar för att uppdatera Dataverse-posten med det nya FHIR-versions-ID och de senast ändrade värdena.
Om den alternativa slutpunkten postas till en FHIR-tjänst, till exempel FHIR-tjänsten Azure Health Data Services, bör det räcka att returnera svar från FHIR-tjänsten. I annat fall bör den alternativa slutpunktsutvecklaren skapa det här paketsvaret. Det här paketet bör vara av typen batchsvar och ska innehålla den uppdaterade FHIR-resursinformationen.
Här är ett exempel på ett paket som innehåller den FHIR-patientresurs som uppdateras:
{
"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"
}
}
]
}
Följande är ett exempelsvar som returnerats för det föregående meddelandet efter att FHIR-tjänsten för Azure Health Data Services:
{
"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"
}
}
]
}
De två viktigaste skillnaderna är fälten versionId och lastUpdated. Dessa fält krävs för att uppdatera Dataverse-posten när den har slutförts.
Ett andra utgående meddelande skickas med information om posten FHIR-proveniens. Den här resursen spårar aktiviteten från föregående patientuppdatering. I likhet med andra uppdateringar lägger tillbakaskrivningstjänsten ut det som ett paket och förväntar sig ett paket av typen batchsvar för att slutföra åtgärden.
Här är ett exempel på proveniensinlägget och svaret för de tidigare tillbakaskrivningsmeddelandena. I det här exemplet publicerar tillbakaskrivningstjänsten en ny härdelsepost och lägger till motsvarande metadata svar.
{
"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"
}
}
]
}
Svarsvärde:
{
"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"
}
}
]
}