Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# 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 utilizzando**CancelRunBatch**.
+ Elimina tutte le esecuzioni di un batch utilizzando**DeleteRunBatch**.
+ Elimina i metadati del batch con**DeleteBatch**.
**Topics**
+ [Concetti relativi all'esecuzione in batch](#batch-concepts)
+ [Prerequisiti](#batch-prerequisites)
+ [Autorizzazioni IAM per operazioni in batch](#batch-iam-permissions)
+ [Guida introduttiva: invia il tuo primo batch](#batch-getting-started)
+ [Avvio di un'esecuzione in batch](#batch-starting)
+ [Monitoraggio del progresso del batch](#batch-monitoring)
+ [Gestione delle esecuzioni non riuscite](#batch-handling-failures)
+ [Annullamento di un batch](#batch-canceling)
+ [Eliminazione delle esecuzioni in batch](#batch-deleting-runs)
+ [Eliminazione dei metadati in batch](#batch-deleting-metadata)
+ [EventBridge eventi per batch](#batch-eventbridge)
+ [Considerazioni e limitazioni](#batch-limitations)
## 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** (`inlineSettings`o`s3UriSettings`): 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 generata`runId`, 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](#batch-level-failures).
+ `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](permissions-service.md).
+ 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**
**StartRunBatch**richiede 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](permissions-service.md).
### 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** (`runTags`in corso `defaultRunSetting` e per esecuzione`runTags`): 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 appropriate`aws: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`. `submissionSummary`Mostra 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 esempio`sample-A`) a quella HealthOmics generata`runId`, 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
**StartRunBatch**Da 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). `runSettingId`Questa è la chiave per correlare i risultati: quando chiami**ListRunsInBatch**, 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'`inlineSettings`array:
```
[
{
"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](rerun-a-run.md) 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 | \$1"referenceUri": "s3://bucket/ref.fasta", "version": "v1"\$1 |
| inlineSettingsvoce | \$1"inputUri": "s3://bucket/sample.fastq", "version": "v2"\$1 |
| Risultato unito | \$1"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"\$1 |
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 | \$1"project": "cancer-research", "pipeline-version": "v2.1"\$1 |
| inlineSettings[].runTags | \$1"patient-id": "patient001", "pipeline-version": "v3.0"\$1 |
| Risultato unito (applicato all'esecuzione) | \$1"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"\$1 |
**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
**StartRunBatch**convalida 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](service-quotas.md)
Il batch passa attraverso i seguenti stati durante la normale elaborazione:
1. `CREATING`— Batch è in fase di creazione.
1. `PENDING`— Batch creato, configurazioni di esecuzione in corso di convalida.
1. `SUBMITTING`— Convalida completata, invio delle singole esecuzioni.
1. `INPROGRESS`— Tutti gli invii di esecuzione sono stati tentati, le esecuzioni sono in esecuzione.
1. `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** e**DeleteRun**: 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`, `STARTING``RUNNING`,`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\$1SUCCESS, CANCEL\$1FAILEDDELETE\$1SUCCESS, oDELETE\$1FAILED. |
| 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_FAILED``DELETE_SUCCESS`, o`DELETE_FAILED`).
+ `submissionFailureReason`e `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 | `failureReason`Messaggio 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:\$1" abc123\$1» ma era:\$1 "def456\$1». 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` o`PROCESSED`), 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 `PENDING``SUBMITTING`, 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 inserire`failedCancelSubmissionCount`. `submissionSummary`
## Eliminazione delle esecuzioni in batch
**DeleteRunBatch**Da 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 inserire`failedDeleteSubmissionCount`. `submissionSummary`
## Eliminazione dei metadati in batch
Utilizzare **DeleteBatch** per rimuovere la risorsa batch e i relativi metadati associati. Si tratta di un'operazione separata da**DeleteRunBatch**.
```
aws omics delete-batch --batch-id 7123456
```
**Importante**
**DeleteBatch**richiede che il batch sia in uno stato terminale (`PROCESSED``FAILED`,`CANCELLED`, o`RUNS_DELETED`).
**DeleteBatch**non 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 chiamare**GetBatch**, **ListRunsInBatch****DeleteRunBatch**, 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, vedere[Utilizzo EventBridge con AWS HealthOmics](eventbridge.md).
### 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\$1DELETING,RUNS\$1DELETED) |
### Campi di dettaglio dell'evento
L'`detail`oggetto 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. **StartRunBatch**consuma quote di servizio. **StartRun** **CancelRunBatch**consuma **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 parziale**StartRunBatch**. **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.