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 dos Serviços de Dados de Saúde do Azure para serviço FHIR 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 de exportação em massa permite que os dados sejam exportados do servidor FHIR de acordo com a especificação FHIR.
Antes de usar $export, verifique se a API do Azure para FHIR está configurada para usá-la. Para definir as configurações de exportação e criar a conta de armazenamento do Azure, consulte a página Configurar dados de exportação.
Observação
Somente as contas de armazenamento na mesma assinatura da API do Azure para FHIR podem ser registradas como destino para $export operações.
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 especificada 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, há um potencial para um trabalho ficar preso em um estado ruim. 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, existe a possibilidade de o trabalho atual estar preso em um estado ruim. 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 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>> - 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>>
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 arquivos seguirão o formato 'resourceName-number-number.ndjson'. Não é garantido que a ordem dos arquivos corresponda a qualquer ordem 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, 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 o ADLS Gen2
Atualmente, oferecemos suporte a $export para contas de armazenamento habilitadas para ADLS Gen2, com a seguinte limitação:
- O usuário não pode tirar proveito de 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 só fornecemos a capacidade de segmentar 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, pois 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
- Prefira - 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 | Yes | Atualmente, oferece 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 | Yes | Permite exportar apenas recursos que foram modificados desde o tempo fornecido |
| _type | Yes | Permite especificar quais tipos de recursos serão incluídos. Por exemplo, _type=Paciente retornaria apenas recursos do paciente |
| _typefilter | Yes | Para solicitar uma filtragem mais refinada, você pode usá_typefilter junto com o parâmetro _type. O valor do parâmetro _typeFilter é uma lista separada por vírgulas de consultas FHIR que restringe 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 é aplicável somente à exportação em nível de sistema. Nesse caso, se as versões históricas não tiverem sido desativadas ou removidas, a exportação garante a visualização verdadeira do instantâneo ou, em outras palavras, permite a viagem no tempo. |
| includeAssociatedData | Não | Permite exportar histórico e recursos excluídos suaves. Esse filtro não funciona com o parâmetro de consulta '_typeFilter'. Inclua o valor como '_history' para exportar recursos com a versão não mais recente. Inclua o valor como '_deleted' para exportar recursos excluídos flexíveis. |
| _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 ressaltar que o uso desse parâmetro pode resultar em um aumento no consumo das unidades de solicitação ao longo da vida útil da exportação. |
Observação
Há um problema conhecido com a operação $export que pode resultar em exportações incompletas com status de sucesso. 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 com 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 daquele 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 da 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 essa conta de armazenamento e salvem 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 está 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 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 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 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 é semelhante ao 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 em tal caso. Você pode tentar novamente se a solicitação de operação falhar, mas até que você use 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óximas etapas
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 registrada da HL7 e é usado com a permissão da HL7.