Batch läuft in HealthOmics

AWS HealthOmics Mit Batch-Läufen können Sie mehrere Läufe in einer einzigen API-Anfrage einreichen. Jeder Lauf im Batch hat eine gemeinsame Basiskonfiguration, kann jedoch unterschiedliche Eingaben und laufspezifische Parameter haben. Batchläufe reduzieren den Übermittlungsaufwand und vereinfachen das Lebenszyklusmanagement für die Verarbeitung umfangreicher Workflows.

Mit Batchläufen können Sie:

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

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

• Verfolgen Sie den gesamten Batch-Status und den Fortschritt der einzelnen Probeneinreichungen durch GetBatch und. ListRunsInBatch

• Brechen Sie alle Läufe in einem Stapel ab mitCancelRunBatch.

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

• Löschen Sie Batch-Metadaten mitDeleteBatch.

Batch-Run-Konzepte

• Batch — Eine Sammlung von Workflow-Läufen mit gemeinsamer Konfiguration, die als einzelne Ressource mit eigenem Amazon-Ressourcennamen (ARN) und Lebenszyklusstatus verwaltet werden.

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

• Ausführungsspezifische Einstellung (inlineSettingsoders3UriSettings) — Konfigurationen pro Lauf, die die Standardausführungseinstellung überschreiben oder mit ihr zusammengeführt werden. Jeder Eintrag muss ein eindeutiges Zeichen enthalten. runSettingId

• Ausführungseinstellungs-ID (runSettingId) — Eine erforderliche, vom Kunden bereitgestellte eindeutige Kennung für jede Ausführungskonfiguration innerhalb eines Batches. Verwenden Sie diese Option, ListRunsInBatch um sie nach der Übermittlung den HealthOmics generierten Daten zuzuordnenrunId, sodass Sie nachvollziehen können, welcher Lauf anhand welcher Eingabekonfiguration erstellt wurde. runSettingId

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

  • CREATING— Der Batch wird erstellt.

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

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

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

  • STOPPING— Eine Stornierungsanfrage wurde empfangen; die Läufe werden gestoppt.

  • CANCELLED— Der Stapel wurde storniert.

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

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

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

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

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

  • SUCCESS— Die Ausführung wurde erfolgreich eingereicht.

  • FAILED— Die Übertragung der Ausführung ist fehlgeschlagen (z. B. aufgrund eines Validierungsfehlers).

  • CANCEL_SUCCESS— Die Ausführung wurde erfolgreich abgebrochen.

  • CANCEL_FAILED— Der Abbruch des Laufs ist fehlgeschlagen.

  • DELETE_SUCCESS— Die Ausführung wurde erfolgreich gelöscht.

  • DELETE_FAILED— Das Löschen des Laufs ist fehlgeschlagen.

Voraussetzungen

Bevor Sie einen Batchlauf starten, stellen Sie sicher, dass Sie über Folgendes verfügen:

• Ein aktiver HealthOmics privater Workflow. Batchlä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 S3-Buckets. Details hierzu finden Sie unter Servicerollen für AWS HealthOmics.

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

• Laufspezifische 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 Batch-Vorgang als auch für den zugrunde liegenden individuellen Ausführungsvorgang verfügen. Die folgende Beispielrichtlinie gewährt Berechtigungen für alle Batch-Operationen:

{
  "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 ausgeführt werden kann.

Für die übergebene IAM-Dienstrolle roleArn (die 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 Runs unterstützt Tags auf zwei Ebenen:

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

• Run-Tags (während runTags defaultRunSetting und pro LaufrunTags) — Wird auf einzelne Laufressourcen 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 Nutzungsbedingungen enthält. aws:TagKeys

Beispiel: Beschränken Sie die Batcherstellung auf Umgebungen außerhalb der Produktion

Die folgende Richtlinie ermöglicht Benutzern das Erstellen von Batches und Läufen, verweigert jedoch das Markieren 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 → Zulässig

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

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

Erste Schritte: Reichen Sie Ihren ersten Batch ein

Im folgenden Beispiel wird beschrieben, wie Sie einen kleinen Stapel von 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-Status

aws omics get-batch --batch-id 7123456

Beobachten Sie den status Feldfortschritt CREATING unter PENDING → SUBMITTING → → INPROGRESS →PROCESSED. submissionSummaryZeigt an, wie viele Läufe erfolgreich eingereicht wurden, und runSummary zeigt den Ausführungsfortschritt.

Schritt 3: Überprüfen Sie einzelne Läufe

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

Jeder Eintrag ordnet Ihre runSettingId (z. B.sample-A) den HealthOmics generierten Proben zurunId, sodass Sie die Ergebnisse auf Ihre Eingabeproben zurückverfolgen können.

Schritt 4: Suchen Sie nach fehlgeschlagenen Einsendungen

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

Falls Läufe nicht gesendet werden konnten, enthält die Antwort Informationen submissionFailureReason und submissionFailureMessage soll Ihnen helfen, das Problem zu diagnostizieren.

Einen Batchlauf starten

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

• defaultRunSetting— Gemeinsame Konfiguration für alle Läufe im Batch.

• batchRunSettings— Die einzelnen Laufkonfigurationen, bereitgestellt als eine der folgenden Konfigurationen:

  • inlineSettings— Eine Reihe von bis zu 100 laufspezifischen Konfigurationen, die direkt im Anforderungstext bereitgestellt werden.

  • s3UriSettings— Ein Amazon S3 S3-URI, der 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, für Menschen lesbarer Name für den Stapel.

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

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

Reichen Sie kleine Chargen mit Inline-Run-Konfigurationen ein

Stellen Sie eine Reihe von ausführspezifischen Konfigurationen direkt im Anfragetext bereit, indem Sie. inlineSettings Jeder Eintrag muss ein eindeutiges runSettingId (erforderliches) Zeichen enthalten. Das runSettingId ist Ihr Schlüssel zum Korrelieren von Ergebnissen — wenn Sie aufrufenListRunsInBatch, ordnet jeder Eintrag Sie dem HealthOmics -generierten runId und runSettingId zu. runArn

Bei Inline-Konfigurationen können Sie bis zu 100 Einträge hinzufügen.

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

Senden Sie große Chargen mit Ausführungskonfigurationen in S3

Für Batches mit mehr als 100 Durchläufen speichern Sie Ihre Ausführungskonfigurationen in einer JSON-Datei in Amazon S3 und geben Sie den URI unter s3UriSettings Die JSON-Datei muss ein Array von laufspezifischen Einstellungsobjekten enthalten, von denen jedes ein eindeutiges Objekt hat. runSettingId Die Datei kann bis zu 100.000 Einträge enthalten.

Das S3-Dateiformat entspricht dem des inlineSettings Arrays:

[
  {
    "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 S3-Objekt haben. s3UriSettings HealthOmics validiert den Zugriff auf die Amazon S3 S3-Datei während des synchronen API-Aufrufs und zeichnet die Dateien auf. ETag Wenn die Datei nach der Übermittlung geändert wird, schlägt der Batch bei der asynchronen Verarbeitung fehl.

Antwort

Bei einer erfolgreichen Anfrage werden eine Batch-ID und ein Anfangsstatus zurückgegeben:

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

Wenn die synchrone Validierung fehlschlägt (z. B. eine ungültige Workflow-ID oder ein unzugänglicher Amazon S3 S3-URI), gibt die API einen Fehler zurück, bevor Läufe eingereicht 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-Ebene () defaultRunSetting	Pro Lauf 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
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 Batch-Übermittlung werden immer neue Läufe erstellt, und jeder Lauf erhält einerunId. Informationen Führen Sie einen Run in erneut aus HealthOmics zur Wiederholung einzelner Läufe finden Sie unter.

Zusammenführen von Parametern

Die Parameter von defaultRunSetting werden mit den laufspezifischen Parametern zusammengeführt, die in inlineSettings oder über eine S3-URI bereitgestellt werden. Laufspezifische 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 Zusammenführungsverhalten gilt für. runTags In der Konfiguration pro Lauf angegebene Tags überschreiben Tags mit demselben Schlüssel vondefaultRunSetting.runTags, und es werden neue Schlüssel 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 (auf die Ausführung angewendet)	{"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"}

Anmerkung

Tags auf Batch-Ebene (auf StartRunBatch Anfrage) werden nur auf die Batch-Ressource selbst angewendet. Sie werden nicht von einzelnen Läufen vererbt. Tags auf Run-Level werden durch defaultRunSetting.runTags und pro Lauf gesteuert. runTags

Schrittweise Einreichung

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

Die vollständige Liste der HealthOmics Kontingente finden Sie unterHealthOmics Servicekontingenten.

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

1. CREATING— Der Batch wird erstellt.

2. PENDING— Batch-Erstellung, Ausführungskonfigurationen werden validiert.

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

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

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

Wichtig

Für die Einreichung von Batchläufen gilt dasselbe StartRun Durchsatzkontingent wie für direkte StartRun API-Aufrufe. Wenn Sie StartRun direkt anrufen, während ein großer Stapel verarbeitet wird, konkurrieren sowohl die Batch-Übermittlungen als auch Ihre direkten Aufrufe um dieselbe Kapazität. Dies kann dazu führen, dass Batchläufe fehlschlagen ThrottlingException (Rate überschritten) oder Ihre direkten StartRun Anrufe 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

Dient GetBatch zum Abrufen des Gesamtstatus und des Übermittlungsfortschritts für einen Stapel.

aws omics get-batch --batch-id 7123456

Die Antwort enthält:

• status— Allgemeiner Batch-Status.

• submissionSummary— Anzahl erfolgreicher und fehlgeschlagener Übermittlungen für Start-, Abbruch- und Löschvorgänge.

• runSummary— Anzahl der Durchlä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ührungsläufe sind letztendlich konsistent und können hinter den tatsächlichen Ausführungsstatus zurückbleiben. Die endgültigen Zählungen werden abgeglichen, wenn der Stapel 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 mit einem der folgenden Abfrageparameter filtern. Pro Aufruf wird nur ein Filter unterstützt.

Filter	Description
submissionStatus	Nach Einreichungsstatus filtern: SUCCESSFAILED,CANCEL_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: Liste fehlgeschlagener Übermittlungen

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

Jedes Ergebnis beinhaltet:

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

• runId— Die HealthOmics generierte 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 Kennung, die Sie in der Ausführungskonfiguration angegeben haben. runIdist die HealthOmics generierte Kennung, die nach erfolgreicher Übermittlung zugewiesen wurde. Falls die Übermittlung fehlgeschlagen runId ist, ist leer.

Batches auflisten

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

aws omics list-batch

Sie können Ergebnisse mit den folgenden Abfrageparametern filtern:

Filter	Description
status	Filtern Sie nach Batchstatus.
name	Filtern Sie nach Batchnamen.
runGroupId	Filtern Sie nach der ID der Ausführungsgruppe.

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.

Ausfälle auf Batch-Ebene

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

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

Kategorie des Fehlers	Beispiel für failureReason eine Nachricht	Action
Validierungsfehler	„Batch hat 100001 Läufe, aber 100.000 Läufe sind das Maximum. „, „Es wurden 50 eindeutige Zeichen erwartet, runSettingIds aber es waren 49", „Ungültiges JSON-Format in Ausführungskonfigurationen“	Korrigieren Sie die Konfiguration und reichen Sie einen neuen Batch ein. Diese Fehler können nicht erneut versucht werden.
Die S3-Konfiguration wurde geändert	„UriConfigs S3-Etag:\" abc123\“ erwartet, lautete aber:\ "def456\“. S3 UriConfigs haben sich seit dem Aufruf geändert“ StartRunBatch	Ändern Sie die S3-Datei nach dem Absenden nicht. Mit der aktuellen Datei erneut einreichen.
Vorübergehender Servicefehler	„Es gab einen vorübergehenden Fehler im Dienst. Versuchen Sie den Stapel erneut.“	Versuchen Sie es erneut, indem Sie denselben Stapel erneut einreichen. Verwenden Sie dasselbe requestId für Idempotenz.

Beispiel: Batch ist aufgrund der 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"
}

Fehler auf Run-Level

Ein Fehler auf Runlevel 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 Fehler.

1. Sehen Sie sich die Zusammenfassung der Einreichung an

aws omics get-batch --batch-id 7123456

Schau dir ansubmissionSummary.failedStartSubmissionCount. Wenn dieser Wert größer als Null ist, schlugen einige Läufe bei der Übermittlung fehl.

2. Liste fehlgeschlagener Einsendungen

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

Jeder fehlgeschlagene Eintrag beinhaltet:

• runSettingId— Welche Run-Konfiguration ist fehlgeschlagen.

• submissionFailureReason— Die Fehlerkategorie.

• submissionFailureMessage— Eine detaillierte 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 — Parameter stimmen beispielsweise nicht mit der Workflow-Definition überein, ungültiges S3-URI-Format oder Verstöße gegen Einschränkungen.	Nein — korrigieren Sie die Konfiguration.
AccessDeniedException	Der IAM-Dienstrolle fehlen die Berechtigungen für den Zugriff auf die erforderlichen Ressourcen (S3-Eingaben, KMS-Schlüssel, CloudWatch Protokolle, ECR-Images).	Nein — aktualisieren Sie die Rollenrichtlinie.
ResourceNotFoundException	Eine referenzierte Ressource (Workflow, Ausführungsgruppe oder Ausführungscache) ist nicht vorhanden oder befindet sich nicht in einem aktiven Status.	Nein — Ressource überprüfen 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 Erhöhung des Kontingents an.
ConflictException	Ein widersprüchlicher Vorgang ist im Gange, z. B. ein Versuch, einen Lauf doppelt zu erstellen.	Wird in der Regel von selbst gelöst.
ThrottlingException	Die Anfrage wurde aufgrund von API-Ratenbeschränkungen gedrosselt.	Der Dienst versucht es automatisch erneut. Wenn der Fehler auch nach erneuten Versuchen bestehen bleibt, reduzieren Sie die Anzahl der gleichzeitigen Batch-Übermittlungen.
RequestTimeoutException	Bei der Verarbeitung der Anfrage wurde das Timeout überschritten.	Der Dienst versucht es automatisch erneut. Wenn der Fehler weiterhin besteht, suchen Sie nach nachgelagerten Problemen.
InternalServerException	Ein unerwarteter Servicefehler ist aufgetreten.	Der Dienst versucht es automatisch erneut. Wenn es nach erneuten Versuchen weiterhin besteht, wenden Sie sich an AWS den Support.

Anmerkung

HealthOmics wiederholt bei jedem Lauf automatisch vorübergehende Fehler (ThrottlingException,RequestTimeoutException,InternalServerException). Ein Lauf wird FAILED erst als markiert, wenn alle Wiederholungsversuche erschöpft sind. Fehler (,,ResourceNotFoundException), die nicht wiederholt werden können ValidationExceptionAccessDeniedException, schlagen sofort ohne erneute Versuche fehl.

4. Fehlgeschlagene Läufe erneut einreichen

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

Einen Stapel stornieren

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

• Verhindert not-yet-submitted den Start von ausstehenden Läufen

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

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

Wichtig

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

• Pro Stapel ist jeweils nur ein Stornierungs- oder Löschvorgang zulässig.

• Abbruchvorgänge sind nicht atomar und können teilweise erfolgreich sein. Wird GetBatch zur Überprüfung successfulCancelSubmissionCount und failedCancelSubmissionCount in der submissionSummary verwendet.

Batch-Läufe löschen

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 Stapel im CANCELLED Status PROCESSED oder zulässig.

• Pro Stapel ist jeweils nur ein Stornierungs- oder Löschvorgang zulässig.

• Löschvorgänge sind nicht atomar und können teilweise erfolgreich sein. Wird GetBatch zur Überprüfung successfulDeleteSubmissionCount und failedDeleteSubmissionCount in der submissionSummary verwendet.

Batch-Metadaten löschen

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 in einem Terminalstatus (PROCESSEDFAILED,CANCELLED, oderRUNS_DELETED) befindet.

• 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 kann nicht mehr auf die Batch-Metadaten zugegriffen werden. Sie könnenGetBatch, ListRunsInBatchDeleteRunBatch, oder CancelRunBatch für einen gelöschten Batch nicht aufrufen.

EventBridge Ereignisse für Batches

HealthOmics sendet Ereignisse an Amazon, EventBridge wenn sich der Status eines Stapels ändert. Sie können diese Ereignisse verwenden, um Workflows 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 HealthOmics Ereignisse. Allgemeine Anweisungen zur Einrichtung finden Sie unterVerwenden EventBridge mit AWS HealthOmics.

Art der Einzelheiten des Ereignisses

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

Felder mit Veranstaltungsdetails

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 Batch-Status.
uuid	Zeichenfolge	Die Batch-UUID.
batchName	Zeichenfolge	Der Batchname (falls angegeben).
totalRuns	Zeichenfolge	Gesamtzahl der Läufe im Stapel.
failureReason	Zeichenfolge	Grund für den Fehler (nur vorhanden, wenn der Status lautetFAILED).
failureMessage	Zeichenfolge	Detaillierte Fehlermeldung (nur vorhanden, wenn der Status lautetFAILED).
successfulStartSubmissionCount	Zeichenfolge	Anzahl der erfolgreich übermittelten Läufe.
failedStartSubmissionCount	Zeichenfolge	Anzahl der Läufe, die nicht gesendet 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 aktuell 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	Die 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: Batch-Fehlgeschlagenereignis

{
  "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 Batch-Vervollständigung

Das folgende Ereignismuster stimmt überein, wenn ein Batch einen Terminalstatus erreicht:

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

Einschränkungen und Überlegungen

• Geteilte Durchsatzquoten — Batch-Operationen verwenden dieselben Kontingente pro Konto wie ihre individuellen API-Gegenstücke. StartRunBatchverbraucht Servicekontingenten. StartRun CancelRunBatchverbraucht CancelRun Kontingente und DeleteRunBatch verbraucht DeleteRun Kontingente. Vermeiden Sie es, eine einzelne Ausführung aufzurufen, APIs während ein großer Stapel bearbeitet wird, da dies zu Übertragungsfehlern führen kann.

• Schrittweise Übermittlung — Batchläufe werden schrittweise und asynchron gemäß Ihren Durchsatzquoten übermittelt.

• Nichtatomare Operationen —StartRunBatch,CancelRunBatch, und DeleteRunBatch können alle teilweise erfolgreich sein. Überprüfen Sie immer die Übermittlungen, um herauszufinden, ob Läufe erneut versucht werden müssen.

• Eventuelle Konsistenz — Die Anzahl der Ausführungsstatus GetBatch kann hinter den tatsächlichen Ausführungsstatus zurückbleiben. Die endgültigen Zählungen sind korrekt, sobald die Charge erreicht hatPROCESSED.

• Ein einziger Filter pro Listenaufruf — ListRunsInBatch und es wird nur ein Filter pro API-Aufruf ListBatch unterstützt.

• Wiederholung nicht unterstützt — Das Feld runId (erneut ausführen) wird in nicht unterstützt. StartRunBatch Bei jeder Batch-Übermittlung werden immer neue Läufe erstellt.

• Ready2Run-Workflows — Batchläufe werden von Ready2Run-Workflows nicht unterstützt.

• Limit für die 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 eingereicht haben. HealthOmics validiert das Entity-Tag (ETag) der Datei während der Übermittlung und schlägt beim Batch fehl, wenn sich die Datei geändert hat.