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

批量运行于 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-generatedrunId，这样您就可以将结果追溯到输入样本。

第 4 步：检查提交失败

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

如果有任何运行未能提交，则响应中会包含submissionFailureReason和submissionFailureMessage以帮助您诊断问题。

开始批量运行

StartRunBatch用于通过单个请求提交多次运行。该请求包括：

您还可以提供以下字段：

使用内联运行配置提交小批量

使用直接在请求正文中提供一系列特定于运行的配置。inlineSettings每个条目必须包含一个唯一的runSettingId（必填项）。runSettingId这是关联结果的关键——当你打电话时ListRunsInBatch，每个条目都会runSettingId将你映射到 HealthOmics-generatedrunId和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参数与 S3 URI 中inlineSettings或通过 S3 URI 提供的特定运行参数合并。 Run-specific 当键重叠时，值优先。

示例：

同样的合并行为适用于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

您可以使用以下查询参数筛选结果：

启用运行指标

运行指标报告批量运行的近乎实时的资源利用率。要启用运行指标，您用于批处理的服务角色必须具有cloudwatch:PutMetricData权限。有关更多信息，请参阅 运行私有工作流程的指标。

向您用于批处理的服务角色添加以下权限。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudwatch:PutMetricData",
      "Resource": "*"
    }
  ]
}

处理失败的运行

批处理中有两种不同类型的故障。了解差异对于故障排除至关重要。

Batch-level 失败

批次级故障意味着批次本身失败——未创建任何运行（或者在失败之前只创建了部分运行）。批次状态为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"
}

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

每个失败的条目都包括：

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 时，都会向亚马逊发送事件。您可以使用这些事件来自动化工作流程，例如，在批处理完成或失败时触发通知，或在所有运行完成时启动下游管道。

批处理事件使用与其他事件相同的事 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"]
  }
}

限制和注意事项