AWS CodeBuild 报告组批量查询实战：深入解析 `aws codebuild batch-get-report-groups` 命令

导读

本篇文章围绕 AWS CLI 中 codebuild 服务族的 batch-get-report-groups 命令展开，该命令用于一次批量获取一个或多个 CodeBuild 报告组（Report Group）的元数据信息，是自动化运维 CodeBuild 测试报告与代码覆盖率报告配置的核心入口之一。通过本文，你将掌握该命令的完整参数语义、输出结构、异常处理方式，以及它在报告组生命周期管理（创建、查询、更新、删除）中的定位，并能基于本仓库的 service-2.json 模型文件理解其底层实现细节。

报告组（Report Group）是什么

在 AWS CodeBuild 中，报告组（Report Group）是一组测试报告（TEST）或代码覆盖率报告（CODE_COVERAGE）的集合容器。构建项目（Build Project）在 buildspec 文件中通过指定测试用例文件的路径，将运行结果归集到某个报告组中，从而形成可追溯、可对比的质量数据。

从本仓库的模型文件 service-2.json 中可以确认，报告组的类型由枚举 ReportType 定义，仅包含两个取值：

取值	含义
TEST	报告组存放测试报告
CODE_COVERAGE	报告组存放代码覆盖率报告

当需要同时了解多个报告组的 ARN、类型、导出配置、创建时间与标签信息时，逐个查询不仅低效，还会产生多次 API 调用。batch-get-report-groups 正是为解决"批量读取"而设计的操作，其官方文档说明为 Returns an array of report groups。

命令语法与参数说明

batch-get-report-groups 的操作在模型文件中定义为：

• HTTP 方法：POST，请求路径 /（即标准 JSON RPC 风格请求）；
• 输入结构：BatchGetReportGroupsInput；
• 输出结构：BatchGetReportGroupsOutput；
• 错误定义：仅声明 InvalidInputException（参数不合法时抛出）。

命令的完整语法为：

aws codebuild batch-get-report-groups \
    --report-group-arns <value> [--cli-input-json <value>]

核心参数 --report-group-arns

这是唯一必需参数，其底层类型为列表 ReportGroupArns，模型中的约束非常明确：

• 最小元素数量：1
• 最大元素数量：100

也就是说，一次调用至少传入 1 个、最多传入 100 个报告组 ARN。每个元素为非空字符串，其格式遵循 CodeBuild 报告组的 ARN 规范：

arn:aws:codebuild:<region-ID>:<user-ID>:report-group/<report-group-name>

其中：

• <region-ID>：报告组所在区域，如 us-east-1；
• <user-ID>：AWS 账户 ID（12 位数字）；
• <report-group-name>：报告组名称，长度限制为 2~128 个字符（对应模型中的 ReportGroupName：min: 2，max: 128）。

一个批量查询多个报告组的命令示例如下：

aws codebuild batch-get-report-groups \
    --report-group-arns \
        arn:aws:codebuild:us-east-1:123456789012:report-group/my-test-group \
        arn:aws:codebuild:us-east-1:123456789012:report-group/my-coverage-group

完整示例与输出解析

本仓库的官方示例文档位于 batch-get-report-groups.rst，该示例查询单个报告组并完整展示了响应结构。命令如下：

aws codebuild batch-get-report-groups \
    --report-group-arns arn:aws:codebuild:<region-ID>:<user-ID>:report-group/<report-group-name>

响应示例：

{
    "reportGroups": [
        {
            "arn": "arn:aws:codebuild:<region-ID>:<user-ID>:report-group/<report-group-name>",
            "name": "report-group-name",
            "type": "TEST",
            "exportConfig": {
                "exportConfigType": "NO_EXPORT"
            },
            "created": "2020-10-01T18:04:08.466000+00:00",
            "lastModified": "2020-10-01T18:04:08.466000+00:00",
            "tags": []
        }
    ],
    "reportGroupsNotFound": []
}

reportGroups 数组：报告组元数据

响应中的 reportGroups 数组包含所有成功匹配的报告组，每个元素对应模型 ReportGroup 结构，其字段含义如下：

字段	类型	说明
arn	字符串	报告组的 ARN
name	字符串	报告组名称（2~128 字符）
type	枚举	TEST 或 CODE_COVERAGE，见 ReportType
exportConfig	结构	报告原始数据的导出目标配置，见下文
created	时间戳	报告组创建时间（ISO 8601 格式）
lastModified	时间戳	报告组最后修改时间
tags	列表	标签键值对列表（最多 50 个），供支持 CodeBuild 报告组标签的 AWS 服务使用
status	枚举	报告组状态，取值 ACTIVE（活跃）或 DELETING（删除中），该属性只读

注意：status 字段在官方示例输出中未出现，但它在模型 ReportGroupStatusType 中已被定义（ACTIVE / DELETING），当报告组处于删除流程中时，批量查询结果中会体现该状态，这是脚本判断"报告组是否可安全重建"时的重要依据。

exportConfig 导出配置深入

exportConfig 对应模型 ReportExportConfig，描述报告原始数据被导出到的位置，包含两个成员：

• exportConfigType：枚举类型 ReportExportConfigType，取值仅两种：
  • S3：报告结果导出到 S3 存储桶；
  • NO_EXPORT：不导出报告结果（示例中的默认形态）。
• s3Destination：仅当 exportConfigType 为 S3 时出现，类型为 S3ReportExportConfig，包含：

子字段	说明
bucket	导出原始数据的 S3 存储桶名称
bucketOwner	存储桶所有者的 AWS 账户 ID，允许将报告数据导出到非构建账户拥有的 S3 存储桶
path	导出报告原始数据的目标路径
packaging	打包方式：NONE（原始数据直接落桶，默认值）或 ZIP（打包为 ZIP 文件）
encryptionKey	报告加密原始数据的加密密钥
encryptionDisabled	布尔值，指定报告结果是否加密

因此，在自动化巡检脚本中，你可以通过检查 exportConfig.exportConfigType 快速发现"未按合规要求导出报告"的报告组，从而联动 update-report-group 进行修正。

reportGroupsNotFound 数组：未匹配项

响应中的 reportGroupsNotFound 与 ReportGroupArns 同类型，列出所有传入但未与任何报告组关联的 ARN。这是 batch-get-report-groups 与单数 get 类操作最大的语义差异：批量接口不会因为某个 ARN 不存在而整体失败，而是将"找到的"与"未找到的"分置于两个数组中返回，便于调用方精准定位失效的 ARN，这在处理历史遗留、已删除报告组的引用时非常实用。

源码级佐证：从模型文件看实现约束

以上全部字段与约束均可在本仓库的 CodeBuild 服务模型 service-2.json 中逐一验证，关键定义如下：

• BatchGetReportGroups 操作：POST /，仅声明错误 InvalidInputException（文档描述 Returns an array of report groups）；
• BatchGetReportGroupsInput：必需成员 reportGroupArns（ReportGroupArns 列表，min: 1，max: 100）；
• BatchGetReportGroupsOutput：reportGroups（ReportGroups）与 reportGroupsNotFound（ReportGroupArns）；
• ReportGroup：arn、name、type、exportConfig、created、lastModified、tags、status 八个成员；
• ReportType：["TEST", "CODE_COVERAGE"]；
• ReportGroupStatusType：["ACTIVE", "DELETING"]；
• ReportExportConfigType：["S3", "NO_EXPORT"]；
• ReportGroupName：min: 2，max: 128；
• TagList：max: 50。

这些约束与上一节的参数表格一一对应，可作为编写参数校验逻辑（如批量数量上限 100、名称长度 2~128）的直接依据。该示例文件位于 awscli/examples/codebuild/，与 examples-1.json 共同构成了 CLI help 输出的示例来源。

在报告组生命周期中的定位

batch-get-report-groups 属于 CodeBuild 报告能力中的"读取"操作，与它同级的报告相关操作在模型文件中可完整列出：

操作	作用
CreateReportGroup	创建报告组
UpdateReportGroup	更新报告组（如调整导出配置）
DeleteReportGroup	删除报告组
ListReportGroups	分页列出报告组 ARN
BatchGetReportGroups	批量获取报告组详情（本文主题）
BatchGetReports	批量获取报告详情
ListReportsForReportGroup	列出指定报告组下的报告
ListSharedReportGroups	列出共享给当前账户的报告组
GetReportGroupTrend	获取报告组趋势数据
DeleteReport	删除单条报告

一个典型的运维组合是：先用 list-report-groups（配合分页）拿到全部 ARN，再以 100 个为一批调用 batch-get-report-groups 拉取元数据；若发现 reportGroupsNotFound 非空，则说明对应报告组已被删除，可用于清理配置引用；若 status 为 DELETING，则需等待删除完成后才能重建同名报告组。

常见实战场景与注意事项

1. 批量巡检导出合规性：遍历 reportGroups[].exportConfig.exportConfigType，找出 NO_EXPORT 的报告组并告警或联动 update-report-group 补设 S3 导出目标（含 bucket、path、packaging 等参数）。
2. 批量数必须 ≤ 100：一次传入超过 100 个 ARN 将触发 InvalidInputException（模型 ReportGroupArns 上限为 100），大批量场景需分批调用后合并结果。
3. 利用 reportGroupsNotFound 做引用清理：该字段天然返回"不存在的 ARN"，无需自行对结果做差集，可直接据此删除外部配置中已失效的引用。
4. 权限要求：调用该命令需要 codebuild:BatchGetReportGroups 权限（AWS Identity and Access Management 策略），IAM 未授权时将被拒绝访问。
5. 输出过滤：在脚本或 CI 中，可借助 --query 与 --output json 精确提取字段，例如仅取名称与导出类型，减少下游解析成本。

综上，batch-get-report-groups 是 CodeBuild 报告体系里面向"批量元数据读取"的关键命令，其"找到/未找到分离返回"的设计、严格的批量上限与丰富的元数据字段，使其非常适合嵌入到合规巡检、引用清理与报告生命周期自动化脚本中。