gogcligog admin users create实战指南用命令行在 Google Workspace 中创建用户【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本指南以 gogcli 项目Google Workspace in your terminal的gog admin users create命令为核心完整讲解其用法、全部命令行参数、密码生成与预哈希密码导入机制、创建后的状态修补行为以及基于 Admin SDK Directory API 的底层实现原理。读完本文你将能够在终端中一键创建 Workspace 用户并将其接入组织单元、恢复信息与安全策略同时理解源码级的关键行为与测试验证方式。命令概览与适用前提gog admin users create是 gogcli 中用于在 Google Workspace 中创建新用户的命令位于 gog admin users 子命令树下。其官方说明为 Create a new user命令别名支持add与new两种形式gog admin users create (add,new) email [flags]在使用该命令前需要明确以下适用前提来源workspace-admin.md仅限 Workspace 账户Admin SDK Directory API 要求 Google Workspace 账户并配合域名级委派domain-wide delegation个人gmail.com/googlemail.com消费级账户不受支持。源码在 requireAdminAccount 中强制了这一约束。需要管理员权限建议以服务账户密钥配合域名级委派并模拟impersonate一个 Workspace 管理员账户gog auth service-account set adminexample.com --key ~/Downloads/service-account.json gog auth service-account status adminexample.com服务账户需被委派 Admin SDK 作用域可通过gog auth services --json查看所需 scope 列表。用户管理相关的 scope 为admin.directory.user以及 group 相关 scope。从源码结构看该命令由 internal/cmd/admin_users.go 中的AdminUsersCreateCmd结构体定义父命令AdminUsersCmd将create注册为name:create aliases:add,new与文档中的(add,new)别名一致。基础用法显式密码创建用户最常见的用法是指定初始密码并创建用户gog --account adminexample.com admin users create adaexample.com \ --first-name Ada \ --last-name Lovelace \ --password TempPass123! \ --change-password \ --ou /Engineering各参数含义如下参数说明--first-name/--given/--fn/--given-name名Given name必填--last-name/--family/--ln/--family-name姓Family name必填--password/--pass初始密码省略时由 gog 自动生成--change-password要求用户首次登录时修改密码--ou/--org-unit组织单元路径如/Engineering命令执行成功后终端会输出Created user: adaexample.com (ID: user-123)自动生成密码最安全的默认行为若省略--passwordgog 会自动生成一个强临时密码强制用户在首次登录时修改并将生成的密码打印在输出中gog --account adminexample.com admin users create graceexample.com \ --given Grace \ --family Hopper \ --json{email:graceexample.com,id:user-456,generatedPassword:Xx9!...}这一行为背后有明确的源码逻辑internal/cmd/admin_users.go当plan.GeneratePassword为 true 时调用generateAdminUserPassword(16)生成 16 位密码生成函数 generateAdminUserPassword 保证密码同时包含小写字母、大写字母、数字与特殊字符四类字符集并通过加密随机源crypto/rand打乱顺序最低长度为 8无论是否显式传密码只要--change-password被设置或密码为自动生成ChangePasswordAtNextLogin都会被置为 trueadmin_user_create_plan.go。在 admin_user_create_plan_test.go 的测试TestNewAdminUserCreatePlanGeneratesPassword中验证了省略密码时GeneratePassword为 true、ChangePasswordAtNextLogin为 true且 dry-run 负载中的密码状态为generated。创建受限状态用户与恢复信息可以在创建时就将用户置于受限状态或附加恢复元数据workspace-admin.md 中的示例gog --account adminexample.com admin users create tempexample.com \ --given Temp \ --family User \ --suspended \ --recovery-email helpdeskexample.com \ --recovery-phone 15551234567参数说明--suspended创建为已暂停状态--archived创建为已归档状态--recovery-email恢复邮箱地址需为合法邮箱格式--recovery-phone恢复手机号E.164 格式如15551234567值得注意的源码细节是两阶段创建admin_user_create_plan.go 与 admin_users.go当--suspended或--archived被指定时创建计划会额外生成一个StatePatch在Users.Insert创建成功后立即对用户执行一次 PATCH以设置受限状态。原因在于部分受限状态字段无法在创建请求中直接生效或需要用户实体已存在。admin_users.go 中的patchAdminUserState还包含一个容错细节创建后立即 PATCH 可能遇到瞬时 404用户实体尚未完全传播此时会以 500ms 间隔重试最多 6 次。这一重试逻辑被测试 TestAdminUsersCreate_JSONSendsWorkspaceUser 覆盖该测试断言 patch 首次返回 404 后重试成功patchCalls最终为 2。预哈希密码导入--hash-function从旧系统迁移用户时可以直接传入预哈希密码及其哈希算法workspace-admin.mdgog --account adminexample.com admin users create importexample.com \ --given Imported \ --family User \ --password sha1-hash \ --hash-function SHA-1支持的哈希算法为MD5、SHA-1与crypt。源码 normalizeAdminUserHashFunction 会对输入做大小写归一化处理md5→MD5、sha1/sha-1→SHA-1、crypt→crypt其余值一律报错invalid --hash-function (expected MD5, SHA-1, crypt)。使用预哈希密码时有两条强制约束admin_user_create_plan.go--password必须同时提供否则报错--password required when --hash-function is set--hash-function值必须属于上述三种算法之一。这两条约束在 admin_user_create_plan_test.go 的TestNewAdminUserCreatePlanValidation表格测试中均有对应用例bad hash与hash without password。完整参数参考下表为gog admin users create支持的全部参数继承自官方生成的命令参考 gog-admin-users-create.md其中包含命令级全局参数FlagTypeDefaultHelp--access-tokenstringUse provided access token directly (bypasses stored refresh tokens; token expires in ~1h)-a--account--acctstringAccount email, alias, or auto for authenticated Google API commands--adminboolNot supported; assign admin roles separately after user creation--archivedboolCreate user in archived state--change-passwordboolRequire password change on first login--clientstringOAuth client name (selects stored credentials token bucket)--colorstringautoColor output: auto|always|never--disable-commandsstringComma-separated list of disabled commands; dot paths allowed-n--dry-run--dryrun--noop--previewboolDo not make changes; print intended actions and exit successfully--enable-commandsstringComma-separated list of enabled command prefixes; dot paths allowed (restricts CLI)--enable-commands-exactstringComma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children--family--family-name--last-name--lnstringFamily (last) name-y--force--assume-yes--yesboolSkip confirmations for destructive commands--given--first-name--fn--given-namestringGiven (first) name--gmail-no-sendboolfalseBlock Gmail send operations (agent safety)--hash-functionstringPassword hash function when --password is pre-hashed (MD5, SHA-1, crypt)-h--helpkong.helpFlagShow context-sensitive help.--homestringOverride gogcli config/data/state/cache root (equivalent to GOG_HOME)-j--json--machineboolfalseOutput JSON to stdout (best for scripting)--no-input--non-interactive--noninteractiveboolNever prompt; fail instead (useful for CI)--org-unit--oustringOrganization unit path--password--passstringInitial password (generated if omitted)-p--plain--tsvboolfalseOutput stable, parseable text to stdout (TSV; no colors)--quota-projectstringGoogle Cloud project to bill for API usage (sent as X-Goog-User-Project; some APIs require it with --access-token or ADC)--readonlyboolfalseBlock mutating API requests at runtime; auth add also requests read-only OAuth scopes--recovery-emailstringRecovery email address--recovery-phonestringRecovery phone number in E.164 format--results-onlyboolIn JSON mode, emit only the primary result (drops envelope fields like nextPageToken)--select--pick--projectstringIn JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands.--suspendedboolCreate user in suspended state-v--verboseboolEnable verbose logging--versionkong.VersionFlagPrint version and exit--wrap-untrustedboolfalseIn JSON/raw output, wrap fetched text fields in external untrusted-content markers几个关键参数的补充说明--admin明确不受支持即使传入也会在参数校验阶段直接报错--admin is not supported; assign admin roles separately after user creationadmin_user_create_plan.go。管理员角色的授予必须在用户创建完成后通过其他管理渠道单独完成这避免了在创建请求中引入权限提升的安全风险。--dry-run用于脚本安全演练gog会在 dry-run 模式下输出计划执行的负载含用户对象与密码状态provided/generated不发起真实创建请求admin_users.go。workspace-admin.md 建议在脚本化执行 create/suspend/delete 前使用gog --account adminexample.com admin users create dryrunexample.com \ --given Dry \ --family Run \ --dry-run \ --json--no-input适合 CI在非交互环境下如流水线配合使用遇到需要确认的场景直接失败而非挂起等待输入。--json输出结构化结果JSON 模式返回email、id、suspended、archived自动生成密码时额外携带generatedPassword字段admin_users.go。输入校验与安全约束创建计划在真正调用 Admin SDK 之前会执行严格的本地校验admin_user_create_plan.goemail 必填且合法空值报email required非法格式报invalid email--given与--family必填分别报--given required、--family required--admin不支持直接拒绝--hash-function合法性仅接受 MD5、SHA-1、crypt且必须配合--password--recovery-email合法性非空时必须为合法邮箱格式。上述规则在 admin_user_create_plan_test.go 与 admin_test.goTestAdminUsersCreate_ValidationErrors中均有完整测试覆盖。所有输入字段都会经过strings.TrimSpace清洗例如测试中的 adaexample.com 会被归一化为adaexample.com。底层原理从命令行到 Admin SDK 的调用链gog admin users create的完整执行链路可以概括为以下步骤依据 internal/cmd/admin_users.go构建创建计划newAdminUserCreatePlan将 CLI 参数email、姓名、密码、组织单元、恢复信息、哈希函数等组装为adminUserCreatePlan内含一个admin.User模板对象校验与密码准备执行上文所述的全部本地校验若未提供密码则调用generateAdminUserPassword生成dry-run 拦截若指定--dry-run输出计划负载并提前成功退出账户与作用域检查requireAdminAccount确认账户为 Workspace 账户拒绝 gmail.com随后建立adminDirectoryService服务插入用户调用 Admin SDK 的Users.Insert通过insertRequest(password)将密码注入请求体注意密码只存在于请求副本中不会污染模板对象admin_user_create_plan.go状态修补若设置了--suspended/--archived创建成功后执行 PATCH带 404 重试输出结果文本模式打印Created user: email (ID: id)与生成的密码JSON 模式输出结构化字段。这一调用链通过 admin_test.go 中的 HTTP 桩测试newAdminTestService模拟 Directory API 响应得到验证测试同时断言了插入请求体中的Password、HashFunctionsha1归一化为SHA-1、ChangePasswordAtNextLogin、OrgUnitPath、恢复信息字段以及创建后的状态 PATCH 行为。此外错误处理层面 wrapAdminDirectoryError 会将常见的 Admin SDK 错误映射为可读提示例如Admin SDK API 未启用 → 提示在 Google Cloud Console 启用admin.googleapis.com权限不足insufficientPermissions→ 提示检查服务账户的域名级委派与admin.directory.user等 scope域名级委派未配置domain_wide_delegation/invalid_grant→ 提示在 Workspace Admin Console 配置。与其他子命令协同gog admin users create属于 gog admin users 子命令树同级的list、get、delete、suspend命令可配合完成用户生命周期的完整管理# 查看域内用户 gog --account adminexample.com admin users list --domain example.com --json # 查看单个用户详情含别名、组织单元、创建时间、最后登录时间 gog --account adminexample.com admin users get adaexample.com --json # 暂停用户需 --force 跳过确认 gog --account adminexample.com admin users suspend adaexample.com --force # 删除用户需 --force 跳过确认 gog --account adminexample.com admin users delete adaexample.com --force示例来源workspace-admin.md。其中list支持--max默认 100、--page/--cursor分页与--all/--all-pages全量拉取get输出 email、姓名、暂停状态、管理员标记、组织单元、创建时间与最后登录时间等字段admin_users.go。需要提醒的是gog admin users create属于写操作。若以 Agent 或自动化脚本方式使用 gogcli请注意 agent-safe.yaml 等安全配置文件默认将admin命令组标记为false禁用以免 Agent 在未授权情况下创建或修改 Workspace 用户。进行此类管理操作时应显式选择包含 admin 能力的配置并配合--dry-run演练。小结gog admin users create是一个功能完整、面向脚本化的 Workspace 用户创建工具它内置强密码自动生成、预哈希密码导入、创建即暂停/归档、恢复信息设置与两阶段状态修补并通过严格的本地校验与 dry-run 机制保障操作安全。其全部行为均有对应源码internal/cmd/admin_users.go、internal/cmd/admin_user_create_plan.go、internal/cmd/admin_common.go与测试internal/cmd/admin_test.go、internal/cmd/admin_user_create_plan_test.go可查证。结合--json输出与--dry-run预演它可以无缝嵌入企业入职自动化的 CI 流水线中。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考