企业官网建设流程全解析

AWS CLI 深入解析：使用codebuild batch-get-projects批量查询 CodeBuild 构建项目详情

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

aws codebuild batch-get-projects是 AWS CLI 中用于一次性获取多个 CodeBuild 构建项目完整配置详情的核心命令。本文将基于本仓库自带的官方示例文档 batch-get-projects.rst，完整还原其命令用法与真实返回结构，并结合仓库内置的 CodeBuild 服务模型 service-2.json 逐一解读projects数组中每个字段的含义、取值范围与默认值。读完本文，你将能熟练使用该命令排查项目配置、批量核对构建环境，并读懂 CodeBuild 项目配置的所有关键维度。

命令基本用法

语法与参数

batch-get-projects的入参只有一个必填字段names，对应 CLI 参数--names：指定要查询的构建项目名称列表。命令格式如下（示例来自 batch-get-projects.rst）：

aws codebuild batch-get-projects --names codebuild-demo-project codebuild-demo-project2 my-other-demo-project

关于--names参数，从服务模型中BatchGetProjectsInput的定义（见 service-2.json）可以确认以下约束：

• 该参数是必填项，且以空格分隔、可一次传入多个名称，属于ProjectNames列表类型，数量范围是1 到 100 个；
• 每个名称可以是项目名或项目 ARN。其中有一条容易被忽略的规则：对于从其他 AWS 账户共享给你的构建项目，必须使用其 ARN 查询，不能使用项目名；
• 项目名称本身遵循ProjectName形状约束：长度 2～150 个字符，匹配模式[A-Za-z0-9][A-Za-z0-9\-_]{1,149}，即首字符为字母或数字，后续可包含字母、数字、连字符与下划线。

底层调用上，该操作通过 HTTPPOST请求发送至 CodeBuild 服务的/端点，唯一的错误类型是InvalidInputException（当names参数格式非法时抛出）。

输出结构总览

命令返回的 JSON 包含两个顶层数组：

• projects：查询成功、找到配置信息的项目对象列表；
• projectsNotFound：指定了但未能找到对应配置的项目名称列表。

这种"成功与缺失分开返回"的设计非常实用：即使你一次性传入了多个项目名，其中个别项目不存在也不会导致整个命令报错，而是在projectsNotFound中明确列出，便于脚本批量处理时精确识别"哪些项目名写错了"。

以下是与上述命令对应的完整输出示例（节选自 batch-get-projects.rst）：

{ "projectsNotFound": [], "projects": [ { "encryptionKey": "arn:aws:kms:us-west-2:123456789012:alias/aws/s3", "name": "codebuild-demo-project2", "queuedTimeoutInMinutes": 480, "timeoutInMinutes": 60, "source": { "buildspec": "version: 0.2\n\n#env:\n #variables:\n # key: \"value\"\n # key: \"value\"\n #parameter-store:\n # key: \"value\"\n # key:\"value\"\n\nphases:\n #install:\n #commands:\n # - command\n # - command\n #pre_build:\n #commands:\n # - command\n # - command\n build:\n commands:\n # - command\n # - command\n #post_build:\n #commands:\n # - command\n # - command\n#artifacts:\n #files:\n # - location\n # - location\n #name: $(date +%Y-%m-%d)\n #discard-paths: yes\n #base-directory: location\n#cache:\n #paths:\n # - paths", "type": "NO_SOURCE", "insecureSsl": false, "gitCloneDepth": 1 }, "artifacts": { "type": "NO_ARTIFACTS" }, "badge": { "badgeEnabled": false }, "lastModified": 1540588091.108, "created": 1540588091.108, "arn": "arn:aws:codebuild:us-west-2:123456789012:project/test-for-sample", "secondarySources": [], "secondaryArtifacts": [], "cache": { "type": "NO_CACHE" }, "serviceRole": "arn:aws:iam::123456789012:role/service-role/my-test-role", "environment": { "image": "aws/codebuild/java:openjdk-8", "privilegedMode": true, "type": "LINUX_CONTAINER", "computeType": "BUILD_GENERAL1_SMALL", "environmentVariables": [] }, "tags": [] }, { "encryptionKey": "arn:aws:kms:us-west-2:123456789012:alias/aws/s3", "name": "my-other-demo-project", "queuedTimeoutInMinutes": 480, "timeoutInMinutes": 60, "source": { "location": "https://github.com/iversonic/codedeploy-sample.git", "reportBuildStatus": false, "buildspec": "buildspec.yml", "insecureSsl": false, "gitCloneDepth": 1, "type": "GITHUB", "auth": { "type": "OAUTH" } }, "artifacts": { "type": "NO_ARTIFACTS" }, "badge": { "badgeEnabled": false }, "lastModified": 1523401711.73, "created": 1523401711.73, "arn": "arn:aws:codebuild:us-west-2:123456789012:project/Project2", "cache": { "type": "NO_CACHE" }, "serviceRole": "arn:aws:iam::123456789012:role/service-role/codebuild-Project2-service-role", "environment": { "image": "aws/codebuild/nodejs:4.4.7", "privilegedMode": false, "type": "LINUX_CONTAINER", "computeType": "BUILD_GENERAL1_SMALL", "environmentVariables": [] }, "tags": [] } ] }

逐字段解读 Project 对象

projects数组中的每个元素都是一个完整的Project结构体。根据服务模型 service-2.json 中Project形状的定义，它包含项目身份信息、源码来源、构建环境、产物、缓存、超时策略、权限与安全配置等全部维度。下面结合上面的示例输出逐一说明。

身份与生命周期字段

source：构建输入源码配置

source对象描述构建的输入源码来自哪里，其中type是必填字段。从服务模型SourceType枚举可以看到，当前支持的源码类型包括：

• CODECOMMIT：源码在 CodeCommit 仓库
• GITHUB：源码在 GitHub 仓库
• GITLAB/GITLAB_SELF_MANAGED：源码在 GitLab 或自托管 GitLab 仓库
• BITBUCKET：源码在 Bitbucket 仓库
• GITHUB_ENTERPRISE：源码在 GitHub Enterprise Server 仓库
• S3：源码位于 S3 存储桶（ZIP 文件或目录）
• CODEPIPELINE：源码设置由 CodePipeline 流水线中的 source 动作决定
• NO_SOURCE：项目没有输入源码

结合示例输出可以看到两种典型形态：

• 第一个项目codebuild-demo-project2的source.type为NO_SOURCE，表示该项目不依赖外部仓库，构建逻辑完全由内联的buildspec定义；
• 第二个项目my-other-demo-project的source.type为GITHUB，location指向仓库克隆地址，auth.type为OAUTH，表示使用 GitHub OAuth 授权访问。

source中其他值得关注的字段：

• buildspec：构建规范声明。可以是内联 buildspec 定义（如第一个项目示例中的完整 YAML 内容），也可以是相对路径（如第二个项目示例中的buildspec.yml），还可以是 S3 中的 buildspec 文件 ARN。若为空，则要求源码根目录自带 buildspec 文件。内联 buildspec 支持声明version、env（含variables与parameter-store）、phases（install/pre_build/build/post_build各阶段的commands）、artifacts与cache等段落；
• gitCloneDepth：Git 克隆深度，示例中均为1（浅克隆）；
• insecureSsl：是否忽略连接源码时的 SSL 告警，示例中为false；
• reportBuildStatus：是否将构建开始/结束状态回写到源码提供方（仅对 GitHub、GitHub Enterprise、GitLab、Bitbucket 有效，且要求关联账户对仓库有写权限）；
• buildStatusConfig：定义回写状态时的context与targetUrl；
• auth：访问源码的授权设置，type可取OAUTH或CODECONNECTIONS等；
• sourceIdentifier：多源码项目的标识符，仅包含字母数字与下划线，长度小于 128 字符。

environment：构建环境配置

environment对象定义了构建运行时的环境，其中type、image、computeType三个字段均为必填：

• type：环境类型，EnvironmentType枚举包含LINUX_CONTAINER、LINUX_GPU_CONTAINER、ARM_CONTAINER、WINDOWS_CONTAINER、WINDOWS_SERVER_2019_CONTAINER、WINDOWS_SERVER_2022_CONTAINER、LINUX_LAMBDA_CONTAINER、ARM_LAMBDA_CONTAINER、LINUX_EC2、ARM_EC2、WINDOWS_EC2、MAC_ARM等。示例中的LINUX_CONTAINER是最常见的 Linux 容器环境；
• image：构建镜像标识，格式为<registry>/<repository>:<tag>（如aws/codebuild/java:openjdk-8、aws/codebuild/nodejs:4.4.7）或镜像摘要<registry>/<repository>@<digest>；
• computeType：计算资源配置，ComputeType枚举包括BUILD_GENERAL1_SMALL（约 2 vCPU / 4 GiB）、BUILD_GENERAL1_MEDIUM（4 vCPU / 8 GiB）、BUILD_GENERAL1_LARGE（8 vCPU / 16 GiB）、BUILD_GENERAL1_XLARGE、BUILD_GENERAL1_2XLARGE以及面向 Lambda 环境类型的BUILD_LAMBDA_1GB至BUILD_LAMBDA_10GB等。示例中两个项目均为BUILD_GENERAL1_SMALL；
• privilegedMode：是否启用特权模式以在容器内运行 Docker daemon。只有构建 Docker 镜像的项目才应设为true，否则构建中尝试与 Docker daemon 交互会失败。示例中codebuild-demo-project2为true，my-other-demo-project为false；
• environmentVariables：环境变量列表。每个变量包含name、value两个必填字段与type字段，type的合法取值为PLAINTEXT（明文，默认）、PARAMETER_STORE（引用 SSM Parameter Store 参数）和SECRETS_MANAGER（引用 Secrets Manager 密钥）。服务模型的说明特别强调：不建议用PLAINTEXT存放敏感值（尤其是 AWS 密钥），敏感值应改用PARAMETER_STORE或SECRETS_MANAGER；
• imagePullCredentialsType：拉取镜像所用凭证，CODEBUILD（使用 CodeBuild 自身凭证）或SERVICE_ROLE（使用项目服务角色）；
• registryCredential：访问私有镜像仓库的凭证；
• certificate：PEM 编码证书所在 S3 位置。

artifacts 与 secondaryArtifacts：构建产物配置

artifacts描述构建输出产物的去向，type为必填字段，ArtifactsType枚举包括：

• NO_ARTIFACTS：不产生构建输出（示例中两个项目均为此值）；
• S3：构建产物存储到 S3 桶，此时可配合location（输出桶名）、path、namespaceType（NONE或BUILD_ID）、name、packaging（NONE或ZIP）等字段；
• CODEPIPELINE：产物交由 CodePipeline 管理。

secondaryArtifacts为辅助产物列表，secondarySources为辅助源码列表，未配置时均为空数组。

cache：缓存配置

cache对象的type为必填字段，CacheType枚举包括：

• NO_CACHE：不使用缓存（示例中两个项目均为此值）；
• S3：缓存读写 S3，此时location为桶名/前缀，还可通过cacheNamespace在多个项目间共享缓存；
• LOCAL：在构建主机本地缓存，可通过modes指定LOCAL_SOURCE_CACHE（缓存 Git 元数据）、LOCAL_DOCKER_LAYER_CACHE（缓存 Docker 层，需 Linux 环境且启用privilegedMode）与LOCAL_CUSTOM_CACHE（按 buildspec 中的 cache paths 缓存目录）的组合。

超时与权限相关字段

• timeoutInMinutes：单次构建超时时间，范围 5～2160 分钟（36 小时），默认 60 分钟（示例中两个项目均为 60）；
• queuedTimeoutInMinutes：构建进入队列后允许等待的超时时间，范围 5～480 分钟，默认 480（示例中两个项目均为 480）；
• serviceRole：允许 CodeBuild 代表账户与依赖的 AWS 服务交互的 IAM 角色 ARN，如示例中的arn:aws:iam::123456789012:role/service-role/my-test-role；
• encryptionKey：用于加密构建产物的 KMS 密钥。可指定 CMK 的 ARN 或别名（alias/<alias-name>）；若不指定，默认使用 S3 的托管 CMK，这正是示例中两个项目均为arn:aws:kms:us-west-2:123456789012:alias/aws/s3的原因；
• resourceAccessRole：允许 CodeBuild 访问项目的 CloudWatch Logs 与 S3 产物的 IAM 角色 ARN。

其他扩展配置

• badge：构建徽章配置，badgeEnabled为true时会生成一个公开可访问的徽章 URL（badgeRequestUrl），示例中两个项目均为false；
• webhook：连接仓库事件与构建项目的 webhook 信息，包括url、payloadUrl、branchFilter、filterGroups等；
• vpcConfig：项目访问的 VPC 配置；
• logsConfig：日志配置，可写入 CloudWatch Logs 与 S3；
• fileSystemLocations：挂载的 EFS 文件系统位置列表；
• buildBatchConfig：批量构建选项；
• concurrentBuildLimit：项目允许的最大并发构建数，超过该值时新构建会被节流；
• autoRetryLimit：构建失败后自动重试的最大次数；
• publicProjectAlias：公开构建 API 使用的项目标识符。

典型使用场景与命令搭配

场景一：批量核对项目配置

先用aws codebuild list-projects（示例见 list-projects.rst）拿到全部项目名列表，再用batch-get-projects一次性拉取这批项目的完整配置，即可批量核对镜像、计算规格、超时时间等是否合规：

aws codebuild list-projects --sort-by NAME --sort-order ASCENDING aws codebuild batch-get-projects --names project-a project-b project-c

由于names最多支持 100 个，而list-projects使用nextToken分页，超出 100 个时需分批调用。若个别项目名拼写错误或已被删除，它们不会导致命令失败，而是出现在projectsNotFound数组中——脚本可以据此区分"配置正常"与"项目不存在"两类结果，实现自动化巡检。

场景二：结合创建命令理解配置闭环

查询到的Project结构与创建项目时create-project的入参结构一一对应（见 create-project.rst 中的示例：以--name、--source、--artifacts、--environment、--service-role定义项目）。因此batch-get-projects也是排查"项目为什么构建异常"的第一入口：例如environment.image是否引用了不存在的镜像、privilegedMode是否未对 Docker 构建开启、timeoutInMinutes是否过短导致构建超时、serviceRole是否缺少所需权限等，都能在返回的项目快照中直接找到证据。

场景三：查询后联动构建记录

查询到目标项目名后，可配合aws codebuild list-builds-for-project查看该项目的历史构建 ID，再用aws codebuild batch-get-builds（示例见 batch-get-builds.rst）拉取构建明细，形成"项目配置 → 构建历史 → 构建详情"的完整排查链路。

小结

aws codebuild batch-get-projects的核心价值在于以一次 API 调用换取最多 100 个构建项目的完整配置快照，并且通过projects与projectsNotFound的分离设计优雅地处理部分项目缺失的场景。本文中的命令与完整输出示例来自仓库文档 batch-get-projects.rst，各字段的约束、枚举与默认值均可在 CodeBuild 服务模型 service-2.json 的BatchGetProjects操作及其关联形状中找到权威定义，读者可据此进一步核对模型中最新的字段与取值。

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