企业官网建设流程全解析

使用 AWS CLI 的batch-delete-builds批量删除 AWS CodeBuild 构建记录

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

本指南围绕 AWS CLI 的codebuild batch-delete-builds命令，讲解如何一次删除多个 AWS CodeBuild 构建记录：先说明命令语法与必填参数--ids，再给出可直接运行的示例与输出解析，并结合仓库中的 AWS CodeBuild API 模型定义（service-2.json）剖析buildsDeleted、buildsNotDeleted两个返回字段的含义与底层数据结构，最后补充获取构建 ID 的配套命令与常见异常处理。读完本文，你将掌握批量清理 CodeBuild 构建记录的标准流程，并能准确解读"部分删除失败"场景的返回结果。

一、命令概览：用一条命令清理多个构建

AWS CodeBuild 的每次构建都会产生一条构建记录，包含构建日志、产物与元数据。随着迭代进行，历史构建记录会不断累积，aws codebuild batch-delete-builds正是用于批量删除构建记录的运维命令，其对应的 API 操作为BatchDeleteBuilds，在仓库的 AWS CodeBuild API 模型文件 service-2.json 中定义（apiVersion 为2016-10-06）。

从 API 模型可以看到该操作的关键特性：

命令基本语法如下：

aws codebuild batch-delete-builds --ids <build-id-1> <build-id-2> ...

官方示例文档位于 awscli/examples/codebuild/batch-delete-builds.rst，本文后续示例即基于该文档展开。

二、核心参数--ids：必填的构建 ID 列表

--ids是batch-delete-builds唯一的输入参数，用于指定要删除的构建 ID 列表。根据 service-2.json 中BatchDeleteBuildsInput的定义：

• 该参数必填（"required":["ids"]）；
• 类型为BuildIds，是一个列表，最少 1 个、最多 100 个元素（"min":1、"max":100）；
• 每个元素为非空字符串（NonEmptyString），即单个构建的 ID。

构建 ID 的格式

CodeBuild 构建 ID 由"项目名 + 冒号 + 构建唯一标识"组成，形如：

<project-name>:<build-uuid>

例如文档示例中的my-build-project-one:a1b2c3d4-5678-9012-abcd-11111EXAMPLE。在同一项目的BatchGetBuilds官方示例（见 examples-1.json）中，可以看到相同的 ID 形态：

"id": "codebuild-demo-project:9b0ac37f-d19e-4254-9079-f47e9a389eEX"

同时，每个构建还拥有完整的 ARN，形如：

arn:aws:codebuild:<region>:<account-id>:build/<project-name>:<build-uuid>

文档示例输出中的buildsDeleted字段返回的正是这种完整 ARN 形式。

三、完整示例与输出解析

以下命令来自 batch-delete-builds.rst，一次删除两个项目各一条构建记录：

aws codebuild batch-delete-builds --ids my-build-project-one:a1b2c3d4-5678-9012-abcd-11111EXAMPLE my-build-project-two:a1b2c3d4-5678-9012-abcd-22222EXAMPLE

返回结果：

{ "buildsNotDeleted": [ { "id": "arn:aws:codebuild:us-west-2:123456789012:build/my-build-project-one:a1b2c3d4-5678-9012-abcd-11111EXAMPLE", "statusCode": "BUILD_IN_PROGRESS" } ], "buildsDeleted": [ "arn:aws:codebuild:us-west-2:123456789012:build/my-build-project-two:a1b2c3d4-5678-9012-abcd-22222EXAMPLE" ] }

输出字段含义

根据 service-2.json 中BatchDeleteBuildsOutput的定义，响应包含两个字段：

• buildsDeleted（类型BuildIds）：成功删除的构建 ID 列表（ARN 形式）；
• buildsNotDeleted（类型BuildsNotDeleted）：删除失败的构建信息列表，其中每个元素（BuildNotDeleted）包含两个子字段：
  • id：未能成功删除的构建 ID；
  • statusCode：关于删除失败的附加信息，例如示例中的BUILD_IN_PROGRESS（构建仍在进行中）。

从示例输出可以看出：my-build-project-one的构建因**仍处于进行中（BUILD_IN_PROGRESS）**而未能删除，被放入buildsNotDeleted；my-build-project-two的构建则被成功删除，其 ARN 出现在buildsDeleted中。

值得注意的细节

• 该操作是**尽力而为（best-effort）**的：即使部分构建删除失败，命令本身仍会正常返回，失败项通过buildsNotDeleted暴露出来，不会导致整体报错；
• 若全部删除成功，buildsNotDeleted为空数组或缺失，buildsDeleted包含全部 ARN；
• 从模型看，删除失败时常见的statusCode会反映构建状态，而StatusType枚举（定义于 service-2.json 的StatusTypeshape）包括SUCCEEDED、FAILED、FAULT、TIMED_OUT、IN_PROGRESS、STOPPED等取值，可用于辅助判断失败原因。

四、如何获取构建 ID：配套查询命令

batch-delete-builds只负责删除，构建 ID 需要提前获取。常用的配套 AWS CLI 命令包括：

• 列出所有构建 ID：

  aws codebuild list-builds

  对应 API 操作为ListBuilds，返回全部构建 ID（分页场景可配合--next-token与--max-items）。

• 按项目列出构建 ID：

  aws codebuild list-builds-for-project --project-name my-build-project

  对应 API 操作为ListBuildsForProject，按项目过滤。

• 查看构建详情确认 ID：

  aws codebuild batch-get-builds --ids <build-id>

  对应 API 操作为BatchGetBuilds，可校验 ID 是否存在及构建当前状态。

以上操作在 service-2.json 中均有对应定义，例如ListBuilds的说明为"获取构建 ID 列表，每个 ID 代表一次构建"。

建议的删除前检查流程

1. 用list-builds或list-builds-for-project拿到目标构建 ID；
2. 结合batch-get-builds确认构建状态（如SUCCEEDED、FAILED）并过滤掉仍在IN_PROGRESS的构建；
3. 将 ID 列表传入batch-delete-builds --ids，一次最多 100 个；
4. 检查响应中的buildsNotDeleted，对未删除项（如仍在运行的构建）在构建结束后重试。

五、异常与边界情况处理

1. 正在运行的构建无法删除

如示例所示，处于BUILD_IN_PROGRESS状态的构建会进入buildsNotDeleted。此时应先用aws codebuild stop-build --id <build-id>停止构建，再执行删除。

2. 输入参数非法

BatchDeleteBuilds操作可能抛出InvalidInputException（见 service-2.json 中该操作的errors定义）。常见触发原因包括：

• --ids为空或缺失（该参数必填）；
• 传入超过 100 个构建 ID（BuildIds上限为 100）；
• ID 格式非法（不是合法的project-name:uuid形式）。

3. 权限不足

删除构建记录需要具备相应的 IAM 权限，例如codebuild:BatchDeleteBuilds允许策略。权限缺失时 AWS CLI 会返回访问拒绝类错误，这与命令本身的参数无关。

4. 删除结果不是全有或全无

务必在脚本中同时解析buildsDeleted与buildsNotDeleted两个字段，切勿只根据命令退出码判断结果。正确做法是：以buildsNotDeleted是否为空作为批量删除是否完全成功的判据。

六、源码级回顾：命令背后的数据结构

为便于排查问题，这里将关键数据结构集中列出（均位于 awscli/botocore/data/codebuild/2016-10-06/service-2.json）：

结合 batch-delete-builds.rst 的示例，可以完整还原一条删除请求的"输入 → 处理 → 输出"链路：输入ids列表 → CodeBuild 逐个尝试删除 → 成功项进入buildsDeleted（返回 ARN），失败项连同原因statusCode进入buildsNotDeleted。

七、总结

aws codebuild batch-delete-builds是管理 AWS CodeBuild 构建记录生命周期的核心运维命令，支持单次传入 1 至 100 个构建 ID 进行批量清理。使用时注意三点：构建 ID 采用<project-name>:<uuid>格式；正在运行的构建无法删除并会出现在buildsNotDeleted中；判断批量删除是否完全成功应检查buildsNotDeleted是否为空。配合list-builds、list-builds-for-project、batch-get-builds与stop-build命令，即可形成完整的"查询 → 停止 → 批量删除"清理闭环。

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