Batch se ejecuta en HealthOmics

AWS HealthOmics las ejecuciones por lotes te permiten enviar varias ejecuciones en una sola solicitud de API. Cada ejecución del lote comparte una configuración base común, pero puede tener diferentes entradas y parámetros específicos de cada ejecución. Las ejecuciones por lotes reducen la sobrecarga de envío y simplifican la administración del ciclo de vida para el procesamiento de flujos de trabajo a gran escala.

Con las ejecuciones por lotes, puede:

• Envíe hasta 100 000 ejecuciones en una sola StartRunBatch llamada, con una configuración compartida definida una vez y aplicada a todas las ejecuciones.

• Aplica anulaciones de parámetros por ejecución para muestras individuales, incluidos el nombre, el URI de salida, los parámetros, la prioridad y las etiquetas.

• Realice un seguimiento del estado general de los lotes y del progreso del envío de las tiradas individuales desde y. GetBatch ListRunsInBatch

• Cancele todas las ejecuciones de un lote utilizandoCancelRunBatch.

• Elimine todas las corridas de un lote utilizandoDeleteRunBatch.

• Elimine los metadatos del lote conDeleteBatch.

Conceptos de ejecución por lotes

• Batch: conjunto de ejecuciones de flujo de trabajo que comparten una configuración común y se administran como un único recurso con su propio nombre de recurso de Amazon (ARN) y estado del ciclo de vida.

• Configuración de ejecución predeterminada (defaultRunSetting): parámetros del flujo de trabajo compartidos en todas las ejecuciones del lote, como el ID del flujo de trabajo, la función de IAM, el URI de salida y los parámetros comunes.

• Configuración específica de la ejecución (inlineSettingsos3UriSettings): configuraciones por ejecución que anulan o se fusionan con la configuración de ejecución predeterminada. Cada entrada debe incluir una única. runSettingId

• ID de configuración de ejecución (runSettingId): un identificador único obligatorio proporcionado por el cliente para cada configuración de ejecución de un lote. Tras el envío, ListRunsInBatch utilícelo para asignar cada una de ellas runSettingId a la HealthOmics generadarunId, lo que le permitirá rastrear qué ejecución se creó a partir de qué configuración de entrada.

• Estado del lote: el estado general de la operación del lote. Valores posibles:

  • CREATING— Se está creando el lote.

  • PENDING— Se ha creado el lote; las configuraciones de ejecución se validan de forma asíncrona.

  • SUBMITTING— Se ha completado la validación; se están enviando ejecuciones individuales.

  • INPROGRESS— Se han intentado enviar todas las ejecuciones; las ejecuciones se están ejecutando.

  • STOPPING— Se ha recibido una solicitud de cancelación; se están deteniendo las ejecuciones.

  • CANCELLED— Se ha cancelado el lote.

  • PROCESSED— Todas las ejecuciones han alcanzado un estado terminal (completadas, fallidas o canceladas).

  • FAILED— El lote en sí falló antes de que se pudieran crear las ejecuciones. Para obtener más información, consulte Fallos a nivel de lote.

  • RUNS_DELETING— Se están eliminando las ejecuciones del lote.

  • RUNS_DELETED— Se han eliminado todas las ejecuciones del lote.

• Estado de envío: el resultado del envío de una tirada individual del lote. Valores posibles:

  • SUCCESS— La ejecución se envió correctamente.

  • FAILED— Falló el envío de la ejecución (por ejemplo, debido a un error de validación).

  • CANCEL_SUCCESS— La ejecución se canceló correctamente.

  • CANCEL_FAILED— Falló la cancelación de la ejecución.

  • DELETE_SUCCESS— La ejecución se ha eliminado correctamente.

  • DELETE_FAILED— Falló la eliminación de la ejecución.

Requisitos previos

Antes de iniciar una ejecución por lotes, asegúrese de tener:

• Un flujo de trabajo HealthOmics privado activo. Las ejecuciones por lotes no son compatibles con los flujos de trabajo Ready2Run.

• Un rol de servicio de IAM con permisos para ejecutar HealthOmics flujos de trabajo y acceder a sus buckets de Amazon S3. Para obtener más información, consulte Funciones de servicio para AWS HealthOmics.

• Ubicaciones de Amazon S3 para los datos de entrada y los resultados de salida.

• Ejecute parámetros específicos para cada muestra o configuración experimental.

Permisos de IAM para operaciones por lotes

Su identidad de IAM debe tener permisos tanto para la operación por lotes como para la operación de ejecución individual subyacente. El siguiente ejemplo de política concede permisos para todas las operaciones por lotes:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowBatchOperations",
      "Effect": "Allow",
      "Action": [
        "omics:StartRunBatch",
        "omics:GetBatch",
        "omics:ListBatch",
        "omics:ListRunsInBatch",
        "omics:CancelRunBatch",
        "omics:DeleteRunBatch",
        "omics:DeleteBatch"
      ],
      "Resource": "arn:aws:omics:*:123456789012:runBatch/*"
    },
    {
      "Sid": "AllowRunCreation",
      "Effect": "Allow",
      "Action": "omics:StartRun",
      "Resource": [
        "arn:aws:omics:*:123456789012:run/*",
        "arn:aws:omics:*:123456789012:workflow/*",
        "arn:aws:omics:*:123456789012:runGroup/*"
      ]
    },
    {
      "Sid": "AllowListOperations",
      "Effect": "Allow",
      "Action": [
        "omics:ListBatch",
        "omics:ListRunsInBatch"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AllowPassRole",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::123456789012:role/OmicsRole",
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "omics.amazonaws.com"
        }
      }
    }
  ]
}

nota

StartRunBatchrequiere una doble autorización: omics:StartRunBatch en el recurso por lotes y omics:StartRun en los recursos en ejecución, en el flujo de trabajo y en el grupo de ejecución. Se deben conceder ambos permisos para que el lote se ejecute correctamente.

La función de servicio de IAM roleArn transferida (utilizada por HealthOmics para ejecutar las ejecuciones) requiere los mismos permisos que para las StartRun llamadas individuales. Para obtener más información, consulte Funciones de servicio para AWS HealthOmics.

Etiquetado y control de acceso basado en etiquetas

Las ejecuciones por lotes admiten etiquetas en dos niveles:

• Etiquetas de lote (etiquetas de la StartRunBatch solicitud): se aplican al recurso de lote. El control de acceso basado en etiquetas (TBAC) se aplica plenamente a las etiquetas de lote.

• Etiquetas de ejecución (dentro runTags defaultRunSetting y por ejecuciónrunTags): se aplican a recursos de ejecución individuales. Estas etiquetas se combinan utilizando las mismas reglas de prioridad que los parámetros.

Si utiliza políticas de control de acceso basadas en etiquetas, asegúrese de que su política de IAM incluya omics:TagResource las condiciones adecuadasaws:RequestTag. aws:TagKeys

Ejemplo: restringir la creación de lotes a entornos que no sean de producción

La siguiente política permite a los usuarios crear lotes y ejecuciones, pero niega etiquetar ningún recurso con: environment=production

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowBatchAndRunCreation",
      "Effect": "Allow",
      "Action": [
        "omics:StartRunBatch",
        "omics:StartRun"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AllowTaggingNonProd",
      "Effect": "Allow",
      "Action": "omics:TagResource",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/environment": ["dev", "test"]
        }
      }
    },
    {
      "Sid": "DenyProductionTags",
      "Effect": "Deny",
      "Action": "omics:TagResource",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/environment": "production"
        }
      }
    }
  ]
}

Con esta política:

• tags: {"environment": "dev"}en el lote → Permitido

• tags: {"environment": "production"}en el lote → Denegado (403)

• runTags: {"environment": "production"}in defaultRunSetting → Denegado para ejecuciones individuales durante la creación asíncrona

Para empezar: envíe su primer lote

En el siguiente ejemplo, se explica cómo enviar un lote pequeño de dos tiradas, comprobar el progreso y revisar los resultados.

Paso 1: Enviar el lote

aws omics start-run-batch \
  --batch-name "my-first-batch" \
  --default-run-setting '{
    "workflowId": "1234567",
    "roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
    "outputUri": "s3://my-bucket/output/",
    "storageType": "DYNAMIC",
    "parameters": {"referenceUri": "s3://my-bucket/reference.fasta"}
  }' \
  --batch-run-settings '{
    "inlineSettings": [
      {
        "runSettingId": "sample-A",
        "parameters": {"inputUri": "s3://my-bucket/sampleA.fastq"}
      },
      {
        "runSettingId": "sample-B",
        "parameters": {"inputUri": "s3://my-bucket/sampleB.fastq"}
      }
    ]
  }'

La respuesta devuelve un identificador de lote que se utilizará para todas las operaciones posteriores:

{
  "id": "7123456",
  "arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
  "status": "CREATING"
}

Paso 2: Compruebe el progreso del lote

aws omics get-batch --batch-id 7123456

Observe el progreso del status campo desde CREATING PENDING → → SUBMITTING → INPROGRESS →PROCESSED. submissionSummaryMuestra cuántas ejecuciones se enviaron correctamente y runSummary muestra el progreso de la ejecución.

Paso 3: Revise las ejecuciones individuales

aws omics list-runs-in-batch --batch-id 7123456

Cada entrada mapea las runSettingId suyas (por ejemplosample-A) con las HealthOmics generadasrunId, para que pueda rastrear los resultados hasta las muestras de entrada.

Paso 4: Compruebe si hay envíos fallidos

aws omics list-runs-in-batch --batch-id 7123456 --submission-status FAILED

Si no se pudo enviar alguna de las tiradas, la respuesta incluye submissionFailureReason y servirá submissionFailureMessage para ayudarte a diagnosticar el problema.

Iniciar una ejecución por lotes

Se utiliza StartRunBatch para enviar varias tiradas con una sola solicitud. La solicitud incluye:

• defaultRunSetting— Configuración compartida para todas las ejecuciones del lote.

• batchRunSettings— Las configuraciones de ejecución individuales, proporcionadas como una de las siguientes:

  • inlineSettings— Un conjunto de hasta 100 configuraciones específicas para cada ejecución que se proporciona directamente en el cuerpo de la solicitud.

  • s3UriSettings— Un URI de Amazon S3 que apunta a un archivo JSON que contiene las configuraciones de ejecución. Se requiere para lotes con más de 100 ejecuciones y admite hasta 100 000 ejecuciones.

También puede proporcionar los siguientes campos:

• batchName— Un nombre opcional legible para las personas para el lote.

• requestId— Un token de idempotencia para evitar el envío de lotes duplicados.

• tags— Etiquetas para asociar al propio recurso del lote.

Envíe lotes pequeños con configuraciones de ejecución en línea

Proporcione una variedad de configuraciones específicas para la ejecución directamente en el cuerpo de la solicitud utilizando. inlineSettings Cada entrada debe incluir una única runSettingId (obligatoria). Esta runSettingId es la clave para correlacionar los resultados: cuando llamasListRunsInBatch, cada entrada te asigna runSettingId al HealthOmics generado runId y. runArn

Puede incluir hasta 100 entradas con configuraciones en línea.

{
  "batchName": "genomics-cohort-analysis",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {
    "project": "genomics-study",
    "environment": "production"
  },
  "defaultRunSetting": {
    "workflowId": "1234567",
    "roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
    "outputUri": "s3://my-bucket/output/",
    "parameters": {
      "referenceUri": "s3://my-bucket/reference/genome.fasta"
    },
    "runTags": {
      "analysis-type": "germline"
    }
  },
  "batchRunSettings": {
    "inlineSettings": [
      {
        "runSettingId": "sample-001",
        "name": "Sample-001-Analysis",
        "parameters": {
          "inputUri": "s3://my-bucket/input/sample-001.fastq",
          "sampleName": "sample-001"
        },
        "runTags": {
          "patient-id": "patient001"
        }
      },
      {
        "runSettingId": "sample-002",
        "name": "Sample-002-Analysis",
        "outputUri": "s3://my-bucket/output/special/",
        "parameters": {
          "inputUri": "s3://my-bucket/input/sample-002.fastq",
          "sampleName": "sample-002"
        },
        "runTags": {
          "patient-id": "patient002"
        }
      }
    ]
  }
}

CLI

aws omics start-run-batch \
  --batch-name "genomics-cohort-analysis" \
  --request-id "a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --default-run-setting '{
    "workflowId": "1234567",
    "roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
    "outputUri": "s3://my-bucket/output/",
    "storageType": "DYNAMIC",
    "parameters": {"referenceUri": "s3://my-bucket/reference.fasta"}
  }' \
  --batch-run-settings '{
    "inlineSettings": [
      {
        "runSettingId": "sample-001",
        "name": "Run-001",
        "parameters": {"inputUri": "s3://my-bucket/input1.fastq"}
      },
      {
        "runSettingId": "sample-002",
        "name": "Run-002",
        "parameters": {"inputUri": "s3://my-bucket/input2.fastq"}
      }
    ]
  }'

Envíe lotes grandes con configuraciones de ejecución en S3

Para lotes con más de 100 ejecuciones, almacene las configuraciones de ejecución en un archivo JSON en Amazon S3 y proporcione el URI mediantes3UriSettings. El archivo JSON debe contener una matriz de objetos de configuración específicos de cada ejecución, cada uno con un objeto único. runSettingId El archivo puede contener hasta 100 000 entradas.

El formato de archivo S3 es el mismo que el de la inlineSettings matriz:

[
  {
    "runSettingId": "sample-001",
    "name": "Sample-001-Analysis",
    "parameters": {
      "inputUri": "s3://my-bucket/input/sample-001.fastq",
      "sampleName": "sample-001"
    }
  },
  {
    "runSettingId": "sample-002",
    "name": "Sample-002-Analysis",
    "parameters": {
      "inputUri": "s3://my-bucket/input/sample-002.fastq",
      "sampleName": "sample-002"
    }
  }
]

Solicitud de API

{
  "defaultRunSetting": {
    "workflowId": "1234567",
    "roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
    "outputUri": "s3://my-bucket/output/",
    "parameters": {
      "referenceUri": "s3://my-bucket/reference/genome.fasta"
    }
  },
  "batchRunSettings": {
    "s3UriSettings": "s3://my-bucket/configs/run-configs.json"
  }
}

CLI

aws omics start-run-batch \
  --default-run-setting '{
    "workflowId": "1234567",
    "roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
    "outputUri": "s3://my-bucket/output/",
    "parameters": {"referenceUri": "s3://my-bucket/reference.fasta"}
  }' \
  --batch-run-settings '{"s3UriSettings": "s3://my-bucket/configs/run-configs.json"}'

importante

La función de servicio de IAM especificada en roleArn debe tener acceso de lectura al objeto Amazon S3 especificado ens3UriSettings. HealthOmics valida el acceso al archivo de Amazon S3 durante la llamada a la API sincrónica y registra el archivo. ETag Si el archivo se modifica después del envío, el lote falla durante el procesamiento asíncrono.

Respuesta

Si la solicitud se realiza correctamente, se devuelve un identificador de lote y su estado inicial:

{
  "id": "7123456",
  "arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
  "status": "CREATING",
  "uuid": "96c57683-74bf-9d6d-ae7e-f09b097db14a",
  "tags": {
    "project": "genomics-study",
    "environment": "production"
  }
}

Si la validación sincrónica falla (por ejemplo, un ID de flujo de trabajo no válido o un URI de Amazon S3 inaccesible), la API devuelve un error antes de que se envíe cualquier ejecución.

Referencia de parámetros

La siguiente tabla muestra qué StartRun campos se pueden configurar por ejecución y cuáles se aplican solo a nivel de lote. Para ver las descripciones completas de los campos, consulta la referencia StartRun de la API.

Campo	Nivel de lote () defaultRunSetting	Configurable por ejecución () inlineSettings
workflowId	Sí	No
workflowType	Sí	No
workflowVersionName	Sí	No
workflowOwnerId	Sí	No
roleArn	Sí	No
storageCapacity	Sí	No
storageType	Sí	No
runGroupId	Sí	No
logLevel	Sí	No
cacheBehavior	Sí	No
cacheId	Sí	No
retentionMode	Sí	No
name	Sí	Sí
outputUri	Sí	Sí
parameters	Sí	Sí (fusionado)
priority	Sí	Sí
runTags	Sí	Sí (fusionado)
outputBucketOwnerId	Sí	Sí

nota

El campo runId (para repeticiones individuales) no se admite como entrada paraStartRunBatch. Cada envío por lotes siempre crea nuevas tiradas y cada tirada recibirá unarunId. Consulte Vuelva a ejecutar una ejecución HealthOmics para volver a intentar ejecuciones individuales.

Combinación de parámetros

Los parámetros de defaultRunSetting se combinan con los parámetros específicos de la ejecución proporcionados en inlineSettings o a través de un URI de S3. Los valores específicos de la ejecución tienen prioridad cuando las claves se superponen.

Ejemplo:

origen	Parameters
defaultRunSetting	{"referenceUri": "s3://bucket/ref.fasta", "version": "v1"}
inlineSettingsentrada	{"inputUri": "s3://bucket/sample.fastq", "version": "v2"}
Resultado fusionado	{"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"}

El mismo comportamiento de fusión se aplica arunTags. Las etiquetas especificadas en la configuración por ejecución anulan las etiquetas con la misma clave de y defaultRunSetting.runTags se añaden nuevas claves.

Ejemplo de combinación de etiquetas:

origen	Tags
defaultRunSetting.runTags	{"project": "cancer-research", "pipeline-version": "v2.1"}
inlineSettings[].runTags	{"patient-id": "patient001", "pipeline-version": "v3.0"}
Resultado combinado (aplicado a la ejecución)	{"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"}

nota

Las etiquetas de nivel de lote (en la StartRunBatch solicitud) se aplican solo al recurso de lote en sí. Las ejecuciones individuales no las heredan. Las etiquetas de nivel de ejecución se controlan mediante defaultRunSetting.runTags y por ejecución. runTags

Envío gradual

StartRunBatchvalida los campos comunes de forma sincrónica y los devuelve inmediatamente con el identificador y el estado del lote. CREATING Las ejecuciones de un lote se envían de forma gradual y asíncrona a un ritmo controlado de acuerdo con sus cuotas de rendimiento.

Para ver la lista completa de cuotas, consulte. HealthOmics HealthOmics cuotas de servicio

El lote pasa por los siguientes estados durante el procesamiento normal:

1. CREATING— Se está creando el lote.

2. PENDING— Batch creado, se están validando las configuraciones de ejecución.

3. SUBMITTING— Se completó la validación y se enviaron ejecuciones individuales.

4. INPROGRESS— Se han intentado enviar todas las ejecuciones, las ejecuciones se están ejecutando.

5. PROCESSED— Todas las corridas han alcanzado un estado terminal.

importante

El envío por lotes comparte la misma cuota de StartRun rendimiento que las llamadas directas a la StartRun API. Si llamas StartRun directamente mientras se está procesando un lote grande, tanto los envíos por lotes como las llamadas directas compiten por la misma capacidad. Esto puede provocar que se produzcan errores al procesar los lotes ThrottlingException (se supere la frecuencia) o que se limiten las StartRun llamadas directas. Lo mismo se aplica a las cuotas de rendimiento que comparten con CancelRun CancelRunBatch yDeleteRun, respectivamente, las cuotas de rendimiento. DeleteRunBatch

Supervisión del progreso de los lotes

Obtenga el estado del lote

Se utiliza GetBatch para recuperar el estado general y el progreso del envío de un lote.

aws omics get-batch --batch-id 7123456

La respuesta incluye:

• status— Estado general del lote.

• submissionSummary— Recuento de envíos correctos y fallidos para las operaciones de inicio, cancelación y eliminación.

• runSummary— Recuentos de ejecuciones en cada estado de ejecución. Valores posibles:PENDING, STARTINGRUNNING,STOPPING,COMPLETED,DELETED,CANCELLED, o FAILED

• Marcas temporales de los eventos del ciclo de vida:creationTime,,submittedTime,processedTime. failedTime

Ejemplo de respuesta:

{
  "id": "7123456",
  "arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
  "uuid": "96c57683-74bf-9d6d-ae7e-f09b097db14a",
  "name": "genomics-cohort-analysis",
  "status": "INPROGRESS",
  "totalRuns": 96,
  "defaultRunSetting": {
    "workflowId": "1234567",
    "roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
    "outputUri": "s3://my-bucket/output/"
  },
  "submissionSummary": {
    "successfulStartSubmissionCount": 94,
    "failedStartSubmissionCount": 2,
    "pendingStartSubmissionCount": 0
  },
  "runSummary": {
    "pendingRunCount": 10,
    "startingRunCount": 5,
    "runningRunCount": 50,
    "stoppingRunCount": 0,
    "completedRunCount": 29,
    "failedRunCount": 0,
    "cancelledRunCount": 0,
    "deletedRunCount": 0
  },
  "creationTime": "2025-03-15T10:00:00Z",
  "submittedTime": "2025-03-15T10:05:00Z",
  "tags": {
    "project": "genomics-study"
  }
}

nota

Los resúmenes de ejecución de las ejecuciones son finalmente consistentes y pueden retrasarse con respecto a los estados de ejecución reales. Los recuentos finales se concilian cuando el lote alcanza su PROCESSED estado.

La lista se ejecuta en un lote

Se utiliza ListRunsInBatch para recuperar información detallada de las ejecuciones individuales de un lote. Los resultados están paginados.

aws omics list-runs-in-batch --batch-id 7123456

Puede filtrar los resultados mediante uno de los siguientes parámetros de consulta. Solo se admite un filtro por llamada.

Filtro	Description (Descripción)
submissionStatus	Filtrar por estado de envío: SUCCESS FAILEDCANCEL_SUCCESS,CANCEL_FAILED,,DELETE_SUCCESS, oDELETE_FAILED.
runSettingId	Recupera la ejecución para un ID de configuración de ejecución específico.
runId	Recupera la ejecución para un ID de ejecución específico.

Ejemplo: Listar los envíos fallidos

aws omics list-runs-in-batch --batch-id 7123456 --submission-status FAILED

Cada resultado incluye:

• runSettingId— El identificador proporcionado por el cliente para la configuración de ejecución.

• runId— El identificador HealthOmics de ejecución generado (vacío si el envío ha fallado).

• runArn— El ARN completo de la ejecución.

• submissionStatus— El resultado de la presentación (SUCCESSFAILED,CANCEL_SUCCESS,CANCEL_FAILED,DELETE_SUCCESS, oDELETE_FAILED).

• submissionFailureReasony submissionFailureMessage — Detalles en caso de error en el envío.

nota

runSettingIdes el identificador especificado por el cliente que proporcionó en la configuración de ejecución. runIdes el identificador HealthOmics generado y asignado tras un envío correcto. Si el envío ha fallado, runId está vacío.

Enumere los lotes

Úselo ListBatch para recuperar todos los recursos del lote de su cuenta. Los resultados están paginados.

aws omics list-batch

Puede filtrar los resultados mediante los siguientes parámetros de consulta:

Filtro	Description (Descripción)
status	Filtrar por estado de lote.
name	Filtrar por nombre de lote.
runGroupId	Filtrar por ID de grupo de carreras.

Gestión de ejecuciones fallidas

Hay dos tipos distintos de errores en el procesamiento por lotes. Comprender la diferencia es fundamental para la solución de problemas.

Fallos a nivel de lote

Un error a nivel de lote significa que el lote en sí ha fallado; no se ha creado ninguna ejecución (o solo se han creado algunas antes del error). El estado del lote es. FAILED

Llama GetBatch y consulta el failureReason campo. Los motivos de falla más comunes incluyen:

Categoría de error	Ejemplo de failureReason mensaje	Action
Error de validación	«Batch tiene 10 000 ejecuciones, pero 100 000 ejecuciones es el máximo. «, «Se esperaban 50 únicas, runSettingIds pero había 49", «El formato JSON no es válido en las configuraciones de ejecución»	Corrija la configuración y envíe un nuevo lote. Estos errores no se pueden volver a intentar.
Se ha modificado la configuración de S3	«Se esperaba s3 UriConfigs etag:\" abc123\» pero era:\ "def456\». s3 UriConfigs ha cambiado desde la llamada» StartRunBatch	No modifique el archivo S3 después de enviarlo. Vuelva a enviarlo con el archivo actual.
Error de servicio transitorio	«Se ha producido un error transitorio en el servicio. Vuelva a intentar el lote».	Vuelva a intentarlo enviando el mismo lote de nuevo. Usa lo mismo requestId para la idempotencia.

Ejemplo: Error en el lote debido a una validación

aws omics get-batch --batch-id 7123456

{
  "id": "7123456",
  "arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
  "status": "FAILED",
  "failureReason": "Batch has 100001 runs but 100000 runs is the max.",
  "failedTime": "2025-03-15T10:01:00Z"
}

Fallos en el nivel de ejecución

Un error en el nivel de ejecución significa que el lote en sí se ha realizado correctamente (el estado es INPROGRESS oPROCESSED), pero las ejecuciones individuales no se han podido enviar. El lote continúa procesando otras ejecuciones; no se detiene cuando se produce el primer error.

1. Consulte el resumen del envío

aws omics get-batch --batch-id 7123456

MirasubmissionSummary.failedStartSubmissionCount. Si es mayor que cero, algunas ejecuciones fallaron durante el envío.

2. Enumere los envíos fallidos

aws omics list-runs-in-batch --batch-id 7123456 --submission-status FAILED

Cada entrada fallida incluye:

• runSettingId— Qué configuración de ejecución falló.

• submissionFailureReason— La categoría de error.

• submissionFailureMessage— Un mensaje de error detallado.

3. Motivos de error en la presentación

La siguiente tabla muestra los valores posibles para submissionFailureReason cada ejecución individual:

submissionFailureReason	Significado	¿Reintentable?
ValidationException	Los parámetros de ejecución no son válidos; por ejemplo, los parámetros no coinciden con la definición del flujo de trabajo, el formato URI de S3 no es válido o infringen las restricciones.	No, corrija la configuración.
AccessDeniedException	La función de servicio de IAM carece de permisos para acceder a los recursos necesarios (entradas de S3, claves de KMS, CloudWatch registros e imágenes de ECR).	No, actualice la política de funciones.
ResourceNotFoundException	El recurso al que se hace referencia (flujo de trabajo, grupo de ejecución o caché de ejecución) no existe o no está en estado activo.	No, verifica el recurso IDs.
ServiceQuotaExceededException	La cuenta ha alcanzado el número máximo de ejecuciones activas u otra cuota de servicio.	Espere a que se completen las ejecuciones o solicite un aumento de la cuota.
ConflictException	Hay una operación conflictiva en curso, por ejemplo, un intento de creación de una ejecución duplicada.	Por lo general, se resuelve por sí solo.
ThrottlingException	La solicitud se retrasó debido a los límites de velocidad de la API.	El servicio se reintenta automáticamente. Si persiste después de volver a intentarlo, reduzca los envíos de lotes simultáneos.
RequestTimeoutException	Se agotó el tiempo de espera de la solicitud durante el procesamiento.	El servicio se reintenta automáticamente. Si persiste, compruebe si hay problemas posteriores.
InternalServerException	Se ha producido un error de servicio inesperado.	El servicio se reintenta automáticamente. Si persiste después de volver a intentarlo, ponte en contacto con AWS Support.

nota

HealthOmics reintenta automáticamente los errores transitorios (ThrottlingException,RequestTimeoutException,InternalServerException) en cada ejecución. Una ejecución se marca como ejecutada FAILED solo después de que se hayan agotado todos los reintentos. Los errores que no se pueden volver a intentar (ValidationException,AccessDeniedException,ResourceNotFoundException) fallan inmediatamente sin reintentos.

4. Vuelva a enviar las ejecuciones fallidas

Cree un lote nuevo que contenga solo las configuraciones de ejecución corregidas. Use lo mismo defaultRunSetting e incluya solo las runSettingId entradas que fallaron. No hay un mecanismo de reintento integrado para las ejecuciones fallidas; debe enviar un lote nuevo.

Cancelar un lote

Se utiliza CancelRunBatch para cancelar un lote en curso. La operación de cancelación:

• Impide que not-yet-submitted se inicien las ejecuciones pendientes

• Envía CancelRun solicitudes de ejecuciones que ya se han iniciado.

aws omics cancel-run-batch --batch-id 7123456

importante

• La cancelación solo está permitida en lotes situados en PENDINGSUBMITTING, o INPROGRESS estado.

• Solo se permite una operación de cancelación o eliminación por lote a la vez.

• Las operaciones de cancelación no son atómicas y pueden tener éxito parcial. Se utiliza GetBatch para revisar successfulCancelSubmissionCount y failedCancelSubmissionCount en elsubmissionSummary.

Eliminar ejecuciones por lotes

Se utiliza DeleteRunBatch para eliminar las corridas individuales de un lote.

aws omics delete-run-batch --batch-id 7123456

importante

• La eliminación solo está permitida en PROCESSED lotes de nuestro CANCELLED estado.

• Solo se permite una operación de cancelación o eliminación por lote a la vez.

• Las operaciones de eliminación no son atómicas y pueden tener éxito parcial. Se utiliza GetBatch para revisar successfulDeleteSubmissionCount y failedDeleteSubmissionCount en elsubmissionSummary.

Eliminar metadatos por lotes

Se utiliza DeleteBatch para eliminar el recurso por lotes y sus metadatos asociados. Se trata de una operación independiente deDeleteRunBatch.

aws omics delete-batch --batch-id 7123456

importante

• DeleteBatchrequiere que el lote esté en un estado terminal (PROCESSEDFAILED,CANCELLED, oRUNS_DELETED).

• DeleteBatchno elimina las corridas individuales. DeleteRunBatchÚselo primero si también desea eliminar los conductos.

• Una vez DeleteBatch finalizado, ya no se podrá acceder a los metadatos del lote. No puede llamar a GetBatchListRunsInBatch,DeleteRunBatch, ni CancelRunBatch a un lote eliminado.

EventBridge eventos para lotes

HealthOmics envía eventos a Amazon EventBridge cada vez que un lote cambia de estado. Puedes usar estos eventos para automatizar los flujos de trabajo, por ejemplo, para activar una notificación cuando un lote se complete o falle, o para iniciar una canalización descendente cuando todas las ejecuciones hayan finalizado.

Los eventos por lotes utilizan el mismo bus de eventos y la misma fuente que HealthOmics los demás eventos. Para obtener instrucciones generales de configuración, consulteUso EventBridge con AWS HealthOmics.

Tipo de detalle del evento

Nombre de evento	Emitido cuando
RunBatch Cambio de estado	El lote pasa a un nuevo estado (CREATING,PENDING,SUBMITTING,INPROGRESS,STOPPING,CANCELLED,PROCESSED,FAILED,RUNS_DELETING,RUNS_DELETED)

Campos de detalles del evento

El detail objeto de un evento por lotes incluye los siguientes campos:

Campo	Tipo	Description (Descripción)
omicsVersion	Cadena	Versión del esquema de eventos (actualmente 1.0.0).
arn	Cadena	El ARN del lote.
batchId	Cadena	El identificador del lote.
status	Cadena	El estado del nuevo lote.
uuid	Cadena	El UUID del lote.
batchName	Cadena	El nombre del lote (si se proporciona).
totalRuns	Cadena	Número total de corridas del lote.
failureReason	Cadena	Motivo del error (solo está presente cuando el estado esFAILED).
failureMessage	Cadena	Mensaje de error detallado (presente solo cuando el estado esFAILED).
successfulStartSubmissionCount	Cadena	Número de ejecuciones enviadas correctamente.
failedStartSubmissionCount	Cadena	Número de corridas que no se pudieron enviar.
pendingStartSubmissionCount	Cadena	Número de corridas pendientes de envío.
pendingRunCount	Cadena	Número de corridas en estado pendiente.
startingRunCount	Cadena	Número de corridas que se están iniciando.
runningRunCount	Cadena	Número de corridas actualmente en ejecución.
stoppingRunCount	Cadena	Número de ejecuciones que se están deteniendo.
completedRunCount	Cadena	Número de corridas completadas.
failedRunCount	Cadena	Número de ejecuciones con error.
cancelledRunCount	Cadena	Número de corridas canceladas.
deletedRunCount	Cadena	Número de corridas eliminadas.
workflowId	Cadena	El identificador del flujo de trabajo.
workflowArn	Cadena	El ARN del flujo de trabajo.
workflowVersionArn	Cadena	La versión ARN del flujo de trabajo (si corresponde).
workflowOwnerId	Cadena	El ID de la cuenta del propietario del flujo de trabajo (para flujos de trabajo compartidos).
runCache	Cadena	El ARN de la caché de ejecución (si corresponde).
runCacheBehavior	Cadena	El comportamiento de la caché de ejecución (si corresponde).

Ejemplos de evento

Ejemplo: evento «Batch completed»

{
  "version": "0",
  "id": "a1b2c3d4-5678-90ab-cdef-example11111",
  "detail-type": "RunBatch Status Change",
  "source": "aws.omics",
  "account": "123456789012",
  "time": "2025-03-15T12:30:00Z",
  "region": "us-west-2",
  "resources": [
    "arn:aws:omics:us-west-2:123456789012:runBatch/7123456"
  ],
  "detail": {
    "omicsVersion": "1.0.0",
    "arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
    "batchId": "7123456",
    "status": "PROCESSED",
    "uuid": "96c57683-74bf-9d6d-ae7e-f09b097db14a",
    "batchName": "genomics-cohort-analysis",
    "totalRuns": "96",
    "successfulStartSubmissionCount": "94",
    "failedStartSubmissionCount": "2",
    "pendingStartSubmissionCount": "0",
    "completedRunCount": "90",
    "failedRunCount": "4",
    "cancelledRunCount": "0",
    "workflowId": "1234567"
  }
}

Ejemplo: evento de Batch fallido

{
  "version": "0",
  "id": "a1b2c3d4-5678-90ab-cdef-example22222",
  "detail-type": "RunBatch Status Change",
  "source": "aws.omics",
  "account": "123456789012",
  "time": "2025-03-15T10:01:00Z",
  "region": "us-west-2",
  "resources": [
    "arn:aws:omics:us-west-2:123456789012:runBatch/7123456"
  ],
  "detail": {
    "omicsVersion": "1.0.0",
    "arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
    "batchId": "7123456",
    "status": "FAILED",
    "failureReason": "VALIDATION_EXCEPTION",
    "failureMessage": "Expected 100 unique runSettingIds but there were 99"
  }
}

Ejemplo: EventBridge regla para completar el lote

El siguiente patrón de eventos coincide cuando un lote alcanza un estado terminal:

{
  "source": ["aws.omics"],
  "detail-type": ["RunBatch Status Change"],
  "detail": {
    "status": ["PROCESSED", "FAILED", "CANCELLED"]
  }
}

Limitaciones y consideraciones

• Cuotas de rendimiento compartidas: las operaciones por lotes comparten las mismas cuotas por cuenta que sus homólogas de API individuales. StartRunBatchconsume cuotas de StartRun servicio. CancelRunBatchconsume CancelRun cuotas y DeleteRunBatch consume DeleteRun cuotas. Evite realizar ejecuciones individuales APIs mientras se esté procesando un lote grande, ya que esto puede provocar errores en el envío.

• Envío gradual: las tiradas de un lote se envían de forma gradual y asíncrona en función de sus cuotas de rendimiento.

• Operaciones no atómicas:StartRunBatch,CancelRunBatch, y todas DeleteRunBatch pueden tener éxito parcial. Compruebe siempre los resúmenes de envío para identificar las ejecuciones que se deben volver a intentar.

• Coherencia eventual: los recuentos del estado de ejecución de las ejecuciones GetBatch pueden estar por debajo de los estados de ejecución reales. Los recuentos finales son precisos una vez que el lote llegaPROCESSED.

• Filtro único por llamada a la lista ListRunsInBatch y solo ListBatch admite un filtro por llamada a la API.

• No se admite la repetición: el campo runId (volver a ejecutar) no se admite en. StartRunBatch Cada envío por lotes siempre crea nuevas tiradas.

• Flujos de trabajo de Ready2Run: las ejecuciones por lotes no son compatibles con los flujos de trabajo de Ready2Run.

• Límite de configuración en línea: las configuraciones en línea (inlineSettings) admiten hasta 100 entradas. Para lotes más grandes, utilice. s3UriSettings Este límite no se puede ajustar.

• Archivo de configuración de S3: el archivo de configuración de S3 debe ser una matriz JSON de objetos de configuración de ejecución. El tamaño máximo del archivo es de 6 GB y admite hasta 100 000 configuraciones de ejecución.

• Inmutabilidad del archivo S3: no modifique el archivo de configuración de S3 después de enviar el lote. HealthOmics valida la etiqueta de entidad del archivo (ETag) durante el envío y no pasa el lote si el archivo ha cambiado.