gogcli 实战用gog classroom submissions turn-in在终端中提交 Google Classroom 学生作业【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读gog classroom submissions turn-in是 gogcliGoogle Workspace in your terminal提供的 Classroom 作业提交命令它把 Google Classroom API 的「学生提交作业」turn in操作封装为一条可复制的终端命令。本文将以该命令为骨架讲解它的完整用法、三个必填参数的含义、全局 Flags 的实际作用并结合 internal/cmd/classroom_submissions.go 的源码剖析其内部执行流程账号解析 → dry-run 拦截 → Classroom API 调用 → 结构化输出帮助你掌握在脚本、CI 与 Agent 场景下安全、可自动化地管理作业提交状态。一、命令定位submissions 家族中的「提交」动作turn-in是gog classroom submissions子命令族的一员与其并列的还有list、get、reclaim、return、grade。从源码看ClassroomSubmissionsCmd 将这些动作统一定义在internal/cmd/classroom_submissions.go中list别名ls列出学生提交get别名info,show查看单个提交详情turn-in别名turnin提交作业本文主角reclaim别名undo回收提交学生撤回已交作业return别名send批改后返还提交grade别名set,edit设置草稿/正式分数turn-in对应 Google Classroom 工作流中的「学生把作业交给老师」在真实教学场景中通常用于学生未能在截止前完成时由教师代为提交、测试环境自动化回归、以及脚本批量处理特定学生的提交状态。二、完整用法与位置参数命令的完整语法如下其中(turnin)表示别名gog classroom (class) submissions (submission) turn-in (turnin) courseId courseworkId submissionId即三个必填位置参数依次为位置参数含义获取方式courseId课程 ID 或课程别名gog classroom courses listcourseworkId作业CourseWorkIDgog classroom coursework list courseIdsubmissionId学生提交 IDgog classroom submissions list courseId courseworkId一个最小可运行示例gog classroom submissions turn-in 123456789 987654321 555111333从源码看这三个参数分别映射到ClassroomSubmissionsTurnInCmd结构体的三个字段classroom_submissions.go#L180-L184并在submissionAction中先做strings.TrimSpace去空格、再逐一校验非空任一为空都会以usage(empty courseId)之类的错误立即返回不会发起任何 API 请求。2.1 别名速记turn-in是官方命令名同时支持别名turnin两者等价gog classroom submissions turnin courseId courseworkId submissionId配合父级命令的别名list→ls你可以写出很短的命令行。三、定位目标先 list 再 turn-in 的完整工作流由于submissionId是课程、作业、学生三重维度下的标识最稳妥的取数方式是先用list命令拿到目标提交。gog classroom submissions list支持以下过滤器见 gog-classroom-submissions-list.md# 查看某作业下所有「已创建但未提交」的学生作业 gog classroom submissions list courseId courseworkId --state CREATED --user studentexample.com # 只看迟交的提交 gog classroom submissions list courseId courseworkId --late late其中--state接受逗号分隔的提交状态枚举NEW,CREATED,TURNED_IN,RETURNED,RECLAIMED_BY_STUDENT--user支持按用户 ID 或邮箱过滤--max/--limit默认 100 条--all/--all-pages可拉取全部分页--fail-empty可在无结果时以退出码 3 结束适合 CI 断言。这些过滤器在源码中逐一映射到 Classroom List API 的参数classroom_submissions.go#L57-L88。拿到submissionId之后再执行提交操作就构成了完整的「查找 → 提交」链路。四、全局 Flags 详解turn-in除了三个位置参数还继承了 gogcli 的全局 Flags。下表完整列出源自文档与gog schema --json生成的命令参考Flag类型默认值说明--access-tokenstring直接使用提供的 access token绕过存储的 refresh tokentoken 约 1 小时过期-a--account--acctstring指定账号邮箱、别名或auto用于已认证的 Google API 命令--clientstringOAuth client 名称选择对应存储的凭据与 token 桶--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以 JSON 输出到 stdout最适合脚本--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 输出中为外部获取的文本字段包裹 untrusted-content 标记五、源码级解析turn-in内部到底做了什么gog classroom submissions turn-in的执行路径非常清晰。命令的Run方法classroom_submissions.go#L186-L188把三个参数与动作名turn-in一起交给公共函数submissionActionclassroom_submissions.go#L210-L276后者依次执行四个阶段5.1 参数校验对三个 ID 逐一TrimSpace并判空任一为空立即usage(...)报错返回。这意味着空参数不会消耗 API 配额也不会触碰认证链路。5.2 Dry-run 拦截if err : dryRunExit(ctx, flags, classroom.submissions.action, map[string]any{ course_id: courseID, coursework_id: courseworkID, submission_id: submissionID, action: action, }); err ! nil { return err }当指定-n/--dry-run时命令会在访问 keyring 或发起任何 API 调用之前就打印出将要执行的操作操作路径为classroom.submissions.turn-in附带课程/作业/提交 ID并成功退出。这是 gogcli 对破坏性操作的重要安全机制——你可以在真实执行前用 dry-run 验证参数是否正确。5.3 账号解析与 Classroom 服务构建requireAccount(flags)负责解析账号支持--account/--acct/-a传入邮箱、别名或autoADC 模式等场景有专门的占位处理见 internal/cmd/account.go。随后classroomService(ctx, account)定义于 internal/cmd/runtime_services.go#L241-L247按需惰性初始化 Classroom API 客户端。5.4 真正的 API 调用case turn-in: if _, err : svc.Courses.CourseWork.StudentSubmissions.TurnIn(courseID, courseworkID, submissionID, classroom.TurnInStudentSubmissionRequest{}).Context(ctx).Do(); err ! nil { return wrapClassroomError(err) }它调用的是 Google Classroom Go SDK 的StudentSubmissions.TurnIn方法请求体为空的TurnInStudentSubmissionRequest。与reclaim对应ReclaimStudentSubmissionRequest、return对应ReturnStudentSubmissionRequest共用同一套submissionAction骨架只是动作字符串不同这体现了该模块「一次校验、多个动作复用」的设计。所有 API 错误统一经过wrapClassroomErrorinternal/cmd/classroom_helpers.go#L15-L29包装会给出可操作的修复提示若返回accessNotConfigured/Classroom API has not been used提示需要先在 Google Cloud Console 启用 Classroom API若返回insufficientPermissions/insufficient authentication scopes提示重新认证gog auth add account --services classroom。六、输出格式终端可读与机器可解析命令成功后根据输出模式不同有两种结果默认表格/键值文本输出ok true course_id 123456789 coursework_id 987654321 submission_id 555111333 action turn-inJSON 模式-j/--json{ ok: true, courseId: 123456789, courseworkId: 987654321, submissionId: 555111333, action: turn-in }JSON 字段名使用 camelCasecourseId等而纯文本键使用 snake_casecourse_id脚本解析时需注意这一差异。这两种输出都由 submissionAction 尾部按outfmt.IsJSON(ctx)分支生成。七、实战示例与组合用法# 1. 列出某作业的提交找到目标学生 gog classroom submissions list 123456789 987654321 --user studentexample.com # 2. 预演提交操作不真正执行 gog classroom submissions turn-in 123456789 987654321 555111333 --dry-run # 3. 正式提交并以 JSON 输出供脚本消费 gog classroom submissions turn-in 123456789 987654321 555111333 -j # 4. 在 CI 中组合使用非交互、禁止提示、机器可读 gog classroom submissions turn-in 123456789 987654321 555111333 --no-input --json注意事项turn-in属于变更型mutating操作--readonly模式下会被运行时拦截若你的账号只有只读 OAuth 范围调用会因权限不足而失败需按提示用gog auth add account --services classroom重新授权提交完成后若需继续批改流程可衔接gog classroom submissions return courseId courseworkId submissionId返还作业或gog classroom submissions grade courseId courseworkId submissionId --assigned 90打分批量场景中建议先list过滤出目标状态如CREATED再逐个 turn-in避免对已提交的作业做无效操作。八、相关命令与延伸阅读父命令gog classroom submissions含全部 6 个子命令索引同类动作reclaim回收、return返还、grade打分它们的实现共用 submissionAction 骨架行为一致定位目标gog classroom submissions list含--state/--late/--user过滤器完整命令索引Command index源码入口internal/cmd/classroom_submissions.go、internal/cmd/classroom_helpers.go、internal/cmd/runtime_services.go【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考