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 o serviço 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 FHIR dos Serviços de Dados de Saúde do Azure é a versão evoluída da API do Azure para FHIR que permite aos clientes gerir serviços FHIR, DICOM e MedTech com integrações noutros serviços do Azure.
A funcionalidade de Exportação em Massa permite que os dados sejam exportados do Servidor FHIR segundo a especificação FHIR.
Antes de usar $export, você deseja certificar-se de que 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.
Nota
Somente contas de armazenamento na mesma assinatura da API do Azure para FHIR podem ser registradas como destino para operações $export.
Usando $export comando
Depois de configurar a API do Azure para FHIR para exportação, você pode usar o comando $export para exportar os dados para fora do serviço. Os dados serão armazenados na conta de armazenamento que você especificou durante a configuração da exportação. Para saber como invocar $export comando no servidor FHIR, leia a documentação sobre a especificação de $export FHIR HL7.
Empregos presos em mau estado
Em algumas situações, existe a possibilidade de um emprego ficar preso em mau estado. Isso pode ocorrer especialmente se as permissões da conta de armazenamento não tiverem sido configuradas corretamente. Uma maneira de validar a exportação é verificar sua conta de armazenamento para ver se os arquivos de contêiner (ou seja, ndjson) correspondentes estão presentes. Se eles não estiverem presentes, e não houver outros trabalhos de exportação em execução, então há uma possibilidade de que o trabalho atual esteja preso em um mau estado. Você deve cancelar o trabalho de exportação enviando uma solicitação de cancelamento e tentar enfileirar o trabalho novamente. Nosso tempo de execução padrão para uma exportação em mau estado é de 10 minutos antes que ela pare e passe para um novo trabalho ou tente novamente a exportação.
A API do Azure para FHIR dá suporte a $export nos seguintes níveis:
- Sistema:
GET https://<<FHIR service base URL>>/$export>> - Doente:
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>>
Com a exportação, 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 para 5.000, mas pode mudar. O resultado é que você pode obter vários arquivos para um tipo de recurso. Os nomes dos ficheiros seguirão o formato 'resourceName-number-number.ndjson'. Não é garantido que a ordem dos ficheiros corresponda a qualquer ordenação dos recursos na base de dados.
Nota
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, a verificação do status de exportação por meio da URL retornada pelo cabeçalho do local durante o enfileiramento é suportada, juntamente com o cancelamento do trabalho de exportação real.
Exportando dados FHIR para ADLS Gen2
Atualmente, suportamos $export para contas de armazenamento habilitadas para ADLS Gen2, com a seguinte limitação:
- O usuário não pode aproveitar os namespaces hierárquicos, mas não há uma maneira de direcionar a exportação para um subdiretório específico dentro do contêiner. Nós fornecemos apenas a capacidade de direcionar um contêiner específico (onde criamos uma nova pasta para cada exportação).
- Quando uma exportação estiver concluída, nunca mais exportaremos nada para essa pasta, uma vez que as exportações subsequentes para o mesmo contêiner estarão dentro de uma pasta recém-criada.
Definiçõ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 - respond-async
Parâmetros de consultas
A API do Azure para FHIR dá suporte aos seguintes parâmetros de consulta. Todos estes parâmetros são opcionais:
| Parâmetro de consulta | Definido pela especificação FHIR? | Description |
|---|---|---|
| _outputFormat | Sim | Atualmente suporta três valores para alinhar com a 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. |
| _since | 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=Paciente devolveria apenas os recursos do paciente |
| _typefilter | Sim | Para solicitar 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 |
| _container | 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. |
| _till | Não | Permite exportar apenas recursos que foram modificados até o tempo fornecido. Este parâmetro é aplicável apenas à exportação no nível do sistema. Nesse caso, se as versões históricas não tiverem sido desativadas ou limpas, a exportação garante uma verdadeira visualização de instantâneo ou, em outras palavras, permite a viagem no tempo. |
| includeAssociatedData | Não | Permite exportar histórico e recursos excluídos suavemente. Este filtro não funciona com o parâmetro de consulta '_typeFilter'. Inclua o valor como '_history' para exportar recursos com histórico de exportação/versões não mais recentes. Inclua o valor como '_deleted' para exportar recursos excluídos por software. |
| _isparallel | Não | O parâmetro de consulta "_isparallel" pode ser adicionado à operação de exportação para melhorar sua taxa de transferência. O valor precisa ser definido como true para permitir a paralelização. É importante notar que o uso deste parâmetro pode resultar em um aumento no consumo das unidades de solicitação ao longo da vida de exportação. |
Nota
Há um problema conhecido com a operação $export que pode resultar em exportações incompletas com status de sucesso. 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 abaixo:
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 do 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
Certifique-se de ter concedido permissão de acesso à conta de armazenamento para a API do Azure para FHIR usando sua identidade gerenciada. Para obter mais informações, consulte Configurar 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 essa conta de armazenamento e salve a configuração.
Agora você está pronto para exportar dados FHIR para a conta de armazenamento com segurança. Observe que a conta de armazenamento está em redes selecionadas e não é acessível 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, vá para a conta do Azure Data Lake Storage Gen2.
No menu à esquerda, selecione Rede.
Selecione Ativado a partir de redes virtuais e endereços IP selecionados.
Na seção Firewall, na caixa Intervalo de endereços, especifique o endereço IP. Adicione intervalos de IP para permitir o acesso a partir da Internet ou das suas redes locais. Você pode encontrar o endereço IP na tabela a seguir para a região do Azure onde 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 E.U.A. Central 52.182.208.31 E.U.A. Leste 20.62.128.148 E.U.A. Leste 2 20.49.102.228 E.U.A. Leste 2 - EUAP 20.39.26.254 Norte da Alemanha 51.116.51.33 Alemanha Centro-Oeste 51.116.146.216 Leste do Japão 20.191.160.26 Coreia do Sul Central 20.41.69.51 E.U.A. Centro-Norte 20.49.114.188 Europa do Norte 52.146.131.52 Norte da África do Sul 102.133.220.197 E.U.A. Centro-Sul 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 E.U.A. Centro-Oeste 52.150.156.44 Europa Ocidental 20.61.98.66 E.U.A. Oeste 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) em vez disso (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 cada vez que você faz uma solicitação de operação.
Nota
É 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 terá sucesso em tal 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 terá êxito.
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óximos passos
Neste artigo, você aprendeu como exportar recursos FHIR usando $export comando. Em seguida, para saber como exportar dados não identificados, consulte
FHIR® é uma marca registada da HL7 e é utilizada com a permissão da HL7.