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.

Le lot s'exécute dans HealthOmics

AWS HealthOmics les exécutions par lots vous permettent de soumettre plusieurs exécutions en une seule demande d'API. Chaque exécution du lot partage une configuration de base commune mais peut avoir des entrées et des paramètres spécifiques à l'exécution différents. Les traitements 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.

Grâce aux traitements par lots, vous pouvez :

Concepts d'exécution par lots

Conditions préalables

Avant de démarrer un traitement par lots, assurez-vous que vous disposez des éléments suivants :

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

Le rôle de service IAM transmis roleArn (utilisé par HealthOmics pour exécuter les exécutions) nécessite les mêmes autorisations que pour les StartRun appels individuels. Pour plus de détails, consultez Rôles de service pour AWS HealthOmics.

Balisage et contrôle d'accès basé sur les balises

Batch exécute les balises de support à deux niveaux :

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 aws:RequestTag et aws:TagKeys appropriées.

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 une ressource 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 :

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'exécutions qui ont été soumises 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 associe votre runSettingId (par exemple,sample-A) à la HealthOmics-generatedrunId, afin que vous puissiez retracer les résultats jusqu'à vos échantillons d'entrée.

Étape 4 : Vérifiez les soumissions ayant échoué

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

Si l'une des exécutions n'a pas été envoyée, la réponse inclut submissionFailureReason et vous aide submissionFailureMessage à diagnostiquer le problème.

Démarrage d'un traitement par lots

Permet StartRunBatch de soumettre plusieurs essais avec une seule demande. La demande comprend :

Vous pouvez également fournir les champs suivants :

Soumettez de petits lots avec des configurations d'exécution en ligne

Fournissez un tableau 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 votre clé pour corréler les résultats : lorsque vous appelezListRunsInBatch, chaque entrée vous met en correspondance runSettingId avec le HealthOmics-generated runId etrunArn.

Vous pouvez inclure jusqu'à 100 entrées avec des 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 de plus de 100 exécutions, stockez vos configurations d'exécution dans un fichier JSON d'Amazon S3 et indiquez l'URI en utilisants3UriSettings. 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 le même que 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"}'

Réponse

Une demande réussie renvoie un identifiant 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 ID 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 quels StartRun champs peuvent être définis par exécution et lesquels s'appliquent uniquement au niveau du lot. Pour une description complète des champs, consultez la référence de StartRun l'API.

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. Run-specific les valeurs sont prioritaires lorsque les touches se chevauchent.

Exemple :

Le même comportement de fusion s'applique à. runTags Les balises spécifiées dans la configuration par exécution remplacent les balises dont la clé provient de la mêmedefaultRunSetting.runTags, et de nouvelles clés sont ajoutées.

Exemple de fusion de balises :

Soumission graduelle

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 :

Suivi de la progression des lots

Obtenir l'état du lot

Permet GetBatch de récupérer l'état général et la progression de la soumission pour un lot.

aws omics get-batch --batch-id 7123456

La réponse inclut :

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

La liste s'exécute par lots

Permet ListRunsInBatch de récupérer des informations détaillées pour les 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.

Exemple : répertorier les soumissions ayant échoué

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

Chaque résultat inclut :

Répertorier les lots

ListBatchUtilisez-le 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 :

Activer les métriques d'exécution

Les métriques d'exécution indiquent l'utilisation des ressources en temps quasi réel pour les exécutions d'un lot. Pour activer les métriques d'exécution, le rôle de service que vous utilisez pour le lot doit disposer de l'cloudwatch:PutMetricDataautorisation requise. Pour plus d’informations, consultez Exécutez des métriques pour les flux de travail privés.

Ajoutez l'autorisation suivante au rôle de service que vous utilisez pour le lot.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudwatch:PutMetricData",
      "Resource": "*"
    }
  ]
}

Gestion des essais échoués

Il existe deux types distincts de défaillances dans le traitement par lots. Il est essentiel de comprendre la différence pour résoudre les problèmes.

Batch-level échecs

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 seulement certaines ont été créées avant l'échec). L'état du lot estFAILED.

Appelez GetBatch et vérifiez le failureReason champ. Les raisons de défaillance courantes incluent :

Exemple : échec du lot en raison de la 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"
}

Run-level échecs

Un échec au niveau de l'exécution signifie que le lot lui-même a réussi (l'état est INPROGRESS ouPROCESSED), mais que les essais individuels n'ont pas été soumis. Le lot continue à traiter les autres cycles ; il ne s'arrête pas au premier échec.

1. Consultez le résumé de la soumission

aws omics get-batch --batch-id 7123456

RegardesubmissionSummary.failedStartSubmissionCount. Si cette valeur est supérieure à zéro, certaines exécutions ont échoué lors de la soumission.

2. Liste des soumissions ayant échoué

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

Chaque entrée échouée inclut :

3. Raisons de l'échec de soumission

Le tableau suivant répertorie les valeurs possibles pour submissionFailureReason des essais individuels :

4. Soumettre à nouveau les exécutions ayant échoué

Créez un nouveau lot contenant uniquement les configurations d'exécution corrigées. Utilisez-le 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 des exécutions. Vous devez soumettre un nouveau lot.

Annulation d'un lot

Permet CancelRunBatch d'annuler un lot en cours. L'opération d'annulation :

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

Supprimer des cycles par lots

Permet DeleteRunBatch de supprimer les essais individuels d'un lot.

aws omics delete-run-batch --batch-id 7123456

Suppression de métadonnées par lots

Permet DeleteBatch de supprimer la ressource par lots et ses métadonnées associées. Il s'agit d'une opération distincte deDeleteRunBatch.

aws omics delete-batch --batch-id 7123456

EventBridge événements pour 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 se termine ou échoue, ou pour démarrer un pipeline en aval lorsque toutes les exécutions sont terminées.

Les événements par lots 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, consultezUtilisation EventBridge avec AWS HealthOmics.

Type de détails de l'événement

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

L'detailobjet d'un événement groupé inclut les champs suivants :

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 : échec d'un événement par lots

{
  "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 pour l'achèvement des lots

Le modèle d'événement suivant correspond à chaque fois qu'un lot atteint un état terminal :

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

Limites et considérations