Utiliser les Dataverse Heathcare API
Les Dataverse Healthcare API contiennent des points de terminaison d’API personnalisés qui vous permettent d’échanger des données FHIR (Fast Healthcare Interoperability Resources) avec Microsoft Cloud for Healthcare. Cet article explique comment utiliser les Dataverse Healthcare API d’upsert et de récupération de pack et couvre également quelques scénarios d’utilisation courants.
Pour plus d’informations sur ces API, accédez à Vue d’ensemble des Dataverse Healthcare API.
Appeler l’API d’upsert de pack à partir de l’API Web
Le nom du schéma de l’API d’upsert de pack est msind_UpsertBundle. Il a deux paramètres de requête et peut être appelé comme suit :
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).>"
}
La réponse contient le statut de la demande complète, ainsi que le statut détaillé de chaque ressource et de ses éléments développés.
{
"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.>"
}
]
}
Pour des informations détaillées sur les paramètres msind_requestactionperformed et msind_requeststatus ainsi que leurs valeurs attendues, accédez à Types d’actions de demande effectuées et Types de statuts de demande.
Avertissements et scénarios d’erreur courants
Cette section répertorie certains des avertissements et erreurs les plus courants lors de l’utilisation de l’API upsert bundle.
Le mappage d’entités est désactivé
Par défaut, tous les mappages d’entités expédiés par Microsoft Cloud for Healthcare sont désactivés. Lorsque vous essayez d’ingérer des données pour une ressource spécifique, les mappages d’entités associés doivent d’abord être activés. Si le pack contient des ressources pour lesquelles les mappages d’entités ne sont pas activés, la réponse affiche un avertissement comme suit :
{
"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"
}
]
}
Le msind_Status est marqué comme true et le msind_requestStatus dans msind_Results est marqué comme 935000001 (avertissement). Ce comportement se produit car vous pouvez désactiver intentionnellement le mappage d’entités pour éviter d’ingérer des ressources « Patient », même si elles se trouvent dans le pack.
Mappage non valide
Les mappages d’attributs pilotent les transformations entre Dataverse et FHIR. L’un des éléments clés du mappage d’attributs à l’origine de cette transformation est le mappage d’éléments FHIR, qui attend un JPath. Si le JPath est incorrect, la réponse suivante devrait s’afficher :
{
"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"
}
}
]
}
Le msind_Status est marqué comme false et le msind_requestStatus dans msind_Results est marqué comme 935000002 (erreur). Les informations dans msind_requeststatusdetail vous permettent d’identifier la mauvaise carte.
L’intégrité référentielle est perdue
Dans chaque ressource d’un pack FHIR, de nombreux éléments sont des références à d’autres ressources. L’API du pack upsert tente de résoudre ces références lorsqu’elle insère des enregistrements dans Dataverse. Si l’API ne peut pas résoudre l’une de ces références, elle ne peut pas insérer l’enregistrement et s’assure que l’intégrité référentielle n’est pas perdue. Dans un tel scénario, la réponse sera la suivante :
{
"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)."
}
]
}
Le msind_Status est marqué comme false et le msind_requestStatus dans msind_Results est marqué comme 935000002 (erreur). Les informations dans msind_requeststatusdetail vous permettent d’identifier la référence qui n’a pas pu être résolue.
Appeler l’API de récupération de pack à partir de l’API Web
L’API de récupération de pack (msind_RetrieveBundle) a un paramètre de requête et peut être appelé comme suit :
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).>"
}
Pour obtenir la liste des requêtes FHIR prises en charge, accédez à Requêtes FHIR prises en charge.
La réponse contient le statut de la demande complète, ainsi que le statut détaillé de chaque ressource et de ses éléments développés.
{
"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.>"
}
Avertissements et scénarios d’erreur courants
Cette section répertorie certains des avertissements et erreurs les plus courants lors de l’utilisation de l’API retrieve bundle.
Ressource ID FHIR non valide
Actuellement, le paramètre de demande de requête FHIR attend un ID FHIR. Si Dataverse n’a pas d’enregistrement avec l’ID FHIR, la réponse sera la suivante :
{
"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
}
Le mappage d’attributs est désactivé
Si la requête FHIR contient une recherche d’éléments, l’API du pack de récupération utilisera les cartes d’attributs activées pour construire un JSON FHIR. Si l’une des cartes d’attributs des éléments de la requête est désactivée, la réponse sera la suivante :
{
"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
}
Écriture différée dans un point de terminaison alternatif
Vous pouvez configurer un point de terminaison alternatif sur lequel le service d’écriture différée peut publier un Pack FHIR contenant la ressource FHIR créée ou mise à jour. Pour savoir comment configurer ce point de terminaison alternatif, consultez Paramètres du point de terminaison sortant alternatif.
Le pack FHIR contient une seule ressource (pour toutes les mises à jour) que le point de terminaison alternatif peut traiter. Ce traitement peut inclure la mise à jour du message FHIR sortant ou son envoi vers un autre point de terminaison. Lorsque le point de terminaison de réception termine le traitement, le service d’écriture différée attend un pack de retour contenant la réponse du service FHIR distant. Ce réponse est nécessaire pour mettre à jour l’enregistrement Dataverse avec le nouvel ID de version FHIR et les dernières valeurs modifiées.
Si le point de terminaison alternatif publie sur un service FHIR, tel que le service FHIR des Services de données de santé Azure, le renvoi de la réponse à partir du service FHIR devrait être suffisant. Sinon, le développeur du point de terminaison alternatif doit construire la réponse de ce pack. Ce pack doit être du type batch-response et doit contenir les détails de la ressource FHIR mise à jour.
Voici un exemple de pack contenant la ressource Patient FHIR en cours de mise à jour :
{
"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"
}
}
]
}
Voici un exemple de réponse renvoyée pour le message précédent après publication sur le service FHIR des Services de données de santé Azure :
{
"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"
}
}
]
}
Les deux principales différences sont les champs versionId et lastUpdated. Ces champs sont obligatoires pour mettre à jour l’enregistrement Dataverse une fois l’opération terminée.
Un deuxième message sortant est envoyé contenant les détails de l’enregistrement Provenance de FHIR. Cette ressource suit l’activité de la mise à jour précédente du patient. Comme pour les autres mises à jour, le service d’écriture différée la publie en tant que pack et attend un pack du type batch-response pour terminer l’opération.
Voici un exemple de publication de la provenance et de réponse pour les messages d’écriture différée précédents. Dans cet exemple, le service d’écriture différée publie un nouvel enregistrement de provenance et ajoute les métadonnées correspondantes à la réponse.
{
"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"
}
}
]
}
Valeur de la réponse :
{
"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"
}
}
]
}