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.
# 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 utilizando**CancelRunBatch**.
+ Elimine todas las corridas de un lote utilizando**DeleteRunBatch**.
+ Elimine los metadatos del lote con**DeleteBatch**.
**Topics**
+ [Conceptos de ejecución por lotes](#batch-concepts)
+ [Requisitos previos](#batch-prerequisites)
+ [Permisos de IAM para operaciones por lotes](#batch-iam-permissions)
+ [Para empezar: envíe su primer lote](#batch-getting-started)
+ [Iniciar una ejecución por lotes](#batch-starting)
+ [Supervisión del progreso de los lotes](#batch-monitoring)
+ [Gestión de ejecuciones fallidas](#batch-handling-failures)
+ [Cancelar un lote](#batch-canceling)
+ [Eliminar ejecuciones por lotes](#batch-deleting-runs)
+ [Eliminar metadatos por lotes](#batch-deleting-metadata)
+ [EventBridge eventos para lotes](#batch-eventbridge)
+ [Limitaciones y consideraciones](#batch-limitations)
## 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** (`inlineSettings`o`s3UriSettings`): 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 generada`runId`, 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](#batch-level-failures).
+ `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](permissions-service.md).
+ 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**
**StartRunBatch**requiere 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](permissions-service.md).
### 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ón`runTags`): 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 adecuadas`aws: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`. `submissionSummary`Muestra 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 ejemplo`sample-A`) con las HealthOmics generadas`runId`, 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 llamas**ListRunsInBatch**, 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 mediante`s3UriSettings`. 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 en`s3UriSettings`. 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 para**StartRunBatch**. Cada envío por lotes siempre crea nuevas tiradas y cada tirada recibirá una`runId`. Consulte [Vuelva a ejecutar una ejecución HealthOmics](rerun-a-run.md) 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 | \$1"referenceUri": "s3://bucket/ref.fasta", "version": "v1"\$1 |
| inlineSettingsentrada | \$1"inputUri": "s3://bucket/sample.fastq", "version": "v2"\$1 |
| Resultado fusionado | \$1"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"\$1 |
El mismo comportamiento de fusión se aplica a`runTags`. 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 | \$1"project": "cancer-research", "pipeline-version": "v2.1"\$1 |
| inlineSettings[].runTags | \$1"patient-id": "patient001", "pipeline-version": "v3.0"\$1 |
| Resultado combinado (aplicado a la ejecución) | \$1"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"\$1 |
**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
**StartRunBatch**valida 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](service-quotas.md)
El lote pasa por los siguientes estados durante el procesamiento normal:
1. `CREATING`— Se está creando el lote.
1. `PENDING`— Batch creado, se están validando las configuraciones de ejecución.
1. `SUBMITTING`— Se completó la validación y se enviaron ejecuciones individuales.
1. `INPROGRESS`— Se han intentado enviar todas las ejecuciones, las ejecuciones se están ejecutando.
1. `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** y**DeleteRun**, 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`, `STARTING``RUNNING`,`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\$1SUCCESS,CANCEL\$1FAILED,,DELETE\$1SUCCESS, oDELETE\$1FAILED. |
| 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 (`SUCCESS``FAILED`,`CANCEL_SUCCESS`,`CANCEL_FAILED`,`DELETE_SUCCESS`, o`DELETE_FAILED`).
+ `submissionFailureReason`y `submissionFailureMessage` — Detalles en caso de error en el envío.
**nota**
`runSettingId`es el identificador especificado por el cliente que proporcionó en la configuración de ejecución. `runId`es 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:\$1" abc123\$1» pero era:\$1 "def456\$1». 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` o`PROCESSED`), 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
```
Mira`submissionSummary.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 `PENDING``SUBMITTING`, 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 el`submissionSummary`.
## 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 el`submissionSummary`.
## Eliminar metadatos por lotes
Se utiliza **DeleteBatch** para eliminar el recurso por lotes y sus metadatos asociados. Se trata de una operación independiente de**DeleteRunBatch**.
```
aws omics delete-batch --batch-id 7123456
```
**importante**
**DeleteBatch**requiere que el lote esté en un estado terminal (`PROCESSED``FAILED`,`CANCELLED`, o`RUNS_DELETED`).
**DeleteBatch**no 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 **GetBatch****ListRunsInBatch**,**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, consulte[Uso EventBridge con AWS HealthOmics](eventbridge.md).
### 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\$1DELETING,RUNS\$1DELETED) |
### 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. **StartRunBatch**consume cuotas de **StartRun** servicio. **CancelRunBatch**consume **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 llega`PROCESSED`.
+ **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.