本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Batch 运行于 HealthOmics
AWS HealthOmics 批量运行允许您在单个 API 请求中提交多次运行。批次中的每个运行都共享一个通用的基本配置，但可以有不同的输入和运行特定的参数。Batch 运行减少了提交开销，并简化了大规模工作流程处理的生命周期管理。
通过批量运行，您可以：
+ 一次**StartRunBatch**调用最多提交 100,000 次运行，共享配置定义一次并应用于所有运行。
+ 对单个样本应用每次运行的参数覆盖，包括名称、输出 URI、参数、优先级和标签。
+ 通过**GetBatch**和跟踪整体批次状态和个人运行提交进度**ListRunsInBatch**。
+ 使用批量取消所有运行**CancelRunBatch**。
+ 使用批量删除所有运行**DeleteRunBatch**。
+ 使用删除批量元数据**DeleteBatch**。
**Topics**
+ [Batch 运行概念](#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)
## Batch 运行概念
+ **Batch** — 一组共享通用配置的工作流程运行，作为具有自己的 Amazon 资源名称 (ARN) 和生命周期状态的单个资源进行管理。
+ **默认运行设置** (`defaultRunSetting`)-批处理中所有运行共享的工作流程参数，例如工作流程 ID、IAM 角色、输出 URI 和常用参数。
+ **Run-specific 设置**（`inlineSettings`或`s3UriSettings`）-覆盖默认运行设置或与默认运行设置合并的 Per-run 配置。每个参赛作品必须包含一个唯一的`runSettingId`。
+ **运行设置 ID** (`runSettingId`)-客户为批次中的每个运行配置提供的必需唯一标识符。提交后，使用**ListRunsInBatch**将每个运行映射`runSettingId`到 HealthOmics-generated `runId`，这样您就可以跟踪哪个运行是根据哪个输入配置创建的。
+ **批处理状态**-批处理操作的总体状态。可能的值：
+ `CREATING`— 正在创建 Batch。
+ `PENDING`— Batch 已创建；正在异步验证运行配置。
+ `SUBMITTING`— 验证已完成；正在提交个人跑步。
+ `INPROGRESS`— 已尝试所有运行提交；运行正在执行。
+ `STOPPING`— 已收到取消请求；正在停止运行。
+ `CANCELLED`— 批次已取消。
+ `PROCESSED`— 所有运行都已达到终止状态（已完成、失败或已取消）。
+ `FAILED`— 在可以创建运行之前，批次本身就失败了。有关详细信息，请参阅 [Batch-level 失败](#batch-level-failures)。
+ `RUNS_DELETING`— 正在删除批次中的运行次数。
+ `RUNS_DELETED`— 批次中的所有运行都已删除。
+ **提交状态**-批次中单个运行的提交结果。可能的值：
+ `SUCCESS`— 运行已成功提交。
+ `FAILED`— 运行提交失败（例如，由于验证错误）。
+ `CANCEL_SUCCESS`— 运行已成功取消。
+ `CANCEL_FAILED`— 取消运行失败。
+ `DELETE_SUCCESS`— Run 已成功删除。
+ `DELETE_FAILED`— 运行删除失败。
## 先决条件
在开始批量运行之前，请确保您已经：
+ 一个活跃的 HealthOmics 私有工作流程。Ready2Run 工作流程不支持批量运行。
+ 一个 IAM 服务角色，具有运行 HealthOmics 工作流程和访问您的 Amazon S3 存储桶的权限。有关更多信息，请参阅 [的服务角色 AWS HealthOmics](permissions-service.md)。
+ Amazon S3 用于存放输入数据和输出结果的位置。
+ Run-specific 每个样本或实验配置的参数。
## 用于批量操作的 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"
}
}
}
]
}
```
**注意**
**StartRunBatch**需要双重授权：`omics:StartRunBatch`批处理资源以及`omics:StartRun`运行、工作流程和运行组资源。必须同时授予这两个权限才能成功完成批处理。
传入的 IAM 服务角色`roleArn`（ HealthOmics 用于执行运行）需要与单个**StartRun**调用相同的权限。有关更多信息，请参阅 [的服务角色 AWS HealthOmics](permissions-service.md)。
### 标记和基于标签的访问控制
Batch 运行支持两个级别的标签：
+ **批处理标签**（**StartRunBatch**请求上的标签）-应用于批处理资源。 Tag-based 对批量标签完全实施访问控制 (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"}`in `defaultRunSetting` → 异步创建期间单独运行被拒绝
## 入门：提交您的第一批
以下示例演示了提交两次运行的小批量、检查进度和查看结果。
**步骤 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-generated`runId`，因此您可以将结果追溯到您的输入样本。
**第 4 步：检查是否提交失败**
```
aws omics list-runs-in-batch --batch-id {{7123456}} --submission-status FAILED
```
如果有任何运行未能提交，则响应将包括`submissionFailureReason`并`submissionFailureMessage`以帮助您诊断问题。
## 开始批量运行
**StartRunBatch**用于通过单个请求提交多次运行。该请求包括：
+ `defaultRunSetting`— 批处理中所有运行的共享配置。
+ `batchRunSettings`— 单独的运行配置，作为以下选项之一提供：
+ `inlineSettings`— 请求正文中直接提供的多达 100 个特定于运行的配置的数组。
+ `s3UriSettings`— 指向包含运行配置的 JSON 文件的 Amazon S3 URI。对于运行次数超过 100 次的批次来说是必需的，并且最多支持 100,000 次运行。
您还可以提供以下字段：
+ `batchName`— 批次的可选人类可读名称。
+ `requestId`— 用于防止重复批量提交的等性标记。
+ `tags`— 要与批处理资源本身关联的标签。
### 使用内联运行配置提交小批量
使用直接在请求正文中提供一系列特定于运行的配置。`inlineSettings`每个参赛作品必须包含唯一的`runSettingId`（必填项）。`runSettingId`是关联结果的关键 — 当你调用时**ListRunsInBatch**，每个条目都会`runSettingId`将你的映射到 HealthOmics-generated`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 文件中，并使用提供 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。如果文件在提交后被修改，则在异步处理期间批处理会失败。
### 响应
成功的请求会返回批次编号和初始状态：
```
{
"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 参考。
| 字段 | Batch-level (`defaultRunSetting`) | Per-run 可配置 (`inlineSettings`) |
| --- | --- | --- |
| workflowId | 是 | 否 |
| workflowType | 是 | 否 |
| workflowVersionName | 是 | 否 |
| workflowOwnerId | 是 | 否 |
| roleArn | 是 | 否 |
| storageCapacity | 是 | 否 |
| storageType | 是 | 否 |
| runGroupId | 是 | 否 |
| logLevel | 是 | 否 |
| cacheBehavior | 是 | 否 |
| cacheId | 是 | 否 |
| retentionMode | 是 | 否 |
| networkingMode | 是 | 否 |
| configurationName | 是 | 否 |
| name | 是 | 是 |
| outputUri | 是 | 是 |
| parameters | 是 | 是（已合并） |
| priority | 支持 | 是 |
| runTags | 是 | 是（已合并） |
| outputBucketOwnerId | 支持 | 是 |
**注意**
不支持`runId`（用于单独重播）字段作为的输入。**StartRunBatch**每次批量提交总是会创建新的运行次数，并且每次运行都将获得一个`runId`。[重跑跑入 HealthOmics](rerun-a-run.md)有关重试单个运行的信息，请参阅。
### 参数合并
中的`defaultRunSetting`参数与 S3 URI 中`inlineSettings`或通过 S3 URI 提供的特定于运行的参数合并。 Run-specific 当键重叠时，值优先。
**示例**：
| 来源 | 参数 |
| --- | --- |
| 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`，并且会添加新的密钥。
**标签合并示例：**
| 来源 | 标签 |
| --- | --- |
| 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"} |
**注意**
Batch-level 标签（根据**StartRunBatch**请求）仅应用于批处理资源本身。它们不是由个人跑步继承的。 Run-level 标签是通过`defaultRunSetting.runTags`和每次运行`runTags`控制的。
### 逐步提交
**StartRunBatch**同步验证常用字段，并立即返回批次 ID 和状态。`CREATING`批量运行将根据您的吞吐量配额以受控的速率逐渐和异步提交。
有关 HealthOmics 配额的完整列表，请参阅[HealthOmics 服务配额](service-quotas.md)。
在正常处理过程中，批处理会进入以下状态：
1. `CREATING`— 正在创建 Batch。
1. `PENDING`— Batch 创建，正在验证运行配置。
1. `SUBMITTING`— 验证已完成，正在提交个人跑步。
1. `INPROGRESS`— 所有已尝试运行提交，运行正在执行。
1. `PROCESSED`— 所有运行都已达到终止状态。
**重要**
Batch run 提交与直接 **StartRun** API 调用共享相同的**StartRun**吞吐量配额。如果您在处理大批量时**StartRun**直接致电，则批量提交和您的直接呼叫都会争夺相同的容量。这可能会导致批处理运行失败`ThrottlingException`（超出速率），或者您的直接**StartRun**呼叫受到限制。这同样适用于**CancelRun**和 **DeleteRun** ——它们**DeleteRunBatch**分别与**CancelRunBatch**和共享吞吐量配额。
## 监控批处理进度
### 获取批次状态
**GetBatch**用于检索批次的总体状态和提交进度。
```
aws omics get-batch --batch-id {{7123456}}
```
响应包括以下内容：
+ `status`— 整体批处理状态。
+ `submissionSummary`— 启动、取消和删除操作的成功和失败提交计数。
+ `runSummary`— 每种执行状态下的运行次数。可能的值：`PENDING``STARTING`、`RUNNING`、、`STOPPING`、`COMPLETED`、`DELETED`、`CANCELLED`、或 `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`状态时，将对最终计数进行核对。
### 列表批量运行
**ListRunsInBatch**用于检索批次中各个运行的详细信息。结果是分页的。
```
aws omics list-runs-in-batch --batch-id {{7123456}}
```
您可以使用以下查询参数之一来筛选结果。每个呼叫仅支持一个过滤器。
| 筛选条件 | 说明 |
| --- | --- |
| submissionStatus | 按提交状态筛选：SUCCESSFAILED、CANCEL\_SUCCESS、CANCEL\_FAILED、DELETE\_SUCCESS、或DELETE\_FAILED。 |
| runSettingId | 检索特定运行设置 ID 的运行结果。 |
| runId | 检索特定运行 ID 的运行结果。 |
**示例：列出失败的提交**
```
aws omics list-runs-in-batch --batch-id {{7123456}} --submission-status FAILED
```
每个结果包括：
+ `runSettingId`— 客户提供的运行配置标识符。
+ `runId`— HealthOmics-generated 运行标识符（如果提交失败则为空）。
+ `runArn`— 跑步的完整 ARN。
+ `submissionStatus`— 提交结果（`SUCCESS`、`FAILED`、`CANCEL_SUCCESS`、`CANCEL_FAILED`、`DELETE_SUCCESS`、或`DELETE_FAILED`）。
+ `submissionFailureReason`和 `submissionFailureMessage` — 提交失败时的详细信息。
**注意**
`runSettingId`是您在运行配置中提供的客户指定的标识符。 `runId`是成功提交后分配的 HealthOmics-generated 标识符。如果提交失败，`runId`则为空。
### 列出批次
**ListBatch**用于检索您账户中的所有批量资源。结果是分页的。
```
aws omics list-batch
```
您可以使用以下查询参数筛选结果：
| 筛选条件 | 说明 |
| --- | --- |
| status | 按批次状态筛选。 |
| name | 按批次名称筛选。 |
| runGroupId | 按运行组 ID 筛选。 |
## 处理失败的运行
批处理中有两种不同的失败类型。了解其中的区别对于故障排除至关重要。
### Batch-level 失败
批次级别的故障意味着批次本身失败——没有创建任何运行（或者在失败之前只创建了一些运行）。批次状态为`FAILED`。
致电**GetBatch**并查看字`failureReason`段。常见的故障原因包括：
| 故障类别 | `failureReason`消息示例 | 处理建议 |
| --- | --- | --- |
| 验证错误 | “Batch 有 100001 次运行，但最大运行次数为 100000 次。 “，“预计 50 次唯一运行SettingIds 但有 49 次”，“运行配置中的 JSON 格式无效” | 修复配置并提交新批次。这些错误不可重试。 |
| S3 配置已更改 | “预计 s3 UriConfigs etag：\\" abc123\\” 但是：\\ “def456\\”。s3 UriConfigs 自调用以来发生了变化” StartRunBatch | 提交后请勿修改 S3 文件。使用当前文件重新提交。 |
| 暂时性服务错误 | “服务中出现了暂时性错误。重试批处理。” | 再次提交相同的批次以重试。对等性使用相同的requestId方法。 |
**示例：由于验证，Batch 失败**
```
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 失败
运行级别失败意味着批次本身已成功（状态为`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 日志、ECR 映像）的权限。 | 否 — 更新角色策略。 |
| ResourceNotFoundException | 引用的资源（工作流、运行组或运行缓存）不存在或未处于活动状态。 | 否 — 验证资源 ID。 |
| ServiceQuotaExceededException | 该账户已达到最大活跃运行次数或其他服务配额。 | 等待运行完成，或申请增加配额。 |
| ConflictException | 正在进行相互冲突的操作，例如，尝试创建重复运行。 | 通常会自行解决。 |
| ThrottlingException | 由于 API 速率限制，该请求受到限制。 | 该服务会自动重试。如果重试后仍然存在，请减少并发的批量提交。 |
| RequestTimeoutException | 请求在处理过程中超时。 | 该服务会自动重试。如果问题仍然存在，请检查是否存在下游问题。 |
| InternalServerException | 发生了意外的服务错误。 | 该服务会自动重试。如果重试后问题仍然存在，请联系 Su AWS pport。 |
**注意**
HealthOmics 每次运行都会自动重试暂时性错误 (`ThrottlingException``RequestTimeoutException`、、`InternalServerException`)。`FAILED`只有在所有重试尝试都用完之后，才会将运行标记为。 Non-retryable 错误 (`ValidationException`,`AccessDeniedException`,`ResourceNotFoundException`) 无需重试即可立即失败。
**4。重新提交失败的运行**
创建一个仅包含更正后的运行配置的新批次。使用相同的方法`defaultRunSetting`并仅包含失败的`runSettingId`条目。对于失败的运行，没有内置的重试机制，您必须提交新的批次。
## 取消批次
**CancelRunBatch**用于取消正在进行的批处理。取消操作：
+ 防止尚未提交和待处理的运行启动
+ 提交已经开始的运行**CancelRun**请求。
```
aws omics cancel-run-batch --batch-id {{7123456}}
```
**重要**
只有处于`PENDING``SUBMITTING`、或`INPROGRESS`状态的批次才允许取消。
一次只能对每个批次执行一次取消或删除操作。
取消操作是非原子操作的，可能会部分成功。**GetBatch**用于查看`successfulCancelSubmissionCount`和`failedCancelSubmissionCount`在`submissionSummary`.
## 删除批量运行
**DeleteRunBatch**用于删除批次中的单个运行。
```
aws omics delete-run-batch --batch-id {{7123456}}
```
**重要**
只有处于`PROCESSED`或`CANCELLED`状态的批次才允许删除。
一次只能对每个批次执行一次取消或删除操作。
删除操作是非原子操作的，可能会部分成功。**GetBatch**用于查看`successfulDeleteSubmissionCount`和`failedDeleteSubmissionCount`在`submissionSummary`.
## 删除批量元数据
用于**DeleteBatch**移除批处理资源及其关联的元数据。这是与之分开的操作**DeleteRunBatch**。
```
aws omics delete-batch --batch-id {{7123456}}
```
**重要**
**DeleteBatch**要求批次处于最终状态（`PROCESSED`、`FAILED``CANCELLED`、或`RUNS_DELETED`）。
**DeleteBatch**不会删除单个游程。如果您还想移除游程，请**DeleteRunBatch**先使用。
**DeleteBatch**完成后，将无法再访问批次元数据。您不能**CancelRunBatch**对已删除的批次调用**GetBatch****ListRunsInBatch****DeleteRunBatch**、、或。
## EventBridge 批处理事件
HealthOmics 每当批次的状态发生变化 EventBridge 时，都会向 Amazon 发送事件。您可以使用这些事件来自动化工作流程，例如，在批处理完成或失败时触发通知，或者在所有运行完成时启动下游管道。
Batch 事件与其他事件使用相同 HealthOmics 的事件总线和源。有关一般设置说明，请参阅[EventBridge 与一起使用 AWS HealthOmics](eventbridge.md)。
### 活动详情类型
| 事件名称 | 何时发出 |
| --- | --- |
| RunBatch 状态变更 | 批处理会过渡到新状态（CREATING、、PENDING、SUBMITTING、INPROGRESS、STOPPING、CANCELLED、PROCESSED、FAILED、RUNS\_DELETING、RUNS\_DELETED） |
### 事件详细信息字段
批处理事件中的`detail`对象包括以下字段：
| 字段 | Type | 说明 |
| --- | --- | --- |
| omicsVersion | 字符串 | 事件架构版本（当前为 1.0.0）。 |
| arn | 字符串 | 批量 ARN。 |
| batchId | 字符串 | 批次标识符。 |
| status | 字符串 | 新的批次状态。 |
| uuid | 字符串 | 批处理 UUID。 |
| batchName | 字符串 | 批次名称（如果提供）。 |
| totalRuns | 字符串 | 批次中的总运行次数。 |
| failureReason | 字符串 | 失败原因（仅在状态为时出现FAILED）。 |
| failureMessage | 字符串 | 详细的失败消息（仅在状态为时显示FAILED）。 |
| successfulStartSubmissionCount | 字符串 | 成功提交的运行次数。 |
| failedStartSubmissionCount | 字符串 | 未能提交的运行次数。 |
| pendingStartSubmissionCount | 字符串 | 仍有待提交的测试次数。 |
| pendingRunCount | 字符串 | 处于待定状态的运行次数。 |
| startingRunCount | 字符串 | 开始运行的次数。 |
| runningRunCount | 字符串 | 当前正在运行的运行次数。 |
| stoppingRunCount | 字符串 | 正在停止的运行次数。 |
| completedRunCount | 字符串 | 已完成的运行次数。 |
| failedRunCount | 字符串 | 失败的运行数量。 |
| cancelledRunCount | 字符串 | 取消的运行次数。 |
| deletedRunCount | 字符串 | 已删除的运行次数。 |
| workflowId | 字符串 | 工作流程标识符。 |
| workflowArn | 字符串 | 工作流程 ARN。 |
| workflowVersionArn | 字符串 | 工作流程版本 ARN（如果适用）。 |
| workflowOwnerId | 字符串 | 工作流程所有者账户 ID（适用于共享工作流程）。 |
| runCache | 字符串 | 运行缓存 ARN（如果适用）。 |
| runCacheBehavior | 字符串 | 运行缓存行为（如果适用）。 |
### 事件示例
**示例：Batch 已完成事件**
```
{
"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"
}
}
```
**示例：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"
}
}
```
**示例：批量完成 EventBridge 规则**
当任何批次达到终止状态时，以下事件模式会匹配：
```
{
"source": ["aws.omics"],
"detail-type": ["RunBatch Status Change"],
"detail": {
"status": ["PROCESSED", "FAILED", "CANCELLED"]
}
}
```
## 限制和注意事项
+ **共享吞吐量配额** — Batch 操作与单个 API 操作共享相同的每账户配额。 **StartRunBatch**消耗**StartRun**服务配额。 **CancelRunBatch**消耗**CancelRun**配额，**DeleteRunBatch**消耗**DeleteRun**配额。避免在大批处理过程中调用单个运行 API，因为这可能会导致提交失败。
+ **逐步提交** — 批量运行将根据您的吞吐量配额逐渐和异步提交。
+ **Non-atomic 操作** — **StartRunBatch** **CancelRunBatch**、、和**DeleteRunBatch**都可以部分成功。请务必查看提交摘要，找出需要重试的运行。
+ **最终一致性**-运行执行状态计数**GetBatch**可能落后于实际运行状态。批次到达后，最终计数是准确`PROCESSED`的。
+ **每个列表调用只有一个过滤器，**ListRunsInBatch**并且每**个 API 调用仅**ListBatch**支持一个过滤器。
+ **Re-run 不支持** — 中不支持`runId`（重新运行）字段。**StartRunBatch**每次批量提交总是会创建新的运行次数。
+ **Ready2Run 工作流程 —** Ready2Run 工作流程不支持批量运行。
+ **内联配置限制**-内联配置 (`inlineSettings`) 最多支持 100 个条目。对于较大的批次，请使用`s3UriSettings`。此限制不可调整。
+ **S3 配置文件**-S3 配置文件必须是运行设置对象的 JSON 数组。最大文件大小为 6 GB，最多支持 100,000 个运行配置。
+ **S3 文件不可变性**-提交批处理后，请勿修改 S3 配置文件。 HealthOmics 在提交过程中验证文件的实体标签 (ETag)，如果文件已更改，则批处理失败。