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 etListRunsInBatch.

• Annulez tous les essais d'un lot à l'aide deCancelRunBatch.

• Supprimez toutes les séries d'un lot à l'aide deDeleteRunBatch.

• Supprimez les métadonnées du lot avecDeleteBatch.

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 (inlineSettingsous3UriSettings) : 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 uniquerunSettingId.

• 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 -generatedrunId, 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 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.

• 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

StartRunBatchné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.

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 (runTagsen cours defaultRunSetting et par exécutionrunTags) : 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éesaws: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. submissionSummaryIndique 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 exemplesample-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). runSettingIdC'est la clé pour corréler les résultats : lorsque vous appelezListRunsInBatch, 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é danss3UriSettings. 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 dansStartRunBatch. Chaque envoi par lots crée toujours de nouveaux cycles, et chaque cycle recevra unrunId. Reportez-vous Réexécuter un run in HealthOmics à 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	{"referenceUri": "s3://bucket/ref.fasta", "version": "v1"}
inlineSettingsentrée	{"inputUri": "s3://bucket/sample.fastq", "version": "v2"}
Résultat fusionné	{"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"}

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é fromdefaultRunSetting.runTags, et de nouvelles clés sont ajoutées.

Exemple de fusion de balises :

Source	Étiquettes
defaultRunSetting.runTags	{"project": "cancer-research", "pipeline-version": "v2.1"}
inlineSettings[].runTags	{"patient-id": "patient001", "pipeline-version": "v3.0"}
Résultat fusionné (appliqué à l'exécution)	{"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"}

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

StartRunBatchvalide 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, voirHealthOmics quotas de service.

Le lot passe par les états suivants au cours du traitement normal :

1. CREATING— Batch est en cours de création.

2. PENDING— Batch créé, configurations d'exécution en cours de validation.

3. SUBMITTING— Validation terminée, les essais individuels sont en cours de soumission.

4. INPROGRESS— Toutes les soumissions de courses ont été tentées, les courses sont en cours d'exécution.

5. 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'StartRunAPI 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_SUCCESS,CANCEL_FAILED,DELETE_SUCCESS, ouDELETE_FAILED.
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 (SUCCESSFAILED,CANCEL_SUCCESS,CANCEL_FAILED,DELETE_SUCCESS, ouDELETE_FAILED).

• submissionFailureReasonet submissionFailureMessage — Détails en cas d'échec de la soumission.

Note

runSettingIdest l'identifiant spécifié par le client que vous avez fourni dans la configuration d'exécution. runIdest 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 estFAILED.

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 : \" abc123 \ » mais c'était le cas : \ "def456 \ ». 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 ouPROCESSED), 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

RegardesubmissionSummary.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 lesubmissionSummary.

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 lesubmissionSummary.

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 deDeleteRunBatch.

aws omics delete-batch --batch-id 7123456

Important

• DeleteBatchnécessite que le lot soit dans un état terminal (PROCESSEDFAILED,CANCELLED, ouRUNS_DELETED).

• DeleteBatchne supprime pas les essais individuels. DeleteRunBatchUtilisez-le d'abord si vous souhaitez également supprimer les points.

• Une fois l'DeleteBatchopération terminée, les métadonnées du lot ne sont plus accessibles. Vous ne pouvez pas appeler GetBatch ListRunsInBatchDeleteRunBatch,, 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, voirUtilisation EventBridge avec AWS HealthOmics.

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_DELETING,RUNS_DELETED)

Champs de détail de l'événement

L'detailobjet 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. StartRunBatchconsomme des quotas StartRun de service. CancelRunBatchconsomme 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 atteintPROCESSED.

• 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, utilisezs3UriSettings. 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é.