Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# 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 mit**CancelRunBatch**.
+ Löschen Sie alle Läufe in einem Batch mit**DeleteRunBatch**.
+ Batch-Metadaten löschen mit**DeleteBatch**.
**Topics**
+ [Batch-Run-Konzepte](#batch-concepts)
+ [Voraussetzungen](#batch-prerequisites)
+ [IAM-Berechtigungen für Batch-Operationen](#batch-iam-permissions)
+ [Erste Schritte: Reichen Sie Ihren ersten Batch ein](#batch-getting-started)
+ [Einen Batchlauf starten](#batch-starting)
+ [Überwachung des Batch-Fortschritts](#batch-monitoring)
+ [Behandlung fehlgeschlagener Läufe](#batch-handling-failures)
+ [Einen Stapel stornieren](#batch-canceling)
+ [Batch-Läufe löschen](#batch-deleting-runs)
+ [Batch-Metadaten löschen](#batch-deleting-metadata)
+ [EventBridge Ereignisse für Batches](#batch-eventbridge)
+ [Einschränkungen und Überlegungen](#batch-limitations)
## 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.
+ **Run-specific Einstellung** (`inlineSettings`oder`s3UriSettings`) — Per-run Konfigurationen, die die Standardausführungseinstellung überschreiben oder mit ihr zusammenführen. Jeder Eintrag muss ein Unikat 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 dem Absenden jeweils dem `runSettingId` zuzuordnen HealthOmics-generated `runId`, sodass Sie nachvollziehen können, welcher Lauf anhand welcher Eingabekonfiguration erstellt wurde.
+ **Batch-Status** — Der Gesamtstatus des Batch-Vorgangs. Mögliche Werte:
+ `CREATING`— 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 [Batch-level Ausfälle](#batch-level-failures).
+ `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](permissions-service.md).
+ Amazon S3 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 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**
**StartRunBatch**erfordert 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](permissions-service.md).
### 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. Tag-based Die Zugriffskontrolle (TBAC) wird für Batch-Tags vollständig durchgesetzt.
+ **Run-Tags** (während `runTags` `defaultRunSetting` und pro Lauf`runTags`) — 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`. `submissionSummary`Zeigt 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`) der zu HealthOmics-generated`runId`, 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 verwendet**StartRunBatch**, 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 anrufen**ListRunsInBatch**, ordnet jeder Eintrag Sie dem HealthOmics-generated `runId` und `runSettingId` `runArn` zu.
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 das ETag der Datei auf. 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-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 Batch-Übermittlung werden immer neue Läufe erstellt, und jeder Lauf erhält eine`runId`. Informationen [Führen Sie einen Run in erneut aus HealthOmics](rerun-a-run.md) 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. 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 Zusammenführungsverhalten gilt für. `runTags` In der Konfiguration pro Lauf angegebene Tags überschreiben Tags mit demselben Schlüssel von`defaultRunSetting.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**
Batch-level Tags (auf **StartRunBatch** Anfrage) werden nur auf die Batch-Ressource selbst angewendet. Sie werden nicht von einzelnen Läufen vererbt. Run-level Tags werden durch `defaultRunSetting.runTags` und pro Lauf `runTags` gesteuert.
### Schrittweise Einreichung
**StartRunBatch**validiert 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 Geschwindigkeit gemäß Ihren Durchsatzquoten übermittelt.
Die vollständige Liste der HealthOmics Kontingente finden Sie unter[HealthOmics Servicekontingenten](service-quotas.md).
Während der normalen Verarbeitung durchläuft der Stapel die folgenden Zustände:
1. `CREATING`— Batch wird erstellt.
1. `PENDING`— Batch-Erstellung, Ausführungskonfigurationen werden validiert.
1. `SUBMITTING`— Die Validierung ist abgeschlossen, einzelne Läufe wurden eingereicht.
1. `INPROGRESS`— Es wurde versucht, alle Durchläufe einzureichen, die Läufe werden ausgeführt.
1. `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** und**DeleteRunBatch**.
## Ü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`, `STARTING``RUNNING`,`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 erreicht`PROCESSED`.
### Die Liste wird stapelweise ausgeführt
Wird verwendet**ListRunsInBatch**, 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-generated Lauf-ID (leer, wenn die Übermittlung fehlgeschlagen ist).
+ `runArn`— Der vollständige ARN des Laufs.
+ `submissionStatus`— Das Ergebnis der Einreichung (`SUCCESS``FAILED`,`CANCEL_SUCCESS`,`CANCEL_FAILED`,`DELETE_SUCCESS`, oder`DELETE_FAILED`).
+ `submissionFailureReason`und `submissionFailureMessage` — Einzelheiten, falls die Einreichung fehlgeschlagen ist.
**Anmerkung**
`runSettingId`ist die vom Kunden angegebene Kennung, die Sie in der Ausführungskonfiguration angegeben haben. `runId`ist die HealthOmics-generated Kennung, die nach erfolgreicher Übermittlung zugewiesen wurde. Falls die Übermittlung fehlgeschlagen `runId` ist, ist leer.
### Batches auflisten
Wird verwendet**ListBatch**, 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 | Nach Batchnamen filtern. |
| 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 entscheidend, den Unterschied zu verstehen.
### Batch-level Ausfälle
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 | `failureReason`Beispielnachricht | Action |
| --- | --- | --- |
| Validierungsfehler | „Batch hat 100001 Läufe, aber 100.000 Läufe sind das Maximum. „, „Es wurden 50 Einzelläufe erwartet, SettingIds aber es gab 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 Dienstfehler | „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"
}
```
### Run-level Misserfolge
Ein Fehler auf Run-Level bedeutet, dass der Batch selbst erfolgreich war (Status ist `INPROGRESS` oder`PROCESSED`), 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 an`submissionSummary.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 Ausführungskonfiguration 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. Beispielsweise stimmen die Parameter nicht mit der Workflow-Definition überein, das S3-URI-Format ist ungültig oder es bestehen Verstöße gegen Beschrä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 — ü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 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. 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 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 verwendet**CancelRunBatch**, um einen laufenden Stapel abzubrechen. Der Vorgang zum Abbrechen:
+ Verhindert, dass noch nicht abgesendete und ausstehende Läufe gestartet werden
+ 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 `PENDING``SUBMITTING`, 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 verwendet**DeleteRunBatch**, 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 verwendet**DeleteBatch**, um die Batch-Ressource und die zugehörigen Metadaten zu entfernen. Dies ist ein separater Vorgang von**DeleteRunBatch**.
```
aws omics delete-batch --batch-id {{7123456}}
```
**Wichtig**
**DeleteBatch**erfordert, dass sich der Stapel in einem Terminalstatus (`PROCESSED``FAILED`,`CANCELLED`, oder`RUNS_DELETED`) befindet.
**DeleteBatch**lö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önnen**GetBatch**, **ListRunsInBatch****DeleteRunBatch**, 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 unter[Verwenden EventBridge mit AWS HealthOmics](eventbridge.md).
### 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. **StartRunBatch**verbraucht Servicekontingenten. **StartRun** **CancelRunBatch**verbraucht **CancelRun** Kontingente und **DeleteRunBatch** verbraucht **DeleteRun** Kontingente. Vermeiden Sie es, einzelne Ausführungs-APIs aufzurufen, während ein großer Batch ausgeführt wird, da dies zu Übertragungsfehlern führen kann.
+ **Schrittweise Übermittlung** — Batchläufe werden schrittweise und asynchron gemäß Ihren Durchsatzquoten eingereicht.
+ **Non-atomic Operationen** —**StartRunBatch**,**CancelRunBatch**, und **DeleteRunBatch** können alle teilweise erfolgreich sein. Überprüfen Sie immer die Übermittlungen, um herauszufinden, welche 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 hat`PROCESSED`.
+ **Ein einziger Filter pro Listenaufruf** — **ListRunsInBatch** und es wird nur ein Filter pro API-Aufruf **ListBatch** unterstützt.
+ **Re-run nicht unterstützt** — Das Feld `runId` (erneut ausgeführt) wird in **StartRunBatch** nicht unterstützt. 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.