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

# 批次在 HealthOmics 中執行
<a name="workflows-batch"></a>

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

透過批次執行，您可以：
+ 在單一**StartRunBatch**呼叫中提交最多 100，000 個執行，並定義一次共用組態並套用至所有執行。
+ 套用個別範例的每次執行參數覆寫，包括名稱、輸出 URI、參數、優先順序和標籤。
+ 透過 和 追蹤整體批次狀態**GetBatch**和個別執行提交進度**ListRunsInBatch**。
+ 使用 取消批次中的所有執行**CancelRunBatch**。
+ 使用 刪除批次中的所有執行**DeleteRunBatch**。
+ 使用 刪除批次中繼資料**DeleteBatch**。

**Topics**
+ [批次執行概念](#batch-concepts)
+ [先決條件](#batch-prerequisites)
+ [批次操作的 IAM 許可](#batch-iam-permissions)
+ [入門：提交您的第一個批次](#batch-getting-started)
+ [啟動批次執行](#batch-starting)
+ [監控批次進度](#batch-monitoring)
+ [處理失敗的執行](#batch-handling-failures)
+ [取消批次](#batch-canceling)
+ [刪除批次執行](#batch-deleting-runs)
+ [刪除批次中繼資料](#batch-deleting-metadata)
+ [批次的 EventBridge 事件](#batch-eventbridge)
+ [限制及考量](#batch-limitations)

## 批次執行概念
<a name="batch-concepts"></a>
+ **批次** — 共用常見組態的工作流程執行集合，以具有自己的 Amazon Resource Name (ARN) 和生命週期狀態的單一資源進行管理。
+ **預設執行設定** (`defaultRunSetting`) — 批次中所有執行共用的工作流程參數，例如工作流程 ID、IAM 角色、輸出 URI 和常見參數。
+ **執行特定設定** (`inlineSettings` 或 `s3UriSettings`) — 覆寫或與預設執行設定合併的每次執行組態。每個項目必須包含唯一的 `runSettingId`。
+ **執行設定 ID** (`runSettingId`) — 批次內每個執行組態的必要、客戶提供的唯一識別符。提交後，使用 **ListRunsInBatch** 將每個 對應`runSettingId`至 HealthOmics 產生的 `runId`，讓您可以追蹤從哪個輸入組態建立的 執行。
+ **批次狀態** — 批次操作的整體狀態。可能的值如下：
  + `CREATING` — 正在建立批次。
  + `PENDING` — 已建立批次；正在非同步驗證執行組態。
  + `SUBMITTING` — 驗證完成；正在提交個別執行。
  + `INPROGRESS` — 已嘗試所有執行提交；正在執行執行。
  + `STOPPING` — 已收到取消請求；正在停止執行。
  + `CANCELLED` — 批次已取消。
  + `PROCESSED` — 所有執行都已達到結束狀態 （已完成、失敗或取消）。
  + `FAILED` — 批次本身在建立執行之前失敗。如需詳細資訊，請參閱 [批次層級失敗](#batch-level-failures)。
  + `RUNS_DELETING` — 正在刪除批次中的執行。
  + `RUNS_DELETED` — 批次中的所有執行都已刪除。
+ **提交狀態** — 批次中個別執行的提交結果。可能的值如下：
  + `SUCCESS` — 執行已成功提交。
  + `FAILED` — 執行提交失敗 （例如，由於驗證錯誤）。
  + `CANCEL_SUCCESS` — 執行已成功取消。
  + `CANCEL_FAILED` — 執行取消失敗。
  + `DELETE_SUCCESS` — 執行已成功刪除。
  + `DELETE_FAILED` — 執行刪除失敗。

## 先決條件
<a name="batch-prerequisites"></a>

開始批次執行之前，請確定您有：
+ 作用中的 HealthOmics 私有工作流程。Ready2Run 工作流程不支援批次執行。
+ IAM 服務角色，具有執行 HealthOmics 工作流程和存取 Amazon S3 儲存貯體的許可。如需詳細資訊，請參閱[的服務角色 AWS HealthOmics](permissions-service.md)。
+ 輸入資料和輸出結果的 Amazon S3 位置。
+ 每個範例或實驗組態的執行特定參數。

## 批次操作的 IAM 許可
<a name="batch-iam-permissions"></a>

您的 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"
        }
      }
    }
  ]
}
```

**注意**  
**StartRunBatch** 需要雙重授權：`omics:StartRunBatch`在批次資源上，以及在執行、工作流程和執行群組資源`omics:StartRun`上。必須授予這兩個許可，批次才能成功。

傳入的 IAM 服務角色 `roleArn`（由 HealthOmics 用來執行執行） 需要與個別**StartRun**呼叫相同的許可。如需詳細資訊，請參閱[的服務角色 AWS HealthOmics](permissions-service.md)。

### 標記和標籤型存取控制
<a name="batch-tagging"></a>

批次執行支援兩個層級的標籤：
+ **批次標籤** (**StartRunBatch**請求上的標籤） — 套用至批次資源。批次標籤完全強制執行標籤型存取控制 (TBAC)。
+ **執行標籤** (`runTags` 中的 `defaultRunSetting`和每次執行 `runTags`) — 套用至個別執行資源。這些標籤會使用與參數相同的優先順序規則合併。

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

使用此政策：
+ `tags: {"environment": "dev"}` 批次 → 允許
+ `tags: {"environment": "production"}` 批次 → 已拒絕 (403)
+ `runTags: {"environment": "production"}` 在 `defaultRunSetting` → 拒絕非同步建立期間的個別執行

## 入門：提交您的第一個批次
<a name="batch-getting-started"></a>

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

**步驟 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` ，以協助您診斷問題。

## 啟動批次執行
<a name="batch-starting"></a>

使用 **StartRunBatch** 以單一請求提交多個執行。請求包括：
+ `defaultRunSetting` — 批次中所有執行的共用組態。
+ `batchRunSettings` — 個別執行組態，以下列其中一種方式提供：
  + `inlineSettings` — 最多 100 個執行特定的組態陣列，直接在請求內文中提供。
  + `s3UriSettings` — 指向包含執行組態的 JSON 檔案的 Amazon S3 URI。超過 100 個執行的批次需要，並支援最多 100，000 個執行。

您也可以提供下列欄位：
+ `batchName` — 批次的選用人類可讀名稱。
+ `requestId` — 防止重複批次提交的等冪字符。
+ `tags` — 要與批次資源本身建立關聯的標籤。

### 使用內嵌執行組態提交小批次
<a name="batch-inline-settings"></a>

使用 在請求內文中直接提供執行特定的組態陣列`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 中使用執行組態提交大型批次
<a name="batch-s3-settings"></a>

對於執行次數超過 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"}'
```

**重要**  
在 中指定的 IAM 服務角色`roleArn`必須具有在 中指定的 Amazon S3 物件的讀取存取權`s3UriSettings`。HealthOmics 會在同步 API 呼叫期間驗證對 Amazon S3 檔案的存取，並記錄檔案的 ETag。如果在提交後修改檔案，批次會在非同步處理期間失敗。

### 回應
<a name="batch-response"></a>

成功的請求會傳回批次 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 會在提交任何執行之前傳回錯誤。

### 參數參考
<a name="batch-parameter-reference"></a>

下表顯示每個執行可以設定哪些**StartRun**欄位，以及哪些欄位僅適用於批次層級。如需完整的欄位描述，請參閱 **StartRun** API 參考。


| 欄位 | 批次層級 (`defaultRunSetting`) | 每次執行可設定 (`inlineSettings`) | 
| --- | --- | --- | 
| workflowId | 是 | 否 | 
| workflowType | 是 | 否 | 
| workflowVersionName | 是 | 否 | 
| workflowOwnerId | 是 | 否 | 
| roleArn | 是 | 否 | 
| storageCapacity | 是 | 否 | 
| storageType | 是 | 否 | 
| runGroupId | 是 | 否 | 
| logLevel | 是 | 否 | 
| cacheBehavior | 是 | 否 | 
| cacheId | 是 | 否 | 
| retentionMode | 是 | 否 | 
| name | 是 | 是 | 
| outputUri | 是 | 是 | 
| parameters | 是 | 是 （合併） | 
| priority | 是 | 是 | 
| runTags | 是 | 是 （合併） | 
| outputBucketOwnerId | 是 | 是 | 

**注意**  
`runId` （針對個別重新執行） 欄位不支援做為 的輸入**StartRunBatch**。每個批次提交一律會建立新的執行，而且每次執行都會收到 `runId`。如需重試個別執行[在 HealthOmics 中重新執行執行](rerun-a-run.md)，請參閱 。

### 參數合併
<a name="batch-parameter-merging"></a>

的參數`defaultRunSetting`會與在 `inlineSettings`中或透過 S3 URI 提供的執行特定參數合併。當索引鍵重疊時，以執行特定值為優先。

**範例**：


| 來源 | Parameters | 
| --- | --- | 
| defaultRunSetting | {"referenceUri": "s3://bucket/ref.fasta", "version": "v1"} | 
| inlineSettings 項目 | {"inputUri": "s3://bucket/sample.fastq", "version": "v2"} | 
| 合併的結果 | {"referenceUri": "s3://bucket/ref.fasta", "inputUri": "s3://bucket/sample.fastq", "version": "v2"} | 

相同的合併行為適用於 `runTags`。每個執行組態中指定的標籤會使用來自 的相同金鑰覆寫標籤`defaultRunSetting.runTags`，並新增新的金鑰。

**標籤合併範例：**


| 來源 | Tags (標籤) | 
| --- | --- | 
| defaultRunSetting.runTags | {"project": "cancer-research", "pipeline-version": "v2.1"} | 
| inlineSettings[].runTags | {"patient-id": "patient001", "pipeline-version": "v3.0"} | 
| 合併結果 （套用至執行） | {"project": "cancer-research", "patient-id": "patient001", "pipeline-version": "v3.0"} | 

**注意**  
批次層級標籤 （在**StartRunBatch**請求上） 只會套用至批次資源本身。它們不會被個別執行繼承。執行層級標籤是透過 `defaultRunSetting.runTags`和每次執行 控制`runTags`。

### 逐步提交
<a name="batch-gradual-submission"></a>

**StartRunBatch** 會同步驗證常見欄位，並立即傳回批次 ID 和狀態 `CREATING`。批次中的執行會根據您的輸送量配額，以受控速率逐漸並以非同步方式提交。

如需 HealthOmics 配額的完整清單，請參閱 [HealthOmics 服務配額](service-quotas.md)。

批次會在正常處理期間轉換下列狀態：

1. `CREATING` — 正在建立批次。

1. `PENDING` — 批次建立，執行正在驗證的組態。

1. `SUBMITTING` — 驗證完成，正在提交個別執行。

1. `INPROGRESS` — 嘗試的所有執行提交，執行正在執行。

1. `PROCESSED` — 所有執行都已達到結束狀態。

**重要**  
批次執行提交與直接 **StartRun** API 呼叫共用相同的**StartRun**輸送量配額。如果您在處理大型批次時**StartRun**直接呼叫 ，批次提交和直接呼叫都會爭用相同的容量。這可能會導致批次執行因 `ThrottlingException`（超過速率） 而失敗，或您的直接**StartRun**呼叫受到調節。同樣適用於 **CancelRun**和 **DeleteRun** — 這些**DeleteRunBatch**分別與 **CancelRunBatch**和 共用輸送量配額。

## 監控批次進度
<a name="batch-monitoring"></a>

### 取得批次狀態
<a name="batch-get-status"></a>

使用 **GetBatch** 擷取批次的整體狀態和提交進度。

```
aws omics get-batch --batch-id {{7123456}}
```

回應包括：
+ `status` — 整體批次狀態。
+ `submissionSummary` — 開始、取消和刪除操作的成功和失敗提交計數。
+ `runSummary` — 每個執行狀態中的執行計數。可能的值：`PENDING`、`STARTING`、`RUNNING`、`STOPPING`、`COMPLETED`、`CANCELLED`、 `DELETED`或 `FAILED`
+ 生命週期事件的時間戳記 — `creationTime`、`submittedTime`、`processedTime`、`failedTime`。

**回應範例：**

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

**注意**  
執行執行摘要最終一致，且可能會落後於實際執行狀態。當批次達到`PROCESSED`狀態時，會核對最終計數。

### 清單以批次執行
<a name="batch-list-runs"></a>

使用 **ListRunsInBatch** 擷取批次中個別執行的詳細資訊。結果會分頁。

```
aws omics list-runs-in-batch --batch-id {{7123456}}
```

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


| 篩選條件 | Description | 
| --- | --- | 
| submissionStatus | 依提交狀態篩選：SUCCESS、FAILED、CANCEL\_SUCCESS、DELETE\_SUCCESS、 CANCEL\_FAILED或 DELETE\_FAILED。 | 
| runSettingId | 擷取特定執行設定 ID 的執行。 | 
| runId | 擷取特定執行 ID 的執行。 | 

**範例：列出失敗的提交**

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

每個結果包括：
+ `runSettingId` — 客戶提供的執行組態識別符。
+ `runId` — HealthOmics 產生的執行識別符 （如果提交失敗，則為空白）。
+ `runArn` — 執行的完整 ARN。
+ `submissionStatus` — 提交結果 (`SUCCESS`、`FAILED`、`CANCEL_SUCCESS``CANCEL_FAILED`、`DELETE_SUCCESS`、 或 `DELETE_FAILED`)。
+ `submissionFailureReason` 和 `submissionFailureMessage` — 提交失敗時的詳細資訊。

**注意**  
`runSettingId` 是您在執行組態中提供的客戶指定識別符。 `runId`是成功提交後指派的 HealthOmics 產生的識別符。如果提交失敗，則 `runId` 為空白。

### 列出批次
<a name="batch-list-batches"></a>

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

```
aws omics list-batch
```

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


| 篩選條件 | Description | 
| --- | --- | 
| status | 依批次狀態篩選。 | 
| name | 依批次名稱篩選。 | 
| runGroupId | 依執行群組 ID 篩選。 | 

## 處理失敗的執行
<a name="batch-handling-failures"></a>

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

### 批次層級失敗
<a name="batch-level-failures"></a>

批次層級失敗表示批次本身失敗 - 未建立執行 （或僅在失敗之前建立部分執行）。批次狀態為 `FAILED`。

呼叫 **GetBatch**並檢查 `failureReason` 欄位。常見的失敗原因包括：


| 失敗類別 | 訊息範例 `failureReason`  | Action | 
| --- | --- | --- | 
| 驗證錯誤 | 「批次有 100001 個執行，但 100000 個執行是最大值」、「預期 50 個唯一的 runSettingIds，但有 49 個」、「執行組態中的 JSON 格式無效」 | 修正組態並提交新的批次。這些錯誤無法重試。 | 
| S3 組態已變更 | 「預期的 s3UriConfigs etag：\\"abc123\\" 但為：\\"def456\\"。 s3UriConfigs 自呼叫 StartRunBatch 以來已變更」 | 請勿在提交後修改 S3 檔案。使用目前的檔案重新提交。 | 
| 暫時性服務錯誤 | 「服務中發生暫時性錯誤。重試批次。」 | 再次提交相同的批次以重試。requestId 對冪等性使用相同的 。 | 

**範例：批次因驗證而失敗**

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

### 執行層級失敗
<a name="batch-run-level-failures"></a>

執行層級失敗表示批次本身成功 （狀態為 `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
```

每個失敗的項目包括：
+ `runSettingId` — 哪些執行組態失敗。
+ `submissionFailureReason` — 錯誤類別。
+ `submissionFailureMessage` — 詳細的錯誤訊息。

**3. 提交失敗原因**

下表列出個別執行`submissionFailureReason`時 的可能值：


| `submissionFailureReason` | 意義 | 可重試？ | 
| --- | --- | --- | 
| ValidationException | 執行參數無效 — 例如，參數不符合工作流程定義、無效的 S3 URI 格式或限制違規。 | 否 — 修正組態。 | 
| AccessDeniedException | IAM 服務角色缺少存取必要資源的許可 (S3 輸入、KMS 金鑰、CloudWatch Logs、ECR 映像）。 | 否 — 更新角色政策。 | 
| ResourceNotFoundException | 參考的資源 （工作流程、執行群組或執行快取） 不存在或處於作用中狀態。 | 否 — 驗證資源 IDs。 | 
| ServiceQuotaExceededException | 帳戶已達到作用中執行的數目上限或其他服務配額。 | 等待執行完成，或請求提高配額。 | 
| ConflictException | 衝突操作正在進行中，例如，重複的執行建立嘗試。 | 通常會自行解析。 | 
| ThrottlingException | 由於 API 速率限制，請求已調節。 | 服務會自動重試。如果重試後仍存在，請減少並行批次提交。 | 
| RequestTimeoutException | 請求在處理期間逾時。 | 服務會自動重試。如果持續存在，請檢查是否有下游問題。 | 
| InternalServerException | 發生非預期的服務錯誤。 | 服務會自動重試。如果重試後仍存在，請聯絡 AWS Support。 | 

**注意**  
HealthOmics 會在每次執行時自動重試暫時性錯誤 (`ThrottlingException`、`RequestTimeoutException`、`InternalServerException`)。`FAILED` 只有在所有重試嘗試都用盡之後，才會將執行標記為 。無法重試的錯誤 (`ValidationException`、`AccessDeniedException`、`ResourceNotFoundException`) 會立即失敗，無需重試。

**4. 重新提交失敗的執行**

建立新的批次，只包含更正後的執行組態。使用相同的 `defaultRunSetting`，並僅包含失敗`runSettingId`的項目。執行失敗時沒有內建的重試機制，您必須提交新的批次。

## 取消批次
<a name="batch-canceling"></a>

使用 **CancelRunBatch**取消進行中的批次。取消操作：
+ 防止not-yet-submitted和待定的執行開始
+ 提交已啟動之執行的**CancelRun**請求。

```
aws omics cancel-run-batch --batch-id {{7123456}}
```

**重要**  
只有處於 `PENDING`、 `SUBMITTING`或 `INPROGRESS` 狀態的批次才允許取消。
每個批次一次只允許一個取消或刪除操作。
取消操作是非原子操作，可能部分成功。使用 **GetBatch** 在 `failedCancelSubmissionCount`中檢閱 `successfulCancelSubmissionCount`和 `submissionSummary`。

## 刪除批次執行
<a name="batch-deleting-runs"></a>

使用 **DeleteRunBatch**刪除批次中的個別執行。

```
aws omics delete-run-batch --batch-id {{7123456}}
```

**重要**  
只有處於 `PROCESSED`或 `CANCELLED` 狀態的批次才允許刪除。
每個批次一次只允許一個取消或刪除操作。
刪除操作是非原子操作，可能部分成功。使用 **GetBatch** 在 `failedDeleteSubmissionCount`中檢閱 `successfulDeleteSubmissionCount`和 `submissionSummary`。

## 刪除批次中繼資料
<a name="batch-deleting-metadata"></a>

使用 **DeleteBatch**移除批次資源及其相關聯的中繼資料。這是與 不同的操作**DeleteRunBatch**。

```
aws omics delete-batch --batch-id {{7123456}}
```

**重要**  
**DeleteBatch** 要求批次處於終端狀態 (`PROCESSED`、`CANCELLED`、 `FAILED`或 `RUNS_DELETED`)。
**DeleteBatch** 不會刪除個別執行。如果您想要一併移除執行，**DeleteRunBatch**請先使用 。
**DeleteBatch** 完成後，即無法再存取批次中繼資料。您無法在已刪除的批次**CancelRunBatch**上呼叫 **GetBatch****ListRunsInBatch**、**DeleteRunBatch**、 或 。

## 批次的 EventBridge 事件
<a name="batch-eventbridge"></a>

HealthOmics 會在批次變更狀態時，將事件傳送至 Amazon EventBridge。您可以使用這些事件來自動化工作流程，例如，在批次完成或失敗時觸發通知，或在所有執行完成時啟動下游管道。

批次事件使用與其他 HealthOmics 事件相同的事件匯流排和來源。如需一般設定說明，請參閱 [搭配 使用 EventBridge AWS HealthOmics](eventbridge.md)。

### 事件詳細資訊類型
<a name="batch-event-detail-type"></a>


| 事件名稱 | 在 時發出 | 
| --- | --- | 
| RunBatch 狀態變更 | 批次會轉換為新狀態 (CREATING、PENDING、SUBMITTING、INPROGRESSSTOPPING、CANCELLED、PROCESSED、FAILED、RUNS\_DELETING、) RUNS\_DELETED | 

### 事件詳細資訊欄位
<a name="batch-event-detail-fields"></a>

批次事件中的`detail`物件包含下列欄位：


| 欄位 | Type | Description | 
| --- | --- | --- | 
| omicsVersion | String | 事件結構描述版本 （目前為 1.0.0)。 | 
| arn | String | 批次 ARN。 | 
| batchId | String | 批次識別符。 | 
| status | String | 新的批次狀態。 | 
| uuid | String | 批次 UUID。 | 
| batchName | String | 批次名稱 （如果提供）。 | 
| totalRuns | String | 批次中的執行總數。 | 
| failureReason | String | 失敗原因 （僅在狀態為 時顯示FAILED)。 | 
| failureMessage | String | 詳細的失敗訊息 （僅在狀態為 時顯示FAILED)。 | 
| successfulStartSubmissionCount | String | 成功提交的執行次數。 | 
| failedStartSubmissionCount | String | 無法提交的執行次數。 | 
| pendingStartSubmissionCount | String | 仍在等待提交的執行數量。 | 
| pendingRunCount | String | 處於待定狀態的執行次數。 | 
| startingRunCount | String | 開始的執行次數。 | 
| runningRunCount | String | 目前正在執行的執行次數。 | 
| stoppingRunCount | String | 正在停止的執行數目。 | 
| completedRunCount | String | 已完成的執行次數。 | 
| failedRunCount | String | 失敗的運行數量。 | 
| cancelledRunCount | String | 已取消的執行次數。 | 
| deletedRunCount | String | 已刪除的執行次數。 | 
| workflowId | String | 工作流程識別符。 | 
| workflowArn | String | 工作流程 ARN。 | 
| workflowVersionArn | String | 工作流程版本 ARN （如適用）。 | 
| workflowOwnerId | String | 工作流程擁有者帳戶 ID （適用於共用工作流程）。 | 
| runCache | String | 執行快取 ARN （如適用）。 | 
| runCacheBehavior | String | 執行快取行為 （如適用）。 | 

### 事件範例
<a name="batch-event-examples"></a>

**範例：批次完成的事件**

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

## 限制及考量
<a name="batch-limitations"></a>
+ **共用輸送量配額** — 批次操作與個別 API 對等項目共用相同的每個帳戶配額。 會**StartRunBatch**消耗**StartRun**服務配額。 **CancelRun** 會**CancelRunBatch**消耗配額，並**DeleteRunBatch**消耗**DeleteRun**配額。避免在進行大型批次時呼叫個別執行 APIs，因為這可能會導致提交失敗。
+ **逐步提交** — 批次中的執行會根據您的輸送量配額逐步和非同步提交。
+ **非原子操作** — **StartRunBatch**、 **CancelRunBatch**和 **DeleteRunBatch** 都可以部分成功。一律檢查提交摘要，以識別需要重試的執行。
+ **最終一致性** — 中的執行執行狀態計數**GetBatch**可能會落後於實際執行狀態。一旦批次達到 ，最終計數就會準確`PROCESSED`。
+ **每個清單呼叫的單一篩選條件** — **ListRunsInBatch**每個 API 呼叫僅**ListBatch**支援一個篩選條件。
+ **不支援重新執行** — 不支援 `runId`（重新執行） 欄位**StartRunBatch**。每個批次提交一律會建立新的執行。
+ **Ready2Run 工作流程** — Ready2Run 工作流程不支援批次執行。
+ **內嵌組態限制** — 內嵌組態 (`inlineSettings`) 最多支援 100 個項目。對於較大的批次，請使用 `s3UriSettings`。此限制不可調整。
+ **S3 組態檔案** — S3 組態檔案必須是執行設定物件的 JSON 陣列。檔案大小上限為 6 GB，最多可支援 100，000 個執行組態。
+ **S3 檔案不可變性** — 提交批次後請勿修改 S3 組態檔案。HealthOmics 會在提交期間驗證檔案的實體標籤 (ETag)，並在檔案變更時使批次失敗。