Använd Dataverse Healthcare APIs

Artikel
06/19/2023

Api Dataverse Healthcare APIs innehåller kundbyggda API-slutpunkter som du kan byta FHIR-data 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 hitta data för en specifik resurs måste relaterade entitetsmappningar aktiveras. Om paketet innehåller resurser som entitetsmappningen inte har aktiverats för visas en varning enligt följande i svaret:

{
    "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). Det här problemet beror på att du avsiktligt kan ha markerat entitetsmappningen som inaktiverad för att inte hitta "patient"-resurser även om de finns i paketet.

Ogiltigt mappning

Attributmappningar driver omvandlingarna mellan Dataverse och FHIR. Ett av huvudelementen i attributmappningar som driver den här omvandlingen är FHIR-elementmappningen, som förväntar sig en JPath. Om JPath är felaktig blir svaret som följer:

{
    "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 (mer information finns i FHIR-referenser). API för upsert-paketet försöker lösa dessa referenser när poster upserting till 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)."
        } 
    ]
}

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
}

Se även

Vad är Microsoft Cloud for Healthcare?
Hantera FHIR-data med verktygslådan för dataintegrering Översikt för Dataverse Healthcare APIs
Konfigurera Dataverse Healthcare APIs
Granska loggar för Dataverse Healthcare APIs

Dela via

Använd Dataverse Healthcare APIs

Anropa upsert-paketet API från webb-API

Vanliga varningar och felscenarier

Entitetsmappning är inaktiverad

Ogiltigt mappning

Refererande integritet förloras

Anropa hämta-paketet API från webb-API

Vanliga varningar och felscenarier

Ogiltigt FHIR-resurs-ID

Attributkarta är inaktiverad

Se även

Ytterligare resurser