View a markdown version of this page

Cómo aplicar parches a los recursos a escala con $bulk-patch - AWS HealthLake
De usoParametersRecursos de segmentaciónFormatos de parches compatiblesEjemplo de iniciar un trabajo de parcheo masivoEncuesta masiva del estado de los trabajos de parchesMotivos comunes omitidosFallos frecuentes de los clientesPrácticas recomendadasAutorizaciónCaracterísticas de rendimientoOperaciones de relacionadas

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Cómo aplicar parches a los recursos a escala con $bulk-patch

AWS HealthLake admite la $bulk-patch operación de aplicar operaciones de parches a un gran número de recursos del FHIR de forma asincrónica. Puede segmentar una lista específica de recursos por ID o todos los recursos de un tipo determinado dentro de un almacén de datos. Con esta operación, puede modificar los recursos a escala sin actualizar cada recurso de forma individual.

La $bulk-patch operación es especialmente útil cuando necesita hacer lo siguiente:

  • Aplique etiquetas o etiquetas de metadatos a los recursos de todo un almacén de datos

  • Actualice campos específicos en miles o millones de recursos

  • Realice correcciones o enriquecimientos masivos de datos

  • Aplica los cambios relacionados con el cumplimiento en todos los tipos de recursos

  • Migre o estandarice los elementos de datos a escala

nota

  • La $bulk-patch operación aplica el mismo parche a todos los recursos de destino. Para modificar un recurso individual, utilice la operación PATCH. Para obtener más información, consulte Modificación de recursos con la operación PATCH.

  • El parche masivo aplica cada parche de forma atómica a cada recurso. Cada recurso tiene éxito o falla de forma independiente.

  • Los recursos que se eliminan o modifican después de enviar el trabajo se omiten en lugar de aplicar parches para evitar sobrescribir los cambios simultáneos.

De uso

La $bulk-patch operación es asincrónica. Para iniciar un trabajo, envíe una solicitud POST:

POST [base]/$bulk-patch

Para sondear el estado de un trabajo, usa el punto final descriptivo:

GET [base]/$bulk-patch/{jobId}

Para empezar con la $bulk-patch operación, haga lo siguiente:

  1. Envíe una solicitud masiva de parches que especifique los recursos de destino y las operaciones de parches. La respuesta incluye un identificador de trabajo.

  2. Sondea el estado del trabajo utilizando el punto final descrito hasta que el estado sea COMPLETED oCOMPLETED_WITH_ERRORS.

  3. Revisa el resumen del trabajo para ver cuántos recursos se han realizado correctamente, han fallado o se han omitido.

Parameters

La $bulk-patch operación admite los siguientes parámetros.

Parámetro Tipo Obligatorio Descripción
resourceType string Sí El tipo de recurso FHIR que se va a aplicar el parche, por ejemplo Patient oObservation.
resourceIds string[] No La lista de identificadores de recursos que se van a aplicar parches. Si se omite este parámetro, la operación corrige todos los recursos del tipo especificado.
operations objeto Sí Las operaciones de parche que se van a aplicar. Acepta una matriz de parches JSON o un Parameters recurso de parches FHIR.
clientToken cadena No User-provided token utilizado para garantizar la idempotencia. Al volver a enviar un trabajo con el mismo token de cliente, se devuelve el trabajo existente en lugar de crear uno nuevo.
validationLevel cadena No El nivel de validación del FHIR aplicado al actualizar cada recurso. Los valores aceptados son strict (predeterminado) structure-only yminimal.

Recursos de segmentación

Puedes segmentar los recursos de dos modos.

Modo de tipo de recurso

En el modo de tipo de recurso, la operación corrige todos los recursos de un tipo específico del almacén de datos.

{
    "resourceType": "Patient",
    "operations": { ... }
}
Modo de identificadores de recursos

En el modo de ID de recursos, la operación parchea una lista específica de recursos por ID. Todos los ID de recursos deben ser del mismo tipo y coincidir con el resourceType parámetro. El formato puede ser una referencia completa ([resourceType]/[id]) o solo el ID ([id]). La lista puede contener hasta 50 000 ID de recursos.

{
    "resourceType": "Patient",
    "resourceIds": ["Patient/001", "Patient/002", "Patient/003"],
    "operations": { ... }
}

Formatos de parches compatibles

La $bulk-patch operación admite las sintaxis JSON Patch (RFC 6902) y FHIR Patch (FHIRPath-based). Utiliza el mismo conjunto de operaciones admitidas y la misma sintaxis que la operación PATCH sincrónica. Para obtener más información, consulte Modificación de recursos con la operación PATCH.

Ejemplo de iniciar un trabajo de parcheo masivo

En el siguiente ejemplo, se envía un trabajo de parches masivos que agrega una etiqueta de cumplimiento a Patient recursos específicos mediante FHIR Patch.

Solicitud de ejemplo

POST [base]/$bulk-patch
Content-Type: application/json

{
    "resourceType": "Patient",
    "resourceIds": ["patient-1", "patient-2", "patient-3"],
    "validationLevel": "strict",
    "clientToken": "unique-idempotency-token-123",
    "operations": {
        "resourceType": "Parameters",
        "parameter": [
            {
                "name": "operation",
                "part": [
                    {"name": "type", "valueCode": "add"},
                    {"name": "path", "valueString": "Patient.meta"},
                    {"name": "name", "valueString": "tag"},
                    {"name": "value", "valueCoding": {
                        "system": "http://example.org/compliance",
                        "code": "2026-audit-complete"
                    }}
                ]
            }
        ]
    }
}
Respuesta de ejemplo

{
    "datastoreId": "datastoreId",
    "jobId": "jobId",
    "jobStatus": "SUBMITTED"
}

Encuesta masiva del estado de los trabajos de parches

Después de enviar un trabajo, sondea su estado para hacer un seguimiento del progreso y recuperar los resultados. El trabajo pasa de un lado a IN_PROGRESS otro SUBMITTED y, después, a un estado terminal de COMPLETED oCOMPLETED_WITH_ERRORS.

GET [base]/$bulk-patch/{jobId}

El siguiente ejemplo muestra una respuesta para un trabajo que está en curso.

{
    "datastoreId": "datastoreId",
    "jobId": "jobId",
    "status": "IN_PROGRESS",
    "submittedTime": "2026-09-14T06:53:31.429Z",
    "summary": {
        "estimatedResourceCount": 1000
    }
}
nota

estimatedResourceCountEs exacto para el modo de ID de recursos y es igual al tamaño de la lista enviada. En el modo de tipo de recurso, la cantidad real de recursos procesados puede variar ligeramente porque los recursos se pueden crear o eliminar mientras se ejecuta el trabajo.

Cuando el trabajo llega a un estado terminal, la respuesta descrita incluye un resumen del recuento de los recursos ejecutados, fallidos y omitidos. Si algún recurso falló o se omitió, la respuesta indica los motivos en failedResources y. skippedResources El estado del trabajo es COMPLETED_WITH_ERRORS cuando se produce algún error, ya sea un error del cliente o un error del servidor. El tamaño de las respuestas limita las skippedResources listas failedResources y, por lo tanto, es posible que se trunquen. Compruebe failedResourcesTruncated y skippedResourcesTruncated determine si se incluye la lista completa.

{
    "datastoreId": "datastoreId",
    "jobId": "jobId",
    "status": "COMPLETED_WITH_ERRORS",
    "submittedTime": "2026-09-14T06:53:31.429Z",
    "endTime": "2026-09-14T07:08:34.930Z",
    "summary": {
        "estimatedResourceCount": 1000,
        "totalResourcesProcessed": 1000,
        "succeeded": 985,
        "failedWithCustomerError": 5,
        "failedWithServerError": 0,
        "skipped": 10
    },
    "failedResources": [
        {
            "resourceId": "Patient/patient-101",
            "message": "FHIR resource in payload failed FHIR validation rules."
        }
    ],
    "skippedResources": [
        {
            "resourceId": "Patient/patient-201",
            "message": "Resource was modified after job submission"
        },
        {
            "resourceId": "Patient/patient-202",
            "message": "Resource was deleted."
        },
        {
            "resourceId": "Patient/patient-203",
            "message": "Resource not found."
        }
    ],
    "failedResourcesTruncated": false,
    "skippedResourcesTruncated": false
}

Motivos comunes omitidos

La operación omite un recurso cuando está dentro de su ámbito, pero no puede aplicar parches al recurso porque su estado cambió entre el envío del trabajo y el procesamiento. Los recursos omitidos no se consideran errores. Los siguientes son los motivos más comunes por los que se omite un recurso.

  • El recurso se modificó después de enviar el trabajo: otra operación actualizó el recurso después de que el trabajo de parche masivo capturara su versión en el momento del envío. En raras ocasiones, es posible que un recurso que se parcheó correctamente aparezca como omitido y que se modifique el motivo después de enviar el trabajo. Esto es normal y puede ocurrir a un ritmo muy bajo (1 de cada millón de recursos).

  • El recurso se eliminó después de enviar el trabajo: el recurso se eliminó después de enviar el trabajo (modo de tipo de recurso). No se garantiza que todos los recursos eliminados aparezcan en la lista omitida. Si se elimina un recurso antes de que el trabajo comience a procesarse, se excluye por completo del ámbito del trabajo y no se refleja en los resultados del trabajo.

  • Se eliminó el recurso: el ID de recurso especificado se encuentra en estado eliminado (modo de ID de recurso).

  • Recurso no encontrado: el identificador de recurso especificado no existe (solo en el modo de identificadores de recursos).

Fallos frecuentes de los clientes

Un recurso falla cuando la operación no puede aplicar el parche debido a un problema con el recurso o con las operaciones del parche. Los recursos fallidos incluyen un mensaje de error con detalles de diagnóstico. Los siguientes son errores comunes de los clientes.

  • Fallo de validación del FHIR: el recurso parcheado no supera la validación del FHIR. El parche masivo aplica la validación del FHIR a todo el recurso parcheado, no solo a los campos modificados. Este error puede producirse cuando el parche produce un valor de campo no válido o cuando el recurso ya contiene campos que no cumplen con el FHIR. Utilice el validationLevel parámetro para controlar el rigor de la validación.

  • Fallo en la aplicación del parche: las operaciones de aplicación del parche son incompatibles con la estructura de los recursos, por ejemplo, reemplazar un campo que no existe o agregarlo a una ruta que no sea una matriz.

Prácticas recomendadas

Cuando utilice la $bulk-patch operación, le recomendamos que siga las siguientes prácticas recomendadas.

  • Pruebe primero con un PATCH sincrónico. AWS HealthLake valida la sintaxis de las operaciones de parches al enviar el trabajo y rechaza las cargas no válidas de forma sincrónica. Sin embargo, las operaciones de parches válidas desde el punto de vista sintáctico aún pueden fallar durante el procesamiento si no coinciden con la estructura de recursos almacenada subyacente. Conozca las características de los recursos de destino y pruebe sus operaciones de parches con la operación de parches sincrónica antes de ejecutar un trabajo de parches masivo. Esto le ayuda a evitar errores a gran escala.

  • Utilice los motivos omitidos y los errores para depurar. Revisa las skippedResources listas failedResources y de la respuesta descriptiva para entender por qué no se han parcheado recursos específicos.

  • Verifique el estado de los recursos antes de volver a intentarlo. Las operaciones de parches no son idempotentes por naturaleza. Aplicar el mismo parche dos veces puede producir resultados diferentes; por ejemplo, al añadir una etiqueta que ya existe se crea un duplicado. Cuando veas los recursos omitidos o fallidos, comprueba el estado actual de los recursos antes de enviar un trabajo de reintento.

Autorización

La $bulk-patch operación admite los siguientes métodos de autorización:

  • AWS Firma de administración de acceso e identidad (IAM), versión 4 (SIGv4), para el acceso programático.

  • SMART en el FHIR con los siguientes alcances obligatorios:

    • Nivel de ámbito: solo se admiten los ámbitos a nivel de sistema. La operación rechaza los alcances a nivel de paciente y usuario.

    • Tipo de recurso: los ámbitos deben coincidir con el tipo de recurso al que se destina el trabajo.

    • Operaciones: los ámbitos requeridos dependen del modo de trabajo y de la versión SMART:

      • Iniciar un trabajo (modo de tipo de recurso): requisitos read y write alcances del SMART v1. Los almacenes de datos SMART v2 requieren search y update abarcan.

      • Iniciar un trabajo (modo de ID de recursos): los requisitos y los alcances de SMART v1. read write Los almacenes de datos SMART v2 requieren read y abarcan. update

      • Describa un trabajo: requiere el alcance. read

Características de rendimiento

La $bulk-patch operación está diseñada para procesar grandes volúmenes y se ejecuta de forma asincrónica.

  • Simultaneidad: cada almacén de datos admite un máximo de 1 trabajo simultáneo de parches masivos. La operación pone en cola los trabajos adicionales y los inicia automáticamente cuando finaliza el trabajo actual.

  • Escalabilidad: cada trabajo admite hasta 2 mil millones de recursos. La operación rechaza los trabajos que superan este límite. Este límite evita tiempos de procesamiento prolongados, durante los cuales muchos recursos pueden cambiar de estado, y evita que los trabajos del almacén de datos se mantengan simultáneos durante un período prolongado. Utilice el modo de ID de recursos para particionar la carga de trabajo. Ejemplo de respuesta cuando un trabajo supera la escala admitida:

    "status": "COMPLETED_WITH_ERRORS",
"message": "The requested bulk patch operation exceeds the supported scale."

  • Operaciones paralelas: el parche masivo no es compatible con las operaciones simultáneas de eliminación, importación o exportación masivas en el mismo almacén de datos.

  • Cancelación: los trabajos de parches masivos no se pueden cancelar una vez enviados.