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à.

Il batch viene eseguito in HealthOmics

AWS HealthOmics le esecuzioni in batch consentono di inviare più esecuzioni in una singola 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:

Concetti di esecuzione in batch

Prerequisiti

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

autorizzazioni IAM per le operazioni in batch

La tua identità IAM deve disporre delle autorizzazioni sia per l'operazione batch che per la singola operazione di esecuzione 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"
        }
      }
    }
  ]
}

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

Tagging e controllo degli accessi basato su tag

Batch esegue i tag di supporto a due livelli:

Se utilizzi politiche di controllo degli accessi basate su tag, assicurati che la tua politica IAM includa omics:TagResource le condizioni e 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 impedisce 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:

Guida introduttiva: invia il tuo primo batch

L'esempio seguente illustra l'invio di un piccolo batch di due esecuzioni, la verifica dello stato di avanzamento e la revisione dei 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 da utilizzare per tutte le operazioni successive:

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

Passaggio 2: verifica 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: Rivedi le singole esecuzioni

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

Ogni voce associa l'utente runSettingId (ad esempiosample-A) a HealthOmics-generatedrunId, in modo da poter ricondurre i risultati ai campioni di input.

Fase 4: Verifica la presenza di invii non riusciti

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

Se alcune esecuzioni non sono state inviate, la risposta include submissionFailureReason e ti aiuta submissionFailureMessage a diagnosticare il problema.

Avvio di un'esecuzione in batch

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

È inoltre possibile fornire i seguenti campi:

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 nome univoco runSettingId (obbligatorio). runSettingIdÈ la chiave per correlare i risultati: quando chiamiListRunsInBatch, ogni voce ti mappa con runSettingId HealthOmics-generated runId la runArn fine.

È possibile 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 valore univoco. runSettingId Il file può contenere fino a 100.000 voci.

Il formato del 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"}'

Risposta

Una richiesta riuscita restituisce l'ID del batch e lo 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.

Unione dei parametri

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

Esempio:

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

Esempio di unione di tag:

Invio graduale

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

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

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

Monitoraggio del progresso del batch

Ottieni lo stato del batch

GetBatchDa utilizzare per recuperare lo stato complessivo e l'avanzamento dell'invio di un batch.

aws omics get-batch --batch-id 7123456

La risposta include:

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

L'elenco viene eseguito in un batch

ListRunsInBatchDa utilizzare per recuperare informazioni dettagliate sulle 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.

Esempio: elenca gli invii non riusciti

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

Ogni risultato include:

Elenca i batch

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

aws omics list-batch

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

Abilita le metriche di esecuzione

Esegui un rapporto sulle metriche sull'utilizzo delle risorse quasi in tempo reale per le esecuzioni di un batch. Per abilitare le metriche di esecuzione, il ruolo di servizio utilizzato per il batch deve disporre dell'autorizzazione. cloudwatch:PutMetricData Per ulteriori informazioni, consulta Esegui metriche per flussi di lavoro privati.

Aggiungi la seguente autorizzazione al ruolo di servizio che usi per il batch.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudwatch:PutMetricData",
      "Resource": "*"
    }
  ]
}

Gestione delle esecuzioni non riuscite

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

Batch-level guasti

Un errore a livello di batch indica che il batch stesso ha avuto esito negativo: non è stata creata alcuna esecuzione (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 insuccesso includono:

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

Run-level guasti

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

1. Controlla il riepilogo dell'invio

aws omics get-batch --batch-id 7123456

Guarda. submissionSummary.failedStartSubmissionCount Se è 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 inserimento non riuscito include:

3. Motivi del mancato invio

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

4. Invia nuovamente le esecuzioni non riuscite

Crea un nuovo batch contenente solo le configurazioni di esecuzione corrette. Usa lo stesso defaultRunSetting e includi solo le runSettingId voci che hanno avuto esito negativo. Non esiste un meccanismo di ripetizione integrato per le esecuzioni non riuscite: è necessario inviare un nuovo batch.

Annullamento di un batch

CancelRunBatchDa utilizzare per annullare un batch in corso. L'operazione di annullamento:

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

Eliminazione delle esecuzioni in batch

Consente DeleteRunBatch di eliminare le singole esecuzioni all'interno di un batch.

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

Eliminazione dei metadati del batch

Consente DeleteBatch di rimuovere la risorsa batch e i metadati associati. Si tratta di un'operazione separata da. DeleteRunBatch

aws omics delete-batch --batch-id 7123456

EventBridge eventi per batch

HealthOmics invia eventi ad Amazon EventBridge ogni volta che un batch cambia 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 downstream al termine di tutte le esecuzioni.

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

Tipo di dettaglio dell'evento

Campi con i dettagli dell'evento

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

Esempi di eventi

Esempio: evento completato in batch

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