翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

HealthOmics でのバッチ実行

AWS HealthOmics バッチ実行では、1 つの API リクエストで複数の実行を送信できます。バッチ内の各実行は共通の基本設定を共有しますが、異なる入力と実行固有のパラメータを持つことができます。バッチ実行は送信オーバーヘッドを削減し、大規模なワークフロー処理のライフサイクル管理を簡素化します。

バッチ実行では、次のことができます。

バッチ実行の概念

前提条件

バッチ実行を開始する前に、以下を確認してください。

バッチオペレーションの IAM アクセス許可

IAM ID には、バッチオペレーションと基盤となる個々の実行オペレーションの両方に対するアクセス許可が必要です。次のポリシー例では、すべてのバッチオペレーションのアクセス許可を付与します。

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

渡された IAM サービスロール roleArn (HealthOmics が実行を実行するために使用する) には、個々のStartRun呼び出しと同じアクセス許可が必要です。詳細については、「のサービスロール AWS HealthOmics」を参照してください。

タグ付けとタグベースのアクセスコントロール

バッチ実行は、次の 2 つのレベルでタグをサポートします。

タグベースのアクセスコントロールポリシーを使用する場合は、IAM ポリシーomics:TagResourceに適切な aws:RequestTagおよび aws:TagKeys条件が含まれていることを確認してください。

例: バッチ作成を非本番環境に制限する

次のポリシーでは、ユーザーはバッチを作成して実行できますが、 を使用したリソースのタグ付けは拒否されます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"
        }
      }
    }
  ]
}

このポリシーでは、次のようになります。

開始方法: 最初のバッチを送信する

次の例では、2 つの実行の小さなバッチの送信、進行状況の確認、結果の確認について説明します。

ステップ 1: バッチを送信する

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

レスポンスは、後続のすべてのオペレーションに使用するバッチ ID を返します。

{
  "id": "7123456",
  "arn": "arn:aws:omics:us-west-2:123456789012:runBatch/7123456",
  "status": "CREATING"
}

ステップ 2: バッチの進行状況を確認する

aws omics get-batch --batch-id 7123456

status フィールドの進行状況を → CREATING → PENDING → SUBMITTING → INPROGRESS → から監視しますPROCESSED。submissionSummary には、正常に送信された実行の数と実行の進行状況runSummaryが表示されます。

ステップ 3: 個々の実行を確認する

aws omics list-runs-in-batch --batch-id 7123456

各エントリは runSettingId ( などsample-A) を HealthOmics が生成した にマッピングするためrunId、結果を入力サンプルにトレースできます。

ステップ 4: 失敗した送信を確認する

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

送信に失敗した実行がある場合、問題の診断に役立つ submissionFailureMessage submissionFailureReasonと がレスポンスに含まれます。

バッチ実行の開始

を使用してStartRunBatch、1 つのリクエストで複数の実行を送信します。リクエストには以下が含まれます。

次のフィールドを指定することもできます。

インライン実行設定を使用して小さなバッチを送信する

を使用して、実行固有の設定の配列をリクエスト本文に直接指定しますinlineSettings。各エントリには一意の runSettingId (必須) を含める必要があります。runSettingId は結果を相関させるためのキーです。 を呼び出すとListRunsInBatch、各エントリは を HealthOmics が生成した runIdと runSettingIdにマッピングしますrunArn。

インライン設定では、最大 100 個のエントリを含めることができます。

{
  "batchName": "genomics-cohort-analysis",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {
    "project": "genomics-study",
    "environment": "production"
  },
  "defaultRunSetting": {
    "workflowId": "1234567",
    "roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
    "outputUri": "s3://my-bucket/output/",
    "parameters": {
      "referenceUri": "s3://my-bucket/reference/genome.fasta"
    },
    "runTags": {
      "analysis-type": "germline"
    }
  },
  "batchRunSettings": {
    "inlineSettings": [
      {
        "runSettingId": "sample-001",
        "name": "Sample-001-Analysis",
        "parameters": {
          "inputUri": "s3://my-bucket/input/sample-001.fastq",
          "sampleName": "sample-001"
        },
        "runTags": {
          "patient-id": "patient001"
        }
      },
      {
        "runSettingId": "sample-002",
        "name": "Sample-002-Analysis",
        "outputUri": "s3://my-bucket/output/special/",
        "parameters": {
          "inputUri": "s3://my-bucket/input/sample-002.fastq",
          "sampleName": "sample-002"
        },
        "runTags": {
          "patient-id": "patient002"
        }
      }
    ]
  }
}

CLI

aws omics start-run-batch \
  --batch-name "genomics-cohort-analysis" \
  --request-id "a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --default-run-setting '{
    "workflowId": "1234567",
    "roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
    "outputUri": "s3://my-bucket/output/",
    "storageType": "DYNAMIC",
    "parameters": {"referenceUri": "s3://my-bucket/reference.fasta"}
  }' \
  --batch-run-settings '{
    "inlineSettings": [
      {
        "runSettingId": "sample-001",
        "name": "Run-001",
        "parameters": {"inputUri": "s3://my-bucket/input1.fastq"}
      },
      {
        "runSettingId": "sample-002",
        "name": "Run-002",
        "parameters": {"inputUri": "s3://my-bucket/input2.fastq"}
      }
    ]
  }'

S3 で実行設定を使用して大きなバッチを送信する

実行数が 100 を超えるバッチの場合、実行設定を Amazon S3 の JSON ファイルに保存し、 を使用して URI を指定しますs3UriSettings。JSON ファイルには、一意の を持つ実行固有の設定オブジェクトの配列が含まれている必要がありますrunSettingId。ファイルには、最大 100,000 個のエントリを含めることができます。

S3 ファイル形式は inlineSettings配列と同じです。

[
  {
    "runSettingId": "sample-001",
    "name": "Sample-001-Analysis",
    "parameters": {
      "inputUri": "s3://my-bucket/input/sample-001.fastq",
      "sampleName": "sample-001"
    }
  },
  {
    "runSettingId": "sample-002",
    "name": "Sample-002-Analysis",
    "parameters": {
      "inputUri": "s3://my-bucket/input/sample-002.fastq",
      "sampleName": "sample-002"
    }
  }
]

API リクエスト

{
  "defaultRunSetting": {
    "workflowId": "1234567",
    "roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
    "outputUri": "s3://my-bucket/output/",
    "parameters": {
      "referenceUri": "s3://my-bucket/reference/genome.fasta"
    }
  },
  "batchRunSettings": {
    "s3UriSettings": "s3://my-bucket/configs/run-configs.json"
  }
}

CLI

aws omics start-run-batch \
  --default-run-setting '{
    "workflowId": "1234567",
    "roleArn": "arn:aws:iam::123456789012:role/OmicsRole",
    "outputUri": "s3://my-bucket/output/",
    "parameters": {"referenceUri": "s3://my-bucket/reference.fasta"}
  }' \
  --batch-run-settings '{"s3UriSettings": "s3://my-bucket/configs/run-configs.json"}'

[応答]

リクエストが成功すると、バッチ ID と初期ステータスが返されます。

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

同期検証が失敗した場合 (無効なワークフロー ID やアクセスできない Amazon S3 URI など）、API は実行が送信される前にエラーを返します。

パラメータリファレンス

次の表は、実行ごとに設定できるStartRunフィールドと、バッチレベルでのみ適用されるフィールドを示しています。フィールドの詳細については、 StartRun API リファレンスを参照してください。

パラメータのマージ

のパラメータdefaultRunSettingは、 inlineSettingsまたは S3 URI を介して提供される実行固有のパラメータとマージされます。キーが重複する場合は、実行固有の値が優先されます。

例:

同じマージ動作が に適用されますrunTags。実行ごとの設定で指定されたタグは、 から同じキーを持つタグを上書きしdefaultRunSetting.runTags、新しいキーが追加されます。

タグマージの例:

段階的な送信

StartRunBatch は共通フィールドを同期的に検証し、バッチ ID とステータス ですぐに を返しますCREATING。バッチの実行は、スループットクォータに従って制御されたレートで段階的かつ非同期的に送信されます。

HealthOmics クォータの完全なリストについては、「」を参照してくださいHealthOmics サービスクォータ。

バッチは、通常の処理中に次の状態に移行します。

バッチの進行状況のモニタリング

バッチステータスの取得

を使用してGetBatch、バッチの全体的なステータスと送信の進行状況を取得します。

aws omics get-batch --batch-id 7123456

レスポンスは以下のとおりです。

レスポンスの例:

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

バッチで実行を一覧表示する

を使用してListRunsInBatch、バッチ内の個々の実行の詳細情報を取得します。結果はページ分割されます。

aws omics list-runs-in-batch --batch-id 7123456

次のいずれかのクエリパラメータを使用して結果をフィルタリングできます。呼び出しごとにサポートされるフィルターは 1 つだけです。

例: 失敗した送信を一覧表示する

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

各結果には以下が含まれます。

バッチを一覧表示する

ListBatch を使用して、アカウント内のすべてのバッチリソースを取得します。結果はページ分割されます。

aws omics list-batch

次のクエリパラメータを使用して結果をフィルタリングできます。

失敗した実行の処理

バッチ処理には 2 つの異なるタイプの障害があります。違いを理解することは、トラブルシューティングに不可欠です。

バッチレベルの障害

バッチレベルの失敗は、バッチ自体が失敗したことを意味します。実行は作成されていません (または、失敗前に作成されたものもあります）。バッチステータスは ですFAILED。

を呼び出しGetBatchて failureReasonフィールドを確認します。一般的な障害の理由は次のとおりです。

例: 検証のためバッチが失敗しました

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

実行レベルの障害

実行レベルの失敗は、バッチ自体が成功した (ステータスは INPROGRESSまたは PROCESSED) が、個々の実行の送信に失敗したことを意味します。バッチは他の実行の処理を続行します。最初の失敗では停止しません。

1. 送信の概要を確認する

aws omics get-batch --batch-id 7123456

「」を参照してくださいsubmissionSummary.failedStartSubmissionCount。これが 0 より大きい場合、一部の実行は送信中に失敗します。

2。失敗した送信を一覧表示する

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

失敗した各エントリには以下が含まれます。

3. 送信失敗の理由

次の表に、個々の実行submissionFailureReasonで に指定できる値を示します。

4。失敗した実行を再送信する

修正された実行設定のみを含む新しいバッチを作成します。同じ を使用しdefaultRunSetting、失敗したrunSettingIdエントリのみを含めます。失敗した実行の再試行メカニズムは組み込まれていないため、新しいバッチを送信する必要があります。

バッチのキャンセル

CancelRunBatch を使用して、進行中のバッチをキャンセルします。キャンセルオペレーション:

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

バッチ実行の削除

DeleteRunBatch バッチ内の個々の実行を削除するには、 を使用します。

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

バッチメタデータの削除

DeleteBatch を使用して、バッチリソースとそれに関連するメタデータを削除します。これは とは別のオペレーションですDeleteRunBatch。

aws omics delete-batch --batch-id 7123456

バッチの EventBridge イベント

HealthOmics は、バッチがステータスを変更するたびにイベントを Amazon EventBridge に送信します。これらのイベントを使用してワークフローを自動化できます。例えば、バッチが完了または失敗したときに通知をトリガーしたり、すべての実行が終了したときにダウンストリームパイプラインを開始したりできます。

バッチイベントは、他の HealthOmics イベントと同じイベントバスとソースを使用します。一般的なセットアップ手順については、「」を参照してくださいでの EventBridge の使用 AWS HealthOmics。

イベントの詳細タイプ

イベント詳細フィールド

バッチイベントの detail オブジェクトには、次のフィールドが含まれます。

イベント例

例: バッチ完了イベント

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

例: バッチ失敗イベント

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

例: バッチ完了の EventBridge ルール

次のイベントパターンは、バッチが終了状態になったときに一致します。

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

制約事項と考慮事項