Funcionalidades de LA API REST de FHIR para el servicio FHIR de Azure Health Data Services
En este artículo, trataremos algunos de los matices de las interacciones RESTful del servicio FHIR de Azure Health Data Services (denominado servicio FHIR).
Creación o actualización condicional
El servicio FHIR admite la creación, la creación condicional, la actualización y la actualización condicional, tal como se define en la especificación de FHIR. Un encabezado útil en estos escenarios es el encabezado If-Match . El If-Match encabezado se usa y validará la versión que se va a actualizar antes de realizar la actualización. ETag Si no coincide con el esperadoETag, generará el mensaje de error 412 Error en la condición previa.
Eliminación y eliminación condicional
El servicio FHIR ofrece dos tipos de eliminación. Hay Delete, que también se conoce como Hard + Soft Delete y Conditional Delete.
Eliminar (eliminación dura y temporal)
La eliminación definida por la especificación FHIR requiere que después de eliminar un recurso, las lecturas posteriores no específicas de la versión de un recurso devuelven un código de estado HTTP 410. Por lo tanto, el recurso ya no se encuentra a través de la búsqueda. Además, el servicio FHIR le permite eliminar por completo (incluido todo el historial) del recurso. Para eliminar completamente el recurso, puede pasar una configuración hardDelete de parámetro a true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Si no pasa este parámetro o se establece hardDelete en false, las versiones históricas del recurso seguirán estando disponibles.
Nota:
Si solo desea eliminar el historial, el servicio FHIR admite una operación personalizada denominada $purge-history. Esta operación permite eliminar el historial de un recurso.
Eliminación condicional
La eliminación condicional permite pasar criterios de búsqueda para eliminar un recurso. De forma predeterminada, la eliminación condicional permite eliminar un elemento a la vez. También puede especificar el _count parámetro para eliminar hasta 100 elementos a la vez. A continuación se muestran algunos ejemplos de uso de la eliminación condicional.
Para eliminar un solo elemento mediante la eliminación condicional, debe especificar criterios de búsqueda que devuelvan un solo elemento.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704
Puede realizar la misma búsqueda, pero incluir hardDelete=true para eliminar también todo el historial.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true
Para eliminar varios recursos, incluya el _count=100 parámetro . Este parámetro eliminará hasta 100 recursos que coincidan con los criterios de búsqueda.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100
Recuperación de archivos eliminados
Si no usa el parámetro de eliminación permanente, los registros del servicio FHIR seguirán existiendo. Los registros se pueden encontrar realizando una búsqueda de historial en el recurso y buscando la última versión con datos.
Si se conoce el identificador del recurso que se eliminó, use el siguiente patrón de dirección URL:
<FHIR_URL>/<resource-type>/<resource-id>/_history
Por ejemplo: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history
Si no se conoce el identificador del recurso, realice una búsqueda de historial en todo el tipo de recurso:
<FHIR_URL>/<resource-type>/_history
Por ejemplo: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history
Después de encontrar el registro que desea restaurar, use la PUT operación para volver a crear el recurso con el mismo identificador o use la POST operación para crear un nuevo recurso con la misma información.
Nota
No hay expiración basada en el tiempo para los datos de historial o eliminación temporal. La única manera de quitar los datos eliminados temporalmente o del historial es con una eliminación permanente o la operación del historial de purga.
Lotes y agrupaciones de transacciones
En FHIR, las agrupaciones se pueden considerar como un contenedor que contiene varios recursos. Los lotes de lotes y transacciones permiten a los usuarios enviar un conjunto de acciones que se van a realizar en un servidor en una única solicitud/respuesta HTTP. Las acciones se pueden realizar de forma independiente como un "lote", o como una única "transacción" atómica donde todo el conjunto de cambios se realiza correctamente o produce un error como una sola entidad. Se pueden enviar acciones en varios recursos de los mismos tipos o diferentes, como crear, actualizar o eliminar. Para obtener más información, visite paquetes de FHIR.
Una interacción de lote o agrupación de transacciones con el servicio FHIR se realiza con el comando HTTP POST en la dirección URL base.
POST {{fhir_url}}
{
"resourceType": "Bundle",
"type": "batch",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "patient-1",
"name": [
{
"given": ["Alice"],
"family": "Smith"
}
],
"gender": "female",
"birthDate": "1990-05-15"
},
"request": {
"method": "POST",
"url": "Patient"
}
},
{
"resource": {
"resourceType": "Patient",
"id": "patient-2",
"name": [
{
"given": ["Bob"],
"family": "Johnson"
}
],
"gender": "male",
"birthDate": "1985-08-23"
},
"request": {
"method": "POST",
"url": "Patient"
}
}
}
]
}
En el caso de un lote, cada entrada se trata como una interacción o operación individuales. En el caso de una agrupación de transacciones, todas las interacciones o operaciones se realizan correctamente o producen errores juntos. Para un lote o una agrupación de transacciones correcta, la respuesta contiene una entrada para cada entrada de la solicitud. En el caso de la agrupación de transacciones con errores, el servicio FHIR devuelve un único OperationOutcome.
Nota
En el caso de las agrupaciones por lotes, no debe haber ninguna interdependencia entre distintas entradas en el lote de FHIR. El éxito o error de una entrada no debería afectar al éxito o error de otra entrada.
Procesamiento paralelo del lote por lotes en versión preliminar pública
Actualmente, los lotes y las agrupaciones de transacciones se ejecutan en serie en el servicio FHIR. Para mejorar el rendimiento y el rendimiento, estamos habilitando el procesamiento paralelo de agrupaciones por lotes en versión preliminar pública.
Para usar la funcionalidad del procesamiento de lotes en paralelo:
- Establezca el valor de encabezado "x-bundle-processing-logic" en "parallel".
- Asegúrese de que no haya ningún identificador de recurso superpuesto que se esté ejecutando en las operaciones DELETE, POST, PUT o PATCH en la misma agrupación.
Importante
El procesamiento paralelo de agrupación se encuentra actualmente en versión preliminar pública. Las API y los SDK en versión preliminar se proporcionan sin contrato de nivel de servicio. Se recomienda no usarlos para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que sus funcionalidades estén limitadas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.
Revisión y revisión condicional
Patch es una valiosa operación RESTful cuando necesita actualizar solo una parte del recurso FHIR. El uso de la revisión permite especificar los elementos que desea actualizar en el recurso sin tener que actualizar todo el registro. FHIR define tres maneras de aplicar revisiones a los recursos: revisión JSON, revisión XML y revisión de FHIRPath. El servicio FHIR admite revisiones JSON y revisión de FHIRPath junto con la revisión JSON condicional y la revisión FHIRPath condicional (que permite aplicar revisiones a un recurso basado en criterios de búsqueda en lugar de un identificador de recurso). Para recorrer algunos ejemplos, consulte el archivo REST de revisión de FHIRPath de ejemplo y el archivo REST de revisión JSON para cada enfoque. Para más información, lea la documentación de HL7 para las operaciones de revisión con FHIR.
Nota
Al usar PATCH en STU3 y, si solicita un conjunto de historial, el recurso Bundle.entry.request.method revisado se asigna a PUT. Esto se debe a que STU3 no contiene una definición para el PATCH verbo en el conjunto de valores HTTPVerb.
Revisión con la revisión de FHIRPath
Este método de revisión es el más eficaz, ya que aprovecha FHIRPath para seleccionar el elemento de destino. Un escenario común consiste en usar FHIRPath Patch para actualizar un elemento de una lista sin conocer el orden de la lista. Por ejemplo, si desea eliminar la información de telecomunicaciones domésticas de un paciente sin conocer el índice, puede usar el ejemplo siguiente.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Tipo de contenido: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "operation",
"part": [
{
"name": "type",
"valueCode": "delete"
},
{
"name": "path",
"valueString": "Patient.telecom.where(use = 'home')"
}
]
}
]
}
Todas las operaciones de revisión de FHIRPath deben tener establecido el application/fhir+json encabezado Content-Type. FHIRPatch Patch admite operaciones de adición, inserción, eliminación, eliminación y movimiento. Las operaciones de revisión de FHIRPatch también se pueden integrar fácilmente en agrupaciones. Para obtener más ejemplos, consulte el archivo REST de revisión de FHIRPath de ejemplo.
Revisión con revisión JSON
La revisión JSON en el servicio FHIR se ajusta a la especificación bien usada definida por el Grupo de tareas de ingeniería de Internet. El formato de carga no usa recursos de FHIR y, en su lugar, usa un documento JSON que aprovecha JSON-Pointers para la selección de elementos. La revisión JSON es más compacta y tiene una operación de prueba que permite validar que una condición es verdadera antes de realizar la revisión. Por ejemplo, si desea establecer un paciente como fallecido solo si aún no están marcados como fallecidos, puede usar el ejemplo siguiente.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Tipo de contenido: application/json-patch+json
[
{
"op": "test",
"path": "/deceasedBoolean",
"value": false
},
{
"op": "replace",
"path": "/deceasedBoolean",
"value": true
}
]
Todas las operaciones de revisión json deben tener establecido el application/json-patch+json encabezado Content-Type. Json Patch admite operaciones de adición, eliminación, reemplazo, copia, movimiento y prueba. Para obtener más ejemplos, consulte el archivo REST de revisión JSON de ejemplo.
Revisión json en agrupaciones
De forma predeterminada, la revisión json no se admite en recursos de agrupación. Esto se debe a que un paquete solo admite con recursos de FHIR y la carga de revisiones JSON no es un recurso de FHIR. Para solucionar esto, usaremos recursos binarios con un tipo de contenido de "application/json-patch+json" y la codificación base64 de la carga JSON dentro de un paquete. Para obtener información sobre esta solución alternativa, vea este tema en FHIR Chat Zulip.
En el ejemplo siguiente, queremos cambiar el género del paciente a una mujer. Hemos tomado la revisión [{"op":"replace","path":"/gender","value":"female"}] JSON y la hemos codificado en base64.
POST https://{FHIR-SERVICE-HOST-NAME}/
Content-Type: application/json
{
"resourceType": "Bundle",
"id": "bundle-batch",
"type": "batch",
"entry": [
{
"fullUrl": "Patient/{PatientID}",
"resource": {
"resourceType": "Binary",
"contentType": "application/json-patch+json",
"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
},
"request": {
"method": "PATCH",
"url": "Patient/{PatientID}"
}
}
]
}
Pasos siguientes
En este artículo, ha obtenido información sobre algunas de las funcionalidades rest del servicio FHIR. A continuación, puede obtener más información sobre los aspectos clave para buscar recursos en el servicio FHIR.
FHIR es una marca registrada de HL7 y se usa con el permiso de HL7.