AWS CLI 实战：用 `aws codebuild list-builds` 获取构建 ID 列表并完整遍历分页结果

AWS CLI 实战：用aws codebuild list-builds获取构建 ID 列表并完整遍历分页结果

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

导读

本文以 AWS CLI 仓库中的 list-builds.rst 官方示例文档为骨架，系统讲解aws codebuild list-builds命令的用法：如何按升序/降序获取当前区域 CodeBuild 构建 ID 列表、如何解读返回的nextToken分页游标、以及如何结合 AWS CLI 内置分页参数编写可完整遍历所有结果的脚本。读完本文，你将掌握构建 ID 的格式、分页机制的底层模型定义，以及从「拿到第一页」到「翻完最后一页」的完整实战方案。

list-builds是干什么的：定位与适用场景

ListBuilds是 AWS CodeBuild 提供的一个查询类操作，其官方模型描述为："Gets a list of build IDs, with each build ID representing a single build"（获取构建 ID 列表，其中每个构建 ID 代表一次构建）。对应的定义位于 service-2.json，通过aws codebuild list-builds命令即可调用。

理解这个命令需要把握三个关键点：

• 它只返回 ID，不返回构建详情。列表中的每个 ID 只是"门票"，如果要获取某次构建的状态、日志位置、构建阶段等详细信息，需要将 ID 交给batch-get-builds等操作去查详情。
• 它作用于当前区域（region），返回的是当前区域账户下所有构建项目的全部构建 ID，不区分项目。
• 它和list-builds-for-project形成互补：后者（对应 list-builds-for-project.rst）按指定项目名过滤，只返回某个--project-name下的构建 ID；而list-builds不做项目过滤，返回范围更广。实际排查问题时，先想清楚你是要"全局看所有构建"，还是"只看某个项目的构建"，再选择命令。

基础用法：按升序获取构建 ID 列表

官方示例文档给出的第一个用例是以升序获取构建 ID 列表：

aws codebuild list-builds --sort-order ASCENDING

--sort-order参数的取值

--sort-order是list-builds的唯一查询筛选参数（另一个参数--next-token用于分页，见下文）。它的合法取值定义在 service-2.json 的SortOrderType枚举中，只有两个：

该参数为可选参数（模型中没有required标记，见 service-2.json）。如果不传，将使用服务端默认顺序；显式传入ASCENDING或DESCENDING可以让结果顺序可预期，方便脚本做去重与增量处理。

响应结构解读

示例文档给出了对应的输出示例：

{ "nextToken": "4AEA6u7J...The full token has been omitted for brevity...MzY2OA==", "ids": [ "codebuild-demo-project:815e755f-bade-4a7e-80f0-efe51EXAMPLE", "codebuild-demo-project:84a7f3d1-d40e-4956-b4cf-7a9d4EXAMPLE", ... The full list of build IDs has been omitted for brevity ... "codebuild-demo-project:931d0b72-bf6f-4040-a472-5c707EXAMPLE" ] }

响应中两个字段的含义，与模型定义 ListBuildsOutput 完全对应：

• ids：构建 ID 字符串数组。模型约束BuildIds为一个元素数量在 1~100 之间的字符串列表（见 service-2.json），单次调用最多返回 100 个 ID。
• nextToken：分页游标。只要响应里出现nextToken，就说明结果还没有取完。

分页机制：理解nextToken与 100 条上限

为什么会有 nextToken

CodeBuild 的构建数量可能成千上万，服务端不可能一次性返回全部 ID。官方模型文档明确说明（见 service-2.json 与 service-2.json）：

如果列表中的条目超过 100 个，则只返回前 100 个，同时返回一个称为nextToken的唯一字符串。要获取列表中的下一批条目，请再次调用该操作，并将该 next token 加入调用；要获取列表中的全部条目，请持续携带每次返回的 nextToken 调用该操作，直到不再返回 nextToken 为止。

这就是标准的分页（pagination）协议：服务端返回一批数据 + 一个游标，客户端把游标传回去换取下一批数据，直到游标消失。

用--next-token取下一页

按照官方示例文档 list-builds.rst，拿到上一页的nextToken后，将其作为--next-token参数再次调用命令：

aws codebuild list-builds --sort-order ASCENDING --next-token 4AEA6u7J...The full token has been omitted for brevity...MzY2OA==

下一页输出示例：

{ "ids": [ "codebuild-demo-project:49015049-21cf-4b50-9708-df115EXAMPLE", "codebuild-demo-project:543e7206-68a3-46d6-a4da-759abEXAMPLE", ... The full list of build IDs has been omitted for brevity ... "codebuild-demo-project:c282f198-4582-4b38-bdc0-26f96EXAMPLE" ] }

注意这一页的响应中没有nextToken字段，说明已经取到了最后一页，遍历到此结束。

分页遍历的完整循环逻辑可以概括为：

1. 不带--next-token调用，拿到第一页；
2. 检查响应中是否有nextToken；
3. 若有，将其作为--next-token再调用，回到第 2 步；
4. 若没有，遍历结束。

官方文档特别强调：重复这一过程，直到响应中不再出现nextToken值为止。

让遍历更简单：AWS CLI 内置分页参数

上面的手写循环在脚本里可以用 shell 循环实现，但 AWS CLI 本身为分页操作提供了更省力的支持。从源码结构看，CLI 的分页定制逻辑位于 paginate.py，它会为「在服务模型分页配置中注册过的操作」自动注入--max-items、--starting-token、--page-size等分页参数（相关逻辑见 paginate.py 与 paginate.py）。

而 CodeBuild 的ListBuilds恰好注册在分页配置中。在 paginators-1.json 中可以找到它的分页器定义：

"ListBuilds": { "output_token": "nextToken", "input_token": "nextToken", "result_key": "ids" }

这段配置告诉我们三件事：

• output_token是nextToken：服务端响应用它标记"还有下一页"；
• input_token是nextToken：客户端请求用--next-token传回游标；
• result_key是ids：真正需要逐条消费的结果字段。

用--max-items控制返回条数

配合分页配置，你可以直接告诉 CLI 每页/总共想要多少条。例如只取最新的 5 个构建 ID：

aws codebuild list-builds --sort-order DESCENDING --max-items 5

--max-items会按照result_key（即ids）来计数，避免你从 JSON 里手动数数。有一点需要注意：CLI 对--max-items传入非正整数时会给出警告（源码见 paginate.py 与 paginate.py），所以请始终传大于 0 的整数。

用--no-paginate关闭自动分页

如果开启了分页，CLI 会循环调用服务端直到取满--max-items指定数量（或不限数量时取完所有页）。若你只想看服务端单次原始返回（最多 100 条），可以加--no-paginate：

aws codebuild list-builds --sort-order ASCENDING --no-paginate

遍历全部构建的推荐姿势

结合上面两个参数，一个「遍历所有构建 ID」的典型做法是：

aws codebuild list-builds --sort-order ASCENDING --max-items 1000

这条命令会把分页封装交给 CLI 处理：内部自动携带nextToken逐页拉取，直到取满 1000 条或取完所有结果。相比手写循环，代码更简洁、可读性更好，也便于在--output json或--query配合下做进一步加工，例如只提取 ID 列表：

aws codebuild list-builds --sort-order ASCENDING --max-items 1000 \ --query "ids[]" --output json

构建 ID 的格式：项目名:唯一标识

从所有示例输出可以看出，CodeBuild 的构建 ID 采用固定格式：

codebuild-demo-project:815e755f-bade-4a7e-80f0-efe51EXAMPLE

即<project-name>:<uuid>—— 冒号前是所属构建项目的名称，冒号后是该次构建的唯一标识符（形如 UUID）。这意味着：

• 仅凭一个构建 ID，就能反推出它属于哪个项目（冒号左侧部分）；
• 同一个项目内每次构建的 ID 后半段不同，因此构建 ID 全局唯一；
• 排序（ASCENDING/DESCENDING）是针对整个 ID 字符串进行的，等价于先按项目名、再按构建标识排序。

关联命令与进阶组合

list-builds返回的 ID 只是起点，配合其他命令才能发挥价值：

• 只看某个项目：aws codebuild list-builds-for-project --project-name codebuild-demo-project --sort-order DESCENDING，用法与list-builds高度一致（示例见 list-builds-for-project.rst），适合聚焦单个项目的构建历史。
• 查详情：把列表中的 ID 传给batch-get-builds，可以批量获取每次构建的状态、开始/结束时间、日志组信息等。两者结合即可实现「先列 ID、再查详情」的两步式流水线。
• 配合 shell 管道：由于 ID 列表是纯文本，可以非常自然地接入jq、grep或循环脚本做自动化处理。

常见问题与注意事项

1. 响应没有nextToken不代表结果为空：只有当ids数组为空时才说明没有任何构建；只要ids非空且长度达到 100，就很可能还有下一页，务必检查nextToken字段。
2. InvalidInputException：ListBuilds操作声明的唯一错误类型是InvalidInputException（见 service-2.json）。当--sort-order传入枚举之外的值（如小写ascending）时会触发该异常，请严格使用ASCENDING/DESCENDING。
3. nextToken的有效期：游标应尽快使用，且应原样传回，不要截断或二次编码；示例文档中展示的 token 已省略中间内容，真实场景中的完整 token 需要完整保留。
4. 区域与权限：命令只返回当前区域的结果，跨区域查看需要配合--region参数；调用方还需要具备codebuild:ListBuilds权限。
5. 结果顺序：手动分页时，请保持--sort-order在每一页调用中一致，否则拼接起来的列表顺序会错乱。

小结

aws codebuild list-builds虽然是一个"只返回 ID"的轻量命令，却是 CodeBuild 构建管理自动化链条的起点。本文基于 list-builds.rst 官方示例，完整覆盖了升序/降序查询、nextToken手动分页、以及--max-items/--no-paginate等 CLI 内置分页能力的用法；其分页行为可以在 paginators-1.json 的ListBuilds配置中找到模型级依据，参数定义则对应 service-2.json。掌握这套分页协议后，无论是手写循环还是借助 CLI 自动分页，都能稳定、完整地遍历当前区域的全部构建 ID。

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