Exportar dados FHIR na API do Azure para FHIR
Importante
A API do Azure para FHIR será desativada em 30 de setembro de 2026. Siga as estratégias de migração para fazer a transição para FHIR® dos Serviços de Dados de Saúde do Azure até essa data. Devido à desativação da API do Azure para FHIR, novas implantações não serão permitidas a partir de 1º de abril de 2025. O serviço dos Serviços de Dados de Saúde do Azure para serviço FHIR é a versão evoluída da API do Azure para FHIR que permite aos clientes gerenciar os serviços FHIR, DICOM e serviço de tecnologia médica com integrações a outros serviços do Azure.
O recurso Exportação em Massa permite que os dados sejam exportados do Servidor FHIR® de acordo com a especificação FHIR.
Antes de usar $exporto , verifique se a API do Azure para FHIR está configurada para usá-la. Para definir as configurações de exportação e criar uma conta de armazenamento do Azure, consulte a página configurar dados de exportação.
Observação
Somente contas de armazenamento na mesma assinatura da API do Azure para FHIR podem ser registradas como o destino para operações $export.
Usando $export comando
Depois de configurar a API do Azure para FHIR para exportação, você pode usar o $export comando para exportar os dados para fora do serviço. Os dados são armazenados na conta de armazenamento especificada durante a configuração da exportação. Para saber como chamar o $export comando no servidor FHIR, leia a documentação na especificação HL7 FHIR $export.
Empregos presos em um estado ruim
Em algumas situações, um trabalho pode ficar preso em um estado ruim. Isso pode ocorrer se as permissões da conta de armazenamento não tiverem sido configuradas corretamente. Uma maneira de validar uma exportação é verificar sua conta de armazenamento para ver se os arquivos de contêiner correspondentes (ou seja, ndjson) estão presentes. Se eles não estiverem presentes e não houver outros trabalhos de exportação em execução, é possível que o trabalho atual esteja preso em um estado incorreto. Você deve cancelar o trabalho de exportação enviando uma solicitação de cancelamento e tentar enfileirar novamente o trabalho. Nosso tempo de execução padrão para uma exportação em mau estado é de 10 minutos antes que ela pare e mude para um novo trabalho ou tente novamente a exportação.
A API do Azure para FHIR dá suporte $export nos seguintes níveis:
- Sistema:
GET https://<<FHIR service base URL>>/$export>> - Paciente:
GET https://<<FHIR service base URL>>/Patient/$export>> - Grupo de pacientes* – a API do Azure para FHIR exporta todos os recursos relacionados, mas não exporta as características do grupo:
GET https://<<FHIR service base URL>>/Group/[ID]/$export>>
Os dados são exportados em vários arquivos, cada um contendo recursos de apenas um tipo. O número de recursos em um arquivo individual será limitado. O número máximo de recursos é baseado no desempenho do sistema. Atualmente, está definido como 5.000, mas pode mudar. O resultado é que você pode obter vários arquivos para um tipo de recurso. Os nomes dos arquivos seguem o formato 'resourceName-number-number.ndjson'. Não há garantia de que a ordem dos arquivos corresponda a qualquer ordenação dos recursos no banco de dados.
Observação
Patient/$export e Group/[ID]/$export pode exportar recursos duplicados se o recurso estiver em um compartimento de mais de um recurso ou estiver em vários grupos.
Além disso, há suporte para a verificação do status de exportação por meio da URL retornada pelo cabeçalho do local durante o enfileiramento, juntamente com o cancelamento do trabalho de exportação real.
Exportando dados FHIR para o ADLS Gen2
Atualmente, damos suporte $export a contas de armazenamento habilitadas para ADLS Gen2, com as seguintes limitações:
- Os usuários não podem tirar proveito de namespaces hierárquicos - não há uma maneira de direcionar uma exportação para um subdiretório específico dentro de um contêiner. Fornecemos apenas a capacidade de direcionar um contêiner específico (onde uma nova pasta é criada para cada exportação).
- Depois que uma exportação é concluída, nada é exportado para essa pasta novamente. As exportações subsequentes para o mesmo contêiner estarão dentro de uma pasta recém-criada.
Configurações e parâmetros
Cabeçalhos
Há dois parâmetros de cabeçalho necessários que devem ser definidos para $export trabalhos. Os valores são definidos pela especificação $export atual.
- Aceitar - application/fhir+json
- Preferir - responda assíncrono
Parâmetros de consulta
A API do Azure para FHIR dá suporte aos seguintes parâmetros de consulta. Todos esses parâmetros são opcionais.
| Parâmetro de consulta | Definido pela especificação FHIR? | Descrição |
|---|---|---|
| _outputFormat | Sim | Atualmente, dá suporte a três valores para alinhar à especificação FHIR: application/fhir+ndjson, application/ndjson ou ndjson. Todos os trabalhos de exportação retornam ndjson e o valor passado não tem efeito sobre o comportamento do código. |
| _desde | Sim | Permite exportar apenas recursos que foram modificados desde o tempo fornecido. |
| _type | Sim | Permite especificar quais tipos de recursos serão incluídos. Por exemplo, _type=Patient retornaria apenas recursos do paciente. |
| _typefilter | Sim | Para solicitar uma filtragem mais refinada, você pode usar _typefilter junto com o parâmetro _type. O valor do parâmetro _typeFilter é uma lista separada por vírgulas de consultas FHIR que restringem ainda mais os resultados. |
| _recipiente | Não | Especifica o contêiner dentro da conta de armazenamento configurada para onde os dados devem ser exportados. Se um contêiner for especificado, os dados serão exportados para uma pasta nesse contêiner. Se o contêiner não for especificado, os dados serão exportados para um novo contêiner. |
| _até | Não | Permite exportar apenas recursos que foram modificados até o tempo fornecido. Esse parâmetro só é aplicável à exportação no nível do sistema. Nesse caso, se as versões históricas não tiverem sido desabilitadas ou limpas, export garante uma exibição de instantâneo verdadeira. Em outras palavras, permite a viagem no tempo. |
| includeAssociatedData | Não | Permite exportar o histórico e os recursos excluídos de forma reversível. Esse filtro não funciona com o parâmetro de consulta '_typeFilter'. Inclua o valor como '_history' para exportar recursos de histórico (versão não mais recente). Inclua o valor como '_deleted' para exportar recursos excluídos de forma reversível. |
| _isparallel | Não | O parâmetro de consulta "_isparallel" pode ser adicionado à operação de exportação para aumentar sua taxa de transferência. O valor precisa ser definido como true para habilitar a paralelização. Observação: o uso desse parâmetro pode resultar em um aumento no consumo de unidades de solicitação durante a vida útil da exportação. |
Observação
Há um problema conhecido com a $export operação que pode resultar em exportações incompletas com status bem-sucedido. O problema ocorre quando o sinalizador is_parallel foi usado. Os trabalhos de exportação executados com _isparallel parâmetro de consulta a partir de 13 de fevereiro de 2024 são afetados por esse problema.
Exportação segura para o Armazenamento do Azure
A API do Azure para FHIR dá suporte a uma operação de exportação segura. Escolha uma das duas opções a seguir.
Permitir que a API do Azure para FHIR como um Serviço Confiável da Microsoft acesse a conta de armazenamento do Azure.
Permitir que endereços IP específicos associados à API do Azure para FHIR acessem a conta de armazenamento do Azure. Essa opção fornece duas configurações diferentes, dependendo se a conta de armazenamento está no mesmo local ou em um local diferente da API do Azure para FHIR.
Permitindo a API do Azure para FHIR como um Serviço Confiável da Microsoft
Selecione uma conta de armazenamento no portal do Azure e, em seguida, selecione a folha Rede . Selecione Redes selecionadas na guia Firewalls e redes virtuais.
Importante
Verifique se você concedeu permissão de acesso à conta de armazenamento para a API do Azure para FHIR usando sua identidade gerenciada. Para obter mais informações, consulte Definir a configuração de exportação e configurar a conta de armazenamento.
Na seção Exceções, marque a caixa Permitir que serviços confiáveis da Microsoft acessem esta conta de armazenamento e salve a configuração.
Agora você está pronto para exportar dados FHIR para a conta de armazenamento com segurança. Observação: A conta de armazenamento está em redes selecionadas e não pode ser acessada publicamente. Para acessar os arquivos, você pode habilitar e usar pontos de extremidade privados para a conta de armazenamento ou habilitar todas as redes para a conta de armazenamento por um curto período de tempo.
Importante
A interface do usuário será atualizada posteriormente para permitir que você selecione o tipo de recurso para a API do Azure para FHIR e uma instância de serviço específica.
Permitir que endereços IP específicos acessem a conta de armazenamento do Azure de outras regiões do Azure
No portal do Azure, acesse a conta do Azure Data Lake Storage Gen2.
No menu à esquerda, selecione Rede.
Selecione Habilitado a partir das redes virtuais e endereços IP selecionados.
Na seção Firewall, na caixa Intervalo de endereços, especifique o endereço IP. Adicionar intervalos de IP para permitir o acesso da Internet ou de suas redes locais. Você pode encontrar o endereço IP na tabela a seguir para a região do Azure em que o serviço FHIR é provisionado.
Região do Azure Endereço IP público Leste da Austrália 20.53.44.80 Canadá Central 20.48.192.84 Centro dos EUA 52.182.208.31 Leste dos EUA 20.62.128.148 Leste dos EUA 2 20.49.102.228 Leste dos EUA 2 EUAP 20.39.26.254 Norte da Alemanha 51.116.51.33 Centro-Oeste da Alemanha 51.116.146.216 Leste do Japão 20.191.160.26 Coreia Central 20.41.69.51 Centro-Norte dos EUA 20.49.114.188 Norte da Europa 52.146.131.52 Norte da África do Sul 102.133.220.197 Centro-Sul dos Estados Unidos 13.73.254.220 Sudeste Asiático 23.98.108.42 Norte da Suíça 51.107.60.95 Sul do Reino Unido 51.104.30.170 Oeste do Reino Unido 51.137.164.94 Centro-Oeste dos EUA 52.150.156.44 Europa Ocidental 20.61.98.66 Oeste dos EUA 2 40.64.135.77
Permitir que endereços IP específicos acessem a conta de armazenamento do Azure na mesma região
O processo de configuração para endereços IP na mesma região é exatamente como o procedimento anterior, exceto que você usa um intervalo de endereços IP específico no formato CIDR (Roteamento entre Domínios Sem Classe) (ou seja, 100.64.0.0/10). Você deve especificar o intervalo de endereços IP (100.64.0.0 a 100.127.255.255) porque um endereço IP para o serviço FHIR é alocado sempre que você faz uma solicitação de operação.
Observação
É possível usar um endereço IP privado dentro do intervalo de 10.0.2.0/24, mas não há garantia de que a operação será bem-sucedida nesse caso. Você pode tentar novamente se a solicitação de operação falhar, mas até usar um endereço IP dentro do intervalo de 100.64.0.0/10, a solicitação não será bem-sucedida.
Esse comportamento de rede para intervalos de endereços IP é por design. A alternativa é configurar a conta de armazenamento em uma região diferente.
Próximas etapas
Neste artigo, você aprendeu a exportar recursos FHIR usando $export o comando. Em seguida, para saber como exportar dados não identificados, consulte
Observação
FHIR® é uma marca registrada da HL7 e é usado com a permissão da HL7.