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**.
+ Löschen Sie Batch-Metadaten 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.
+ **Ausführungsspezifische Einstellung** (`inlineSettings`oder`s3UriSettings`) — 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 zuzuordnen`runId`, 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](#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.
+ 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**
**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. Die tagbasierte 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`) den HealthOmics generierten Proben zu`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 aufrufen**ListRunsInBatch**, 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 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. Laufspezifische Werte haben Vorrang, wenn sich Schlüssel überschneiden.
**Beispiel:**
| Quelle | Parameters |
| --- | --- |
| defaultRunSetting | \$1"referenceUri": "s3://bucket/ref.fasta", "version": "v1"\$1 |
| inlineSettingsEintrag | \$1"inputUri": "s3://bucket/sample.fastq", "version": "v2"\$1 |
| Zusammengeführtes Ergebnis | \$1"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"\$1 |
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 | \$1"project": "cancer-research", "pipeline-version": "v2.1"\$1 |
| inlineSettings[].runTags | \$1"patient-id": "patient001", "pipeline-version": "v3.0"\$1 |
| Zusammengeführtes Ergebnis (auf die Ausführung angewendet) | \$1"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"\$1 |
**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
**StartRunBatch**validiert 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 unter[HealthOmics Servicekontingenten](service-quotas.md).
Während der normalen Verarbeitung durchläuft der Stapel die folgenden Zustände:
1. `CREATING`— Der 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\$1SUCCESS,CANCEL\$1FAILED,DELETE\$1SUCCESS, oderDELETE\$1FAILED. |
| 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 (`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 generierte 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 | 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:\$1" abc123\$1“ erwartet, lautete aber:\$1 "def456\$1“. 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` 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 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 `ValidationException``AccessDeniedException`, 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 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 `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\$1DELETING,RUNS\$1DELETED) |
### 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, 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 hat`PROCESSED`.
+ **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.