本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

批次在 HealthOmics 中執行

AWS HealthOmics 批次執行可讓您在單一 API 請求中提交多個執行。批次中的每個執行都會共用共同的基本組態，但可以有不同的輸入和執行特定的參數。批次執行可減少提交開銷，並簡化大規模工作流程處理的生命週期管理。

透過批次執行，您可以：

批次執行概念

先決條件

開始批次執行之前，請確定您有：

批次操作的 IAM 許可

您的 IAM 身分必須具有批次操作和基礎個別執行操作的許可。下列範例政策會授予所有批次操作的許可：

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

標記和標籤型存取控制

批次執行支援兩個層級的標籤：

如果您使用標籤型存取控制政策，請確保您的 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"
        }
      }
    }
  ]
}

使用此政策：

入門：提交您的第一個批次

下列範例會逐步解說提交一小批的兩個執行、檢查進度和檢閱結果。

步驟 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

從 CREATING → PENDING → SUBMITTING → INPROGRESS → 觀看status欄位進度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

如果有任何執行無法提交，回應會包含 submissionFailureReason和 submissionFailureMessage ，以協助您診斷問題。

啟動批次執行

使用 StartRunBatch 以單一請求提交多個執行。請求包括：

您也可以提供下列欄位：

使用內嵌執行組態提交小批次

使用 在請求內文中直接提供執行特定的組態陣列inlineSettings。每個項目都必須包含唯一的 runSettingId（必要）。runSettingId 是關聯結果的金鑰 - 當您呼叫 時ListRunsInBatch，每個項目都會將 映射runSettingId至 HealthOmics 產生的 runId和 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 檔案中，並使用 提供 URIs3UriSettings。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

您可以使用下列其中一個查詢參數來篩選結果。每個呼叫僅支援一個篩選條件。

範例：列出失敗的提交

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

每個結果包括：

列出批次

使用 ListBatch擷取您帳戶中的所有批次資源。結果會分頁。

aws omics list-batch

您可以使用下列查詢參數來篩選結果：

處理失敗的執行

批次處理中有兩種不同的失敗類型。了解差異對於故障診斷至關重要。

批次層級失敗

批次層級失敗表示批次本身失敗 - 未建立執行 （或僅在失敗之前建立部分執行）。批次狀態為 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。如果大於零，有些執行會在提交期間失敗。

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

限制及考量