Operação de importação

  • Artigo

A operação de importação permite carregar dados FHIR® (Fast Healthcare Interoperability Resources) para o servidor FHIR com alta taxa de transferência usando a operação de $import. A importação dá suporte à carga de dados inicial e incremental no servidor FHIR.

Usando $import operação

Observação

Você deve ter a função importador de dados FHIR no servidor FHIR para usar $import.

Para usar $import, você precisa configurar o servidor FHIR usando as instruções no artigo Definir configurações de importação . Os dados FHIR a serem importados devem ser armazenados em arquivos específicos do recurso no formato FHIR NDJSON no repositório de blobs do Azure.

Para a operação de importação, verifique

  • Todos os recursos em um arquivo devem ser do mesmo tipo. Você pode ter vários arquivos por tipo de recurso.
  • Os dados a serem importados devem estar no mesmo locatário do serviço FHIR.
  • O número máximo de arquivos a serem importados por operação é de 10.000.

Observação:

  • A operação de importação não dá suporte a referências condicionais em recursos.
  • Durante a operação de importação, se vários recursos compartilharem a mesma ID de recurso, apenas um desses recursos será importado aleatoriamente. Há um erro registrado para os recursos que compartilham a mesma ID de recurso.

Chamando $import

Faça uma POST chamada para <<FHIR service base URL>>/$import com o cabeçalho e o corpo da solicitação mostrados:

Cabeçalho da solicitação

Prefer:respond-async
Content-Type:application/fhir+json

Corpo

Nome do Parâmetro Descrição Cartão. Valores aceitos
inputFormat Cadeia de caracteres que representa o nome do formato da fonte de dados. Atualmente, há suporte apenas para arquivos FHIR NDJSON. 1..1 application/fhir+ndjson
mode Valor do modo de importação 1..1 Para o valor inicial do modo de uso InitialLoad de importação. Para o modo de importação incremental, use IncrementalLoad o valor do modo. Se nenhum valor de modo for fornecido, o valor do modo IncrementalLoad será considerado por padrão.
input Detalhes dos arquivos de entrada. 1..* Uma matriz JSON com três partes descritas na tabela abaixo.
Nome da parte de entrada Descrição Cartão. Valores aceitos
tipo Tipo de recurso do arquivo de entrada 1..1 Um tipo de recurso FHIR válido que corresponde ao arquivo de entrada.
URL URL de armazenamento do Azure do arquivo de entrada 1..1 Valor de URL do arquivo de entrada que não pode ser modificado.
etag Etag do arquivo de entrada no armazenamento do Azure usado para verificar se o conteúdo do arquivo não foi alterado. 0..1 Valor de Etag do arquivo de entrada que não pode ser modificado.

Corpo de exemplo para importação de carga inicial:

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputFormat",
            "valueString": "application/fhir+ndjson"
        },
        {
            "name": "mode",
            "valueString": "InitialLoad"
        },
        {
            "name": "input",
            "part": [
                {
                    "name": "type",
                    "valueString": "Patient"
                },
                {
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/Patient.ndjson"
                },
                {
                    "name": "etag",
                    "valueUri": "0x8D92A7342657F4F"
                }
            ]
        },
        {
            "name": "input",
            "part": [
                {
                    "name": "type",
                    "valueString": "CarePlan"
                },
                {
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/CarePlan.ndjson"
                }
            ]
        }
    ]
}

Verificando status de importação

Depois que $import é iniciado, um corpo de resposta vazio com um link de retorno de chamada é retornado no Content-location cabeçalho da resposta junto com 202-Accepted status código. Armazene esse link de retorno de chamada para marcar o status de importação.

Para marcar importar status, faça a chamada REST com o GET método para o link de retorno de chamada retornado na etapa anterior. Você pode interpretar a resposta usando a tabela a seguir:

Código de resposta Corpo da resposta Descrição
202 Aceito A operação ainda está em execução.
200 OK O corpo da resposta não contém nenhuma entrada error.url Todos os recursos foram importados com êxito.
200 OK O corpo da resposta contém uma entrada error.url Erro ao importar alguns dos recursos. Consulte os arquivos localizados em error.url para obter os detalhes. O restante dos recursos foi importado com êxito.
Outro Ocorreu um erro fatal e a operação foi interrompida. Os recursos importados com êxito não foram revertidos.

A tabela a seguir fornece alguns dos campos importantes no corpo da resposta:

Campo Descrição
transactionTime Hora de início da operação de importação em massa.
output.count Contagem de recursos que foram importados com êxito
error.count Contagem de recursos que não foram importados devido a algum erro
error.url URL do arquivo que contém detalhes do erro. Cada error.url é exclusivo de uma URL de entrada.

Resposta de exemplo:

{
    "transactionTime": "2021-07-16T06:46:52.3873388+00:00",
    "request": "https://importperf.azurewebsites.net/$Import",
    "output": [
        {
            "type": "Patient",
            "count": 10000,
            "inputUrl": "https://example.blob.core.windows.net/resources/Patient.ndjson"
        },
        {
            "type": "CarePlan",
            "count": 199949,
            "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.ndjson"
        }
    ],
    "error": [
        { 
        "type": "OperationOutcome",
        "count": 51,
        "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.ndjson",
        "url": "https://example.blob.core.windows.net/fhirlogs/CarePlan06b88c6933a34c7c83cb18b7dd6ae3d8.ndjson"
        }
    ]
}

Solução de problemas

Permite soluções passo a passo para alguns códigos de erro que você pode encontrar durante a operação de importação.

200 OK, mas há um erro com a URL na resposta

Comportamento: A operação de importação é bem-sucedida e retorna 200 OK. No entanto, error.url estão presentes no corpo da resposta. Os arquivos presentes no error.url local contêm fragmentos JSON semelhantes ao exemplo abaixo:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "details": {
                "text": "Given conditional reference '{0}' does'nt resolve to a resource."
            },
            "diagnostics": "Failed to process resource at line: {0} with stream start offset: {1}"
        }
    ]
}

Causa: Os arquivos NDJSON contêm recursos com referências condicionais, que atualmente não têm suporte do $import.

Solução: Substitua as referências condicionais a referências normais nos arquivos NDJSON.

400 Solicitação Inválida

Comportamento: Falha na operação de importação e 400 Bad Request é retornada. O corpo da resposta tem o seguinte conteúdo:

{
    "resourceType": "OperationOutcome",
    "id": "13876ec9-3170-4525-87ec-9e165052d70d",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: No such host is known. (example.blob.core.windows.net:443)"
        }
    ]
}

Solução: Verifique se o link para o armazenamento do Azure está correto. Verifique as configurações de rede e firewall para garantir que o servidor FHIR possa acessar o armazenamento. Se o serviço estiver em uma VNet, verifique se o armazenamento está na mesma VNet ou em uma VNet que tenha emparelhamento com a VNet do serviço FHIR.

403 Proibido

Comportamento: Falha na operação de importação e 403 Forbidden é retornada. O corpo da resposta tem o seguinte conteúdo:

{
    "resourceType": "OperationOutcome",
    "id": "bd545acc-af5d-42d5-82c3-280459125033",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature."
        }
    ]
}

Causa: Usamos a identidade gerenciada para autenticação de armazenamento de origem. Esse erro pode ser causado por uma atribuição de função ausente ou incorreta.

Solução: Atribua a função colaborador de dados de blob de armazenamento ao servidor FHIR seguindo o guia do RBAC.

Erro interno de servidor 500

Comportamento: Falha na operação de importação e 500 Internal Server Error é retornada. O corpo da resposta tem o seguinte conteúdo:

{
    "resourceType": "OperationOutcome",
    "id": "0d0f007d-9e8e-444e-89ed-7458377d7889",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: The database '****' has reached its size quota. Partition or delete data, drop indexes, or consult the documentation for possible resolutions."
        }
    ]
}

Causa: Você atingiu o limite de armazenamento do serviço FHIR.

Solução: Reduza o tamanho dos dados ou considere a API do Azure para FHIR, que tem um limite de armazenamento maior.

Próximas etapas

Neste artigo, você aprendeu sobre como a operação de importação permite importar dados FHIR para o servidor FHIR com alta taxa de transferência. Para obter mais informações sobre como converter dados em FHIR, exportar configurações para configurar uma conta de armazenamento e mover dados para Azure Synapse, consulte

Convertendo seus dados em FHIR

Definir configurações de exportação e configurar uma conta de armazenamento

Copiar dados da API do Azure para FHIR para o Azure Synapse Analytics

FHIR® é uma marca registrada da HL7 e é usado com a permissão da HL7.