Operación de importación
La operación de importación permite cargar datos rápidos de recursos de interoperabilidad sanitaria (FHIR®) en el servidor de FHIR con un alto rendimiento mediante la operación de $import. La importación admite la carga de datos inicial e incremental en el servidor FHIR.
Uso de $import operación
Nota
Debe tener el rol FHIR Data Importer en el servidor FHIR para usar $import.
Para usar $import, debe configurar el servidor FHIR mediante las instrucciones del artículo Configuración de las opciones de importación . Los datos de FHIR que se van a importar deben almacenarse en archivos específicos del recurso en formato FHIR NDJSON en el almacén de blobs de Azure.
Para la operación de importación, asegúrese de
- Todos los recursos de un archivo deben ser del mismo tipo. Es posible que tenga varios archivos por tipo de recurso.
- Los datos que se van a importar deben estar en el mismo inquilino que el servicio FHIR.
- El número máximo de archivos que se van a importar por operación es de 10 000.
Nota:
- La operación de importación no admite referencias condicionales en recursos.
- Durante la operación de importación, si varios recursos comparten el mismo identificador de recurso, solo se importa uno de esos recursos de forma aleatoria. Se ha registrado un error para que los recursos compartan el mismo identificador de recurso.
Llamada a $import
Realice una POST llamada a <<FHIR service base URL>>/$import con el encabezado y el cuerpo de la solicitud que se muestran:
Encabezado de la solicitud
Prefer:respond-async
Content-Type:application/fhir+json
Cuerpo
| Nombre de parámetro | Descripción | Tarjeta. | Valores aceptados |
|---|---|---|---|
| formatoDeEntrada | Cadena que representa el nombre del formato del origen de datos. Actualmente solo se admiten archivos FHIR NDJSON. | 1..1 | application/fhir+ndjson |
| mode | Valor del modo de importación | 1..1 | Para el valor del modo de uso InitialLoad de importación inicial. Para el valor del modo de importación incremental, use IncrementalLoad el valor del modo . Si no se proporciona ningún valor de modo, el valor del modo IncrementalLoad se considera de forma predeterminada. |
| input | Detalles de los archivos de entrada. | 1..* | Matriz JSON con tres partes descritas en la tabla siguiente. |
| Nombre del elemento de entrada | Descripción | Tarjeta. | Valores aceptados |
|---|---|---|---|
| tipo | Tipo de recurso de archivo de entrada | 1..1 | Tipo de recurso FHIR válido que coincide con el archivo de entrada. |
| Resolución | Dirección URL de Almacenamiento de Azure del archivo de entrada | 1..1 | Valor de dirección URL del archivo de entrada que no se puede modificar. |
| ETag | Etag del archivo de entrada en Azure Storage usado para comprobar que el contenido del archivo no ha cambiado. | 0..1 | Valor Etag del archivo de entrada que no se puede modificar. |
Cuerpo de ejemplo para importación 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"
}
]
}
]
}
Comprobación del estado de importación
Una vez que se inicia $import, se devuelve un cuerpo de respuesta vacío con un vínculo de devolución de llamada en el encabezado de la respuesta junto con 202-Accepted el Content-location código de estado. Almacene este vínculo de devolución de llamada para comprobar el estado de importación.
Para comprobar el estado de importación, realice la llamada REST con el GET método al vínculo de devolución de llamada devuelto en el paso anterior.
Puede interpretar la respuesta mediante la tabla siguiente:
| Response code | Response body | Descripción |
|---|---|---|
| 202 - Aceptado | La operación todavía se está ejecutando. | |
| 200 OK | El cuerpo de la respuesta no contiene ninguna entrada error.url. | Todos los recursos se importaron correctamente. |
| 200 OK | El cuerpo de la respuesta contiene alguna entrada error.url. | Error al importar algunos de los recursos. Consulte los archivos ubicados en error.url para obtener los detalles. El resto de los recursos se importaron correctamente. |
| Otros | Se ha producido un error irrecuperable y la operación se ha detenido. Los recursos importados correctamente no se han revertido. |
En la tabla siguiente se proporcionan algunos de los campos importantes en el cuerpo de la respuesta:
| Campo | Descripción |
|---|---|
| transactionTime | Hora de inicio de la operación de importación masiva. |
| output.count | Recuento de recursos que se importaron correctamente |
| error.count | Recuento de recursos que no se importaron debido a algún error |
| error.url | Dirección URL del archivo que contiene los detalles del error. Cada error.url es único para una dirección URL de entrada. |
Respuesta de ejemplo:
{
"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"
}
]
}
Solución de problemas
Permite realizar un tutorial de soluciones a algunos códigos de error que se pueden encontrar durante la operación de importación.
200 CORRECTO, pero hay un error con la dirección URL en la respuesta.
Comportamiento: La operación de importación se realiza correctamente y devuelve 200 OK. Sin embargo, error.url están presentes en el cuerpo de la respuesta. Los archivos presentes en la error.url ubicación contienen fragmentos JSON similares al ejemplo siguiente:
{
"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: Los archivos NDJSON contienen recursos con referencias condicionales, que actualmente no son compatibles con $import.
Solución: Reemplace las referencias condicionales a referencias normales en los archivos NDJSON.
400 - Solicitud incorrecta
Comportamiento: Error en la operación de importación y 400 Bad Request se devuelve. El cuerpo de la respuesta tiene el siguiente contenido:
{
"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)"
}
]
}
Solución: Compruebe que el vínculo al almacenamiento de Azure es correcto. Compruebe la configuración de red y firewall para asegurarse de que el servidor FHIR puede acceder al almacenamiento. Si el servicio está en una red virtual, asegúrese de que el almacenamiento está en la misma red virtual o en una red virtual que tenga emparejamiento con la red virtual del servicio FHIR.
403 Prohibido
Comportamiento: Error en la operación de importación y 403 Forbidden se devuelve. El cuerpo de la respuesta tiene el siguiente contenido:
{
"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 la identidad administrada para la autenticación de almacenamiento de origen. Este error puede deberse a una asignación de roles que falta o no es correcta.
Solución: Asigne el rol Colaborador de datos de Storage Blob al servidor FHIR siguiendo la guía de RBAC.
Error de servidor interno 500
Comportamiento: Error en la operación de importación y 500 Internal Server Error se devuelve. El cuerpo de la respuesta tiene el siguiente contenido:
{
"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: Ha alcanzado el límite de almacenamiento del servicio FHIR.
Solución: Reduzca el tamaño de los datos o considere la posibilidad de que Azure API for FHIR tenga un límite de almacenamiento mayor.
Pasos siguientes
En este artículo, ha aprendido cómo la operación de importación permite importar datos de FHIR al servidor de FHIR con un alto rendimiento. Para obtener más información sobre cómo convertir datos en FHIR, exportar la configuración para configurar una cuenta de almacenamiento y mover datos a Azure Synapse, consulte
FHIR® es una marca registrada de HL7 y se usa con su permiso.