Usar las Dataverse Healthcare APIs
Las API de atención médica de Dataverse contienen puntos finales de API personalizados que le permiten intercambiar datos FHIR (recursos de interoperabilidad rápida de atención médica) con Microsoft Cloud for Healthcare. En este artículo, se explica cómo usar las API de paquetes de actualización y recuperación de atención sanitaria de Dataverse y también se cubren algunos escenarios de uso comunes.
Para obtener más información sobre estas APIs, vaya a Descripción general de las Dataverse Healthcare APIs.
Invoque la API del paquete upsert desde la API web
El nombre del esquema de la API del paquete upsert es msind_UpsertBundle. Tiene dos parámetros de solicitud y se puede invocar de la siguiente manera:
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 respuesta contiene el estado de la solicitud completa y el estado detallado de cada recurso y sus elementos expandidos.
{
"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.>"
}
]
}
Para obtener información detallada sobre los parámetros msind_requestactionperformed y msind_requeststatus junto con sus valores esperados, vaya a Tipos de acciones de solicitud realizadas y Tipos de estado de solicitud.
Advertencias comunes y escenarios de error
Esta sección enumera algunas de las advertencias y errores más comunes al usar la API del paquete upsert.
La asignación de entidades está deshabilitada
De manera predeterminada, todos los mapas de entidades que envía Microsoft Cloud for Healthcare están desactivados. Cuando intenta ingerir datos para un recurso específico, primero se deben habilitar las asignaciones de entidades relacionadas. En caso de que el paquete contenga recursos para los cuales las asignaciones de entidades no están habilitadas, la respuesta muestra una advertencia como la siguiente:
{
"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 se marca como verdadero y msind_requestStatus en msind_Results se marca como 935000001 (Advertencia). Este comportamiento se produce porque es posible que desactive intencionalmente la asignación de entidades para evitar la ingesta de recursos "Paciente", incluso si están en el paquete.
Asignación no válida
Los mapas de atributos impulsan las transformaciones entre Dataverse y FHIR. Uno de los elementos clave de la asignación de atributos que impulsa esta transformación es la asignación de elementos FHIR, que espera un JPath. Si el JPath es incorrecto, puede esperar la siguiente respuesta:
{
"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 se marca como falso y msind_requestStatus en msind_Results se marca como 935000002 (Error). La información en msind_requeststatusdetail le ayuda a identifica el mapa incorrecto.
Se pierde la integridad referencial
En cada recurso de un paquete FHIR, muchos elementos son referencias a otros recursos. La API del paquete upsert intenta resolver estas referencias cuando inserta registros en Dataverse. Si la API no puede resolver ninguna de estas referencias, no puede alterar el registro y garantiza que no se pierda la integridad referencial. En tal escenario, la respuesta sería la siguiente:
{
"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 se marca como falso y msind_requestStatus en msind_Results se marca como 935000002 (Error). La información en msind_requeststatusdetail le ayuda a identificar qué referencia no se pudo resolver.
Invoque la API del paquete de recuperación desde la API web
La API del paquete de recuperación (msind_RetrieveBundle) tiene un parámetro de solicitud y se puede invocar de la siguiente manera:
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).>"
}
Para ver la lista de consultas FHIR admitidas, vaya a Consultas FHIR admitidas.
La respuesta contiene el estado de la solicitud completa y el estado detallado de cada recurso y sus elementos expandidos.
{
"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.>"
}
Advertencias comunes y escenarios de error
Esta sección enumera algunas de las advertencias y errores más comunes al usar la API del paquete retrieve.
Id. de recurso FHIR no válido
Actualmente, el parámetro de solicitud de consulta FHIR espera un ID de FHIR. Si Dataverse no tiene registro con el ID de FHIR, la respuesta sería la siguiente:
{
"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
}
El mapa de atributos está deshabilitado
Si la consulta FHIR contiene una búsqueda de elementos, la API del paquete de recuperación utiliza los mapas de atributos habilitados para construir un FHIR JSON. En caso de que alguno de los mapas de atributos para los elementos de la consulta esté deshabilitado, la respuesta sería la siguiente:
{
"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
}
Escribir de nuevo en un punto de conexión alternativo
Puede configurar un punto de conexión alternativo en el que el servicio de escritura diferida pueda publicar un Paquete FHIR que contiene el recurso FHIR creado o actualizado. Para saber cómo configurar este punto final alternativo, consulte Configuraciones alternativas de puntos de conexión salientes.
El paquete FHIR contiene un único recurso (para todas las actualizaciones) que el punto de conexión alternativo puede procesar. Este procesamiento puede incluir la actualización del mensaje FHIR saliente o enrutarlo a otro punto final. Cuando el punto de conexión receptor completa el procesamiento, el servicio de escritura espera un paquete de retorno que contenga respuesta del servicio FHIR remoto. Este respuesta es necesaria para actualizar el registro de Dataverse con el nuevo ID de la versión FHIR y los últimos valores modificados.
Si el punto de conexión alternativo publica en un servicio FHIR, como el servicio FHIR de Azure Health Data Service, devolver la respuesta desde el servicio FHIR debería ser suficiente. De lo contrario, el desarrollador del punto de conexión alternativo debe construir este paquete respuesta. Este paquete debe ser del tipo batch-response y debe contener los detalles actualizados de los recursos FHIR.
A continuación se muestra un ejemplo de un paquete que contiene el recurso para pacientes de FHIR que se está actualizando:
{
"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"
}
}
]
}
A continuación se muestra un ejemplo respuesta devuelto para el mensaje anterior después de publicarlo en el servicio FHIR de Azure Health Data Services:
{
"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"
}
}
]
}
Las dos diferencias clave son los campos versionId y lastUpdated. Estos campos son obligatorios para actualizar el registro de Dataverse al finalizar.
Se envía un segundo mensaje saliente que contiene los detalles del registro Procedencia del FHIR. Este recurso rastrea la actividad de la actualización del paciente anterior. De manera similar a otras actualizaciones, el servicio de escritura diferida lo publica como un paquete y espera un paquete del tipo batch-response para completar la operación.
A continuación se muestra un ejemplo de la publicación de procedencia y respuesta para los mensajes de escritura anteriores. En este ejemplo, el servicio de escritura diferida publica un nuevo registro de procedencia y agrega los metadatos correspondientes a respuesta.
{
"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"
}
}
]
}
Valor de respuesta:
{
"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"
}
}
]
}