Exportación de datos de FHIR en Azure API for FHIR
Importante
Azure API for FHIR se retirará el 30 de septiembre de 2026. Siga las estrategias de migración para realizar la transición al servicio FHIR de Azure Health Data Services en esa fecha. Debido a la retirada de Azure API for FHIR, no se permitirán nuevas implementaciones a partir del 1 de abril de 2025. El servicio FHIR de Azure Health Data Services es la versión evolucionada de la API de Azure para FHIR que permite a los clientes administrar FHIR, DICOM y los servicios de tecnologías médicas con integraciones en otros servicios de Azure.
La característica de exportación masiva permite exportar datos desde el servidor de FHIR según la especificación FHIR.
Antes de usar $export, quiere asegurarse de que Azure API for FHIR está configurado para usarlo. Para configurar las opciones de exportación y crear una cuenta de almacenamiento de Azure, consulte la página de configuración de los datos de exportación.
Nota:
Solo se permiten registrar cuentas de almacenamiento en la misma suscripción que para Azure API for FHIR como destino para las operaciones de $export.
Uso del comando $export
Después de configurar Azure API for FHIR para la exportación, puede usar el comando $export para exportar los datos fuera del servicio. Los datos se almacenarán en la cuenta de almacenamiento que especificó al configurar la exportación. Para más información sobre cómo invocar el comando $export en el servidor de FHIR, lea la documentación sobre la especificación de $export del estándar FHIR de HL7.
Trabajos bloqueados en estado incorrecto
En algunas situaciones, existe la posibilidad de que un trabajo se quede bloqueado en un estado incorrecto. Esto puede ocurrir especialmente si los permisos de la cuenta de almacenamiento no se han configurado correctamente. Una manera de validar la exportación es comprobar la cuenta de almacenamiento para ver si los archivos del contenedor correspondiente (es decir, ndjson) están presentes. Si no están presentes y no hay ningún otro trabajo de exportación en ejecución, existe la posibilidad de que el trabajo actual esté bloqueado en un estado incorrecto. Debe cancelar el trabajo de exportación enviando una solicitud de cancelación e intenta volver a poner en cola el trabajo. El tiempo de ejecución predeterminado para una exportación en estado incorrecto es de 10 minutos antes de que se detenga y se mueva a un nuevo trabajo o la exportación se vuelva a intentar.
Azure API for FHIR admite $export en los siguientes niveles:
- Sistema:
GET https://<<FHIR service base URL>>/$export>> - Paciente:
GET https://<<FHIR service base URL>>/Patient/$export>> - Grupo de pacientes*: Azure API for FHIR exporta todos los recursos relacionados, pero no exporta las características del grupo:
GET https://<<FHIR service base URL>>/Group/[ID]/$export>>
Con la exportación, los datos se exportan en varios archivos, cada uno de los cuales contiene recursos de un solo tipo. El número de recursos de un archivo individual estará limitado. El número máximo de recursos se basa en el rendimiento del sistema. Actualmente está establecido en 5000, pero puede cambiar. El resultado es que puede obtener varios archivos para un tipo de recurso. Los nombres de archivo seguirán el formato "resourceName-number-number.ndjson". No se garantiza que el orden de los archivos se corresponda con ninguna ordenación de los recursos de la base de datos.
Nota:
Patient/$export y Group/[ID]/$export pueden exportar recursos duplicados si el recurso está en un compartimiento de más de un recurso o se encuentra en varios grupos.
Además, se admite la comprobación del estado de exportación a través de la dirección URL devuelta por el encabezado de ubicación durante la puesta en cola, junto con la cancelación del trabajo de exportación real.
Exportación de datos de FHIR a ADLS Gen2
Actualmente se admiten $export para las cuentas de almacenamiento habilitadas para ADLS Gen2, con la siguiente limitación:
- El usuario no puede aprovechar los espacios de nombres jerárquicos, pero no hay una manera de dirigirse a la exportación a un subdirectorio específico dentro del contenedor. Solo se ofrece la posibilidad de destinar a un contenedor específico (donde crearemos una carpeta para cada exportación).
- Una vez completada la exportación, nunca se exporta nada de nuevo a esa carpeta, ya que las exportaciones posteriores al mismo contenedor estarán dentro de una carpeta recién creada.
Configuración y parámetros
Encabezados
Hay dos parámetros de encabezado necesarios que se deben establecer para los trabajos de $export. Los valores se definen mediante la especificación de $export actual.
- Accept (Aceptar): application/fhir+json.
- Prefer (Preferir): respond-async.
Parámetros de consulta
Azure API for FHIR admite los siguientes parámetros de consulta. Todos estos parámetros son opcionales:
| Parámetro de consulta | ¿Se define mediante la especificación de FHIR? | Descripción |
|---|---|---|
| _outputFormat | Sí | Actualmente admite tres valores para alinearse con la especificación de FHIR: application/fhir+ndjson, application/ndjson o ndjson. Todos los trabajos de exportación devuelven ndjson y el valor pasado no tiene ningún efecto en el comportamiento del código. |
| _Desde | Sí | Permite exportar solo los recursos que se han modificado desde el momento indicado. |
| _type | Sí | Permite especificar los tipos de recursos que se van a incluir. Por ejemplo, _type=Patient devolvería solo los recursos del paciente. |
| _typefilter | Sí | Para solicitar un filtrado más preciso, puede usar _typefilter junto con el parámetro _type. El valor del parámetro _typeFilter es una lista separada por comas de consultas de FHIR que restringen aún más los resultados. |
| _Contenedor | No | Especifica el contenedor en la cuenta de almacenamiento configurada donde se deben exportar los datos. Si se especifica un contenedor, los datos se exportarán a una carpeta en ese contenedor. Si no se especifica el contenedor, los datos se exportarán a un nuevo contenedor. |
| _Hasta | No | Permite exportar solo los recursos que se han modificado hasta el momento proporcionado. Este parámetro solo es aplicable a la exportación de nivel de sistema. En este caso, si las versiones históricas no se han deshabilitado o purgado, la exportación garantiza una vista de instantánea verdadera o, en otras palabras, permite el viaje en el tiempo. |
| includeAssociatedData | No | Permite exportar el historial y los recursos eliminados temporalmente. Este filtro no funciona con el parámetro de consulta "_typeFilter". Incluya el valor como "_history" para exportar el historial o los recursos con versiones no más recientes. Incluya el valor como "_deleted" para exportar recursos eliminados temporalmente. |
| _isparallel | No | El parámetro de consulta "_isparallel" se puede agregar a la operación de exportación para mejorar su rendimiento. El valor debe establecerse en true para habilitar la paralelización. Es importante tener en cuenta que el uso de este parámetro puede dar lugar a un aumento del consumo de unidades de solicitud durante la vida útil de la exportación. |
Nota:
Hay un problema conocido con la operación de $export que podría dar lugar a exportaciones incompletas con el estado correcto. El problema se produce cuando se usó la marca is_parallel. Los trabajos de exportación ejecutados con _isparallel parámetro de consulta a partir del 13 de febrero de 2024 se ven afectados con este problema.
Exportación segura a Azure Storage
Azure API for FHIR admite una operación de exportación segura. Elija una de las dos opciones siguientes:
Permitir que Azure API for FHIR sea un servicio de confianza de Microsoft para acceder a la cuenta de almacenamiento de Azure.
Permitir que direcciones IP específicas asociadas a Azure API for FHIR accedan a la cuenta de Azure Storage. Esta opción proporciona dos configuraciones diferentes en función de si la cuenta de almacenamiento está en la misma ubicación que o está en una ubicación diferente de la de Azure API for FHIR.
Permitir Azure API for FHIR como servicio de confianza de Microsoft
Seleccione una cuenta de almacenamiento en Azure Portal y luego seleccione la hoja Redes. Seleccione Redes seleccionadas en la pestaña Firewalls y redes virtuales.
Importante
Asegúrese de que ha concedido permiso de acceso a la cuenta de almacenamiento para Azure API for FHIR mediante su identidad administrada. Para más información, consulte Configuración de la configuración de exportación y configuración de la cuenta de almacenamiento.
En la sección Excepciones, seleccione Permitir que los servicios de Microsoft de confianza accedan a esta cuenta de almacenamiento y guarde la configuración.
Ya está listo para exportar datos de FHIR a la cuenta de almacenamiento de forma segura. Tenga en cuenta que la cuenta de almacenamiento está en redes seleccionadas y no es accesible públicamente. Para acceder a los archivos, puede habilitar y usar puntos de conexión privados para la cuenta de almacenamiento, o bien habilitar todas las redes para la cuenta de almacenamiento durante un breve período de tiempo.
Importante
La interfaz de usuario se actualizará más adelante para permitirle seleccionar el tipo de recurso para Azure API for FHIR y una instancia de servicio específica.
Permitir que direcciones IP específicas accedan a la cuenta de Almacenamiento de Azure desde otras regiones de Azure
En Azure Portal, vaya a la cuenta de Azure Data Lake Storage Gen2.
En el menú de la izquierda, seleccione Redes.
Seleccione Habilitado desde redes virtuales y direcciones IP seleccionadas.
En la sección Firewall , en el cuadro Intervalo de direcciones, especifique la dirección IP. Agregue intervalos IP para permitir el acceso desde Internet o redes locales. Puede encontrar la dirección IP en la tabla siguiente para la región de Azure donde se aprovisiona el servicio FHIR.
Región de Azure Dirección IP pública Este de Australia 20.53.44.80 Centro de Canadá 20.48.192.84 Centro de EE. UU. 52.182.208.31 Este de EE. UU. 20.62.128.148 Este de EE. UU. 2 20.49.102.228 EUAP de Este de EE. UU. 2 20.39.26.254 Norte de Alemania 51.116.51.33 Centro-oeste de Alemania 51.116.146.216 Japón Oriental 20.191.160.26 Centro de Corea del Sur 20.41.69.51 Centro-Norte de EE. UU 20.49.114.188 Norte de Europa 52.146.131.52 Norte de Sudáfrica 102.133.220.197 Centro-sur de EE. UU. 13.73.254.220 Sudeste de Asia 23.98.108.42 Norte de Suiza 51.107.60.95 Sur de Reino Unido 2 51.104.30.170 Oeste de Reino Unido 51.137.164.94 Centro-Oeste de EE. UU. 52.150.156.44 Oeste de Europa 20.61.98.66 Oeste de EE. UU. 2 40.64.135.77
Permitir que direcciones IP específicas accedan a la cuenta de almacenamiento de Azure en la misma región
El proceso de configuración de las direcciones IP de la misma región es igual que el procedimiento anterior, salvo que se usa un intervalo de direcciones IP específico en formato de enrutamiento entre dominios sin clases (CIDR) en su lugar (es decir, 100.64.0.0/10). Debe especificar el intervalo de direcciones IP (100.64.0.0 a 100.127.255.255) porque se asigna una dirección IP para el servicio FHIR cada vez que realice una solicitud de operación.
Nota:
Es posible usar una dirección IP privada dentro del intervalo de 10.0.2.0/24, pero no hay ninguna garantía de que la operación se realice correctamente en tal caso. Puede reintentar si se produce un error en la solicitud de operación, pero hasta que use una dirección IP dentro del intervalo de 100.64.0.0/10, la solicitud no se realizará correctamente.
Este comportamiento de red para los intervalos de direcciones IP es por diseño. La alternativa es configurar la cuenta de almacenamiento en una región diferente.
Pasos siguientes
En este artículo, ha aprendido a exportar recursos de FHIR mediante el comando $export. A continuación, para obtener información sobre cómo exportar datos desidentificados, consulte
FHIR® es una marca registrada de HL7 y se usa con su permiso.