Dataverse Healthcare API ‑ohjelmointirajapintojen käyttäminen
Dataverse Healthcare API -ohjelmointirajapinnat sisältävät mukautettuja ohjelmointirajapintojen päätepisteitä, jotka mahdollistavat FHIR (Fast Healthcare Interoperability Resources) -tietojen vaihtamisen Microsoft Cloud for Healthcaren kanssa. Tässä artikkelissa käsitellään Dataverse Healthcare API -ohjelmointirajapintojen upsert- ja retrieve-pakettien osalta sekä joitakin yleisiä käyttöskenaarioita.
Lisätietoja näistä ohjelmointirajapinnoista on kohdassa Dataverse Healthcare API -ohjelmointirajapintojen yleiskatsaus.
Upsert-paketin ohjelmointirajapinnan käynnistäminen verkko-ohjelmointirajapinnasta
Upsert-paketin ohjelmointirajapinnan rakenteen nimi on msind_UpsertBundle. Sillä on kaksi pyyntöparametria, jotka voidaan käynnistää seuraavasti:
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).>"
}
Vastaus sisältää valmiin pyynnön tilan sekä kunkin resurssin ja sen laajennettujen elementtien yksityiskohtaisen tilan.
{
"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.>"
}
]
}
Lisätietoja msind_requestactionperformed- ja msind_requeststatus-parametreista sekä niiden odotetuista arvoista on kohdissa Suoritettujen pyyntötoimintojen tyypit ja Pyynnön tilatyypit.
Yleiset varoitukset ja virheskenaariot
Tässä osassa on lueteltu joitakin yleisimpiä varoituksia ja virheitä käytettäessä upsert-pakettiohjelmointirajapintaa.
Entiteettien yhdistämismääritys on poistettu käytöstä
Kaikki Microsoft Cloud for Healthcaren lähettämät entiteettikartat ovat oletusarvoisesti pois käytöstä. Kun yrität käsitellä tietyn resurssin tietoja, siihen liittyvät entiteettien yhdistämismääritykset on ensin otettava käyttöön. Jos paketti sisältää resursseja, joille entieettien yhdistämismäärityksiä ei ole otettu käyttöön, vastauksena näkyy seuraava varoitus:
{
"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-arvoksi merkitään tosi ja msind_requestStatus-tilan arvoksi msind_Results-tuloksissa merkitään 935000001 (varoitus). Tämä tapahtuu, koska saatat tarkoituksella poistaa entiteetin yhdistämismäärityksen käytöstä välttääksesi Potilas-resurssien käsittelyn, vaikka ne kuuluisivat pakettiin.
Virheellinen kartta
Määritekartat ovat pohjana muunnoksille Dataversen ja FHIR:n välillä. Yksi keskeisistä määritteen yhdistämismäärityksen elementeistä, joka on tämän muunnoksen taustalla, on FHIR-elementin yhdistämismääritys, joka edellyttää JPathia. Jos JPath on virheellinen, vastaus on oletettavasti seuraava:
{
"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-arvoksi merkitään epätosi ja msind_requestStatus-tilan arvoksi msind_Results-tuloksissa merkitään 935000002 (virhe). msind_requeststatusdetail-tiedoissa ilmaistaan virheellinen kartta.
Viite-eheys menetetään
Kussakin FHIR-paketin resurssissa useat elementit ovat viitteitä muihin resursseihin. Upsert-paketin ohjelmointirajapinta yrittää ratkaista nämä viitteet, kun se päivittää ja lisää tietueita Dataverseen. Jos ohjelmointirajapinta ei pysty ratkaisemaan jotakin näistä viittauksista, tietueen upsert-toiminto epäonnistuu, mikä varmistaa, ettei viitteiden eheys katoa. Tällaisessa skenaariossa vastaus on seuraava:
{
"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-arvoksi merkitään epätosi ja msind_requestStatus-tilan arvoksi msind_Results-tuloksissa merkitään 935000002 (virhe). msind_requeststatusdetail-tiedot ilmaisevat, mitä viitettä ei onnistuttu ratkaisemaan.
Retrieve-paketin ohjelmointirajapinnan käynnistäminen verkko-ohjelmointirajapinnasta
Paketin noutamisen ohjelmointirajapinnassa (msind_RetrieveBundle) on yksi pyyntöparametri, ja se voidaan käynnistää seuraavasti:
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).>"
}
Tuettujen FHIR-kyselyjen luettelo on kohdassa Tuetut FHIR-kyselyt.
Vastaus sisältää valmiin pyynnön tilan sekä kunkin resurssin ja sen laajennettujen elementtien yksityiskohtaisen tilan.
{
"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.>"
}
Yleiset varoitukset ja virheskenaariot
Tässä osassa on lueteltu joitakin yleisimpiä varoituksia ja virheitä käytettäessä noudettavaa pakettiohjelmointirajapintaa.
Virheellinen FHIR-resurssitunnus
Tällä hetkellä FHIR-kyselypyyntöparametri odottaa FHIR-tunnusta. Jos Dataversessä ei ole tietuetta kulloisellakin FHIR-tunnuksella, vastaus on seuraava:
{
"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
}
Määritekartta on pois käytöstä
Jos FHIR-kysely sisältää elementtihaun, paketin noutamisen ohjelmointirajapinta muodostaa FHIR JSON -tiedoston käyttämällä käytössä olevia määritekarttoja. Jos jokin kyselyn elementtien määritekartoista on pois käytöstä, vastaus on seuraava:
{
"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
}
Takaisinkirjoitus vaihtoehtoiseen päätepisteeseen
Voit määrittää vaihtoehtoisen päätepisteen, johon takaisinkirjoituspalvelu voi julkaista FHIR-paketin, joka sisältää luodun tai päivitetyn FHIR-resurssin. Tutustu tämän vaihtoehtoisen päätepisteen määrittämiseen Vaihtoehtoiset lähtevät päätepisteasetukset.
FHIR-paketti sisältää yksittäisen resurssin (kaikkien päivitysten osalta), jonka vaihtoehtoinen päätepiste pystyy käsittelemään. Käsittelyyn voi kuulua lähtevän FHIR-sanoman päivittäminen tai sen reitittäminen toiseen päätepisteeseen. Kun vastaanottavan päätepisteen suorittama käsittely on valmis, takaisinkirjoituspalvelu odottaa palautuspakettia, joka sisältää FHIR-etäpalvelun vastauksen. Vastaus tarvitaan Dataverse-tietueen päivittämiseen uudella FHIR-versiotunnuksella sekä viimeksi muokatuilla arvoilla.
Jos vaihtoehtoinen päätepiste suorittaa julkaisun FHIR-palveluun, kuten Azure Health-tietopalvelujen FHIR-palveluun, FHIR-palvelun vastauksen palauttamisen pitäisi riittää. Muussa tapauksessa vaihtoehtoisen päätepisteen kehittäjän on luotava tämä pakettivastaus. Paketin pitäisi olla tyyppiä erävastaus, ja sen pitäisi sisältää päivitetyt FHIR-resurssin tiedot.
Tässä on esimerkki paketista, joka sisältää päivitettävän FHIR-potilasresurssin:
{
"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"
}
}
]
}
Seuraavassa on esimerkkivastaus, joka palautetaan edelliseen sanomaan, kun se on julkaistu Azure Health -tietopalvelujen FHIR-palveluun:
{
"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"
}
}
]
}
Kaksi keskeistä eroa ovat kentät versionId ja lastUpdated. Nämä kentät ovat pakollisia Dataverse-tietueen päivittämiseksi toiminnon valmistuttua.
Toinen, FHIR-alkuperä-tietueen tiedot sisältävä lähtevä sanoma lähetetään. Tämä resurssi seuraa edellisen Potilas-päivityksen aktiviteettia. Kuten muutkin päivitykset, takaisinkirjoituspalvelu julkaisee sen pakettina ja odottaa tyypin erävastaus pakettia toiminnon loppuun suorittamista varten.
Tässä on esimerkki alkuperän julkaisemisesta ja vastauksesta edellisten takaisinkirjoitussanomien osalta. Tässä esimerkissä takaisinkirjoituspalvelu julkaisee uuden alkuperätietueen ja lisää vastaukseen vastaavat metatiedot.
{
"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"
}
}
]
}
Vastausarvo:
{
"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"
}
}
]
}