gogcli 的 Google Classroom 终端控制台：`gog classroom` 命令完全指南

gogcli 的 Google Classroom 终端控制台gog classroom命令完全指南【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog classroom是 gogcliGoogle Workspace in your terminal为 Google Classroom 提供的一整套终端命令入口让教师、管理员和脚本开发者无需打开浏览器即可完成课程管理、作业发布、公告推送、花名册维护与成绩评定。读完本文你将掌握gog classroom的完整命令树、全部子命令的用法与别名、全局 Flag 的含义以及如何借助 JSON/TSV 输出、dry-run 与只读模式安全地集成到自动化脚本中。命令入口与整体结构gog classroom是 gogcli 针对 Google Classroom API 的二级命令组。根据 命令参考文档其调用形式为gog classroom (class) command [flags]其中class是命令组自带的别名即gog classroom与gog class等价。在源码中命令组定义于 internal/cmd/classroom.goClassroomCmd结构体通过cmd:标签注册了 13 个下辖命令组并逐一配置了别名子命令别名功能coursescourse课程管理增删改查、归档、加入/退出studentsstudent课程学生花名册teachersteacher课程教师花名册rostermembers课程花名册学生 教师合并视图courseworkwork作业/课程作业管理materialsmaterial课程作业资料submissionssubmission学生提交与评分announcementsannouncement,ann公告管理topicstopic主题Topic管理invitationsinvitation,invites课程邀请guardiansguardian监护人管理guardian-invitationsguardian-invites监护人邀请profileme用户档案当前用户简写me文档由gog schema --json自动生成页面顶部标注了不要手工编辑请运行make docs-commands因此本文描述的 Flag 与子命令与当前源码严格一致。认证与权限作用域所有 Classroom 命令都通过 OAuth 用户认证访问 Google Classroom API。在 internal/googleapi/classroom.go 中服务通过newGoogleServiceForAccount(ctx, email, googleauth.ServiceClassroom, classroom, classroom.NewService)创建即每个命令都会按--account/--acct指定的账号解析 OAuth 凭据。Classroom 服务的作用域在 internal/googleauth/service.go 中集中声明共 10 个classroom.courses classroom.rosters classroom.coursework.students classroom.coursework.me classroom.courseworkmaterials classroom.announcements classroom.topics classroom.guardianlinks.students classroom.profile.emails classroom.profile.photos这意味着一次gog auth add account --services classroom授权即可覆盖课程、花名册、作业、公告、主题、监护人等全部 Classroom 功能。若授权时漏掉该服务调用时会触发权限错误详见下文错误处理一节。若需以其他 Google 服务联动使用例如把作业同步到 Gmail可在gog auth add时同时声明多个--services。课程管理gog classroom courses课程是整个 Classroom 数据模型的根。courses命令组在 internal/cmd/classroom_courses.go 中注册了 10 个动作命令。列出课程gog classroom courses list [--state ACTIVE,ARCHIVED] [--teacher id] [--student id] [--max 100] [--all]list是 courses 的默认子命令default:withargs别名ls支持按课程状态、教师、学生过滤。课程状态取值在源码中定义为四个常量classroom_courses.go状态值含义ACTIVE进行中的课程ARCHIVED已归档课程PROVISIONED已创建但尚未接受教学邀请的课程DECLINED已拒绝教学邀请的课程分页由--max默认 100、--page/--cursor、--all别名--all-pages控制--fail-empty别名--non-empty、--require-results可在无结果时以退出码 3 结束便于脚本判断。从实现看classroom_courses.go列表请求直接透传CourseStates、TeacherId、StudentId到 ClassroomCourses.ListAPI。查看与创建课程gog classroom courses get courseId gog classroom courses create --name 计算机科学导论 --section 2026-A \ --description-heading CS101 --description ... --room A301 \ [--owner me] [--state ACTIVE]get别名info、show接受课程 ID 或课程别名文本输出为key\tvalue格式依次展示 id、name、section、description_heading、description、room、state、owner、enrollment_code、link。create别名add、new的--name为必填项--owner默认me创建前会先经过buildClassroomCourseCreatePlan校验并在 dry-run 模式下打印将要创建的课程结构而不实际调用 APIclassroom_courses.go。更新、归档与状态一致性等待gog classroom courses update courseId [--name ...] [--section ...] [--state ACTIVE] gog classroom courses archive courseId # 别名 arch gog classroom courses unarchive courseId # 别名 unarch, restoreupdate别名edit、set采用 PATCH updateMask的方式只更新用户显式传入的字段classroom_courses.go。archive与unarchive本质上都是update --state但实现上使用了独立的操作名classroom.courses.archive/classroom.courses.unarchive并调用waitForClassroomCourseState轮询课程状态直至与目标一致——因为 Classroom 的状态变更存在最终一致性延迟。轮询延迟序列定义在 classroom_courses.go0ms, 200ms, 500ms, 1s, 2s, 3s, 4s, 5s若在轮询窗口内始终读不到目标状态命令会以可重试退出码结束并提示稍后重试classroom_courses.go这正是gog classroom courses state-visibility相关测试classroom_courses_state_visibility_test.go覆盖的行为。删除课程必须先归档gog classroom courses delete courseId # 别名 rm, del, remove删除是破坏性操作命令会先触发 dry-run 检查与交互确认dryRunAndConfirmDestructive并且只允许删除已归档ARCHIVED的课程。若课程仍处于其他状态会得到精确的错误提示classroom_courses.goACTIVE提示先归档gog classroom courses archive courseIdPROVISIONED提示先接受教学邀请再归档后删除DECLINED提示已拒绝的课程无法删除或恢复。加入、退出与 URLgog classroom courses join courseId [--role student|teacher] [--user id] [--enrollment-code XXX] gog classroom courses leave courseId [--role student|teacher] [--user id] gog classroom courses url courseId...join别名enroll默认以student身份加入学生加入时可通过--enrollment-code携带注册码--user默认me也支持代他人加入。leave别名unenroll是破坏性操作同样需要 dry-run 确认。url别名link接受一个或多个课程 ID逐个查询并输出课程在 Classroom 网页端的AlternateLink。作业与内容管理coursework、materials、announcements、topics作业Courseworkgog classroom coursework list courseId [--state DRAFT,PUBLISHED] [--topic topicId] [--scan-pages 3] gog classroom coursework get courseId courseworkId gog classroom coursework create courseId --title 第三章作业 \ --type ASSIGNMENT --max-points 100 --due 2026-10-01 23:59 --state PUBLISHED作业命令组在 internal/cmd/classroom_coursework.go 定义包含 list/get/create/update/delete/assignees。--type支持ASSIGNMENT、SHORT_ANSWER_QUESTION、MULTIPLE_CHOICE_QUESTION默认ASSIGNMENT。截止时间--due接受 RFC3339 或YYYY-MM-DD [HH:MM]格式也可拆分为--due-date与--due-time分别指定日期解析与格式化集中在 internal/cmd/classroom_helpers.go例如parseClassroomDue会把输入统一按 UTC 换算成DateTimeOfDay。值得注意的细节list提供--topic按主题过滤由于 API 不直接支持按 topic 过滤实现会在最多--scan-pages默认 3页内逐页扫描并收集匹配项scanClassroomTopicPages见 classroom_helpers.go。公告Announcementsgog classroom announcements list courseId [--state PUBLISHED,DRAFT] gog classroom announcements create courseId --text 本周五停课一次 [--state PUBLISHED] [--scheduled RFC3339] gog classroom announcements update courseId announcementId [--text ...] [--state ...] gog classroom announcements delete courseId announcementId公告组在 internal/cmd/classroom_announcements.go 定义额外提供assignees子命令别名assign用于调整公告的收件人范围--mode ALL_STUDENTS|INDIVIDUAL_STUDENTS配合--add-student/--remove-student逗号分隔精确增删个别学生。公告的assignees底层调用ModifyAssignees接口classroom_announcements.go。主题Topics与资料Materialsgog classroom topics list courseId # 别名 ls gog classroom topics create courseId --name 第三章 gog classroom topics update courseId topicId --name 第三章改 gog classroom topics delete courseId topicId gog classroom materials list courseId # 别名 ls gog classroom materials get courseId materialId主题组classroom_topics.go提供 list/get/create/update/delete其中list返回 id、name、updateTime 等字段。资料组classroom_materials.go围绕课程作业资料coursework materials提供 list/get/create/update/delete。花名册与人students、teachers、roster、invitations、guardians、profile学生与教师gog classroom students list courseId # 别名 ls gog classroom students get courseId userId gog classroom students add courseId userId [--enrollment-code XXX] gog classroom students remove courseId userId gog classroom teachers list courseId gog classroom teachers add courseId userId gog classroom teachers remove courseId userId学生组在 internal/cmd/classroom_rosters.go 定义教师组在同一文件内。get输出会额外展示学生的work_folderClassroom 自动分配的学生作业 Drive 文件夹 IDadd是写操作会先经过 dry-run 检查classroom_rosters.go。roster别名members则是一次性合并展示学生与教师的汇总视图。邀请、监护人、档案gog classroom invitations list | get invitationId | create | delete | accept gog classroom guardians list courseId | get courseId guardianId | delete courseId guardianId gog classroom guardian-invitations list courseId | get | create gog classroom profile get userId # 别名 me邀请组负责课程加入邀请的创建、查询、删除与接受监护人guardians与监护人邀请用于中小学场景的家长通知profile用于查询用户档案me别名可直接查当前登录用户。作业提交与评分gog classroom submissionsgog classroom submissions list courseId courseworkId \ [--state NEW,CREATED,TURNED_IN,RETURNED,RECLAIMED_BY_STUDENT] [--late late|not-late] [--user id] gog classroom submissions get courseId courseworkId submissionId gog classroom submissions turn-in courseId courseworkId submissionId # 别名 turnin gog classroom submissions reclaim courseId courseworkId submissionId # 别名 undo gog classroom submissions return courseId courseworkId submissionId # 别名 send gog classroom submissions grade courseId courseworkId submissionId --grade 95 # 别名 set, edit提交组在 internal/cmd/classroom_submissions.go 定义。list的--late参数会映射为 API 的LATE_ONLY/NOT_LATE_ONLY过滤classroom_submissions.go--state支持五种提交状态过滤。grade用于设置草稿/已定稿成绩return对应教师退回提交turn-in/reclaim模拟学生端的交卷与撤回。全局 Flags每个命令都可用所有gog classroom子命令均继承下表所示的全局 Flag与 命令参考文档 的 Flags 表一致Flag类型默认说明--access-tokenstring直接使用提供的访问令牌绕过已存储的 refresh token令牌约 1 小时后过期-a--account--acctstring认证账号邮箱、别名或 auto用于所有需要认证的 Google API 命令--clientstringOAuth 客户端名称选择已存储的凭据与令牌桶--colorstringauto彩色输出auto|always|never--disable-commandsstring逗号分隔的禁用命令列表支持点路径-n--dry-run--dryrun--noop--previewbool不实际修改打印预期操作并以成功退出写命令可用--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径限制 CLI 范围--enable-commands-exactstring逗号分隔的精确启用命令列表父命令不会连带启用子命令-y--force--assume-yes--yesbool跳过破坏性命令的交互确认--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全开关-h--helpkong.helpFlag显示上下文相关的帮助--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j--json--machineboolfalse向 stdout 输出 JSON最适合脚本化--no-input--non-interactive--noninteractivebool永不提示直接失败适合 CI-p--plain--tsvboolfalse输出稳定、可解析的文本TSV无颜色--quota-projectstring计费的 Google Cloud 项目以X-Goog-User-Project发送部分 API 配合--access-token或 ADC 需要--readonlyboolfalse运行时阻止所有修改类 API 请求auth add也会只请求只读 OAuth 作用域--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等信封字段--select--pick--projectstringJSON 模式下按逗号分隔选择字段尽力而为支持点路径多数命令更推荐使用--fields-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中为抓取的文本字段包裹外部不可信内容标记其中对 Classroom 场景最常用的是--account指定操作身份、-j/--json输出结构化结果、-p/--plain输出 TSV 便于awk/cut处理、-n/--dry-run预览写操作、-y跳过破坏性确认以及--readonly在自动化巡检场景下提供双重保险运行时拦截修改请求。输出与分页把 Classroom 数据接入脚本gog classroom系列命令在文本模式下输出key\tvalue或表格在 JSON 模式下输出带信封字段如nextPageToken的结构化对象。列表命令统一支持--max别名--limit单页大小默认 100--page别名--cursor翻页令牌用于手动分页--all别名--all-pages自动拉取全部页面--fail-empty别名--non-empty、--require-results无结果时以退出码 3 结束。JSON 输出时加上--results-only可只保留主结果数组方便直接喂给jq。典型组合示例# 列出所有进行中的课程输出 JSON 供 jq 处理 gog classroom courses list --state ACTIVE --all -j --results-only # 以 TSV 输出课程 ID 与名称便于逐行处理 gog classroom courses list -p # 自动化评分先预览再执行 gog classroom submissions grade c w s --grade 90 -n gog classroom submissions grade c w s --grade 90 -y错误处理与故障排查Classroom 相关的 API 错误会被wrapClassroomErrorclassroom_helpers.go统一包装并给出可执行的修复提示accessNotConfigured/ Classroom API has not been usedClassroom API 未在 Google Cloud 控制台启用提示前往 API 库启用classroom.googleapis.cominsufficientPermissions/ insufficient authentication scopes当前账号缺少 Classroom 权限提示重新执行gog auth add account --services classroom补齐作用域。配合 gog-auth-add、gog-auth-status 可以随时核查当前账号的授权服务与状态。所有写操作都遵循 gogcli 统一的 dry-run / 确认机制可在生产环境放心编排。相关资源命令总览gog classroom 与命令索引核心实现classroom.go、classroom_helpers.go、googleapi/classroom.go授权作用域googleauth/service.go测试验证classroom_courses_state_visibility_test.go、classroom_helpers_test.go、execute_classroom_more_commands_test.go认证相关gog auth、gog auth add、gog auth services通用安全机制safety-profiles【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考