AWS CLI `codebuild batch-get-build-batches` 命令详解：批量查询 CodeBuild 构建批次状态与运行细节

AWS CLIcodebuild batch-get-build-batches命令详解：批量查询 CodeBuild 构建批次状态与运行细节

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli

导读

aws codebuild batch-get-build-batches是 AWS CLI 提供的批量查询接口，用于按 ID 同时获取一个或多个 AWS CodeBuild 构建批次（batch build）的完整信息，包括当前阶段、状态、源码版本、构建组（build group）拓扑及每个子构建的概要。本文基于 batch-get-build-batches.rst 示例文档，结合 service-2.json 中 CodeBuild 服务的 API 模型，带你掌握该命令的用法、输出字段含义与底层数据结构，从而能够独立完成构建批次的批量状态核查与问题定位。

一、命令概览：batch-get-build-batches 能做什么

CodeBuild 的批量构建（batch build）机制允许一次提交同时在多个构建组（build group）上运行构建，适用于需要并行编译、分阶段依赖执行的复杂构建流水线。batch-get-build-batches正是用来“按 ID 批量拉取这些构建批次详情”的查询命令。

在 service-2.json 的 API 模型定义中，该操作描述为 "Retrieves information about one or more batch builds"，其 HTTP 调用方式为POST /（JSON 协议，目标前缀CodeBuild_20161006）。它面向的典型场景包括：

• CI/CD 流水线结束后批量确认各批次是否成功；
• 针对失败的批次，检查其阶段（phase）时间线与上下文信息以定位问题；
• 分析构建组之间的依赖关系与实际执行时间。

与之相对的，aws codebuild batch-get-builds用于查询普通（非批次）构建，示例见 batch-get-builds.rst。

二、命令用法与参数详解

基本命令示例

原文示例（来源：batch-get-build-batches.rst）：

aws codebuild batch-get-build-batches \ --ids codebuild-demo-project:e9c4f4df-3f43-41d2-ab3a-60fe2EXAMPLE

--ids参数

这是该命令唯一且必填的参数。根据 service-2.json 中BatchGetBuildBatchesInput的定义，ids被标记为required，类型为BuildBatchIds：

• 单个 ID 的格式为项目名:批次ID，如codebuild-demo-project:e9c4f4df-3f43-41d2-ab3a-60fe2EXAMPLE；
• BuildBatchIds是一个字符串列表，约束为min: 0、max: 100（见 service-2.json），即一次最多可传入 100 个批次 ID；
• 传入多个 ID 时，在命令行中重复使用--ids并追加值即可，例如：

aws codebuild batch-get-build-batches \ --ids codebuild-demo-project:e9c4f4df-3f43-41d2-ab3a-60fe2EXAMPLE \ codebuild-demo-project:a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d

输出结构

根据BatchGetBuildBatchesOutput（service-2.json），响应包含两个顶层字段：

请求中的 ID 只会落在其中一个字段中，两列表互斥且合起来覆盖全部请求 ID。

三、完整输出解析：一次构建批次的生命周期快照

以下是执行上述示例命令后返回的完整 JSON 输出（继承自原文档），它完整展示了一个已成功构建批次的所有维度：

{ "buildBatches": [ { "id": "codebuild-demo-project:e9c4f4df-3f43-41d2-ab3a-60fe2EXAMPLE", "arn": "arn:aws:codebuild:us-west-2:123456789012:build-batch/codebuild-demo-project:e9c4f4df-3f43-41d2-ab3a-60fe2EXAMPLE", "startTime": "2020-11-03T21:52:20.775000+00:00", "endTime": "2020-11-03T21:56:59.784000+00:00", "currentPhase": "SUCCEEDED", "buildBatchStatus": "SUCCEEDED", "resolvedSourceVersion": "0a6546f68309560d08a310daac92314c4d378f6b", "projectName": "codebuild-demo-project", "phases": [ { "phaseType": "SUBMITTED", "phaseStatus": "SUCCEEDED", "startTime": "2020-11-03T21:52:20.775000+00:00", "endTime": "2020-11-03T21:52:20.976000+00:00", "durationInSeconds": 0 }, { "phaseType": "DOWNLOAD_BATCHSPEC", "phaseStatus": "SUCCEEDED", "startTime": "2020-11-03T21:52:20.976000+00:00", "endTime": "2020-11-03T21:52:57.401000+00:00", "durationInSeconds": 36 }, { "phaseType": "IN_PROGRESS", "phaseStatus": "SUCCEEDED", "startTime": "2020-11-03T21:52:57.401000+00:00", "endTime": "2020-11-03T21:56:59.751000+00:00", "durationInSeconds": 242 }, { "phaseType": "COMBINE_ARTIFACTS", "phaseStatus": "SUCCEEDED", "startTime": "2020-11-03T21:56:59.751000+00:00", "endTime": "2020-11-03T21:56:59.784000+00:00", "durationInSeconds": 0 }, { "phaseType": "SUCCEEDED", "startTime": "2020-11-03T21:56:59.784000+00:00" } ], "source": { "type": "GITHUB", "location": "https://github.com/my-repo/codebuild-demo-project.git", "gitCloneDepth": 1, "gitSubmodulesConfig": { "fetchSubmodules": false }, "reportBuildStatus": false, "insecureSsl": false }, "secondarySources": [], "secondarySourceVersions": [], "artifacts": { "location": "" }, "secondaryArtifacts": [], "cache": { "type": "NO_CACHE" }, "environment": { "type": "LINUX_CONTAINER", "image": "aws/codebuild/amazonlinux2-x86_64-standard:3.0", "computeType": "BUILD_GENERAL1_SMALL", "environmentVariables": [], "privilegedMode": false, "imagePullCredentialsType": "CODEBUILD" }, "logConfig": { "cloudWatchLogs": { "status": "ENABLED" }, "s3Logs": { "status": "DISABLED", "encryptionDisabled": false } }, "buildTimeoutInMinutes": 60, "queuedTimeoutInMinutes": 480, "complete": true, "initiator": "Strohm", "encryptionKey": "arn:aws:kms:us-west-2:123456789012:alias/aws/s3", "buildBatchNumber": 6, "buildBatchConfig": { "serviceRole": "arn:aws:iam::123456789012:role/service-role/codebuild-demo-project", "restrictions": { "maximumBuildsAllowed": 100 }, "timeoutInMins": 480 }, "buildGroups": [ { "identifier": "DOWNLOAD_SOURCE", "ignoreFailure": false, "currentBuildSummary": { "arn": "arn:aws:codebuild:us-west-2:123456789012:build/codebuild-demo-project:379737d8-bc35-48ec-97fd-776d27545315", "requestedOn": "2020-11-03T21:52:21.394000+00:00", "buildStatus": "SUCCEEDED", "primaryArtifact": { "type": "no_artifacts", "identifier": "DOWNLOAD_SOURCE" }, "secondaryArtifacts": [] } }, { "identifier": "linux_small", "dependsOn": [], "ignoreFailure": false, "currentBuildSummary": { "arn": "arn:aws:codebuild:us-west-2:123456789012:build/codebuild-demo-project:dd785171-ed84-4bb6-8ede-ceeb86e54bdb", "requestedOn": "2020-11-03T21:52:57.604000+00:00", "buildStatus": "SUCCEEDED", "primaryArtifact": { "type": "no_artifacts", "identifier": "linux_small" }, "secondaryArtifacts": [] } }, { "identifier": "linux_medium", "dependsOn": [ "linux_small" ], "ignoreFailure": false, "currentBuildSummary": { "arn": "arn:aws:codebuild:us-west-2:123456789012:build/codebuild-demo-project:97cf7bd4-5313-4786-8243-4aef350a1267", "requestedOn": "2020-11-03T21:54:18.474000+00:00", "buildStatus": "SUCCEEDED", "primaryArtifact": { "type": "no_artifacts", "identifier": "linux_medium" }, "secondaryArtifacts": [] } }, { "identifier": "linux_large", "dependsOn": [ "linux_medium" ], "ignoreFailure": false, "currentBuildSummary": { "arn": "arn:aws:codebuild:us-west-2:123456789012:build/codebuild-demo-project:60a194cd-0d03-4337-9db1-d41476a17d27", "requestedOn": "2020-11-03T21:55:39.203000+00:00", "buildStatus": "SUCCEEDED", "primaryArtifact": { "type": "no_artifacts", "identifier": "linux_large" }, "secondaryArtifacts": [] } } ] } ], "buildBatchesNotFound": [] }

四、核心字段深度解读（基于 API 模型）

BuildBatch结构在 service-2.json 中有完整定义，下面按维度拆解各字段含义。

1. 基础身份信息

• id：批次标识符，格式为项目名:批次UUID；
• arn：批次资源的 Amazon 资源名称，形如arn:aws:codebuild:<region>:<account-id>:build-batch/<id>，是后续调用其他 API（如batch-get-build-batches的再次查询）的可靠凭据；
• projectName：所属构建项目名称；
• buildBatchNumber：该批次在项目内的序号。按模型说明，项目内第一个批次数值为1，此后每次递增 1，且删除批次不会改变其他批次的序号；
• initiator：启动该批次的实体，可能是用户名、CodePipeline 管道名（格式codepipeline/xxx）或CodeBuild-Jenkins-Plugin。

2. 状态与时间

• startTime/endTime：批次开始与结束时间（ISO 8601 时间戳）；
• currentPhase：当前所处阶段名（见下文阶段枚举）；
• buildBatchStatus：批次整体状态，取值来自StatusType枚举（service-2.json）：SUCCEEDED、FAILED、FAULT、TIMED_OUT、IN_PROGRESS、STOPPED；
• complete：布尔值，标识批次是否已结束；
• buildTimeoutInMinutes/queuedTimeoutInMinutes：单次构建的最长执行时间与排队超时时间（分钟）。模型中对BuildTimeOut的约束为min: 5, max: 2160（见 service-2.json）。

3. 阶段时间线（phases）

phases数组由BuildBatchPhase对象组成（service-2.json），每个阶段包含phaseType、phaseStatus、startTime、endTime、durationInSeconds以及故障排查用的contexts。phaseType的合法取值由BuildBatchPhaseType枚举限定（service-2.json）：

phaseStatus使用StatusType枚举（SUCCEEDED、FAILED、FAULT、TIMED_OUT、IN_PROGRESS、STOPPED）。上例中最后一个阶段SUCCEEDED没有endTime与durationInSeconds，因为该阶段是当前正在经历的终态阶段，这也解释了为何currentPhase同样是SUCCEEDED。

通过各阶段的durationInSeconds，你可以快速定位耗时瓶颈——例如上例中DOWNLOAD_BATCHSPEC花了 36 秒、IN_PROGRESS花了 242 秒，而SUBMITTED与COMBINE_ARTIFACTS近乎瞬时。

4. 源码与构建配置

• source：主源码配置，示例为 GitHub 仓库（type: GITHUB），包含gitCloneDepth（克隆深度）、gitSubmodulesConfig.fetchSubmodules（是否拉取子模块）、reportBuildStatus（是否回写构建状态到 GitHub）、insecureSsl等；
• resolvedSourceVersion：实际解析出的源码版本。模型说明指出：CodeCommit / GitHub / GitHub Enterprise / Bitbucket 场景下为 commit ID，CodePipeline 场景下为管道提供的源修订版本，S3 场景下该字段不适用；
• secondarySources/secondarySourceVersions：次级源码及其版本（示例中为空数组）；
• environment：构建环境，包括容器类型（如LINUX_CONTAINER）、镜像（如aws/codebuild/amazonlinux2-x86_64-standard:3.0）、计算规格（如BUILD_GENERAL1_SMALL）、环境变量、privilegedMode（特权模式，用于 Docker-in-Docker）及镜像拉取凭据类型；
• artifacts/secondaryArtifacts：主/次级构建产物信息（location为空表示本例未配置产物上传位置）；
• cache：缓存配置，NO_CACHE表示不启用缓存（CacheType枚举还包含S3、LOCAL）；
• logConfig：日志配置，示例开启 CloudWatch Logs（cloudWatchLogs.status: ENABLED）而关闭 S3 日志（s3Logs.status: DISABLED）；
• encryptionKey：用于加密构建产物的 KMS 密钥 ARN 或别名；
• vpcConfig/fileSystemLocations：VPC 网络配置与 EFS 文件系统挂载配置（本示例未展示）。

5. 批次配置（buildBatchConfig）

buildBatchConfig展示该项目为批次构建设定的全局配置，示例中包含：

• serviceRole：批次构建使用的 IAM 服务角色 ARN；
• restrictions.maximumBuildsAllowed：批内允许的最大构建数（示例为 100）；
• timeoutInMins：批次整体超时时间（分钟，示例为 480）。

五、构建组（buildGroups）：并行与依赖的核心数据结构

批量构建的精髓在于构建组拓扑。buildGroups数组中的每个元素是BuildGroup对象（service-2.json），模型文档将其定义为“用于组合可并行运行的构建，同时允许对其他构建组设置依赖”。

以示例输出为例：

DOWNLOAD_SOURCE（无依赖） → linux_small（无依赖） → linux_medium（依赖 linux_small） → linux_large（依赖 linux_medium）

各字段含义：

• identifier：构建组的唯一标识，对应 buildspec 中 batch 段定义的组名；
• dependsOn：该组依赖的其他构建组标识符列表。示例中linux_medium依赖linux_small、linux_large依赖linux_medium，而linux_small的dependsOn为空，说明它可以在DOWNLOAD_SOURCE完成后立即并行启动；
• ignoreFailure：是否忽略该组的失败（为true时该组失败不会导致整个批次失败）；
• currentBuildSummary：当前执行（或最后执行）的构建概要，类型为BuildSummary（service-2.json），包含本次构建的arn、启动时间requestedOn、状态buildStatus（StatusType枚举）以及primaryArtifact/secondaryArtifacts产物概要；
• priorBuildSummaryList：历史构建概要列表（重试/多次运行时出现）。

通过buildGroups，你可以完整还原批次的并行调度图、确认每组产物去向，并借助每组currentBuildSummary.arn跳转到对应普通构建的详情（即aws codebuild batch-get-builds --ids <该ARN>），实现从“批次”到“单个构建”的下钻排查。

六、常见使用技巧与注意事项

1. 配合列表命令定位 ID：批次 ID 不易记忆，可先用aws codebuild list-build-batches --project-name <项目名>获取批次列表，再用batch-get-build-batches拉取详情。
2. 失败定位：当buildBatchStatus为FAILED/FAULT/TIMED_OUT时，优先查看phases[].contexts（模型说明其用于辅助排查失败的阶段）以及各buildGroups[].currentBuildSummary.buildStatus，快速锁定是哪个构建组、哪个阶段出了问题。
3. 批量查询上限：--ids一次最多传 100 个 ID（BuildBatchIds与BuildBatches的max均为 100），超过上限需要分批查询。
4. ID 拼写与已删除批次：查询不到的 ID 会原样出现在响应字段buildBatchesNotFound中，而不是整体报错，脚本中应对该字段做非空检查。
5. 从源码理解命令：命令的完整参数与响应模型定义在 service-2.json 的BatchGetBuildBatchesInput/BatchGetBuildBatchesOutput/BuildBatch等结构中，是排查字段含义的第一手依据；同目录下的 batch-get-builds.rst、batch-delete-builds.rst 等示例可作为相关命令的参考。

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli