Die Dataverse Healthcare APIs verwenden
Die Dataverse Healthcare APIs enthalten benutzerdefinierte API-Endpunkte, die Ihnen den Austausch von FHIR-Daten (Fast Healthcare Interoperability Resources) mit Microsoft Cloud for Healthcare erlauben. In diesem Artikel wird die Verwendung der Dataverse Upsert- und Retrieval-Bundle-APIs für das Gesundheitswesen erläutert und auch einige häufige Verwendungsszenarien behandelt.
Weitere Informationen über diese APIs finden Sie unter Übersicht über Dataverse Healthcare APIs.
Aufrufen der upsert bundle API über die Web-API
Der Name des Upsert-Paket-API-Schemas lautet msind_UpsertBundle. Sie hat zwei Anfrageparameter und kann wie folgt aufgerufen werden:
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).>"
}
Diese Antwort umfasst den Status der vollständigen Anfrage sowie den detaillierten Status jeder Ressource und ihrer erweiterten Elemente enthält.
{
"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.>"
}
]
}
Ausführliche Informationen zu den Parametern msind_requestactionperformed und msind_requeststatus zusammen mit ihren erwarteten Werten finden Sie unter Typen der ausgeführten Anforderungsaktionen und Arten des Anfragestatus.
Allgemeine Warnungen und Fehlerszenarien
Dieser Abschnitt listet einige der häufig auftretenden Warnungen und Fehler bei der Verwendung der Upsert-Paket-API auf.
Entitätszuordnung ist deaktiviert
Standardmäßig sind alle Zuordnungen von Entitäten, die mit Microsoft Cloud for Healthcare ausgeliefert werden, deaktiviert. Wenn Sie versuchen, Daten für eine bestimmte Ressource zu erfassen, müssen zuerst die zugehörigen Entitätszuordnungen aktiviert werden. Falls das Paket Ressourcen enthält, für welche die Entitätszuordnungen nicht aktiviert sind, zeigt die Antwort die folgende Warnung an:
{
"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"
}
]
}
Der msind_Status wird als wahr und die msind_requestStatus innerhalb der msind_Results als 935000001 (Warnung) markiert. Dieses Verhalten tritt auf, weil Sie die Entitätszuordnung möglicherweise absichtlich deaktivieren, um die Erfassung von „Patienten“-Ressourcen zu vermeiden, selbst wenn diese im Paket enthalten sind.
Ungültige Zuordnung
Attributzuordnungen steuern die Transformationen zwischen Dataverse und FHIR. Eines der wichtigsten Attributzuordnungselemente, die diese Transformation steuern, ist die FHIR-Elementzuordnung, die einen JPath erwartet. Wenn der JPath falsch ist, können Sie die folgende Antwort erwarten:
{
"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"
}
}
]
}
Der msind_Status wird als falsch und die msind_requestStatus innerhalb der msind_Results als 935000002 (Fehler) markiert. Die Information in msind_requeststatusdetail hilft, die falsche Zuordnung zu identifizieren.
Referentielle Integrität geht verloren
In jeder Ressource in einem FHIR-Paket sind viele Elemente Verweise auf andere Ressourcen. Die Upsert-Bundle-API versucht, diese Verweise aufzulösen, wenn sie ein Upsert von Datensätzen in Dataverse durchführt. Wenn die API einen dieser Verweise nicht auflösen kann, kann sie den Datensatz nicht umkehren und stellt sicher, dass die referenzielle Integrität nicht verloren geht. In einem solchen Szenario sähe die Antwort wie folgt aus:
{
"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)."
}
]
}
Der msind_Status wird als falsch und die msind_requestStatus innerhalb der msind_Results als 935000002 (Fehler) markiert. Die Information in msind_requeststatusdetail hilft zu identifizieren, welcher Verweis nicht aufgelöst werden konnte.
Aufrufen der Paket-API von der Web-API aus
Die API zum Abrufen von Bundles (msind_RetrieveBundle) hat einen Anfrageparameter und kann wie folgt aufgerufen werden:
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).>"
}
Die Liste der unterstützten FHIR-Abfragen finden Sie unter Unterstützte FHIR-Abfragen.
Diese Antwort umfasst den Status der vollständigen Anfrage sowie den detaillierten Status jeder Ressource und ihrer erweiterten Elemente enthält.
{
"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.>"
}
Allgemeine Warnungen und Fehlerszenarien
Dieser Abschnitt listet einige der häufig auftretenden Warnungen und Fehler beim Abrufen der Paket-API auf.
Ungültige FHIR-Ressourcen-ID
Derzeit erwartet der Parameter der FHIR-Abfrage eine FHIR-ID. Wenn Dataverse keinen Datensatz mit der FHIR ID hat, wäre die Antwort wie folgt:
{
"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
}
Attributzuordnung ist deaktiviert
Wenn die FHIR-Abfrage eine Elementsuche enthält, verwendet die abfragende Paket-API die aktivierten Attributzuordnungen, um ein FHIR JSON zu konstruieren. Falls eine der Attributzuordnungen für die Elemente in der Abfrage deaktiviert ist, sähe die Antwort wie folgt:
{
"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
}
An einen alternativen Endpunkt zurückschreiben
Sie können einen alternativen Endpunkt konfigurieren, an den der Rückschreibedienst ein FHIR-Paket bereitstellen kann, dass die erstellte oder aktualisierte FHIR-Ressource enthält. Informationen zum Konfigurieren dieses alternativen Endpunkts finden Sie unter Alternative ausgehende Endpunkteinstellungen.
Das FHIR-Paket enthält eine einzelne Ressource (für alle Updates), die der alternative Endpunkt verarbeiten kann. Zu dieser Verarbeitung kann die Aktualisierung der ausgehenden FHIR-Nachricht oder die Weiterleitung an einen anderen Endpunkt gehören. Wenn der empfangende Endpunkt die Verarbeitung abgeschlossen hat, erwartet der Rückschreibedienst ein Rückgabepaket mit Antwort vom Remote-FHIR-Dienst. Dieser Antwort wird benötigt, um den Dataverse-Datensatz mit der neuen FHIR-Versions-ID und den zuletzt geänderten Werten zu aktualisieren.
Wenn der alternative Endpunkt an einen FHIR-Dienst bereitstellt, etwa den FHIR-Dienst von Azure Health Data Services, sollte es ausreichen, die Antwort vom FHIR-Dienst zurückzugeben. Andernfalls sollte die Entwicklungsfachkraft des alternativen Endpunkts diese Paketantwort erstellen. Dieses Paket sollte den Typ Batchantwort haben und sollte die aktualisierten FHIR-Ressourcendetails enthalten.
Hier ist ein Beispiel für ein Paket, das die zu aktualisierende FHIR-Patientenressource enthält:
{
"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"
}
}
]
}
Nachfolgend sehen Sie eine Beispielantwort, die für die vorherige Nachricht zurückgegeben wurde, nachdem sie an den FHIR-Dienst von Azure Health Data Services bereitgestellt wurde:
{
"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"
}
}
]
}
Die beiden Hauptunterschiede sind versionId- und lastUpdated-Felder. Diese Felder sind erforderlich, um den Dataverse-Datensatz nach Abschluss zu aktualisieren.
Eine zweite ausgehende Nachricht wird mit den FHIR-Herkunft-Datensatzdetails gesendet. Diese Ressource verfolgt die Aktivität seit der letzten Patientenaktualisierung. Ähnlich wie bei anderen Updates veröffentlicht der Rückschreibedienst dies als Paket und erwartet ein Paket vom Typ Batchantwort, um den Vorgang abzuschließen.
Hier ist ein Beispiel für die Herkunftsbereitstellung und -antwort für die vorherigen Rückschreibenachrichten. In diesem Beispiel veröffentlicht der Rückschreibedienst einen neuen Herkunftsdatensatz und fügt die entsprechenden Metadaten zur Antwort hinzu.
{
"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"
}
}
]
}
Antwortwert:
{
"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"
}
}
]
}