Batch viene eseguito in HealthOmics

AWS HealthOmics le esecuzioni in batch consentono di inviare più esecuzioni in un'unica richiesta API. Ogni esecuzione del batch condivide una configurazione di base comune, ma può avere input e parametri specifici dell'esecuzione diversi. Le esecuzioni in batch riducono il sovraccarico di invio e semplificano la gestione del ciclo di vita per l'elaborazione di flussi di lavoro su larga scala.

Con le esecuzioni in batch, puoi:

• Invia fino a 100.000 esecuzioni in una singola StartRunBatch chiamata, con una configurazione condivisa definita una volta e applicata a tutte le esecuzioni.

• Applica sostituzioni di parametri per esecuzione per singoli campioni, tra cui nome, URI di output, parametri, priorità e tag.

• Tieni traccia dello stato generale del batch e dell'avanzamento dell'invio delle singole esecuzioni tramite e. GetBatch ListRunsInBatch

• Annulla tutte le esecuzioni di un batch utilizzandoCancelRunBatch.

• Elimina tutte le esecuzioni di un batch utilizzandoDeleteRunBatch.

• Elimina i metadati del batch conDeleteBatch.

Concetti relativi all'esecuzione in batch

• Batch: una raccolta di flussi di lavoro che condividono una configurazione comune, gestita come un'unica risorsa con Amazon Resource Name (ARN) e stato del ciclo di vita propri.

• Impostazione di esecuzione predefinita (defaultRunSetting): parametri del flusso di lavoro condivisi tra tutte le esecuzioni del batch, come l'ID del flusso di lavoro, il ruolo IAM, l'URI di output e i parametri comuni.

• Impostazione specifica per l'esecuzione (inlineSettingsos3UriSettings): configurazioni per esecuzione che sostituiscono o si uniscono all'impostazione di esecuzione predefinita. Ogni voce deve includere un nome univoco. runSettingId

• Run setting ID (runSettingId): un identificatore univoco obbligatorio fornito dal cliente per ogni configurazione di esecuzione all'interno di un batch. Dopo l'invio, consente di mappare ciascuna ListRunsInBatch di esse runSettingId alla configurazione HealthOmics generatarunId, in modo da tracciare quale esecuzione è stata creata da quale configurazione di input.

• Stato del batch: lo stato generale dell'operazione batch. Valori possibili:

  • CREATING— Batch è in fase di creazione.

  • PENDING— Il batch è stato creato; le configurazioni di esecuzione vengono convalidate in modo asincrono.

  • SUBMITTING— Convalida completata; vengono inviate le singole esecuzioni.

  • INPROGRESS— Sono stati tentati tutti gli invii di esecuzione; le esecuzioni sono in esecuzione.

  • STOPPING— È stata ricevuta una richiesta di annullamento; le esecuzioni vengono interrotte.

  • CANCELLED— Il batch è stato annullato.

  • PROCESSED— Tutte le esecuzioni hanno raggiunto lo stato terminale (completata, fallita o annullata).

  • FAILED— Il batch stesso ha avuto esito negativo prima che potessero essere create le esecuzioni. Per informazioni dettagliate, vedi Guasti a livello di batch.

  • RUNS_DELETING— Le esecuzioni del batch vengono eliminate.

  • RUNS_DELETED— Tutte le esecuzioni del batch sono state eliminate.

• Stato di invio: il risultato dell'invio per una singola esecuzione all'interno del batch. Valori possibili:

  • SUCCESS— L'esecuzione è stata inviata correttamente.

  • FAILED— Invio dell'esecuzione non riuscito (ad esempio, a causa di un errore di convalida).

  • CANCEL_SUCCESS— L'esecuzione è stata annullata con successo.

  • CANCEL_FAILED— Annullamento dell'esecuzione non riuscito.

  • DELETE_SUCCESS— L'esecuzione è stata eliminata con successo.

  • DELETE_FAILED— Eliminazione dell'esecuzione non riuscita.

Prerequisiti

Prima di iniziare un'esecuzione in batch, assicurati di disporre di:

• Un flusso di lavoro HealthOmics privato attivo. Le esecuzioni in batch non sono supportate con i flussi di lavoro Ready2Run.

• Un ruolo di servizio IAM con autorizzazioni per eseguire HealthOmics flussi di lavoro e accedere ai bucket Amazon S3. Per informazioni dettagliate, vedi Ruoli di servizio per AWS HealthOmics.

• Posizioni Amazon S3 per i dati di input e i risultati di output.

• Parametri specifici di esecuzione per ogni esempio o configurazione sperimentale.

Autorizzazioni IAM per operazioni in batch

La tua identità IAM deve disporre delle autorizzazioni sia per l'operazione batch che per l'operazione di esecuzione individuale sottostante. La seguente politica di esempio concede le autorizzazioni per tutte le operazioni batch:

{
  "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

StartRunBatchrichiede una doppia autorizzazione: omics:StartRunBatch sulla risorsa batch e sulle risorse di esecuzione, omics:StartRun sul flusso di lavoro e sulle risorse del gruppo di esecuzione. Entrambe le autorizzazioni devono essere concesse affinché il batch abbia successo.

Il ruolo di servizio IAM passato roleArn (utilizzato da HealthOmics per eseguire le esecuzioni) richiede le stesse autorizzazioni delle singole StartRun chiamate. Per informazioni dettagliate, vedi Ruoli di servizio per AWS HealthOmics.

Etichettatura e controllo degli accessi basati su tag

Batch esegue i tag di supporto a due livelli:

• Tag batch (tag su StartRunBatch richiesta): applicati alla risorsa batch. Il controllo degli accessi basato su tag (TBAC) è completamente applicato per i tag batch.

• Tag di esecuzione (runTagsin corso defaultRunSetting e per esecuzionerunTags): applicati alle singole risorse di esecuzione. Questi tag vengono uniti utilizzando le stesse regole di precedenza dei parametri.

Se utilizzi policy di controllo degli accessi basate su tag, assicurati che la tua policy IAM includa le condizioni e omics:TagResource le condizioni appropriateaws:RequestTag. aws:TagKeys

Esempio: limita la creazione di batch agli ambienti non di produzione

La seguente politica consente agli utenti di creare batch ed esecuzioni, ma nega di etichettare qualsiasi risorsa 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 questa politica:

• tags: {"environment": "dev"}sul batch → Consentito

• tags: {"environment": "production"}sul batch → Negato (403)

• runTags: {"environment": "production"}in defaultRunSetting → Negato per le singole esecuzioni durante la creazione asincrona

Guida introduttiva: invia il tuo primo batch

L'esempio seguente illustra come inviare un piccolo batch di due esecuzioni, verificare lo stato di avanzamento e rivedere i risultati.

Fase 1: Inviare il batch

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 risposta restituisce un ID batch utilizzato per tutte le operazioni successive:

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

Fase 2: Verificare l'avanzamento del batch

aws omics get-batch --batch-id 7123456

Guarda l'avanzamento del status campo da CREATING PENDING → → SUBMITTING → INPROGRESS →PROCESSED. submissionSummaryMostra quante esecuzioni sono state inviate con successo e runSummary mostra l'avanzamento dell'esecuzione.

Fase 3: Esamina le singole esecuzioni

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

Ogni voce associa la tua runSettingId (ad esempiosample-A) a quella HealthOmics generatarunId, in modo da poter ricondurre i risultati ai campioni inseriti.

Fase 4: Verifica la presenza di invii non riusciti

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

Se non riesci a inviare alcuna esecuzione, la risposta include informazioni submissionFailureReason utili submissionFailureMessage per aiutarti a diagnosticare il problema.

Avvio di un'esecuzione in batch

StartRunBatchDa utilizzare per inviare più esecuzioni con una sola richiesta. La richiesta include:

• defaultRunSetting— Configurazione condivisa per tutte le esecuzioni del batch.

• batchRunSettings— Le configurazioni di esecuzione individuali, fornite come una delle seguenti:

  • inlineSettings— Una serie di un massimo di 100 configurazioni specifiche per l'esecuzione fornite direttamente nel corpo della richiesta.

  • s3UriSettings— Un URI Amazon S3 che punta a un file JSON contenente le configurazioni di esecuzione. Richiesto per batch con più di 100 esecuzioni e supporta fino a 100.000 esecuzioni.

È inoltre possibile fornire i seguenti campi:

• batchName— Un nome facoltativo leggibile dall'uomo per il batch.

• requestId— Un token di idempotenza per impedire l'invio di batch duplicati.

• tags— Tag da associare alla risorsa batch stessa.

Invia piccoli batch con configurazioni di esecuzione in linea

Fornisci una serie di configurazioni specifiche per l'esecuzione direttamente nel corpo della richiesta utilizzando. inlineSettings Ogni voce deve includere un codice univoco runSettingId (obbligatorio). runSettingIdQuesta è la chiave per correlare i risultati: quando chiamiListRunsInBatch, ogni voce corrisponde runSettingId a quella HealthOmics generata runId e. runArn

Puoi includere fino a 100 voci con configurazioni in linea.

{
  "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"}
      }
    ]
  }'

Invia batch di grandi dimensioni con configurazioni di esecuzione in S3

Per i batch con più di 100 esecuzioni, archivia le configurazioni di esecuzione in un file JSON in Amazon S3 e fornisci l'URI utilizzando. s3UriSettings Il file JSON deve contenere una serie di oggetti di impostazione specifici per l'esecuzione, ciascuno con un unico. runSettingId Il file può contenere fino a 100.000 voci.

Il formato di file S3 è lo stesso dell'inlineSettingsarray:

[
  {
    "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"
    }
  }
]

Richiesta 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

Il ruolo di servizio IAM specificato in roleArn deve avere accesso in lettura all'oggetto Amazon S3 specificato in. s3UriSettings HealthOmics convalida l'accesso al file Amazon S3 durante la chiamata API sincrona e registra i file. ETag Se il file viene modificato dopo l'invio, il batch ha esito negativo durante l'elaborazione asincrona.

Risposta

Una richiesta riuscita restituisce un ID batch e uno stato iniziale:

{
  "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"
  }
}

Se la convalida sincrona fallisce (ad esempio, un ID di flusso di lavoro non valido o un URI Amazon S3 inaccessibile), l'API restituisce un errore prima dell'invio di qualsiasi esecuzione.

Documentazione di riferimento dei parametri

La tabella seguente mostra quali StartRun campi possono essere impostati per esecuzione e quali si applicano solo a livello di batch. Per le descrizioni complete dei campi, consulta il riferimento StartRun API.

Campo	A livello di batch () defaultRunSetting	Configurabile per esecuzione () 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ì (unito)
priority	Sì	Sì
runTags	Sì	Sì (unito)
outputBucketOwnerId	Sì	Sì

Nota

Il campo runId (per singole riesecuzioni) non è supportato come input per. StartRunBatch Ogni invio in batch crea sempre nuove esecuzioni e ogni esecuzione riceverà un. runId Vedi Esegui nuovamente un run in HealthOmics per riprovare le singole esecuzioni.

Unione dei parametri

I parametri di defaultRunSetting vengono uniti ai parametri specifici dell'esecuzione forniti in inlineSettings o tramite un URI S3. I valori specifici dell'esecuzione hanno la precedenza quando le chiavi si sovrappongono.

Esempio:

Origine	Parameters
defaultRunSetting	{"referenceUri": "s3://bucket/ref.fasta", "version": "v1"}
inlineSettingsvoce	{"inputUri": "s3://bucket/sample.fastq", "version": "v2"}
Risultato unito	{"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"}

Lo stesso comportamento di fusione si applica a. runTags I tag specificati nella configurazione per esecuzione sostituiscono i tag con la stessa chiave di origine e vengono defaultRunSetting.runTags aggiunte nuove chiavi.

Esempio di fusione di tag:

Origine	Tag
defaultRunSetting.runTags	{"project": "cancer-research", "pipeline-version": "v2.1"}
inlineSettings[].runTags	{"patient-id": "patient001", "pipeline-version": "v3.0"}
Risultato unito (applicato all'esecuzione)	{"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"}

Nota

I tag a livello di batch (su StartRunBatch richiesta) vengono applicati solo alla risorsa batch stessa. Non vengono ereditati dalle singole esecuzioni. I tag a livello di esecuzione vengono controllati tramite defaultRunSetting.runTags e per singola esecuzione. runTags

Invio graduale

StartRunBatchconvalida i campi comuni in modo sincrono e restituisce immediatamente l'ID e lo stato del batch. CREATING Le esecuzioni in batch vengono inviate gradualmente e in modo asincrono a una velocità controllata in base alle quote di produttività stabilite.

Per l'elenco completo delle quote, vedere. HealthOmics HealthOmics quote di servizio

Il batch passa attraverso i seguenti stati durante la normale elaborazione:

1. CREATING— Batch è in fase di creazione.

2. PENDING— Batch creato, configurazioni di esecuzione in corso di convalida.

3. SUBMITTING— Convalida completata, invio delle singole esecuzioni.

4. INPROGRESS— Tutti gli invii di esecuzione sono stati tentati, le esecuzioni sono in esecuzione.

5. PROCESSED— Tutte le esecuzioni hanno raggiunto lo stato terminale.

Importante

L'invio dell'esecuzione in Batch condivide la stessa quota di StartRun throughput delle chiamate StartRun API dirette. Se chiami StartRun direttamente mentre è in corso l'elaborazione di un batch di grandi dimensioni, sia gli invii in batch che le chiamate dirette competono per la stessa capacità. Ciò può causare l'interruzione delle esecuzioni in batch ThrottlingException (frequenza superata) o la limitazione StartRun delle chiamate dirette. Lo stesso vale per CancelRun eDeleteRun: condividono le quote di throughput rispettivamente con e. CancelRunBatch DeleteRunBatch

Monitoraggio del progresso del batch

Ottieni lo stato del batch

Consente GetBatch di recuperare lo stato generale e l'avanzamento dell'invio di un batch.

aws omics get-batch --batch-id 7123456

La risposta include:

• status— Stato generale del batch.

• submissionSummary— Conteggio degli invii riusciti e non riusciti per le operazioni di avvio, annullamento ed eliminazione.

• runSummary— Conteggio delle esecuzioni in ogni stato di esecuzione. Valori possibili:PENDING, STARTINGRUNNING,STOPPING,COMPLETED,DELETED,CANCELLED, o FAILED

• Timestamp per gli eventi del ciclo di vita —creationTime,,,. submittedTime processedTime failedTime

Esempio di risposta:

{
  "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

I riepiloghi di esecuzione delle esecuzioni alla fine sono coerenti e possono rimanere indietro rispetto agli stati di esecuzione effettivi. I conteggi finali vengono riconciliati quando il batch raggiunge lo stato. PROCESSED

L'elenco viene eseguito in un batch

Utilizzato ListRunsInBatch per recuperare informazioni dettagliate per le singole esecuzioni all'interno di un batch. I risultati sono suddivisi in pagine.

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

È possibile filtrare i risultati utilizzando uno dei seguenti parametri di interrogazione. È supportato un solo filtro per chiamata.

Filtro	Description
submissionStatus	Filtra per stato di invio:SUCCESS,FAILED,CANCEL_SUCCESS, CANCEL_FAILEDDELETE_SUCCESS, oDELETE_FAILED.
runSettingId	Recupera la corsa per un ID di impostazione di corsa specifico.
runId	Recupera la corsa per un ID di corsa specifico.

Esempio: elenca gli invii non riusciti

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

Ogni risultato include:

• runSettingId— L'identificatore fornito dal cliente per la configurazione di esecuzione.

• runId— L'identificatore HealthOmics di esecuzione generato (vuoto se l'invio non è riuscito).

• runArn— L'ARN completo della corsa.

• submissionStatus— Il risultato dell'invio (SUCCESS,,FAILED,CANCEL_SUCCESS, CANCEL_FAILEDDELETE_SUCCESS, oDELETE_FAILED).

• submissionFailureReasone submissionFailureMessage — Dettagli se l'invio non è riuscito.

Nota

runSettingIdè l'identificatore specificato dal cliente fornito nella configurazione di esecuzione. runIdè l' HealthOmicsidentificatore generato assegnato dopo l'invio riuscito. Se l'invio non è riuscito, è vuoto. runId

Elenca i batch

Utilizzalo ListBatch per recuperare tutte le risorse in batch presenti nel tuo account. I risultati sono suddivisi in pagine.

aws omics list-batch

È possibile filtrare i risultati utilizzando i seguenti parametri di interrogazione:

Filtro	Description
status	Filtra per stato del batch.
name	Filtra per nome del batch.
runGroupId	Filtra per ID del gruppo di esecuzione.

Gestione delle esecuzioni non riuscite

Esistono due tipi distinti di errori nell'elaborazione in batch. Comprendere la differenza è fondamentale per la risoluzione dei problemi.

Guasti a livello di batch

Un errore a livello di batch significa che il batch stesso ha avuto esito negativo: non sono state create esecuzioni (o ne sono state create solo alcune prima dell'errore). Lo stato del batch è. FAILED

Chiama GetBatch e controlla il failureReason campo. I motivi più comuni di errore includono:

Categoria di errore	failureReasonMessaggio di esempio	Azione
Errore di convalida	«Batch ha 100001 esecuzioni, ma 100000 esecuzioni è il massimo. «, «Previste 50 univoche runSettingIds ma ce n'erano 49", «Formato JSON non valido nelle configurazioni di esecuzione»	Correggi la configurazione e invia un nuovo batch. Questi errori non sono riutilizzabili.
Configurazione S3 modificata	«Era previsto l'UriConfigs etag di s3:\" abc123\» ma era:\ "def456\». s3 è cambiato dopo la chiamata» UriConfigs StartRunBatch	Non modificare il file S3 dopo l'invio. Invia nuovamente con il file corrente.
Errore temporaneo del servizio	«Si è verificato un errore temporaneo nel servizio. Riprova il batch.»	Riprova inviando nuovamente lo stesso batch. Usalo requestId per l'idempotenza.

Esempio: Batch non riuscito a causa della convalida

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"
}

Errori a livello di esecuzione

Un errore a livello di esecuzione indica che il batch stesso ha avuto esito positivo (lo stato è INPROGRESS oPROCESSED), ma le singole esecuzioni non sono state inviate. Il batch continua a elaborare le altre esecuzioni e non si interrompe al primo errore.

1. Controlla il riepilogo dell'invio

aws omics get-batch --batch-id 7123456

Guardate. submissionSummary.failedStartSubmissionCount Se questo valore è maggiore di zero, alcune esecuzioni non sono riuscite durante l'invio.

2. Elenca gli invii non riusciti

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

Ogni immissione non riuscita include:

• runSettingId— Quale configurazione di esecuzione non è riuscita.

• submissionFailureReason— La categoria di errore.

• submissionFailureMessage— Un messaggio di errore dettagliato.

3. Motivi del mancato invio

La tabella seguente elenca i valori possibili per le submissionFailureReason singole esecuzioni:

submissionFailureReason	Significato	Non irreversibile?
ValidationException	I parametri di esecuzione non sono validi, ad esempio i parametri non corrispondono alla definizione del flusso di lavoro, al formato URI S3 non valido o alle violazioni dei vincoli.	No: correggi la configurazione.
AccessDeniedException	Il ruolo di servizio IAM non dispone delle autorizzazioni per accedere alle risorse richieste (input S3, chiavi KMS, CloudWatch registri, immagini ECR).	No: aggiorna la politica del ruolo.
ResourceNotFoundException	Una risorsa di riferimento (workflow, run group o run cache) non esiste o non è in uno stato attivo.	No: verifica la risorsa IDs.
ServiceQuotaExceededException	L'account ha raggiunto il numero massimo di esecuzioni attive o un'altra quota di servizio.	Attendi il completamento delle esecuzioni o richiedi un aumento della quota.
ConflictException	È in corso un'operazione in conflitto, ad esempio un tentativo di creazione di un'esecuzione duplicata.	In genere si risolve da solo.
ThrottlingException	La richiesta è stata limitata a causa dei limiti di velocità dell'API.	Il servizio riprova automaticamente. Se il problema persiste dopo i nuovi tentativi, riduci gli invii simultanei di batch.
RequestTimeoutException	La richiesta è scaduta durante l'elaborazione.	Il servizio riprova automaticamente. Se il problema persiste, verifica la presenza di problemi a valle.
InternalServerException	Si è verificato un errore di servizio imprevisto.	Il servizio riprova automaticamente. Se il problema persiste dopo altri tentativi, contatta l'assistenza AWS .

Nota

HealthOmics riprova automaticamente gli errori transitori (ThrottlingException,RequestTimeoutException,InternalServerException) per ogni esecuzione. Un'esecuzione viene contrassegnata come valida FAILED solo dopo l'esaurimento di tutti i tentativi. Gli errori non rieseguibili (ValidationException,AccessDeniedException,ResourceNotFoundException) falliscono immediatamente senza nuovi tentativi.

4. Reinvio di esecuzioni non riuscite

Crea un nuovo batch contenente solo le configurazioni di esecuzione corrette. Utilizza lo stesso codice defaultRunSetting e includi solo le runSettingId voci non riuscite. Non esiste un meccanismo di riprova integrato per le esecuzioni non riuscite: è necessario inviare un nuovo batch.

Annullamento di un batch

Utilizzare CancelRunBatch per annullare un batch in corso. L'operazione di annullamento:

• Impedisce l'avvio not-yet-submitted e le esecuzioni in sospeso

• Invia CancelRun richieste per esecuzioni già iniziate.

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

Importante

• L'annullamento è consentito solo per i batch in PENDINGSUBMITTING, o INPROGRESS stato.

• È consentita una sola operazione di annullamento o eliminazione per batch alla volta.

• Le operazioni di annullamento non sono atomiche e possono avere esito positivo parziale. Utilizzare GetBatch per rivedere successfulCancelSubmissionCount e inserirefailedCancelSubmissionCount. submissionSummary

Eliminazione delle esecuzioni in batch

DeleteRunBatchDa utilizzare per eliminare le singole esecuzioni all'interno di un batch.

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

Importante

• L'eliminazione è consentita solo per i batch presenti nel PROCESSED nostro CANCELLED stato.

• È consentita una sola operazione di annullamento o eliminazione per batch alla volta.

• Le operazioni di eliminazione non sono atomiche e possono avere esito positivo parziale. Utilizzare GetBatch per rivedere successfulDeleteSubmissionCount e inserirefailedDeleteSubmissionCount. submissionSummary

Eliminazione dei metadati in batch

Utilizzare DeleteBatch per rimuovere la risorsa batch e i relativi metadati associati. Si tratta di un'operazione separata daDeleteRunBatch.

aws omics delete-batch --batch-id 7123456

Importante

• DeleteBatchrichiede che il batch sia in uno stato terminale (PROCESSEDFAILED,CANCELLED, oRUNS_DELETED).

• DeleteBatchnon elimina le singole esecuzioni. Usa DeleteRunBatch prima se vuoi rimuovere anche le esecuzioni.

• Una volta DeleteBatch completati, i metadati del batch non sono più accessibili. Non è possibile chiamareGetBatch, ListRunsInBatchDeleteRunBatch, o CancelRunBatch su un batch eliminato.

EventBridge eventi per batch

HealthOmics invia eventi ad Amazon EventBridge ogni volta che un batch cambia lo stato. Puoi utilizzare questi eventi per automatizzare i flussi di lavoro, ad esempio per attivare una notifica quando un batch viene completato o fallito o per avviare una pipeline a valle al termine di tutte le esecuzioni.

Gli eventi Batch utilizzano lo stesso bus di eventi e la stessa origine HealthOmics degli altri eventi. Per istruzioni generali sulla configurazione, vedereUtilizzo EventBridge con AWS HealthOmics.

Tipo di dettaglio dell'evento

Nome evento	Emesso quando
RunBatch Modifica dello stato	Il batch passa a un nuovo stato (CREATING,PENDING,SUBMITTING,INPROGRESS,STOPPING,CANCELLED,PROCESSED, FAILEDRUNS_DELETING,RUNS_DELETED)

Campi di dettaglio dell'evento

L'detailoggetto in un evento batch include i seguenti campi:

Campo	Tipo	Description
omicsVersion	Stringa	Versione dello schema degli eventi (attualmente 1.0.0).
arn	Stringa	L'ARN del lotto.
batchId	Stringa	L'identificatore del batch.
status	Stringa	Il nuovo stato del batch.
uuid	Stringa	L'UUID del batch.
batchName	Stringa	Il nome del batch (se fornito).
totalRuns	Stringa	Numero totale di tirature del batch.
failureReason	Stringa	Motivo dell'errore (presente solo quando lo stato èFAILED).
failureMessage	Stringa	Messaggio di errore dettagliato (presente solo quando lo stato èFAILED).
successfulStartSubmissionCount	Stringa	Numero di esecuzioni inviate con successo.
failedStartSubmissionCount	Stringa	Numero di esecuzioni non inviate.
pendingStartSubmissionCount	Stringa	Numero di esecuzioni ancora in attesa di invio.
pendingRunCount	Stringa	Numero di esecuzioni in sospeso.
startingRunCount	Stringa	Numero di esecuzioni iniziali.
runningRunCount	Stringa	Numero di esecuzioni attualmente in esecuzione.
stoppingRunCount	Stringa	Numero di esecuzioni interrotte.
completedRunCount	Stringa	Numero di esecuzioni completate.
failedRunCount	Stringa	Numero di esecuzioni non riuscite.
cancelledRunCount	Stringa	Numero di corse annullate.
deletedRunCount	Stringa	Numero di esecuzioni eliminate.
workflowId	Stringa	L'identificatore del flusso di lavoro.
workflowArn	Stringa	L'ARN del flusso di lavoro.
workflowVersionArn	Stringa	La versione del flusso di lavoro ARN (se applicabile).
workflowOwnerId	Stringa	L'ID dell'account del proprietario del flusso di lavoro (per i flussi di lavoro condivisi).
runCache	Stringa	L'ARN della cache di esecuzione (se applicabile).
runCacheBehavior	Stringa	Il comportamento di esecuzione della cache (se applicabile).

Esempi di eventi

Esempio: evento Batch completato

{
  "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"
  }
}

Esempio: evento Batch non riuscito

{
  "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"
  }
}

Esempio: EventBridge regola per il completamento del batch

Il seguente schema di eventi corrisponde quando un batch raggiunge uno stato terminale:

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

Considerazioni e limitazioni

• Quote di throughput condivise: le operazioni Batch condividono le stesse quote per account delle loro controparti API individuali. StartRunBatchconsuma quote di servizio. StartRun CancelRunBatchconsuma CancelRun quote e consuma quote. DeleteRunBatch DeleteRun Evita di chiamare single run APIs mentre è in corso un batch di grandi dimensioni, poiché ciò può causare errori di invio.

• Invio graduale: le esecuzioni in batch vengono inviate gradualmente e in modo asincrono in base alle quote di velocità effettiva stabilite.

• Operazioni non atomiche: e tutte possono avere un successo parzialeStartRunBatch. CancelRunBatch DeleteRunBatch Controlla sempre i riepiloghi degli invii per identificare le esecuzioni che richiedono un nuovo tentativo.

• Coerenza finale: il conteggio dello stato di esecuzione dell'esecuzione GetBatch può essere inferiore agli stati di esecuzione effettivi. I conteggi finali sono accurati una volta raggiunto il batch. PROCESSED

• Filtro singolo per chiamata all'elenco ListRunsInBatch e ListBatch supporto di un solo filtro per chiamata API.

• Re-run non supportata: il campo runId (re-run) non è supportato in. StartRunBatch Ogni invio in batch crea sempre nuove esecuzioni.

• Flussi di lavoro Ready2Run: le esecuzioni in batch non sono supportate con i flussi di lavoro Ready2Run.

• Limite di configurazione in linea: le configurazioni in linea () supportano fino a 100 voci. inlineSettings Per lotti più grandi, usa. s3UriSettings Questo limite non è regolabile.

• File di configurazione S3: il file di configurazione S3 deve essere un array JSON di oggetti di impostazione di esecuzione. La dimensione massima del file è di 6 GB e supporta fino a 100.000 configurazioni di esecuzione.

• Immutabilità del file S3: non modificare il file di configurazione S3 dopo l'invio del batch. HealthOmics convalida il tag di entità (ETag) del file durante l'invio e fallisce il batch se il file è cambiato.