gogcli `gog classroom students list` 命令完全指南：在终端中查询 Google Classroom 学生名单

gogcligog classroom students list命令完全指南在终端中查询 Google Classroom 学生名单【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本篇技术指南围绕 gogcliGoogle Workspace in your terminal的gog classroom students list命令展开讲解如何通过终端快速列出指定 Google Classroom 课程的学生名单包括命令语法、全部可用标志Flags、分页与 JSON 输出、--fail-empty脚本化退出码以及底层分页实现原理。读完本指南你将能在日常管理与自动化脚本中熟练使用该命令并理解其与 classroom API 的映射关系。gog classroom students list是 gogcli 中面向 Google Classroom 课程花名册Roster管理的只读查询命令归属于gog classroom students子命令组该组还包含get查询单个学生、add添加学生、remove移除学生三个操作见 gog-classroom-students.md。列表查询本身不会修改任何数据因此非常适合用于巡检、导出与 CI 集成。命令语法与别名gog classroom (class) students (student) list (ls) courseId [flags]该语法中的括号表示命令级别名aliasclassroom可缩写为classstudents可缩写为studentlist可缩写为ls。因此下面三种写法完全等价gog classroom students list courseId gog class student list courseId gog classroom students ls courseId别名定义在源码 internal/cmd/classroom.goClassroomCmd中Students的aliases:student与 internal/cmd/classroom_rosters.goClassroomStudentsCmd.List声明为default:withargs aliases:ls。需要说明的是由于list是students组的默认子命令default:withargsgog classroom students courseId这种省略list的写法同样会被解析为列出学生。courseId是唯一的必填位置参数positional argument它对应 Google Classroom API 中的 course ID也接受课程别名alias其定义见 internal/cmd/classroom_rosters.go 中CourseID string字段的arg: name:courseId声明。分页与结果控制标志gog classroom students list专有的分页与结果控制标志定义在ClassroomStudentsListCmd结构体中直接映射到 Google Classroom API 的courses.students.list接口分页字段为pageSize/pageToken/nextPageToken。标志类型默认值说明--max--limitint64100单页最多返回的学生数作为 API 的pageSize传入取值必须大于 0否则命令报max must be 0--page--cursorstring空分页令牌page token用于从指定页继续拉取令牌来自上一轮输出的nextPageToken--all--all-pages--allpagesboolfalse自动翻页拉取全部学生忽略nextPageToken分页--fail-empty--non-empty--require-resultsboolfalse当结果为空时以退出码 3 结束便于脚本判断无结果状态这四个标志的解析逻辑位于 internal/cmd/classroom_rosters.go其中Run方法将参数装配成classroomPagedListOptions后交给通用分页器runClassroomPagedList执行见 internal/cmd/classroom_list_helpers.go。分页行为解析分页核心由 internal/cmd/paged_list_helpers.go 的loadPagedItems实现未开启--all只请求当前页返回该页学生列表及nextPageToken若还有下一页开启--all循环调用collectAllPages直至翻完所有页此时结果不再附带nextPageToken。实际发起 API 请求的是 internal/cmd/classroom_list_helpers.go 的fetchClassroomStudentPage它调用svc.Courses.Students.List(courseID).PageSize(pageSize).PageToken(pageToken)读取响应中的Students与NextPageToken。当返回内容有更多页时非 JSON 模式下会在 stderr 输出类似# Next page: --page token的提示--all/--all-pages可跳过翻页。注意Google Classroom API 单次pageSize的上限为 1000而本命令默认--max 100。若课程人数较多建议显式增大--max或直接使用--all一次性获取完整名单。输出格式表格、TSV 与 JSONgog classroom students list的输出由 gogcli 的 outfmt 组件统一管理核心命令标志如下标志类型默认值说明-j--json--machineboolfalse输出 JSON 到 stdout最适合脚本处理-p--plain--tsvboolfalse输出稳定的 TSV 纯文本无颜色便于 parse--results-onlybool空JSON 模式下只输出主结果去掉nextPageToken等信封字段--select--pick--projectstring空JSON 模式下按逗号分隔选择字段支持点路径尽力而为--colorstringauto颜色输出auto/always/never默认表格输出默认情况下按表格输出三列列定义见 internal/cmd/classroom_presentation.go 的classroomStudentColumns列名数据来源USER_IDstudent.UserIdGoogle Classroom 的学生用户 IDEMAILprofileEmail(student.Profile)即UserProfile.EmailAddressNAMEprofileName(student.Profile)优先取Name.FullName否则拼接 GivenName FamilyName姓名/邮箱的取值辅助函数profileName与profileEmail定义在 internal/cmd/classroom_helpers.go。JSON 输出脚本友好gog classroom students list courseId --jsonJSON 负载为信封结构{students: [...], nextPageToken: ...}。其中students是 Google Classroom API 的Student对象数组含userId、profile、studentWorkFolder等完整字段。nextPageToken存在时表示还有更多页可作为下一轮--page的值追加--results-only可只保留students主结果方便 jq 等工具直接消费gog classroom students list courseId --json --results-only信封组装与--results-only的行为在 internal/cmd/classroom_list_helpers.go 的writeClassroomPagedList中实现JSON 模式下写jsonKey此处为studentsnextPageToken非 JSON 模式走表格渲染。空结果与退出码当没有学生时非 JSON 模式在 stderr 输出No students并提示用--all/--all-pages获取全部页无论哪种输出格式若指定了--fail-empty命令以退出码3结束见 internal/cmd/paging.go 的failEmptyExit未指定则正常退出码 0。这在自动化巡检中非常实用例如gog classroom students list courseId --json --fail-empty \ || [ $? -eq 3 ] echo 该课程暂无学生全局标志与认证除命令专属标志外所有 gogcli 命令共享一批全局标志students list同样适用标志类型默认值说明--access-tokenstring空直接使用提供的访问令牌绕过存储的 refresh token令牌约 1 小时过期-a--account--acctstring空认证账号邮箱、别名或auto用于所有 Google API 命令--clientstring空OAuth 客户端名称选择存储的凭据与令牌桶--quota-projectstring空计费用的 Google Cloud 项目作为X-Goog-User-Project头发送部分 API 在--access-token或 ADC 下需要它--readonlyboolfalse运行时阻止一切变更类 API 请求auth add也会请求只读 OAuth scope--homestring空覆盖 gogcli 配置/数据/状态/缓存根目录等价于环境变量GOG_HOME-n--dry-run--dryrun--noop--previewboolfalse不执行变更仅打印预期操作并以成功退出对只读命令无副作用--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全开关--enable-commands/--enable-commands-exact/--disable-commandsstring空按逗号分隔的命令前缀/精确路径启用或禁用命令可限制 CLI 暴露范围--no-input--non-interactive--noninteractivebool空禁止交互式提示否则直接失败适合 CI-v--verboseboolfalse开启详细日志--versionkong.VersionFlag空打印版本并退出-h--helpkong.helpFlag空显示上下文相关的帮助信息--wrap-untrustedboolfalseJSON/raw 输出中为抓取的外部文本字段加上不可信内容包裹标记使用前需先完成认证gog auth add account --services classroom确保账号对目标课程具有查看学生名单的权限老师身份。认证与服务管理见 gog-auth.md 与 gog-auth-add.md。若遇到权限或启用问题命令会给出针对性提示——internal/cmd/classroom_helpers.go 的wrapClassroomError会识别两类典型错误accessNotConfigured/Classroom API has not been used提示先在 Google Cloud Console 启用 Classroom APIinsufficientPermissions/insufficient authentication scopes提示执行gog auth add account --services classroom重新授权。使用示例1. 列出某课程的学生默认前 100 条gog classroom students list 1234567890 gog classroom students ls 1234567890 # 别名写法 gog classroom students 1234567890 # 默认子命令写法2. 一次性获取全部学生gog classroom students list 1234567890 --all3. 增大单页大小并控制页大小gog classroom students list 1234567890 --max 5004. 翻页遍历先取第一页记录输出的nextPageToken再带入--pagegog classroom students list 1234567890 --max 200 --json gog classroom students list 1234567890 --max 200 --page nextPageToken5. 输出 TSV 用于管道处理gog classroom students list 1234567890 --plain | awk -F \t {print $2}6. 脚本化检查空课程if gog classroom students list 1234567890 --json --fail-empty /tmp/students.json 2/dev/null; then echo 有学生数量$(jq .students | length /tmp/students.json) else echo 退出码 $?无学生或出错 fi底层实现与测试验证从源码结构看students list的实现是 gogcli 通用的分页列表模式的一个实例命令入口 internal/cmd/classroom_rosters.go 的Run把courseId、max、page、all、failEmpty与 JSON 键名students组装进classroomPagedListOptions通用分页器 internal/cmd/classroom_list_helpers.go 校验courseId非空、max 0然后通过loadPagedItemsinternal/cmd/paged_list_helpers.go驱动分页循环每页数据由fetchClassroomStudentPageinternal/cmd/classroom_list_helpers.go调用Courses.Students.List获取最终由writeClassroomPagedListinternal/cmd/classroom_list_helpers.go按 JSON / 表格两种模式渲染并处理空结果提示与--fail-empty退出码。同一分页骨架也被classroom teachers listfetchClassroomTeacherPage、classroom topics list等命令复用体现了 gogcli 对 Classroom 各列表类命令的统一抽象。对应的测试在 internal/cmd/classroom_list_helpers_test.go 中TestClassroomDirectListJSONEmptyArray通过 mock HTTP 服务模拟GET /courses/c1/students返回{nextPageToken:}断言students键在 JSON 输出中序列化为[]而非null保证脚本侧对空结果的解析稳定测试还覆盖了 invitations 等其他列表命令的同一契约。此外 internal/cmd/classroom_presentation_test.go 验证了classroomStudentColumns的列渲染逻辑。相关命令gog classroom students —— students 子命令组add / get / list / removegog classroom students get —— 查询单个学生详情含StudentWorkFoldergog classroom students add —— 添加学生支持--enrollment-codegog classroom students remove —— 移除学生gog classroom roster —— 同时列出老师与学生的完整花名册gog classroom —— Classroom 命令组入口Command index —— 全部命令索引【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考