gogcli 管理 Google Workspace 组织单位：gog admin orgunits create命令全解析
【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli
本命令页面由
gog schema --json自动生成（参见 docs/commands/gog-admin-orgunits-create.md 顶部说明，重新生成需执行make docs-commands）。
导读
gog admin orgunits create是 gogcli（Google Workspace in your terminal）提供的用于在 Google Workspace 中创建组织单位（Organizational Unit，OU）的命令。它是gog admin orgunits子命令族的一员，面向需要以脚本化、可重复方式搭建企业目录结构的运维与管理员。读完本文，你将掌握该命令的完整用法、参数语义、底层 API 调用链（基于 Google Admin SDK Directory API 的Orgunits.Insert）、前置权限要求、输出格式选项以及相关的测试验证方式，能够直接在你的终端中落地创建组织单位的操作。
命令概览与别名
该命令位于gog admin orgunits命令族下，完整用法为：
gog admin orgunits (org-units,ou) create (add,new) <name> [flags]从源码看，子命令与别名定义在 internal/cmd/admin_orgunits.go：
type AdminOrgunitsCmd struct { List AdminOrgunitsListCmd `cmd:"" name:"list" aliases:"ls" help:"List organizational units"` Get AdminOrgunitsGetCmd `cmd:"" name:"get" aliases:"info,show" help:"Get organizational unit details"` Create AdminOrgunitsCreateCmd `cmd:"" name:"create" aliases:"add,new" help:"Create an organizational unit"` Update AdminOrgunitsUpdateCmd `cmd:"" name:"update" aliases:"edit,set" help:"Update an organizational unit"` Delete AdminOrgunitsDeleteCmd `cmd:"" name:"delete" aliases:"rm,del,remove" help:"Delete an organizational unit"` }因此以下写法完全等价：
gog admin orgunits create Engineering gog admin orgunits add Engineering gog admin orgunits new Engineering gog admin ou create Engineering gog admin org-units create Engineeringgog admin orgunits命令族还包含 get、list、update、delete 等子命令，详见 gog admin orgunits，其父命令为 gog admin。
位置参数与业务参数
create子命令接受一个必选位置参数和两个可选业务参数，定义于 internal/cmd/admin_orgunits.go：
type AdminOrgunitsCreateCmd struct { Name string `arg:"" name:"name" help:"Org unit name"` Parent string `name:"parent" help:"Parent org unit path" default:"/"` Description string `name:"description" help:"Description"` }| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
<name> | string（位置参数） | 是 | 新建组织单位的名称。源码中会先TrimSpace去除首尾空白；若为空则报错org unit name required |
--parent | string | 否 | 父组织单位路径，默认值为/（即根目录）。传入/Product这类以/开头的路径即可 |
--description | string | 否 | 组织单位的描述信息，同样会被去除首尾空白后写入 |
默认父路径与参数清洗逻辑
create的参数清洗与默认值逻辑在 internal/cmd/admin_orgunit_plan.go 中实现：
func newAdminOrgUnitCreatePlan(input adminOrgUnitCreateInput) (adminOrgUnitCreatePlan, error) { name := strings.TrimSpace(input.Name) if name == "" { return adminOrgUnitCreatePlan{}, usage("org unit name required") } parent := strings.TrimSpace(input.Parent) if parent == "" { parent = "/" } return adminOrgUnitCreatePlan{ Request: &admin.OrgUnit{ Name: name, ParentOrgUnitPath: parent, Description: strings.TrimSpace(input.Description), }, }, nil }值得注意的两点实现事实：
- 名称必填：
<name>为空（或全为空白）时，命令直接以org unit name required的用法错误退出； - 父路径兜底：
--parent即使显式传入空字符串，也会被回退为/，保证组织单位始终挂在某个父节点之下（根路径为/）。
底层执行流程与 Admin SDK API 调用
create子命令的Run方法（internal/cmd/admin_orgunits.go）按以下顺序执行：
- 构建创建计划
adminOrgUnitCreatePlan（即上文的参数清洗与默认值处理）； - 调用
dryRunExit(ctx, flags, "admin.orgunits.create", plan.Request)检查是否处于--dry-run模式——若启用则只打印将要执行的动作并成功退出，不会真正改动云端数据； - 调用
requireAdminAccount(flags)校验账户； - 通过
adminOrgUnitDirectoryService(ctx, account)获取 Admin SDK Directory 服务（见 internal/cmd/runtime_services.go）； - 调用 Directory API 的
Orgunits.Insert(adminCustomerID, plan.Request)创建组织单位，其中adminCustomerID固定为"my_customer"（见 internal/cmd/admin_common.go），表示操作当前 Workspace 客户域； - 按输出模式输出结果：JSON 模式下输出 API 返回的完整
OrgUnit对象，普通模式下打印Created org unit: <name> (<path>)。
created, err := svc.Orgunits.Insert(adminCustomerID, plan.Request).Context(ctx).Do() if err != nil { return wrapAdminOrgUnitDirectoryError(err, account) } if outfmt.IsJSON(ctx) { return outfmt.WriteJSON(ctx, stdoutWriter(ctx), created) } u.Out().Linef("Created org unit: %s (%s)", created.Name, created.OrgUnitPath)成功创建后，API 返回的OrgUnit对象会带上服务端生成的OrgUnitPath（如/Engineering）与OrgUnitId，可用get/list子命令复核。
前置条件：账户与权限要求
创建组织单位属于管理类写操作，requireAdminAccount（internal/cmd/admin_common.go）会强制要求使用Google Workspace 账户，普通消费者账户（gmail.com / googlemail.com）会被直接拒绝：
Admin SDK Directory API requires a Google Workspace account with domain-wide delegation; consumer accounts (gmail.com/googlemail.com) are not supported.
同时，wrapAdminOrgUnitDirectoryError（internal/cmd/admin_common.go）会针对常见失败场景给出可操作的错误提示：
accessNotConfigured/Admin SDK API has not been used：提示先在 Google Cloud Console 启用 Admin SDK API（admin.googleapis.com）；insufficientPermissions/Not Authorized：提示服务账号需启用admin.directory.orgunit作用域的域级委派（domain-wide delegation）；domain_wide_delegation/invalid_grant：提示在 Google Workspace 管理控制台正确配置域级委派。
因此，运行本命令前请确保：已配置 Workspace 管理员账户（--account指定或--acct别名），并具备admin.directory.orgunit读写作用域的授权。
完整 Flags 参考
除业务参数外，gog admin orgunits create继承 gogcli 全部全局标志，完整清单如下（与 docs/commands/gog-admin-orgunits-create.md 一致）：
| Flag | 类型 | 默认值 | 说明 |
|---|---|---|---|
--access-token | string | 直接使用提供的访问令牌（绕过已存储的刷新令牌；令牌约 1 小时过期） | |
-a--account--acct | string | 用于 Google API 认证命令的账户邮箱、别名或auto | |
--client | string | OAuth 客户端名称（选择已存储的凭据与令牌桶） | |
--color | string | auto | 彩色输出：auto\|always\|never |
--description | string | 组织单位描述 | |
--disable-commands | string | 逗号分隔的禁用命令列表；支持点路径 | |
-n--dry-run--dryrun--noop--preview | bool | 不做任何修改；打印预期动作并以成功状态退出 | |
--enable-commands | string | 逗号分隔的启用命令前缀列表；支持点路径（限制 CLI 可用范围） | |
--enable-commands-exact | string | 逗号分隔的精确启用命令列表；支持点路径，父命令不会自动启用子命令 | |
-y--force--assume-yes--yes | bool | 跳过破坏性命令的确认提示 | |
--gmail-no-send | bool | false | 阻止 Gmail 发送操作（Agent 安全开关） |
-h--help | kong.helpFlag | 显示上下文相关帮助 | |
--home | string | 覆盖 gogcli 配置/数据/状态/缓存根目录（等价于GOG_HOME） | |
-j--json--machine | bool | false | 向 stdout 输出 JSON（最适合脚本化处理） |
--no-input--non-interactive--noninteractive | bool | 永不提示；改为直接失败（适合 CI） | |
--parent | string | / | 父组织单位路径 |
-p--plain--tsv | bool | false | 向 stdout 输出稳定、可解析的纯文本（TSV，无颜色） |
--quota-project | string | 用于 API 用量计费的 Google Cloud 项目（以X-Goog-User-Project头发送；部分 API 在--access-token或 ADC 模式下要求此参数） | |
--readonly | bool | false | 运行时阻止变更型 API 请求；auth add也仅申请只读 OAuth 作用域 |
--results-only | bool | JSON 模式下仅输出主结果（丢弃nextPageToken等信封字段） | |
--select--pick--project | string | JSON 模式下按逗号分隔选择字段（尽力而为，支持点路径）。更推荐使用--fields | |
-v--verbose | bool | 开启详细日志 | |
--version | kong.VersionFlag | 打印版本并退出 | |
--wrap-untrusted | bool | false | JSON/raw 输出中，将抓取到的文本字段包裹在外部不可信内容标记中 |
实战示例
1. 在根目录下创建组织单位
gog admin orgunits create Engineering输出示例：
Created org unit: Engineering (/Engineering)2. 指定父路径与描述
gog admin orgunits create Frontend --parent /Engineering --description "Web frontend team"3. 使用别名与账户指定
gog admin ou add Frontend --parent /Engineering --acct admin@example.com4. 预演模式（不真正创建）
gog admin orgunits create Engineering --dry-run--dry-run（别名-n/--noop/--preview）会调用dryRunExit（见 internal/cmd/dryrun.go）打印预期动作后成功退出，适合在批量建 OU 前校验脚本；对应的端到端测试位于 internal/cmd/dryrun_e2e_test.go。
5. 脚本化：JSON 输出
gog admin orgunits create Analytics --jsonJSON 模式直接输出 Admin SDK 返回的OrgUnit对象（含orgUnitPath、orgUnitId、parentOrgUnitPath等字段），方便被下游脚本消费；配合--results-only可只保留主结果。
输出校验与后续操作
创建成功后，可以用同族的 list（--parent、--type支持）或 get 验证结果。list的表格输出列定义在 internal/cmd/admin_presentation.go，包含PATH、NAME、ID、PARENT、DESCRIPTION五列：
gog admin orgunits list gog admin orgunits get /Engineering需要调整名称、父路径或描述时使用 update；需要移除组织单位时使用 delete（该命令为破坏性操作，会触发确认提示，可通过-y/--force跳过）。完整命令索引见 docs/commands/README.md。
测试与实现佐证
仓库为创建计划的参数处理提供了单元测试（internal/cmd/admin_orgunit_plan_test.go），可验证三个关键行为：
- 首尾空白清理：
Name: " Engineering "会被整理为Engineering，Parent: " /Product "会被整理为/Product； - 默认父路径：未传
--parent时ParentOrgUnitPath为/； - 名称必填校验：空名称返回
org unit name required（见同文件TestNewAdminOrgUnitPlanValidation）。
总结
gog admin orgunits create将 Google Workspace 管理控制台中"新建组织单位"的操作完整映射为一条可脚本化、可预演、可 JSON 输出的 CLI 命令。其核心链路为：参数清洗（admin_orgunit_plan.go）→ 账户与权限校验（admin_common.go）→ Admin SDK Directory APIOrgunits.Insert。结合--dry-run预演、--json结构化输出以及同族的list/get/update/delete子命令，可以安全、高效地以代码方式维护整个 Workspace 的组织架构。
【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
