本文详解加载 Google Classroom 课程学生所需的 OAuth 2.0 授权作用域（scopes），指出常见错误配置，并提供官方推荐的只读与读写权限组合，确保 courses.students.list 接口调用成功。
本文详解加载 google classroom 课程学生所需的 oauth 2.0 授权作用域（scopes），指出常见错误配置，并提供官方推荐的只读与读写权限组合，确保 `courses.students.list` 接口调用成功。
在使用 Google Classroom API 获取某门课程的学生列表（即调用 courses.students.list）时，必须显式声明具备“班级名册（roster）访问权限”的 scope。许多开发者误以为 CLASSROOM_COURSEWORK_STUDENTS* 等作用域可覆盖学生名单读取，但实际上这些 scope 仅用于课程作业（coursework）相关的操作（如获取学生提交记录），不授予访问课程成员（students/teachers）的权限——这正是触发 Request had insufficient authentication scopes 错误的根本原因。
✅ 正确的作用域如下（推荐使用只读版本以满足最小权限原则）：
# Ruby 示例（Google API Client Library） scopes = [ 'https://www.googleapis.com/auth/classroom.rosters.readonly', # ✅ 必需：读取课程学生/教师名单 'https://www.googleapis.com/auth/classroom.profile.emails', # 可选：获取学生邮箱（需额外授权） 'https://www.googleapis.com/auth/classroom.profile.photos' # 可选：获取头像（若需展示用户信息） ]
# Python 示例（google-api-python-client）
SCOPES = [
'https://www.googleapis.com/auth/classroom.rosters.readonly',
'https://www.googleapis.com/auth/classroom.profile.emails'
]⚠️ 注意事项：
-
classroom.rosters（读写）和classroom.rosters.readonly（只读）是唯一直接支持courses.students.list的作用域，其他如courses.readonly或coursework.*均无效； - 若需返回学生邮箱地址（
profile.emails字段），必须额外添加classroom.profile.emailsscope，否则响应中该字段为空； - 所有 scope 需在 OAuth 2.0 授权流程中一次性请求，且用户需在授权页面明确同意；新增 scope 后，必须让用户重新完成授权（旧 token 不自动升级权限）；
- 在 Google Cloud Console 的 OAuth 同意屏幕中，若启用敏感 scope（如
profile.emails），可能需提交应用验证（尤其面向外部用户时）。
? 最佳实践建议：
始终优先选用 *.readonly 作用域（如 classroom.rosters.readonly），避免申请不必要的写权限；结合 Google Classroom Auth 指南 和 scope 参考表 定期复核权限配置，确保安全合规。
