De Dataverse Healthcare APIs gebruiken
De Dataverse API's voor gezondheidszorg bevatten op maat gemaakte API-eindpunten waarmee u FHIR-gegevens (Fast Healthcare Interoperability Resources) kunt uitwisselen met Microsoft Cloud for Healthcare Dit artikel legt uit hoe u de upsert-bundel-API′s en ophaalbundel-API van Dataverse Healthcare kunt gebruiken en behandelt ook enkele veelvoorkomende gebruiksscenario's.
Ga voor meer informatie over deze API′s naar Overzicht van Dataverse Healthcare APIs.
De upsert-bundel-API aanroepen vanuit de web-API
De naam van het upsert-bundel-API-schema is msind_UpsertBundle. Deze API heeft twee aanvraagparameters en kan als volgt worden aangeroepen:
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).>"
}
De respons bevat de status van het volledige verzoek en de gedetailleerde status van elke resource en de bijbehorende uitgevouwen elementen.
{
"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.>"
}
]
}
Ga voor gedetailleerde informatie over de parameters msind_requestactionperformed en msind_requeststatus samen met hun verwachte waarden naar Typen uitgevoerde verzoekacties en Typen verzoekstatussen.
Veelvoorkomende waarschuwingen en foutscenario's
In deze sectie worden een aantal veelvoorkomende waarschuwingen en fouten vermeld die kunnen voorkomen tijdens het gebruik van de upsert-bundel-API.
Entiteitstoewijzing is uitgeschakeld
Standaard worden alle door Microsoft Cloud for Healthcare verzonden entiteitstoewijzingen uitgeschakeld. Wanneer u gegevens voor een specifieke resource wilt opnemen, moeten de bijbehorende entiteitstoewijzingen eerst worden ingeschakeld. Als de bundel resources bevat waarvoor de entiteitstoewijzingen niet zijn ingeschakeld, geeft respons de volgende waarschuwing weer:
{
"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 is gemarkeerd als waar en msind_requestStatus in msind_Results is gemarkeerd als 935000001 (waarschuwing). Dit probleem treedt op omdat u de entiteitstoewijzing opzettelijk uitschakelt om te voorkomen dat 'Patiënt'-resources worden opgenomen, zelfs als deze zich in de bundel bevinden.
Ongeldige toewijzing
Kenmerktoewijzingen sturen de transformaties tussen Dataverse en FHIR aan. Een van de belangrijkste elementen van de kenmerktoewijzing die deze transformatie aanstuurt, is de FHIR-elementtoewijzing die een JPath verwacht. Als JPath onjuist is, kunt u de volgende respons verwachten:
{
"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 is gemarkeerd als onwaar en msind_requestStatus in msind_Results is gemarkeerd als 935000002 (fout). Met hulp van de gegevens in msind_requeststatusdetail kunt u de onjuiste toewijzing identificeren.
Referentiële integriteit gaat verloren
In elke resource in een FHIR-bundel zijn veel elementen referenties naar andere resources. De upsert bundle-API probeert deze referenties op te lossen wanneer het records naar Dataverse upsert. Als de API een van deze referenties niet kan oplossen, mislukt de upsert voor de record en wordt ervoor gezorgd dat de referentiële integriteit niet verloren gaat. In een dergelijk scenario zou de respons als volgt zijn:
{
"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 is gemarkeerd als onwaar en msind_requestStatus in msind_Results is gemarkeerd als 935000002 (fout). De gegevens in msind_requeststatusdetail helpen u om te identificeren welke verwijzing niet kon worden opgelost.
De ophaalbundel-API aanroepen vanuit de web-API
De ophaalbundel-API (msind_RetrieveBundle) heeft één aanvraagparameter en kan als volgt worden aangeroepen:
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).>"
}
Ga voor de lijst met ondersteunde FHIR-query's naar Ondersteunde FHIR-query's.
De respons bevat de status van het volledige verzoek en de gedetailleerde status van elke resource en de bijbehorende uitgevouwen elementen.
{
"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.>"
}
Veelvoorkomende waarschuwingen en foutscenario's
In deze sectie worden een aantal veelvoorkomende waarschuwingen en fouten vermeld die kunnen voorkomen tijdens het gebruik van de ophaalbundel-API.
Ongeldige FHIR-resource-id
Momenteel verwacht de aanvraagparameter van de FHIR-query een FHIR-id. Als Dataverse geen record heeft met de FHIR-id, is de respons als volgt:
{
"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
}
Kenmerktoewijzing wordt uitgeschakeld
Als de FHIR-query de zoekopdracht voor een element bevat, gebruikt de ophaalbundel-API de ingeschakelde kenmerktoewijzingen om een FHIR-JSON te maken. Als een van de kenmerktoewijzingen voor de elementen in de query is uitgeschakeld, is de respons als volgt:
{
"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
}
Terugschrijven naar een alternatief eindpunt
U kunt een alternatief eindpunt configureren waarnaar de terugschrijfservice een FHIR-bundel kan posten met de FHIR-resource die is gemaakt of bijgewerkt. Zie Alternatieve uitgaande eindpuntinstellingen voor meer informatie over het configureren van dit alternatieve eindpunt.
De FHIR-bundel bevat één enkele resource (voor alle updates) die het alternatieve eindpunt kan verwerken. Deze verwerking kan bestaan uit het bijwerken van het uitgaande FHIR-bericht of het routeren ervan naar een ander eindpunt. Wanneer het ontvangende eindpunt de verwerking voltooit, verwacht de terugschrijfservice een retourbundel met het antwoord van de externe FHIR-service. Deze respons is nodig om de Dataverse-record bij te kunnen werken met de nieuwe FHIR-versie-id en de laatst gewijzigde waarden.
Als het alternatieve eindpunt naar een FHIR-service post, zoals de Azure Health Data Services FHIR-service, zou het voldoende moeten zijn om respons vanuit de FHIR-service te retourneren. Anders moet de ontwikkelaar van het alternatieve eindpunt deze bundel respons samenstellen. Deze bundel zou van het type batchrespons moeten zijn en moet de bijgewerkte FHIR-resourcegevens bevatten.
Hier volgt een voorbeeld van een bundel met de FHIR-patiëntresource die wordt bijgewerkt:
{
"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"
}
}
]
}
Hieronder ziet u een voorbeeld dat respons retourneerde voor het vorige bericht na het posten naar de FHIR-service van de 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 twee belangrijkste verschillen zijn de velden versionId en lastUpdated. Deze velden zijn vereist om het Dataverse-record bij voltooiing bij te werken.
Er wordt een tweede uitgaand bericht verzonden met de recordgegevens van de FHIR-herkomst. Deze resource houdt de activiteit bij sinds de vorige patiëntupdate. Net als bij andere updates plaatst de terugschrijfservice het als een bundel en verwacht een bundel van het type batchrespons om de bewerking te kunnen voltooien.
Hier volgt een voorbeeld van de herkomstpost en respons voor de vorige terugschrijfberichten. In dit voorbeeld plaatst de terugschrijfservice een nieuw herkomstrecord en voegt de bijbehorende metagegevens toe aan de respons.
{
"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"
}
}
]
}
Responswaarde:
{
"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"
}
}
]
}