本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Batch 运行于 HealthOmics

AWS HealthOmics 批量运行允许您在单个 API 请求中提交多次运行。批次中的每个运行都共享一个通用的基本配置，但可以有不同的输入和运行特定的参数。Batch 运行可减少提交开销，并简化大规模工作流程处理的生命周期管理。

通过批量运行，您可以：

Batch 运行概念

先决条件

在开始批量运行之前，请确保您已经：

用于批量操作的 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。

标记和基于标签的访问控制

Batch 运行支持两个级别的标签：

如果您使用基于标签的访问控制策略，请确保您的 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 文件中，并使用提供 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": "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参数与 S3 URI 中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段。常见的故障原因包括：

示例：由于验证，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"
}

运行级故障

运行级别失败意味着批次本身已成功（状态为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 每当批次的状态发生变化 EventBridge 时，都会向 Amazon 发送事件。您可以使用这些事件来自动化工作流程，例如，在批处理完成或失败时触发通知，或者在所有运行完成时启动下游管道。

Batch 事件与其他事件使用相同 HealthOmics 的事件总线和源。有关一般设置说明，请参阅EventBridge 与一起使用 AWS HealthOmics。

活动详情类型

事件详细信息字段

批处理事件中的detail对象包括以下字段：

事件示例

示例：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"]
  }
}

限制和注意事项