Batch läuft in HealthOmics

AWS HealthOmics Mit Batchläufen können Sie mehrere Läufe in einer einzigen API-Anforderung einreichen. Jeder Lauf im Batch hat eine gemeinsame Basiskonfiguration, kann jedoch unterschiedliche Eingaben und laufspezifische Parameter haben. Batchläufe reduzieren den Aufwand für die Einreichung und vereinfachen das Lebenszyklusmanagement bei umfangreichen Workflow-Verarbeitungen.

Mit Batchläufen können Sie:

• Reichen Sie bis zu 100.000 Läufe in einem einzigen StartRunBatch Aufruf ein, wobei eine gemeinsame Konfiguration einmal definiert und auf alle Läufe angewendet wird.

• Wenden Sie Parameterüberschreibungen pro Lauf für einzelne Samples an, einschließlich Name, Ausgabe-URI, Parameter, Priorität und Tags.

• Verfolgen Sie den Gesamtstatus der Charge und den Fortschritt der einzelnen Durchläufe bis GetBatch zum Ende. ListRunsInBatch

• Stornieren Sie alle Läufe in einem Stapel mitCancelRunBatch.

• Löschen Sie alle Läufe in einem Stapel mitDeleteRunBatch.

• Löschen Sie Batch-Metadaten mitDeleteBatch.

Konzepte für die Batch-Ausführung

• Batch — Eine Sammlung von Workflow-Ausführungen mit einer gemeinsamen Konfiguration, die als einzelne Ressource mit eigenem Amazon-Ressourcennamen (ARN) und Lebenszyklusstatus verwaltet wird.

• Standard-Ausführungseinstellung (defaultRunSetting) — Workflow-Parameter, die von allen Läufen im Batch gemeinsam genutzt werden, wie Workflow-ID, IAM-Rolle, Ausgabe-URI, Sitzungsrichtlinie und gemeinsame Parameter.

• Run-specific Einstellung (inlineSettingsoders3UriSettings) — Per-run Konfigurationen, die die standardmäßige Ausführungseinstellung überschreiben oder mit ihr zusammenführen. Jeder Eintrag muss ein Unikat enthaltenrunSettingId.

• Run Setting-ID (runSettingId) — Eine erforderliche, vom Kunden bereitgestellte eindeutige Kennung für jede Ausführungskonfiguration innerhalb eines Batches. Verwenden Sie diese Option, ListRunsInBatch um die einzelnen Befehle runSettingId nach der HealthOmics-generated runId zuzuordnen, sodass Sie nachvollziehen können, welcher Lauf mit welcher Eingabekonfiguration erstellt wurde.

• Batch-Status — Der Gesamtstatus des Batch-Vorgangs. Mögliche Werte:

  • CREATING— Der Stapel wird erstellt.

  • PENDING— Der Stapel wurde erstellt; die Ausführungskonfigurationen werden asynchron validiert.

  • SUBMITTING— Die Validierung ist abgeschlossen; einzelne Läufe werden eingereicht.

  • INPROGRESS— Es wurde versucht, alle Durchläufe einzureichen; die Läufe werden ausgeführt.

  • STOPPING— Eine Stornierungsanfrage ist eingegangen; die Läufe werden gestoppt.

  • CANCELLED— Der Stapel wurde storniert.

  • PROCESSED— Alle Läufe haben einen Endzustand erreicht (abgeschlossen, fehlgeschlagen oder abgebrochen).

  • FAILED— Der Stapel selbst ist fehlgeschlagen, bevor die Läufe erstellt werden konnten. Details dazu finden Sie unter Batch-level Ausfälle.

  • RUNS_DELETING— Die Läufe im Stapel werden gelöscht.

  • RUNS_DELETE_FAILED— Einige oder alle Läufe im Stapel konnten nicht gelöscht werden.

  • RUNS_DELETED— Alle Läufe im Stapel wurden gelöscht.

• Übermittlungsstatus — Das Übermittlungsergebnis für einen einzelnen Durchlauf innerhalb des Batches. Mögliche Werte:

  • SUCCESS— Der Lauf wurde erfolgreich übermittelt.

  • FAILED— Die Übertragung des Laufs ist fehlgeschlagen (z. B. aufgrund eines Validierungsfehlers).

  • CANCEL_SUCCESS— Der Lauf wurde erfolgreich abgebrochen.

  • CANCEL_FAILED— Der Abbruch des Laufs ist fehlgeschlagen.

  • DELETE_SUCCESS— Der Lauf wurde erfolgreich gelöscht.

  • DELETE_FAILED— Der Löschvorgang ist fehlgeschlagen.

Voraussetzungen

Bevor Sie eine Batchausführung starten, stellen Sie sicher, dass Sie über Folgendes verfügen:

• Ein aktiver HealthOmics privater Workflow. Batch-Läufe werden mit Ready2Run-Workflows nicht unterstützt.

• Eine IAM-Servicerolle mit Berechtigungen zum Ausführen von HealthOmics Workflows und zum Zugriff auf Ihre Amazon S3-Buckets. Details hierzu finden Sie unter Servicerollen für AWS HealthOmics.

• Amazon S3-Standorte für Eingabedaten und Ausgabeergebnisse.

• Run-specific Parameter für jede Probe oder experimentelle Konfiguration.

IAM-Berechtigungen für Batch-Operationen

Ihre IAM-Identität muss über Berechtigungen sowohl für den Batchvorgang als auch für den zugrunde liegenden individuellen Ausführungsvorgang verfügen. Die folgende Beispielrichtlinie gewährt Berechtigungen für alle Batchvorgänge:

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

Anmerkung

StartRunBatcherfordert eine doppelte Autorisierung: omics:StartRunBatch für die Batch-Ressource und omics:StartRun für die Run-, Workflow- und Run-Gruppenressourcen. Beide Berechtigungen müssen erteilt werden, damit der Batch erfolgreich ist.

Für die übergebene roleArn IAM-Servicerolle (die von HealthOmics zur Ausführung der Läufe verwendet wird) sind dieselben Berechtigungen erforderlich wie für einzelne StartRun Aufrufe. Details hierzu finden Sie unter Servicerollen für AWS HealthOmics.

Tagging und tagbasierte Zugriffskontrolle

Batch-Läufe unterstützen Tags auf zwei Ebenen:

• Batch-Tags (Tags auf der StartRunBatch Anfrage) — Auf die Batch-Ressource angewendet. Tag-based Die Zugriffskontrolle (TBAC) wird für Batch-Tags vollständig durchgesetzt.

• Run-Tags (runTagsin defaultRunSetting und pro LaufrunTags) — Wird auf einzelne Ausführungsressourcen angewendet. Diese Tags werden unter Verwendung derselben Prioritätsregeln wie Parameter zusammengeführt.

Wenn Sie tagbasierte Zugriffskontrollrichtlinien verwenden, stellen Sie sicher, dass Ihre IAM-Richtlinie die omics:TagResource entsprechenden aws:RequestTag Randbedingungen enthält. aws:TagKeys

Beispiel: Beschränken Sie die Batch-Erstellung auf Umgebungen außerhalb der Produktion

Die folgende Richtlinie ermöglicht Benutzern das Erstellen von Batches und Läufen, verweigert jedoch das Taggen von Ressourcen mit: 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"
        }
      }
    }
  ]
}

Mit dieser Richtlinie:

• tags: {"environment": "dev"}auf dem Stapel → Erlaubt

• tags: {"environment": "production"}auf dem Stapel → Abgelehnt (403)

• runTags: {"environment": "production"}in defaultRunSetting → Verweigert für einzelne Läufe während der asynchronen Erstellung

Erste Schritte: Reichen Sie Ihren ersten Stapel ein

Das folgende Beispiel zeigt, wie Sie einen kleinen Batch mit zwei Durchläufen einreichen, den Fortschritt überprüfen und die Ergebnisse überprüfen.

Schritt 1: Senden Sie den Stapel

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

Die Antwort gibt eine Batch-ID zurück, die Sie für alle nachfolgenden Operationen verwenden:

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

Schritt 2: Überprüfen Sie den Batch-Fortschritt

aws omics get-batch --batch-id 7123456

Verfolgen Sie den Fortschritt des status Feldes von CREATING PENDING → → SUBMITTING → INPROGRESS → ausPROCESSED. submissionSummaryZeigt an, wie viele Durchläufe erfolgreich eingereicht wurden, und runSummary zeigt den Ausführungsfortschritt.

Schritt 3: Einzelne Läufe überprüfen

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

Bei jedem Eintrag werden Ihre runSettingId Daten (z. B.sample-A) dem zugeordnet HealthOmics-generatedrunId, sodass Sie die Ergebnisse auf Ihre Eingabesamples zurückverfolgen können.

Schritt 4: Suchen Sie nach fehlgeschlagenen Einreichungen

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

Wenn bei einem Durchlauf ein Fehler aufgetreten ist, wird in der Antwort Folgendes submissionFailureReason angegebensubmissionFailureMessage, um Ihnen bei der Problemdiagnose zu helfen.

Einen Batch-Lauf starten

Wird verwendetStartRunBatch, um mehrere Läufe mit einer einzigen Anfrage zu senden. Die Anfrage beinhaltet:

• defaultRunSetting— Gemeinsame Konfiguration für alle Läufe im Batch. Dazu gehören Felder wie workflowIdroleArn,outputUri, parametersscratchStorageMode, undengineSettings. Für Nextflow-Workflows verwenden Sie diese Option, engineSettings um Profile anzugeben, die für alle Läufe im Batch gelten. Weitere Informationen finden Sie unter Geben Sie die Nextflow-Engine-Einstellungen an.

• batchRunSettings— Die einzelnen Ausführungskonfigurationen, bereitgestellt als eine der folgenden:

  • inlineSettings— Eine Reihe von bis zu 100 laufspezifischen Konfigurationen, die direkt im Anforderungstext bereitgestellt werden. Jede Inline-Einstellung kann das Überschreiben des Standardprofils für einzelne Läufe beinhaltenengineSettings.

  • s3UriSettings— Eine Amazon S3-URI, die auf eine JSON-Datei verweist, die die Ausführungskonfigurationen enthält. Erforderlich für Batches mit mehr als 100 Läufen und unterstützt bis zu 100.000 Läufe.

Sie können auch die folgenden Felder angeben:

• batchName— Ein optionaler, von Menschen lesbarer Name für den Stapel.

• requestId— Ein Idempotenz-Token, um doppelte Batch-Einreichungen zu verhindern.

• tags— Tags, die der Batch-Ressource selbst zugeordnet werden sollen.

Reichen Sie kleine Batches mit Inline-Run-Konfigurationen ein

Stellen Sie eine Reihe laufspezifischer Konfigurationen direkt im Anforderungstext mithilfe von bereit. inlineSettings Jeder Eintrag muss ein Unikat runSettingId (erforderlich) enthalten. Das runSettingId ist Ihr Schlüssel zum Korrelieren von Ergebnissen — wenn Sie anrufenListRunsInBatch, ordnet jeder Eintrag Sie dem runSettingId HealthOmics-generated runId Ende zu. runArn

Sie können bis zu 100 Einträge mit Inline-Konfigurationen einbeziehen.

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

Reichen Sie große Batches mit Run-Konfigurationen in S3 ein

Speichern Sie Ihre Ausführungskonfigurationen für Batches mit mehr als 100 Durchläufen in einer JSON-Datei in Amazon S3 und geben Sie den URI mithilfe von an. s3UriSettings Die JSON-Datei muss ein Array von laufspezifischen Einstellungsobjekten enthalten, jedes mit einem eindeutigen Objekt. runSettingId Die Datei kann bis zu 100.000 Einträge enthalten.

Das S3-Dateiformat ist dasselbe wie das 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"
    }
  }
]

API-Anfrage

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

Wichtig

Die in angegebene IAM-Servicerolle roleArn muss Lesezugriff auf das unter angegebene Amazon S3-Objekt haben. s3UriSettings HealthOmics validiert den Zugriff auf die Amazon S3-Datei während des synchronen API-Aufrufs und zeichnet das ETag der Datei auf. Wenn die Datei nach der Übermittlung geändert wird, schlägt der Batch während der asynchronen Verarbeitung fehl.

Antwort

Eine erfolgreiche Anfrage gibt eine Batch-ID und einen Anfangsstatus zurück:

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

Schlägt die synchrone Validierung fehl (z. B. eine ungültige Workflow-ID oder eine Amazon S3-URI, auf die nicht zugegriffen werden kann), gibt die API einen Fehler zurück, bevor irgendwelche Läufe übermittelt werden.

Parameterreferenz

Die folgende Tabelle zeigt, welche StartRun Felder pro Lauf festgelegt werden können und welche nur auf Batch-Ebene gelten. Vollständige Feldbeschreibungen finden Sie in der StartRun API-Referenz.

Feld	Batch-level (defaultRunSetting)	Per-run konfigurierbar (inlineSettings)
workflowId	Ja	Nein
workflowType	Ja	Nein
workflowVersionName	Ja	Nein
workflowOwnerId	Ja	Nein
roleArn	Ja	Nein
storageCapacity	Ja	Nein
storageType	Ja	Nein
runGroupId	Ja	Nein
logLevel	Ja	Nein
cacheBehavior	Ja	Nein
cacheId	Ja	Nein
retentionMode	Ja	Nein
networkingMode	Ja	Nein
configurationName	Ja	Nein
name	Ja	Ja
outputUri	Ja	Ja
parameters	Ja	Ja (zusammengeführt)
priority	Ja	Ja
runTags	Ja	Ja (zusammengeführt)
outputBucketOwnerId	Ja	Ja

Anmerkung

Das Feld runId (für einzelne Wiederholungen) wird nicht als Eingabe für unterstützt. StartRunBatch Bei jeder Stapelübermittlung werden immer neue Durchläufe erstellt, und jeder Durchlauf erhält einerunId. Informationen Führen Sie einen Run in erneut aus HealthOmics zum erneuten Versuch einzelner Läufe finden Sie unter.

Zusammenführen von Parametern

Parameter von defaultRunSetting werden mit den laufspezifischen Parametern zusammengeführt, die in inlineSettings oder über eine S3-URI bereitgestellt werden. Run-specific Werte haben Vorrang, wenn sich Schlüssel überschneiden.

Beispiel:

Quelle	Parameters
defaultRunSetting	{"referenceUri": "s3://bucket/ref.fasta", "version": "v1"}
inlineSettingsEintrag	{"inputUri": "s3://bucket/sample.fastq", "version": "v2"}
Zusammengeführtes Ergebnis	{"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"}

Das gleiche Verhalten beim Zusammenführen gilt für. runTags In der Konfiguration pro Ausführung angegebene Tags überschreiben Tags mit demselben Schlüssel vondefaultRunSetting.runTags, und neue Schlüssel werden hinzugefügt.

Beispiel für das Zusammenführen von Tags:

Quelle	Tags (Markierungen)
defaultRunSetting.runTags	{"project": "cancer-research", "pipeline-version": "v2.1"}
inlineSettings[].runTags	{"patient-id": "patient001", "pipeline-version": "v3.0"}
Zusammengeführtes Ergebnis (wird auf die Ausführung angewendet)	{"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"}

Anmerkung

Batch-level Tags (auf StartRunBatch Anfrage) werden nur auf die Batch-Ressource selbst angewendet. Sie werden nicht an einzelne Läufe vererbt. Run-level Die Tags werden durch defaultRunSetting.runTags und pro Lauf runTags gesteuert.

Schrittweise Einreichung

StartRunBatchvalidiert gemeinsame Felder synchron und kehrt sofort mit einer Batch-ID und einem Status zurück. CREATING Läufe in einem Batch werden schrittweise und asynchron mit einer kontrollierten Rate gemäß Ihren Durchsatzquoten übermittelt.

Die vollständige Liste der HealthOmics Kontingente finden Sie unter. HealthOmics Servicekontingente

Während der normalen Verarbeitung durchläuft der Stapel die folgenden Zustände:

1. CREATING— Der Stapel wird gerade erstellt.

2. PENDING— Der Stapel wurde erstellt, die Ausführungskonfigurationen werden überprüft.

3. SUBMITTING— Die Validierung ist abgeschlossen, einzelne Läufe werden eingereicht.

4. INPROGRESS— Es wurde versucht, alle Läufe einzureichen, die Läufe werden ausgeführt.

5. PROCESSED— Alle Läufe haben einen Endzustand erreicht.

Wichtig

Für die Übermittlung von Batchläufen gilt dasselbe StartRun Durchsatzkontingent wie für direkte StartRun API-Aufrufe. Wenn Sie StartRun direkt anrufen, während ein großer Batch verarbeitet wird, konkurrieren sowohl die Batch-Übermittlungen als auch Ihre direkten Aufrufe um dieselbe Kapazität. Dies kann dazu führen, dass Batch-Läufe fehlschlagen ThrottlingException (Rate überschritten) oder dass Ihre StartRun Direktanrufe gedrosselt werden. Das Gleiche gilt für CancelRun und DeleteRun — diese teilen sich die Durchsatzquoten jeweils mit CancelRunBatch undDeleteRunBatch.

Überwachung des Batch-Fortschritts

Batch-Status abrufen

Wird verwendetGetBatch, um den Gesamtstatus und den Übermittlungsfortschritt für einen Stapel abzurufen.

aws omics get-batch --batch-id 7123456

Die Antwort enthält:

• status— Allgemeiner Batch-Status.

• submissionSummary— Zählt erfolgreiche und fehlgeschlagene Übermittlungen für Start-, Abbruch- und Löschvorgänge.

• runSummary— Anzahl der Läufe in jedem Ausführungsstatus. Mögliche Werte:PENDING, STARTINGRUNNING,STOPPING,COMPLETED,DELETED,CANCELLED, oder FAILED

• Zeitstempel für Lebenszyklusereignisse —creationTime,submittedTime,processedTime,failedTime.

Beispiel für eine Antwort:

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

Anmerkung

Die Zusammenfassungen der Ausführungsausführung sind letztendlich konsistent und können hinter den tatsächlichen Ausführungszuständen zurückbleiben. Die endgültigen Zählungen werden abgeglichen, wenn der Batch den Status erreichtPROCESSED.

Die Liste wird stapelweise ausgeführt

Wird verwendetListRunsInBatch, um detaillierte Informationen für einzelne Läufe innerhalb eines Batches abzurufen. Die Ergebnisse sind paginiert.

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

Sie können Ergebnisse mithilfe eines der folgenden Abfrageparameter filtern. Pro Aufruf wird nur ein Filter unterstützt.

Filter	Description
submissionStatus	Nach Übermittlungsstatus filtern: SUCCESS FAILEDCANCEL_SUCCESS,CANCEL_FAILED,DELETE_SUCCESS, oderDELETE_FAILED.
runSettingId	Ruft den Lauf für eine bestimmte Ausführungseinstellungs-ID ab.
runId	Ruft den Lauf für eine bestimmte Lauf-ID ab.

Beispiel: Fehlgeschlagene Übermittlungen auflisten

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

Jedes Ergebnis beinhaltet:

• runSettingId— Die vom Kunden angegebene ID für die Run-Konfiguration.

• runId— Die HealthOmics-generated Lauf-ID (leer, wenn die Übermittlung fehlgeschlagen ist).

• runArn— Der vollständige ARN des Laufs.

• submissionStatus— Das Ergebnis der Einreichung (SUCCESSFAILED,CANCEL_SUCCESS,CANCEL_FAILED,DELETE_SUCCESS, oderDELETE_FAILED).

• submissionFailureReasonund submissionFailureMessage — Einzelheiten, falls die Einreichung fehlgeschlagen ist.

Anmerkung

runSettingIdist die vom Kunden angegebene ID, die Sie in der Ausführungskonfiguration angegeben haben. runIdist die HealthOmics-generated ID, die nach erfolgreicher Übermittlung zugewiesen wurde. Wenn die Übermittlung fehlgeschlagen runId ist, ist leer.

Stapel auflisten

Wird verwendetListBatch, um alle Batch-Ressourcen in Ihrem Konto abzurufen. Die Ergebnisse sind paginiert.

aws omics list-batch

Sie können Ergebnisse mithilfe der folgenden Abfrageparameter filtern:

Filter	Description
status	Filtern Sie nach Stapelstatus.
name	Nach Stapelnamen filtern.
runGroupId	Filtern Sie nach der Run-Gruppen-ID.

Aktivieren Sie Run-Metriken

Der Bericht „Ausführungsmetriken“ berichtet nahezu in Echtzeit über die Ressourcenauslastung für die Läufe in einem Batch. Um Ausführungsmetriken zu aktivieren, muss die Servicerolle, die Sie für den Batch verwenden, über die cloudwatch:PutMetricData entsprechende Berechtigung verfügen. Weitere Informationen finden Sie unter Metriken für private Workflows ausführen.

Fügen Sie der Servicerolle, die Sie für den Batch verwenden, die folgende Berechtigung hinzu.

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

Behandlung fehlgeschlagener Läufe

Bei der Stapelverarbeitung gibt es zwei verschiedene Arten von Fehlern. Für die Problembehandlung ist es wichtig, den Unterschied zu verstehen.

Batch-level Ausfälle

Ein Ausfall auf Batchebene bedeutet, dass der Batch selbst fehlgeschlagen ist — es wurden keine Läufe erstellt (oder nur einige wurden vor dem Ausfall erstellt). Der Batch-Status lautet. FAILED

Rufen Sie an GetBatch und überprüfen Sie das failureReason Feld. Zu den häufigsten Ausfallgründen gehören:

Kategorie „Ausfall“	Beispiel für failureReason eine Nachricht	Action
Validierungsfehler	„Batch hat 100001 Läufe, aber 100000 Läufe sind das Maximum. „, „Es wurden 50 einzelne Durchläufe erwartet, SettingIds aber es waren 49", „Ungültiges JSON-Format in Ausführungskonfigurationen“	Korrigieren Sie die Konfiguration und senden Sie einen neuen Stapel. Diese Fehler können nicht wiederholt werden.
Die S3-Konfiguration wurde geändert	„Erwartete UriConfigs s3-Etag:\" abc123\“, war aber:\ "def456\“. S3 UriConfigs haben sich seit dem Aufruf geändert“ StartRunBatch	Ändern Sie die S3-Datei nach dem Absenden nicht. Senden Sie die Datei erneut mit der aktuellen Datei.
Vorübergehender Servicefehler	„Im Service ist ein vorübergehender Fehler aufgetreten. Versuchen Sie den Stapel erneut.“	Versuchen Sie es erneut, indem Sie denselben Stapel erneut senden. Verwenden Sie dasselbe requestId für Idempotenz.

Beispiel: Der Stapel ist aufgrund einer Validierung fehlgeschlagen

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 Ausfälle

Ein Fehler auf Run-Level bedeutet, dass der Batch selbst erfolgreich war (Status ist INPROGRESS oderPROCESSED), einzelne Läufe jedoch nicht gesendet werden konnten. Der Stapel setzt die Verarbeitung anderer Läufe fort — er stoppt nicht beim ersten Ausfall.

1. Prüfen Sie die Zusammenfassung der Einreichung

aws omics get-batch --batch-id 7123456

Schau dir ansubmissionSummary.failedStartSubmissionCount. Wenn dieser Wert größer als Null ist, sind einige Durchläufe beim Senden fehlgeschlagen.

2. Fehlgeschlagene Beiträge auflisten

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

Jeder fehlgeschlagene Eintrag beinhaltet:

• runSettingId— Welche Ausführungskonfiguration ist fehlgeschlagen.

• submissionFailureReason— Die Fehlerkategorie.

• submissionFailureMessage— Eine ausführliche Fehlermeldung.

3. Gründe für das Scheitern der Einreichung

In der folgenden Tabelle sind die möglichen Werte für submissionFailureReason einzelne Durchläufe aufgeführt:

submissionFailureReason	Bedeutung	Wiederholbar?
ValidationException	Ausführungsparameter sind ungültig. Beispiel: Parameter stimmen nicht mit der Workflow-Definition überein, das S3-URI-Format ist ungültig oder es gibt Verstöße gegen Einschränkungen.	Nein — korrigieren Sie die Konfiguration.
AccessDeniedException	Der IAM-Servicerolle fehlen die Berechtigungen für den Zugriff auf die erforderlichen Ressourcen (S3-Eingaben, KMS-Schlüssel, CloudWatch Protokolle, ECR-Bilder).	Nein — aktualisieren Sie die Rollenrichtlinie.
ResourceNotFoundException	Eine Ressource, auf die verwiesen wird (Workflow, Ausführungsgruppe oder Run-Cache), ist nicht vorhanden oder befindet sich nicht in einem aktiven Zustand.	Nein — überprüfen Sie die Ressourcen-IDs.
ServiceQuotaExceededException	Das Konto hat die maximale Anzahl aktiver Läufe oder ein anderes Dienstkontingent erreicht.	Warten Sie, bis die Läufe abgeschlossen sind, oder fordern Sie eine Kontingenterhöhung an.
ConflictException	Ein widersprüchlicher Vorgang ist im Gange, z. B. ein Versuch, einen doppelten Lauf zu erstellen.	In der Regel löst er sich von selbst auf.
ThrottlingException	Die Anfrage wurde aufgrund von API-Ratenbeschränkungen gedrosselt.	Der Dienst versucht es automatisch erneut. Wenn das Problem auch nach wiederholten Versuchen bestehen bleibt, reduzieren Sie die Anzahl gleichzeitiger Batch-Übermittlungen.
RequestTimeoutException	Bei der Anfrage ist während der Verarbeitung ein Timeout aufgetreten.	Der Dienst versucht es automatisch erneut. Wenn das Problem weiterhin besteht, suchen Sie nach Downstream-Problemen.
InternalServerException	Ein unerwarteter Servicefehler ist aufgetreten.	Der Dienst versucht es automatisch erneut. Wenn er auch nach erneuten Versuchen weiterhin besteht, wenden Sie sich an den Support. AWS

Anmerkung

HealthOmics wiederholt automatisch vorübergehende Fehler (ThrottlingException,RequestTimeoutException,InternalServerException) bei jedem Lauf. Ein Lauf wird als FAILED erst markiert, wenn alle Wiederholungsversuche ausgeschöpft sind. Non-retryable Fehler (ValidationException,AccessDeniedException,ResourceNotFoundException) schlagen sofort ohne erneute Versuche fehl.

4. Fehlgeschlagene Läufe erneut einreichen

Erstellen Sie einen neuen Stapel, der nur die korrigierten Laufkonfigurationen enthält. Verwenden Sie dasselbe defaultRunSetting und schließen Sie nur die runSettingId Einträge ein, bei denen ein Fehler aufgetreten ist. Es gibt keinen integrierten Wiederholungsmechanismus für fehlgeschlagene Läufe — Sie müssen einen neuen Stapel einreichen.

Einen Batch stornieren

Wird verwendetCancelRunBatch, um einen laufenden Stapel abzubrechen. Der Vorgang zum Abbrechen:

• Verhindert, dass noch nicht gesendete und ausstehende Ausführungen gestartet werden

• Sendet CancelRun Anfragen für Läufe, die bereits gestartet wurden.

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

Wichtig

• Abbrechen ist nur für Batches im Status PENDINGSUBMITTING, oder INPROGRESS zulässig.

• Pro Stapel ist jeweils nur ein Vorgang zum Abbrechen oder Löschen zulässig.

• Abbruchvorgänge sind nicht atomar und können teilweise erfolgreich sein. Verwenden Sie GetBatch zur Überprüfung successfulCancelSubmissionCount und failedCancelSubmissionCount in dersubmissionSummary.

Löschen von Batchläufen

Wird verwendetDeleteRunBatch, um die einzelnen Läufe innerhalb eines Batches zu löschen.

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

Wichtig

• Das Löschen ist nur für Batches im CANCELLED Status PROCESSED oder zulässig.

• Pro Stapel ist jeweils nur ein Vorgang zum Abbrechen oder Löschen zulässig.

• Löschvorgänge sind nicht atomar und können teilweise erfolgreich sein. Verwenden Sie GetBatch zur Überprüfung successfulDeleteSubmissionCount und failedDeleteSubmissionCount in dersubmissionSummary.

Löschen von Batch-Metadaten

Wird verwendetDeleteBatch, um die Batch-Ressource und die zugehörigen Metadaten zu entfernen. Dies ist ein separater Vorgang vonDeleteRunBatch.

aws omics delete-batch --batch-id 7123456

Wichtig

• DeleteBatcherfordert, dass sich der Stapel im Endzustand befindet (PROCESSEDFAILED,CANCELLED,RUNS_DELETE_FAILED, oderRUNS_DELETED).

• DeleteBatchlöscht die einzelnen Läufe nicht. Verwenden Sie DeleteRunBatch zuerst, wenn Sie auch die Läufe entfernen möchten.

• Nach DeleteBatch Abschluss des Vorgangs sind die Batch-Metadaten nicht mehr zugänglich. Sie könnenGetBatch, ListRunsInBatchDeleteRunBatch, oder CancelRunBatch für einen gelöschten Batch nicht aufrufen.

EventBridge Ereignisse für Stapel

HealthOmics sendet Ereignisse an Amazon, EventBridge wenn ein Stapel den Status ändert. Sie können diese Ereignisse verwenden, um Arbeitsabläufe zu automatisieren, z. B. um eine Benachrichtigung auszulösen, wenn ein Batch abgeschlossen ist oder fehlschlägt, oder um eine Downstream-Pipeline zu starten, wenn alle Läufe abgeschlossen sind.

Batch-Ereignisse verwenden denselben Event-Bus und dieselbe Quelle wie andere Ereignisse. HealthOmics Allgemeine Anweisungen zur Einrichtung finden Sie unterVerwenden EventBridge mit AWS HealthOmics.

Typ der Veranstaltungsdetails

Ereignisname	Wird ausgegeben wenn
RunBatch Status ändern	Der Stapel wechselt in einen neuen Status (CREATINGPENDING,SUBMITTING,INPROGRESS,STOPPING,CANCELLED,PROCESSED,FAILED,RUNS_DELETING,RUNS_DELETED)

Felder mit Eventdetails

Das detail Objekt in einem Batch-Ereignis umfasst die folgenden Felder:

Feld	Typ	Description
omicsVersion	Zeichenfolge	Version des Ereignisschemas (derzeit 1.0.0).
arn	Zeichenfolge	Der Batch-ARN.
batchId	Zeichenfolge	Die Batch-ID.
status	Zeichenfolge	Der neue Batchstatus.
uuid	Zeichenfolge	Die Batch-UUID.
batchName	Zeichenfolge	Der Batchname (falls angegeben).
totalRuns	Zeichenfolge	Gesamtzahl der Durchläufe im Stapel.
failureReason	Zeichenfolge	Fehlergrund (nur vorhanden, wenn der Status lautetFAILED).
failureMessage	Zeichenfolge	Detaillierte Fehlermeldung (nur vorhanden, wenn der Status erreicht istFAILED).
successfulStartSubmissionCount	Zeichenfolge	Anzahl der erfolgreich übermittelten Läufe.
failedStartSubmissionCount	Zeichenfolge	Anzahl der Läufe, die nicht übermittelt werden konnten.
pendingStartSubmissionCount	Zeichenfolge	Anzahl der Läufe, die noch eingereicht werden müssen.
pendingRunCount	Zeichenfolge	Anzahl der Läufe im Status „Ausstehend“.
startingRunCount	Zeichenfolge	Anzahl der startenden Läufe.
runningRunCount	Zeichenfolge	Anzahl der derzeit laufenden Läufe.
stoppingRunCount	Zeichenfolge	Anzahl der Läufe, die gestoppt werden.
completedRunCount	Zeichenfolge	Anzahl der abgeschlossenen Läufe.
failedRunCount	Zeichenfolge	Anzahl der fehlgeschlagenen Läufe.
cancelledRunCount	Zeichenfolge	Anzahl der stornierten Läufe.
deletedRunCount	Zeichenfolge	Anzahl der gelöschten Läufe.
workflowId	Zeichenfolge	Die Workflow-ID.
workflowArn	Zeichenfolge	Der Workflow-ARN.
workflowVersionArn	Zeichenfolge	Der ARN der Workflow-Version (falls zutreffend).
workflowOwnerId	Zeichenfolge	Die Konto-ID des Workflow-Besitzers (für gemeinsam genutzte Workflows).
runCache	Zeichenfolge	Der Run-Cache-ARN (falls zutreffend).
runCacheBehavior	Zeichenfolge	Das Verhalten des Run-Cache (falls zutreffend).

Beispiele für Ereignisse

Beispiel: Ereignis „Batch abgeschlossen“

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

Beispiel: Ereignis „Batch ist fehlgeschlagen“

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

Beispiel: EventBridge Regel für die Stapelvervollständigung

Das folgende Ereignismuster stimmt überein, wenn ein Stapel einen Endzustand erreicht:

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

Einschränkungen und Überlegungen

• Kontingente für gemeinsamen Durchsatz — Für Batch-Operationen gelten dieselben Kontingente pro Konto wie für ihre jeweiligen API-Gegenstücke. StartRunBatchverbraucht StartRun Servicekontingente. CancelRunBatchverbraucht CancelRun Kontingente und DeleteRunBatch verbraucht DeleteRun Kontingente. Vermeiden Sie es, einzelne Ausführungs-APIs aufzurufen, während ein großer Batch in Bearbeitung ist, da dies zu Fehlern bei der Übermittlung führen kann.

• Schrittweise Übermittlung — Läufe in einem Batch werden schrittweise und asynchron gemäß Ihren Durchsatzquoten übermittelt.

• Non-atomic Operationen — StartRunBatchCancelRunBatch, und alle DeleteRunBatch können teilweise erfolgreich sein. Überprüfe immer die Übermittlungszusammenfassungen, um herauszufinden, welche Läufe wiederholt werden müssen.

• Eventuelle Konsistenz — Die Anzahl der Ausführungsstatuswerte GetBatch kann hinter den tatsächlichen Ausführungszuständen zurückbleiben. Die endgültigen Zählungen sind korrekt, sobald der Batch den Status erreicht hatPROCESSED.

• Ein Filter pro Listenaufruf — ListRunsInBatch und ListBatch unterstützt nur einen Filter pro API-Aufruf.

• Re-run nicht unterstützt — Das Feld runId (erneut ausführen) wird in StartRunBatch nicht unterstützt. Bei jeder Stapelübermittlung werden immer neue Durchläufe erstellt.

• Ready2Run-Workflows — Batch-Läufe werden in Ready2Run-Workflows nicht unterstützt.

• Begrenzung der Inline-Konfiguration — Inline-Konfigurationen (inlineSettings) unterstützen bis zu 100 Einträge. Verwenden s3UriSettings Sie für größere Chargen. Diese Grenze ist nicht einstellbar.

• S3-Konfigurationsdatei — Die S3-Konfigurationsdatei muss ein JSON-Array von Run-Setting-Objekten sein. Die maximale Dateigröße beträgt 6 GB und unterstützt bis zu 100.000 Ausführungskonfigurationen.

• Unveränderlichkeit der S3-Datei — Ändern Sie die S3-Konfigurationsdatei nicht, nachdem Sie den Batch gesendet haben. HealthOmics validiert das Entitäts-Tag (ETag) der Datei während der Übermittlung und schlägt beim Batch fehl, wenn sich die Datei geändert hat.