Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Batch s'exécute dans HealthOmics
AWS HealthOmics les exécutions par lots vous permettent de soumettre plusieurs exécutions dans une seule demande d'API. Chaque exécution du lot partage une configuration de base commune mais peut avoir des entrées différentes et des paramètres spécifiques à l'exécution. Les séries par lots réduisent les frais de soumission et simplifient la gestion du cycle de vie pour le traitement des flux de travail à grande échelle.
Avec les séries par lots, vous pouvez :
+ Soumettez jusqu'à 100 000 essais en un seul **StartRunBatch** appel, avec une configuration partagée définie une fois et appliquée à tous les cycles.
+ Appliquez des remplacements de paramètres par exécution pour des échantillons individuels, notamment le nom, l'URI de sortie, les paramètres, la priorité et les balises.
+ Suivez l'état général des lots et la progression des soumissions individuelles via **GetBatch** et**ListRunsInBatch**.
+ Annulez tous les essais d'un lot à l'aide de**CancelRunBatch**.
+ Supprimez toutes les séries d'un lot à l'aide de**DeleteRunBatch**.
+ Supprimez les métadonnées du lot avec**DeleteBatch**.
**Topics**
+ [Concepts d'exécution par lots](#batch-concepts)
+ [Conditions préalables](#batch-prerequisites)
+ [Autorisations IAM pour les opérations par lots](#batch-iam-permissions)
+ [Pour commencer : soumettez votre premier lot](#batch-getting-started)
+ [Démarrage d'un traitement par lots](#batch-starting)
+ [Surveillance de la progression des lots](#batch-monitoring)
+ [Gestion des essais infructueux](#batch-handling-failures)
+ [Annulation d'un lot](#batch-canceling)
+ [Supprimer des séries par lots](#batch-deleting-runs)
+ [Suppression des métadonnées par lots](#batch-deleting-metadata)
+ [EventBridge événements pour les lots](#batch-eventbridge)
+ [Limites et considérations](#batch-limitations)
## Concepts d'exécution par lots
+ **Batch** : ensemble d'exécutions de flux de travail partageant une configuration commune, gérées comme une ressource unique avec son propre Amazon Resource Name (ARN) et son propre statut de cycle de vie.
+ **Paramètre d'exécution par défaut** (`defaultRunSetting`) : paramètres de flux de travail partagés entre toutes les exécutions du lot, tels que l'ID du flux de travail, le rôle IAM, l'URI de sortie et les paramètres communs.
+ **Paramètre spécifique à l'exécution** (`inlineSettings`ou`s3UriSettings`) : configurations par exécution qui remplacent ou fusionnent avec le paramètre d'exécution par défaut. Chaque entrée doit inclure un numéro unique`runSettingId`.
+ **ID de réglage d'exécution** (`runSettingId`) : identifiant unique obligatoire fourni par le client pour chaque configuration d'exécution au sein d'un lot. Après la soumission, utilisez cette **ListRunsInBatch** option pour `runSettingId` mapper chacune d'entre elles au HealthOmics -generated`runId`, ce qui vous permet de savoir quelle exécution a été créée à partir de quelle configuration d'entrée.
+ **État du lot** : état général de l'opération par lots. Valeurs possibles :
+ `CREATING`— Batch est en cours de création.
+ `PENDING`— Le batch a été créé ; les configurations d'exécution sont validées de manière asynchrone.
+ `SUBMITTING`— Validation terminée ; des essais individuels sont en cours de soumission.
+ `INPROGRESS`— Toutes les soumissions de courses ont été tentées ; les courses sont en cours d'exécution.
+ `STOPPING`— Une demande d'annulation a été reçue ; les courses sont en cours d'arrêt.
+ `CANCELLED`— Le lot a été annulé.
+ `PROCESSED`— Toutes les exécutions ont atteint un état terminal (terminé, échoué ou annulé).
+ `FAILED`— Le lot lui-même a échoué avant que des cycles n'aient pu être créés. Consultez [Défaillances par lots](#batch-level-failures) pour plus de détails.
+ `RUNS_DELETING`— Les essais du lot sont supprimés.
+ `RUNS_DELETED`— Toutes les séries du lot ont été supprimées.
+ **État** de la soumission : résultat de la soumission pour une série individuelle au sein du lot. Valeurs possibles :
+ `SUCCESS`— L'exécution a été envoyée avec succès.
+ `FAILED`— L'exécution de la soumission a échoué (par exemple, en raison d'une erreur de validation).
+ `CANCEL_SUCCESS`— L'exécution a été annulée avec succès.
+ `CANCEL_FAILED`— L'annulation de l'exécution a échoué.
+ `DELETE_SUCCESS`— La commande Run a été correctement supprimée.
+ `DELETE_FAILED`— L'exécution de la suppression a échoué.
## Conditions préalables
Avant de commencer un traitement par lots, assurez-vous que vous disposez des éléments suivants :
+ Un flux de travail HealthOmics privé actif. Les exécutions par lots ne sont pas prises en charge par les flux de travail Ready2Run.
+ Rôle de service IAM autorisé à exécuter des HealthOmics flux de travail et à accéder à vos compartiments Amazon S3. Pour en savoir plus, consultez [Rôles de service pour AWS HealthOmics](permissions-service.md).
+ Emplacements Amazon S3 pour les données d'entrée et les résultats de sortie.
+ Paramètres spécifiques à l'exécution pour chaque échantillon ou configuration expérimentale.
## Autorisations IAM pour les opérations par lots
Votre identité IAM doit disposer d'autorisations à la fois pour l'opération par lots et pour l'opération d'exécution individuelle sous-jacente. L'exemple de politique suivant accorde des autorisations pour toutes les opérations par lots :
```
{
"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"
}
}
}
]
}
```
**Note**
**StartRunBatch**nécessite une double autorisation : `omics:StartRunBatch` sur la ressource par lots et `omics:StartRun` sur les ressources d'exécution, de flux de travail et de groupe d'exécution. Les deux autorisations doivent être accordées pour que le lot réussisse.
Le rôle de service IAM transmis `roleArn` (utilisé HealthOmics pour exécuter les exécutions) nécessite les mêmes autorisations que pour les **StartRun** appels individuels. Pour en savoir plus, consultez [Rôles de service pour AWS HealthOmics](permissions-service.md).
### Marquage et contrôle d'accès basé sur des balises
Batch exécute les balises de support à deux niveaux :
+ **Balises de lot** (balises sur la **StartRunBatch** demande) : appliquées à la ressource par lots. Le contrôle d'accès basé sur les balises (TBAC) est entièrement appliqué pour les balises par lots.
+ **Balises d'exécution** (`runTags`en cours `defaultRunSetting` et par exécution`runTags`) : appliquées à des ressources d'exécution individuelles. Ces balises sont fusionnées selon les mêmes règles de priorité que les paramètres.
Si vous utilisez des politiques de contrôle d'accès basées sur des balises, assurez-vous que votre politique IAM inclut `omics:TagResource` les conditions appropriées`aws:RequestTag`. `aws:TagKeys`
**Exemple : Restreindre la création de lots aux environnements hors production**
La politique suivante permet aux utilisateurs de créer des lots et des exécutions, mais interdit de baliser les ressources avec : `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"
}
}
}
]
}
```
Avec cette politique :
+ `tags: {"environment": "dev"}`sur le lot → Autorisé
+ `tags: {"environment": "production"}`sur le lot → Refusé (403)
+ `runTags: {"environment": "production"}`dans `defaultRunSetting` → Refusé pour des exécutions individuelles lors de la création asynchrone
## Pour commencer : soumettez votre premier lot
L'exemple suivant explique comment soumettre un petit lot de deux essais, vérifier la progression et examiner les résultats.
**Étape 1 : Soumettre le lot**
```
aws omics start-run-batch \
--batch-name "my-first-batch" \
--default-run-setting '{
"workflowId": "1234567",
"roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
"outputUri": "s3://my-bucket/output/",
"storageType": "DYNAMIC",
"parameters": {"referenceUri": "s3://my-bucket/reference.fasta"}
}' \
--batch-run-settings '{
"inlineSettings": [
{
"runSettingId": "sample-A",
"parameters": {"inputUri": "s3://my-bucket/sampleA.fastq"}
},
{
"runSettingId": "sample-B",
"parameters": {"inputUri": "s3://my-bucket/sampleB.fastq"}
}
]
}'
```
La réponse renvoie un identifiant de lot que vous utiliserez pour toutes les opérations suivantes :
```
{
"id": "7123456",
"arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
"status": "CREATING"
}
```
**Étape 2 : vérifier la progression du lot**
```
aws omics get-batch --batch-id 7123456
```
Suivez la progression du `status` terrain à partir de `CREATING` `PENDING` → `SUBMITTING` → → `INPROGRESS` →`PROCESSED`. `submissionSummary`Indique le nombre d'essais soumis avec succès et `runSummary` indique la progression de l'exécution.
**Étape 3 : Passez en revue les courses individuelles**
```
aws omics list-runs-in-batch --batch-id 7123456
```
Chaque entrée fait correspondre votre `runSettingId` (par exemple`sample-A`) à ce que vous avez HealthOmics généré`runId`, afin que vous puissiez retracer les résultats jusqu'à vos échantillons d'entrée.
**Étape 4 : Vérifier les soumissions ayant échoué**
```
aws omics list-runs-in-batch --batch-id 7123456 --submission-status FAILED
```
Si l'un des essais n'a pas pu être soumis, la réponse inclut `submissionFailureReason` et `submissionFailureMessage` pour vous aider à diagnostiquer le problème.
## Démarrage d'un traitement par lots
**StartRunBatch**À utiliser pour soumettre plusieurs essais avec une seule demande. La demande inclut :
+ `defaultRunSetting`— Configuration partagée pour toutes les exécutions du lot.
+ `batchRunSettings`— Les configurations d'exécution individuelles, fournies sous la forme de l'une des suivantes :
+ `inlineSettings`— Un ensemble contenant jusqu'à 100 configurations spécifiques à l'exécution fournies directement dans le corps de la demande.
+ `s3UriSettings`— Un URI Amazon S3 pointant vers un fichier JSON contenant les configurations d'exécution. Nécessaire pour les lots de plus de 100 essais, et prend en charge jusqu'à 100 000 essais.
Vous pouvez également renseigner les champs suivants :
+ `batchName`— Un nom lisible par l'homme facultatif pour le lot.
+ `requestId`— Un jeton d'idempuissance pour empêcher les soumissions de lots dupliquées.
+ `tags`— Balises à associer à la ressource batch elle-même.
### Soumettez de petits lots avec des configurations d'exécution en ligne
Fournissez un ensemble de configurations spécifiques à l'exécution directement dans le corps de la requête à l'aide de. `inlineSettings` Chaque entrée doit inclure un numéro unique `runSettingId` (obligatoire). `runSettingId`C'est la clé pour corréler les résultats : lorsque vous appelez**ListRunsInBatch**, chaque entrée correspond `runSettingId` au et HealthOmics généré`runId`. `runArn`
Vous pouvez inclure jusqu'à 100 entrées dans les configurations en ligne.
```
{
"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"
}
}
]
}
}
```
**INTERFACE DE LIGNE DE COMMANDE (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"}
}
]
}'
```
### Soumettez de gros lots avec des configurations d'exécution dans S3
Pour les lots comportant plus de 100 exécutions, stockez vos configurations d'exécution dans un fichier JSON dans Amazon S3 et fournissez l'URI à l'aide `s3UriSettings` de. Le fichier JSON doit contenir un tableau d'objets de réglage spécifiques à l'exécution, chacun ayant une valeur unique. `runSettingId` Le fichier peut contenir jusqu'à 100 000 entrées.
Le format de fichier S3 est identique à celui du `inlineSettings` tableau :
```
[
{
"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"
}
}
]
```
**Demande d'API**
```
{
"defaultRunSetting": {
"workflowId": "1234567",
"roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
"outputUri": "s3://my-bucket/output/",
"parameters": {
"referenceUri": "s3://my-bucket/reference/genome.fasta"
}
},
"batchRunSettings": {
"s3UriSettings": "s3://my-bucket/configs/run-configs.json"
}
}
```
**INTERFACE DE LIGNE DE COMMANDE (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"}'
```
**Important**
Le rôle de service IAM spécifié dans `roleArn` doit disposer d'un accès en lecture à l'objet Amazon S3 spécifié dans`s3UriSettings`. HealthOmics valide l'accès au fichier Amazon S3 lors de l'appel d'API synchrone et enregistre les informations du fichier. ETag Si le fichier est modifié après sa soumission, le lot échoue lors du traitement asynchrone.
### Réponse
Une demande réussie renvoie un ID de lot et un statut initial :
```
{
"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"
}
}
```
Si la validation synchrone échoue (par exemple, un identifiant de flux de travail non valide ou un URI Amazon S3 inaccessible), l'API renvoie une erreur avant que les exécutions ne soient soumises.
### Référence des paramètres
Le tableau suivant indique **StartRun** les champs qui peuvent être définis par cycle et ceux qui s'appliquent uniquement au niveau du lot. Pour une description complète des champs, consultez la référence de **StartRun** l'API.
| Champ | Au niveau du lot () `defaultRunSetting` | Configurable par exécution () `inlineSettings` |
| --- | --- | --- |
| workflowId | Oui | Non |
| workflowType | Oui | Non |
| workflowVersionName | Oui | Non |
| workflowOwnerId | Oui | Non |
| roleArn | Oui | Non |
| storageCapacity | Oui | Non |
| storageType | Oui | Non |
| runGroupId | Oui | Non |
| logLevel | Oui | Non |
| cacheBehavior | Oui | Non |
| cacheId | Oui | Non |
| retentionMode | Oui | Non |
| name | Oui | Oui |
| outputUri | Oui | Oui |
| parameters | Oui | Oui (fusionné) |
| priority | Oui | Oui |
| runTags | Oui | Oui (fusionné) |
| outputBucketOwnerId | Oui | Oui |
**Note**
Le champ `runId` (pour les réexécutions individuelles) n'est pas pris en charge en tant que saisie dans**StartRunBatch**. Chaque envoi par lots crée toujours de nouveaux cycles, et chaque cycle recevra un`runId`. Reportez-vous [Réexécuter un run in HealthOmics](rerun-a-run.md) à la section pour réessayer des essais individuels.
### Fusion de paramètres
Les paramètres de `defaultRunSetting` sont fusionnés avec les paramètres spécifiques à l'exécution fournis dans `inlineSettings` ou via un URI S3. Les valeurs spécifiques à l'exécution sont prioritaires lorsque les touches se chevauchent.
**Exemple :**
| Source | Parameters |
| --- | --- |
| defaultRunSetting | \$1"referenceUri": "s3://bucket/ref.fasta", "version": "v1"\$1 |
| inlineSettingsentrée | \$1"inputUri": "s3://bucket/sample.fastq", "version": "v2"\$1 |
| Résultat fusionné | \$1"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"\$1 |
Le même comportement de fusion s'applique à. `runTags` Les balises spécifiées dans la configuration par exécution remplacent les balises avec la même clé from`defaultRunSetting.runTags`, et de nouvelles clés sont ajoutées.
**Exemple de fusion de balises :**
| Source | Étiquettes |
| --- | --- |
| defaultRunSetting.runTags | \$1"project": "cancer-research", "pipeline-version": "v2.1"\$1 |
| inlineSettings[].runTags | \$1"patient-id": "patient001", "pipeline-version": "v3.0"\$1 |
| Résultat fusionné (appliqué à l'exécution) | \$1"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"\$1 |
**Note**
Les balises au niveau du lot (sur la **StartRunBatch** demande) ne sont appliquées qu'à la ressource par lots elle-même. Ils ne sont pas hérités par des courses individuelles. Les balises au niveau de l'exécution sont contrôlées pendant `defaultRunSetting.runTags` et par exécution. `runTags`
### Soumission progressive
**StartRunBatch**valide les champs communs de manière synchrone et renvoie immédiatement un numéro de lot et un statut. `CREATING` Les exécutions par lots sont soumises progressivement et de manière asynchrone à un rythme contrôlé en fonction de vos quotas de débit.
Pour la liste complète des HealthOmics quotas, voir[HealthOmics quotas de service](service-quotas.md).
Le lot passe par les états suivants au cours du traitement normal :
1. `CREATING`— Batch est en cours de création.
1. `PENDING`— Batch créé, configurations d'exécution en cours de validation.
1. `SUBMITTING`— Validation terminée, les essais individuels sont en cours de soumission.
1. `INPROGRESS`— Toutes les soumissions de courses ont été tentées, les courses sont en cours d'exécution.
1. `PROCESSED`— Toutes les courses ont atteint l'état terminal.
**Important**
La soumission par lots partage le même quota de **StartRun** débit que les appels d'**StartRun**API directs. Si vous appelez **StartRun** directement pendant le traitement d'un lot important, les soumissions par lots et vos appels directs se disputent la même capacité. Cela peut entraîner l'échec des traitements par lots `ThrottlingException` (débit dépassé) ou la limitation de vos **StartRun** appels directs. Il en va de même pour **CancelRun** et **DeleteRun** — ils partagent des quotas de débit avec **CancelRunBatch** et **DeleteRunBatch** respectivement.
## Surveillance de la progression des lots
### Obtenir le statut du lot
Permet **GetBatch** de récupérer le statut général et la progression de la soumission d'un lot.
```
aws omics get-batch --batch-id 7123456
```
La réponse inclut :
+ `status`— État général du lot.
+ `submissionSummary`— Nombre de soumissions réussies et échouées pour les opérations de démarrage, d'annulation et de suppression.
+ `runSummary`— Nombre d'essais dans chaque état d'exécution. Valeurs possibles :`PENDING`,`STARTING`,`RUNNING`,`STOPPING`,`COMPLETED`,`DELETED`,`CANCELLED`, ou `FAILED`
+ Horodatages des événements du cycle de vie —`creationTime`,,`submittedTime`,`processedTime`. `failedTime`
**Exemple de réponse :**
```
{
"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"
}
}
```
**Note**
Les résumés d'exécution des exécutions sont finalement cohérents et peuvent être en retard par rapport aux états d'exécution réels. Les dénombrements finaux sont rapprochés lorsque le lot atteint son `PROCESSED` statut.
### La liste est exécutée par lots
Permet **ListRunsInBatch** de récupérer des informations détaillées pour des essais individuels au sein d'un lot. Les résultats sont paginés.
```
aws omics list-runs-in-batch --batch-id 7123456
```
Vous pouvez filtrer les résultats à l'aide de l'un des paramètres de requête suivants. Un seul filtre par appel est pris en charge.
| Filtre | Description |
| --- | --- |
| submissionStatus | Filtrer par statut de soumission : SUCCESSFAILED,CANCEL\$1SUCCESS,CANCEL\$1FAILED,DELETE\$1SUCCESS, ouDELETE\$1FAILED. |
| runSettingId | Récupérez l'exécution pour un ID de paramètre d'exécution spécifique. |
| runId | Récupérez l'exécution pour un ID d'exécution spécifique. |
**Exemple : Répertorier les soumissions ayant échoué**
```
aws omics list-runs-in-batch --batch-id 7123456 --submission-status FAILED
```
Chaque résultat inclut :
+ `runSettingId`— L'identifiant fourni par le client pour la configuration d'exécution.
+ `runId`— L'identifiant d'exécution HealthOmics généré par -generated (vide en cas d'échec de la soumission).
+ `runArn`— L'ARN complet de l'exécution.
+ `submissionStatus`— Le résultat de la soumission (`SUCCESS``FAILED`,`CANCEL_SUCCESS`,`CANCEL_FAILED`,`DELETE_SUCCESS`, ou`DELETE_FAILED`).
+ `submissionFailureReason`et `submissionFailureMessage` — Détails en cas d'échec de la soumission.
**Note**
`runSettingId`est l'identifiant spécifié par le client que vous avez fourni dans la configuration d'exécution. `runId`est l'identifiant HealthOmics généré attribué après une soumission réussie. En cas d'échec de la soumission, `runId` est vide.
### Lister les lots
**ListBatch**À utiliser pour récupérer toutes les ressources par lots de votre compte. Les résultats sont paginés.
```
aws omics list-batch
```
Vous pouvez filtrer les résultats à l'aide des paramètres de requête suivants :
| Filtre | Description |
| --- | --- |
| status | Filtrez par statut du lot. |
| name | Filtrez par nom de lot. |
| runGroupId | Filtrez par ID de groupe d'exécution. |
## Gestion des essais infructueux
Il existe deux types distincts de défaillances dans le traitement par lots. Comprendre la différence est essentiel pour le dépannage.
### Défaillances par lots
Une défaillance au niveau du lot signifie que le lot lui-même a échoué : aucune exécution n'a été créée (ou seules certaines ont été créées avant l'échec). L'état du lot est`FAILED`.
Appelez **GetBatch** et vérifiez le `failureReason` terrain. Les causes de défaillance les plus courantes incluent :
| Catégorie de défaillance | Exemple de `failureReason` message | Action |
| --- | --- | --- |
| Erreur de validation | « Batch compte 10 0001 essais, mais le maximum est de 100 000 essais. «, « 50 exemplaires uniques attendus runSettingIds mais il y en avait 49 », « Format JSON non valide dans les configurations d'exécution » | Corrigez la configuration et soumettez un nouveau lot. Ces erreurs ne peuvent pas être réessayées. |
| Configuration S3 modifiée | « UriConfigs Etag s3 attendu : \$1" abc123 \$1 » mais c'était le cas : \$1 "def456 \$1 ». s3 a changé UriConfigs depuis l'appel » StartRunBatch | Ne modifiez pas le fichier S3 après son envoi. Soumettez à nouveau avec le fichier actuel. |
| Erreur de service transitoire | « Une erreur passagère s'est produite dans le service. Réessayez le lot. » | Réessayez en soumettant à nouveau le même lot. Utilisez la même méthode requestId pour l'idempuissance. |
**Exemple : échec du lot en raison d'une validation**
```
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"
}
```
### Défaillances au niveau de l'exécution
Un échec au niveau de l'exécution signifie que le lot lui-même a réussi (le statut est `INPROGRESS` ou`PROCESSED`), mais que les essais individuels n'ont pas été soumis. Le lot continue à traiter les autres exécutions ; il ne s'arrête pas au premier échec.
**1. Consultez le résumé des soumissions**
```
aws omics get-batch --batch-id 7123456
```
Regarde`submissionSummary.failedStartSubmissionCount`. Si ce chiffre est supérieur à zéro, certaines exécutions ont échoué lors de la soumission.
**2. Lister les soumissions ayant échoué**
```
aws omics list-runs-in-batch --batch-id 7123456 --submission-status FAILED
```
Chaque entrée échouée inclut :
+ `runSettingId`— Quelle configuration d'exécution a échoué.
+ `submissionFailureReason`— Catégorie d'erreur.
+ `submissionFailureMessage`— Un message d'erreur détaillé.
**3. Motifs d'échec de la soumission**
Le tableau suivant répertorie les valeurs possibles pour `submissionFailureReason` des essais individuels :
| `submissionFailureReason` | Signification | Récupérable ? |
| --- | --- | --- |
| ValidationException | Les paramètres d'exécution ne sont pas valides. Par exemple, ils ne correspondent pas à la définition du flux de travail, le format d'URI S3 n'est pas valide ou les restrictions ne sont pas respectées. | Non, corrigez la configuration. |
| AccessDeniedException | Le rôle de service IAM ne dispose pas des autorisations nécessaires pour accéder aux ressources requises (entrées S3, clés KMS, CloudWatch journaux, images ECR). | Non, mettez à jour la politique des rôles. |
| ResourceNotFoundException | Une ressource référencée (flux de travail, groupe d'exécution ou cache d'exécution) n'existe pas ou n'est pas active. | Non, vérifiez la ressource IDs. |
| ServiceQuotaExceededException | Le compte a atteint le nombre maximum d'essais actifs ou un autre quota de service. | Attendez la fin des essais ou demandez une augmentation du quota. |
| ConflictException | Une opération conflictuelle est en cours, par exemple une tentative de création d'un double cycle. | Il se résout généralement tout seul. |
| ThrottlingException | La demande a été limitée en raison des limites de débit de l'API. | Le service réessaie automatiquement. S'il persiste après de nouvelles tentatives, réduisez le nombre de soumissions par lots simultanées. |
| RequestTimeoutException | Le délai de traitement de la demande a expiré. | Le service réessaie automatiquement. Si le problème persiste, vérifiez s'il existe des problèmes en aval. |
| InternalServerException | Une erreur de service inattendue s'est produite. | Le service réessaie automatiquement. Si le problème persiste après de nouvelles tentatives, contactez le AWS Support. |
**Note**
HealthOmics réessaie automatiquement les erreurs transitoires (`ThrottlingException`,`RequestTimeoutException`,`InternalServerException`) pour chaque exécution. Une exécution n'est marquée comme étant exécutée `FAILED` qu'une fois toutes les nouvelles tentatives épuisées. Les erreurs non réessayables (`ValidationException`,`AccessDeniedException`,`ResourceNotFoundException`) échouent immédiatement sans nouvelle tentative.
**4. Soumettre à nouveau les courses ayant échoué**
Créez un nouveau lot contenant uniquement les configurations d'exécution corrigées. Utilisez le même `defaultRunSetting` et incluez uniquement les `runSettingId` entrées qui ont échoué. Il n'existe aucun mécanisme de nouvelle tentative intégré en cas d'échec d'exécution. Vous devez soumettre un nouveau lot.
## Annulation d'un lot
**CancelRunBatch**À utiliser pour annuler un lot en cours. L'opération d'annulation :
+ Empêche not-yet-submitted le démarrage des courses et celles en attente
+ Soumet des **CancelRun** demandes pour les courses déjà commencées.
```
aws omics cancel-run-batch --batch-id 7123456
```
**Important**
L'annulation n'est autorisée que pour les lots `PENDING` `SUBMITTING` en `INPROGRESS` état ou.
Une seule opération d'annulation ou de suppression par lot est autorisée à la fois.
Les opérations d'annulation ne sont pas atomiques et peuvent être partiellement réussies. **GetBatch**À utiliser pour consulter `successfulCancelSubmissionCount` et `failedCancelSubmissionCount` dans le`submissionSummary`.
## Supprimer des séries par lots
**DeleteRunBatch**À utiliser pour supprimer les séries individuelles d'un lot.
```
aws omics delete-run-batch --batch-id 7123456
```
**Important**
La suppression n'est autorisée que pour les lots en cours `PROCESSED` ou en `CANCELLED` état.
Une seule opération d'annulation ou de suppression par lot est autorisée à la fois.
Les opérations de suppression ne sont pas atomiques et peuvent être partiellement réussies. **GetBatch**À utiliser pour consulter `successfulDeleteSubmissionCount` et `failedDeleteSubmissionCount` dans le`submissionSummary`.
## Suppression des métadonnées par lots
**DeleteBatch**À utiliser pour supprimer la ressource par lots et les métadonnées associées. Il s'agit d'une opération distincte de**DeleteRunBatch**.
```
aws omics delete-batch --batch-id 7123456
```
**Important**
**DeleteBatch**nécessite que le lot soit dans un état terminal (`PROCESSED``FAILED`,`CANCELLED`, ou`RUNS_DELETED`).
**DeleteBatch**ne supprime pas les essais individuels. **DeleteRunBatch**Utilisez-le d'abord si vous souhaitez également supprimer les points.
Une fois l'**DeleteBatch**opération terminée, les métadonnées du lot ne sont plus accessibles. Vous ne pouvez pas appeler **GetBatch** **ListRunsInBatch****DeleteRunBatch**,, ou **CancelRunBatch** sur un lot supprimé.
## EventBridge événements pour les lots
HealthOmics envoie des événements à Amazon EventBridge chaque fois qu'un lot change de statut. Vous pouvez utiliser ces événements pour automatiser les flux de travail, par exemple pour déclencher une notification lorsqu'un lot est terminé ou échoue, ou pour démarrer un pipeline en aval lorsque tous les cycles sont terminés.
Les événements Batch utilisent le même bus d'événements et la même source que les autres HealthOmics événements. Pour les instructions générales de configuration, voir[Utilisation EventBridge avec AWS HealthOmics](eventbridge.md).
### Type de détail de l'événement
| Nom de l’événement | Émis lorsque |
| --- | --- |
| RunBatch Changement de statut | Le lot passe à un nouveau statut (CREATINGPENDING,SUBMITTING,INPROGRESS,STOPPING,CANCELLED,PROCESSED,FAILED,RUNS\$1DELETING,RUNS\$1DELETED) |
### Champs de détail de l'événement
L'`detail`objet d'un événement par lots inclut les champs suivants :
| Champ | Type | Description |
| --- | --- | --- |
| omicsVersion | String | Version du schéma d'événements (actuellement 1.0.0). |
| arn | String | L'ARN du lot. |
| batchId | String | L'identifiant du lot. |
| status | String | Le nouveau statut du lot. |
| uuid | String | L'UUID du lot. |
| batchName | String | Le nom du lot (s'il est fourni). |
| totalRuns | String | Nombre total d'essais dans le lot. |
| failureReason | String | Motif de l'échec (présent uniquement lorsque le statut l'estFAILED). |
| failureMessage | String | Message d'échec détaillé (présent uniquement lorsque l'état l'estFAILED). |
| successfulStartSubmissionCount | String | Nombre de courses soumises avec succès. |
| failedStartSubmissionCount | String | Nombre de courses qui n'ont pas pu être soumises. |
| pendingStartSubmissionCount | String | Nombre de tirages toujours en attente de soumission. |
| pendingRunCount | String | Nombre de courses en attente. |
| startingRunCount | String | Nombre de courses démarrant. |
| runningRunCount | String | Nombre de courses en cours. |
| stoppingRunCount | String | Nombre de courses arrêtées. |
| completedRunCount | String | Nombre de courses terminées. |
| failedRunCount | String | Nombre de courses infructueuses. |
| cancelledRunCount | String | Nombre de courses annulées. |
| deletedRunCount | String | Nombre de passages supprimés. |
| workflowId | String | L'identifiant du flux de travail. |
| workflowArn | String | L'ARN du flux de travail. |
| workflowVersionArn | String | La version ARN du flux de travail (le cas échéant). |
| workflowOwnerId | String | L'ID de compte du propriétaire du flux de travail (pour les flux de travail partagés). |
| runCache | String | L'ARN du cache d'exécution (le cas échéant). |
| runCacheBehavior | String | Le comportement du cache d'exécution (le cas échéant). |
### Exemples d'événements
**Exemple : événement terminé par lots**
```
{
"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"
}
}
```
**Exemple : événement d'échec du Batch**
```
{
"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"
}
}
```
**Exemple : EventBridge règle d'achèvement par lots**
Le modèle d'événement suivant correspond lorsqu'un lot atteint un état terminal :
```
{
"source": ["aws.omics"],
"detail-type": ["RunBatch Status Change"],
"detail": {
"status": ["PROCESSED", "FAILED", "CANCELLED"]
}
}
```
## Limites et considérations
+ **Quotas de débit partagés** : les opérations par lots partagent les mêmes quotas par compte que leurs homologues d'API individuels. **StartRunBatch**consomme des quotas **StartRun** de service. **CancelRunBatch**consomme **CancelRun** des quotas, et **DeleteRunBatch** consomme **DeleteRun** des quotas. Évitez d'appeler une exécution individuelle APIs alors qu'un lot volumineux est en cours, car cela peut entraîner des échecs de soumission.
+ **Soumission progressive** — Les séries par lots sont soumises progressivement et de manière asynchrone en fonction de vos quotas de débit.
+ **Opérations non atomiques** —**StartRunBatch**,**CancelRunBatch**, et **DeleteRunBatch** peuvent toutes être partiellement réussies. Vérifiez toujours les résumés des soumissions pour identifier les essais qui doivent être réessayés.
+ **Cohérence éventuelle** — Le nombre d'états d'exécution des exécutions **GetBatch** peut être inférieur à celui des états d'exécution réels. Les dénombrements finaux sont exacts une fois le lot atteint`PROCESSED`.
+ **Filtre unique par appel de liste**, **ListRunsInBatch** et ne **ListBatch** prend en charge qu'un seul filtre par appel d'API.
+ **Réexécution non prise en charge** — Le champ `runId` (réexécution) n'est pas pris en charge dans. **StartRunBatch** Chaque envoi par lots crée toujours de nouveaux cycles.
+ **Flux de travail Ready2Run —** Les exécutions par lots ne sont pas prises en charge par les flux de travail Ready2Run.
+ **Limite de configuration en ligne** : les configurations en ligne (`inlineSettings`) prennent en charge jusqu'à 100 entrées. Pour des lots plus importants, utilisez`s3UriSettings`. Cette limite n’est pas réglable.
+ **Fichier de configuration S3** — Le fichier de configuration S3 doit être un tableau JSON d'objets de configuration d'exécution. La taille de fichier maximale est de 6 Go et prend en charge jusqu'à 100 000 configurations d'exécution.
+ **Immuabilité du fichier S3** — Ne modifiez pas le fichier de configuration S3 après avoir soumis le lot. HealthOmics valide la balise d'entité (ETag) du fichier lors de la soumission et échoue au traitement par lots si le fichier a changé.