Bruge Dataverse Healthcare API'er
Dataverse healthcare API'er indeholder brugerdefinerede API-slutpunkter, som du kan bruge til at udveksle FHIR-data (Fast Healthcare Interoperability Resources)-data med Microsoft Cloud for Healthcare. I denne artikel forklares, hvordan du kan bruge Dataverse healthcare-upsert og hente bundt-API'er, og den omhandler også nogle almindelige brugsscenarier.
Du kan finde flere oplysninger om disse API'er i Oversigt over Dataverse healthcare API'er.
Aktivere upsert-bundt-API'en fra web-API'en
Navnet på upsert bundt API-skemaet er msind_UpsertBundle. Den har to anmodningsparametre og kan aktiveres på følgende måde:
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 indeholder status for den fuldstændige anmodning, samt den detaljerede status for hver enkelt ressource og dens udvidede elementer.
{
"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.>"
}
]
}
Du kan finde detaljerede oplysninger om msind_requestactionperformed og msind_requeststatus parametrene sammen med de forventede værdier ved at gå til Typer af handlinger til anmodninger, der udføres, og typer af anmodningsstatus.
Almindelige advarsler og fejlscenarier
Dette afsnit indeholder nogle af de mest almindelige advarsler og fejl, når du bruger upsert-bundt-API'en.
Objekttilknytning er deaktiveret
Som standard er alle objekttilknytninger, der sendes af Microsoft Cloud for Healthcare, som standard deaktiveret. Når du forsøger at oprette data for en bestemt ressource, skal de relaterede objekttilknytninger først aktiveres. Hvis bundtet indeholder ressourcer, som objekttilknytningerne ikke er aktiveret for, vises svar med advarsel på følgende måde:
{
"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 er markeret som sand og msind_requestStatus i msind_Results er markeret som 935000001 (advarsel). Dette forekommer, fordi du med overlæg deaktiverer objekttilknytningen for at undgå at bruge "Patient"-ressourcer, også selvom de findes i bundtet.
Ugyldig tilknytning
Attributknytninger driver transformeringerne mellem Dataverse og FHIR. Et af de vigtigste attributtilknytningselementer, der driver denne transformering, er elementtilknytningen FHIR, som forventer en JPath. Hvis JPath ikke er korrekt, kan du forvente følgende 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 er markeret som falsk og msind_requestStatus i msind_Results er markeret som 935000002 (fejl). Oplysningerne i msind_requeststatusdetail hjælper dig med at identificere den forkerte tilknytning.
Refererende integritet går tabt
I hver ressource i et FHIR-bundt er mange elementer referencer til andre ressourcer. Upsert-bundt API forsøger at løse disse referencer, når den overfører poster i Dataverse. Hvis API'en ikke løser nogen af disse referencer, kan den ikke opdatere posten og sikrer, at den refererende integritet ikke går tabt. I et sådant scenarie vil svaret være følgende:
{
"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 er markeret som falsk og msind_requestStatus i msind_Results er markeret som 935000002 (fejl). Oplysningerne i msind_requeststatusdetail hjælper dig med at identificere, hvilken reference der ikke blev fortolket.
Aktivere hent-bundt-API'en fra web-API'en
Hent bundt-API'en (msind_RetrieveBundle) har én anmodningsparameter og kan aktiveres på følgende måde:
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).>"
}
Gå til Understøttede FHIR-forespørgsler for at få vist listen over understøttede FHIR-forespørgsler.
Svaret indeholder status for den fuldstændige anmodning, samt den detaljerede status for hver enkelt ressource og dens udvidede elementer.
{
"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.>"
}
Almindelige advarsler og fejlscenarier
Dette afsnit indeholder nogle af de mest almindelige advarsler og fejl, når du bruger hent bundt-API'en.
Ugyldig FHIR-ressource-ID
I øjeblikket forventer parameteren FHIR-forespørgselsanmodning et FHIR-id. Hvis Dataverse ikke har en post med FHIR-id, vil svaret være følgende:
{
"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
}
Attribut-tilknytning er deaktiveret
Hvis FHIR-forespørgslen indeholder en elementsøgning, bruger hent bundt-API'en de aktiverede attributtilknytninger til at oprette en FHIR JSON. Hvis en eller flere attributattributtilknytninger for elementerne i forespørgslen deaktiveres, vil svaret være følgende:
{
"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 tilbage til et alternativt slutpunkt
Du kan konfigurere et alternativt slutpunkt, som tjenesten til skrivning tilbage kan sende et FHIR-bundt til, som indeholder den FHIR-ressource, der oprettes eller opdateres. Du kan få mere at vide om, hvordan du konfigurerer dette alternative slutpunkt, under Indstillinger for alternative udgående slutpunkter.
FHIR-bundtet indeholder en enkelt ressource (for alle opdateringer), som det alternative slutpunkt kan behandle. Denne behandling kan omfatte opdatering af den udgående FHIR-meddelelse eller routing til et andet slutpunkt. Når det modtagende slutpunkt fuldfører processen, forventer tilbageskrivningstjeneste et returbundt, der indeholder svar fra den eksterne FHIR-tjeneste. Denne svar skal bruges, hvis du vil opdatere Dataverse posten med det nye FHIR-versions-id og de seneste ændrede værdier.
Hvis de alternative slutpunkter sender indlæg til en FHIR-tjeneste, f.eks. Azure Health Data Services FHIR-tjenesten, er det tilstrækkeligt at returnere svar fra tjenesten FHIR. Ellers skal den alternative slutpunktsudvikler opbygge dette bundt-svar. Dette bundt skal være af typen batchsvar og skal indeholde de opdaterede FHIR-ressourcedetaljer.
Her er et eksempel på en bundt, der indeholder den FHIR-patientressource, der opdateres:
{
"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"
}
}
]
}
Her følger et eksempelsvar, der returneres for den forrige meddelelse, når du har sendt indlæg til Azure Health Data Services FHIR-tjenesten:
{
"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 to vigtigste forskelle er felterne versionId og lastUpdated. Disse felter skal udfyldes for at opdatere Dataverse-posten, når den er fuldført.
Der sendes endnu en udgående meddelelse, der indeholder oplysningerne FHIR Provenance-postoplysninger. Denne ressource sporer aktiviteten fra den tidligere patientopdatering. På samme måde som andre opdateringer skriver tjenesten tilbage i et bundt og forventer et bundt af typen batch-svar for at fuldføre handlingen.
Her er et eksempel på oprindelsesposten og svar til de tidligere meddelelser, der er blevet skrevet tilbage. I dette eksempel skriver tilbageførselstjenesten en ny provenancepost og føjer de tilsvarende metadata til svaret.
{
"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"
}
}
]
}
Svarværdi:
{
"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"
}
}
]
}