Usar as Dataverse Healthcare APIs
As Dataverse Healthcare APIs contêm pontos de extremidade de API personalizados que permitem que você troque dados FHIR (Fast Healthcare Interoperability Resources) com o Microsoft Cloud for Healthcare. Este artigo explica como usar as APIs healthcare upsert e retrieve bundle do Dataverse e também aborda alguns cenários de uso comuns.
Para obter mais informações sobre essas APIs, acesse Visão geral das Dataverse Healthcare APIs.
Invoque a API upsert bundle da API Web
O nome do esquema da API upsert bundle é msind_UpsertBundle. Ela tem dois parâmetros de solicitação e pode ser invocado da seguinte forma:
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).>"
}
A resposta contém o status da solicitação completa e o status detalhado de cada recurso e seus 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 obter informações detalhadas sobre os parâmetros msind_requestactionperformed e msind_requeststatus junto com seus valores esperados, acesse Tipos de ações de solicitação executadas e Tipos de status de solicitação.
Avisos comuns e cenários de erro
Esta seção lista alguns dos avisos e erros comumente vistos ao usar a API do pacote upsert.
O mapa de entidade está desativado
Por padrão, todos os mapas de entidade enviados pelo Microsoft Cloud for Healthcare estão desabilitados. Ao tentar ingerir dados para um recurso específico, os mapas de entidade relacionados devem primeiro ser habilitados. Caso o pacote contenha recursos para os quais os mapas de entidade não estejam habilitados, a resposta exibirá um aviso da seguinte forma:
{
"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"
}
]
}
O msind_Status será marcado como verdadeiro e o msind_requestStatus dentro de msind_Results será marcado como 935000001 (aviso). Esse comportamento ocorre porque você pode desabilitar intencionalmente o mapa de entidades para evitar a ingestão de recursos "Paciente", mesmo que estejam no pacote.
Mapa inválido
Os mapas de atributos conduzem as transformações entre Dataverse e FHIR. Um dos principais elementos do mapa de atributos que conduzem essa transformação é o mapa do elemento FHIR, que espera um JPath. Se o JPath estiver incorreto, você poderá esperar as seguintes resposta:
{
"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"
}
}
]
}
O msind_Status será marcado como falso e o msind_requestStatus dentro de msind_Results será marcado como 935000002 (erro). As informações em msind_requeststatusdetail ajudarão você a identificar o mapa incorreto.
A integridade referencial é perdida
Em cada recurso em um pacote FHIR, muitos elementos são referências a outros recursos. A API de pacote upsert tenta resolver essas referências quando faz upsert de registros no Dataverse. Se a API falhar em resolver qualquer uma dessas referências, ela não atualizará o registro e garantirá que a integridade referencial não seja perdida. Nesse cenário, a resposta será a seguinte:
{
"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)."
}
]
}
O msind_Status será marcado como falso e o msind_requestStatus dentro de msind_Results será marcado como 935000002 (erro). As informações em msind_requeststatusdetail ajudarão você a identificar qual referência falhou na resolução.
Invoque a API de pacote de recuperação da API Web
A API de pacote de recuperação (msind_RetrieveBundle) tem um parâmetro de solicitação e pode ser invocada da seguinte forma:
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 obter a lista de consultas FHIR compatíveis, acesse Consultas FHIR compatíveis.
A resposta contém o status da solicitação completa e o status detalhado de cada recurso e seus 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.>"
}
Avisos comuns e cenários de erro
Esta seção lista alguns dos avisos e erros comumente vistos ao usar a API de pacote de recuperação.
ID de recurso FHIR inválido
Atualmente, o parâmetro de solicitação de consulta FHIR espera uma ID FHIR. Se o Dataverse não tiver um registro com a ID FHIR, a resposta será a seguinte:
{
"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
}
O mapa de atributos está desativado
Se a consulta de FHIR contiver uma pesquisa de elemento, a API de pacote de recuperação usará os mapas de atributos ativados para construir um JSON FHIR. Caso algum dos mapas de atributos dos elementos da consulta esteja desabilitado, a resposta será a seguinte:
{
"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
}
Write-back em um ponto de extremidade alternativo
Você pode configurar um ponto de extremidade alternativo no qual o serviço de write-back pode postar um pacote FHIR contendo o recurso FHIR criado ou atualizado. Para saber como configurar esse ponto de extremidade alternativo, consulte Configurações do ponto de extremidade de saída alternativo.
O pacote FHIR contém um único recurso (para todas as atualizações) que o ponto de extremidade alternativo pode processar. Esse processamento pode incluir a atualização da mensagem FHIR de saída ou o encaminhamento para outro ponto de extremidade. Quando o ponto de extremidade de recebimento conclui o processamento, o serviço de write-back espera um pacote de retorno contendo o resposta do serviço FHIR remoto. Essa resposta é necessária para atualizar o registro do Dataverse com a nova ID de versão do FHIR e os últimos valores modificados.
Se os pontos de extremidade alternativos postar em um serviço FHIR, como o serviço FHIR dos Serviços de Dados de Saúde do Azure, retornar o resposta do serviço FHIR deverá ser suficiente. Caso contrário, o desenvolvedor do ponto de extremidade alternativo deve construir essa resposta do pacote. Esse pacote deve ser do tipo resposta de lote e deve conter os detalhes atualizados do recurso FHIR.
Veja um exemplo de um pacote que contém o recurso FHIR Paciente que está sendo atualizado:
{
"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"
}
}
]
}
Veja a seguir um exemplo de resposta retornada para a mensagem anterior após postar no serviço FHIR dos Serviços de Dados de Saúde do 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"
}
}
]
}
As duas principais diferenças são os campos versionId e lastUpdated. Esses campos são obrigatórios para atualizar o registro do Dataverse na conclusão.
Uma segunda mensagem de saída é enviada contendo os detalhes do registro de Proveniência do FHIR. Esse recurso rastreia a atividade da atualização anterior do Paciente. Semelhante a outras atualizações, o serviço de write-back a posta como um pacote e espera que um pacote do tipo resposta de lote conclua a operação.
Veja um exemplo de postagem de proveniência e resposta para as mensagens de write-back anteriores. Nesse exemplo, o serviço de write-back posta um novo registro de proveniência e adiciona os metadados correspondentes à resposta.
{
"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 da resposta:
{
"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"
}
}
]
}