Usar as Dataverse Healthcare APIs

Artigo
11/08/2023

As Dataverse Healthcare APIs contêm pontos de extremidade de API personalizados que permitem que você troque dados FHIR 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 ser ativados. Caso o pacote contenha recursos para os quais os mapas de entidade não foram ativados, a resposta exibe 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 ter marcado intencionalmente o mapa de entidade como desabilitado para não ingerir recursos de "Paciente", mesmo que estejam no pacote.

Mapa inválido

Os mapas de atributos conduzem as transformações entre Dataverse e FHIR. Um dos elementos-chave nos mapas de atributos que conduzem essa transformação é o mapa do elemento FHIR, que espera um JPath. Se o JPath estiver incorreto, 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_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 (para obter mais informações, acesse Referências FHIR). A API de Pacote Upsert tenta resolver essas referências ao fazer 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)."
        } 
    ]
}

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
}

Confira também

O que é o Microsoft Cloud for Healthcare?
Gerenciar dados de FHIR usando o kit de ferramentas de integração de dados Visão geral das Dataverse Healthcare APIs
Configurar as Dataverse Healthcare APIs
Revisar logs das Dataverse Healthcare APIs

Compartilhar via

Usar as Dataverse Healthcare APIs

Invoque a API upsert bundle da API Web

Avisos comuns e cenários de erro

O mapa de entidade está desativado

Mapa inválido

A integridade referencial é perdida

Invoque a API de pacote de recuperação da API Web

Avisos comuns e cenários de erro

ID de recurso FHIR inválido

O mapa de atributos está desativado

Confira também

Recursos adicionais