mirror of
https://github.com/GAM-team/GAM.git
synced 2026-06-03 22:01:39 +00:00
e555e5440d
Some checks failed
Build and test GAM / build (false, build, 1, Build Intel Ubuntu Jammy, ubuntu-22.04) (push) Has been cancelled
Build and test GAM / build (false, build, 10, Build x86_64 macOS 15, macos-15-intel) (push) Has been cancelled
Build and test GAM / build (false, build, 11, Build Arm MacOS 26, macos-26) (push) Has been cancelled
Build and test GAM / build (false, build, 12, Build Intel Windows, windows-2025) (push) Has been cancelled
Build and test GAM / build (false, build, 13, Build Arm Windows, windows-11-arm) (push) Has been cancelled
Build and test GAM / build (false, build, 2, Build Intel Ubuntu Noble, ubuntu-24.04) (push) Has been cancelled
Build and test GAM / build (false, build, 3, Build Arm Ubuntu Noble, ubuntu-24.04-arm) (push) Has been cancelled
Build and test GAM / build (false, build, 4, Build Arm Ubuntu Jammy, ubuntu-22.04-arm) (push) Has been cancelled
Build and test GAM / build (false, build, 5, Build Intel StaticX Legacy, ubuntu-22.04, yes) (push) Has been cancelled
Build and test GAM / build (false, build, 6, Build Arm StaticX Legacy, ubuntu-22.04-arm, yes) (push) Has been cancelled
Build and test GAM / build (false, build, 8, Build Arm MacOS 14, macos-14) (push) Has been cancelled
Build and test GAM / build (false, build, 9, Build Arm MacOS 15, macos-15) (push) Has been cancelled
Build and test GAM / build (false, test, 14, Test Python 3.10, ubuntu-24.04, 3.10) (push) Has been cancelled
Build and test GAM / build (false, test, 15, Test Python 3.11, ubuntu-24.04, 3.11) (push) Has been cancelled
Build and test GAM / build (false, test, 16, Test Python 3.12, ubuntu-24.04, 3.12) (push) Has been cancelled
Build and test GAM / build (false, test, 17, Test Python 3.15-dev, ubuntu-24.04, 3.15-dev) (push) Has been cancelled
Build and test GAM / build (true, test, 18, Test Python 3.14 freethread, ubuntu-24.04, 3.14) (push) Has been cancelled
Build and test GAM / merge (push) Has been cancelled
Build and test GAM / publish (push) Has been cancelled
CodeQL / Analyze (python) (push) Has been cancelled
Check for Google Root CA Updates / check-certs (push) Has been cancelled
Push wiki / pushwiki (push) Has been cancelled
214 lines
11 KiB
Markdown
214 lines
11 KiB
Markdown
# Classroom - Membership
|
|
- [API documentation](#api-documentation)
|
|
- [Definitions](#definitions)
|
|
- [Special quoting for course aliases](#special-quoting-for-course-aliases)
|
|
- [Manage membership for courses](#manage-membership-for-courses)
|
|
- [Legacy manage membership](#legacy-manage-membership)
|
|
- [Bulk membership changes](#bulk-membership-changes)
|
|
- [Display course membership](#display-course-membership)
|
|
- [Display course membership counts](#display-course-membership-counts)
|
|
- [Display course counts for teachers-students](#display-course-counts-for-teachers-students)
|
|
|
|
## API documentation
|
|
* [Google Classroom API](https://developers.google.com/classroom/reference/rest)
|
|
* [Google Classroom API - Courses Students](https://developers.google.com/classroom/reference/rest/v1/courses.students)
|
|
* [Google Classroom API - Courses Teachers](https://developers.google.com/classroom/reference/rest/v1/courses.teachers)
|
|
* [Classroom Membership Limits](https://support.google.com/edu/classroom/answer/7300976)
|
|
|
|
## Definitions
|
|
```
|
|
<DomainName> ::= <String>(.<String>)+
|
|
<EmailAddress> ::= <String>@<DomainName>
|
|
<UniqueID> ::= id:<String>
|
|
<UserItem> ::= <EmailAddress>|<UniqueID>|<String>
|
|
|
|
<CourseAlias> ::= <String>
|
|
<CourseID> ::= <Number>|d:<CourseAlias>
|
|
<CourseIDList> ::= "<CourseID>(,<CourseID>)*"
|
|
<CourseEntity> ::=
|
|
<CourseIDList> | <FileSelector> | <CSVFileSelector | <CSVkmdSelector>
|
|
See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items
|
|
<CourseState> ::= active|archived|provisioned|declined|suspended
|
|
<CourseStateList> ::= all|"<CourseState>(,<CourseState>)*"
|
|
```
|
|
## Special quoting for course aliases
|
|
As course aliases can contain spaces, some care must be used when entering `<CourseAliasList>`, `<CourseID>`, `<CourseIDList>` and `<CourseEntity>`.
|
|
|
|
Suppose you have a course with the alias `Math Class`. To get information about it you enter the command: `gam info course "d:Math Class"`
|
|
|
|
The shell strips the `"` leaving a single argument `d:Math Class`; gam correctly processes the argument as it is expecting a single course.
|
|
|
|
Suppose you enter the command: `gam info courses "d:Math Class"`
|
|
|
|
The shell strips the `"` leaving a single argument `d:Math Class`; as gam is expecting a list, it splits the argument on space leaving two items and then tries to process `d:Math` and `Class`, not what you want.
|
|
|
|
You must enter: `gam info courses "'d:Math Class'"`
|
|
|
|
The shell strips the `"` leaving a single argument `'d:Math Class'`; as gam is expecting a list, it splits the argument on space while honoring the `'` leaving one item `d:Math Class` and correctly processes the item.
|
|
|
|
For multiple aliases you must enter: `gam info courses "'d:Math Class','d:Science Class'"`
|
|
|
|
See: [Lists and Collections](Lists-and-Collections)
|
|
|
|
## Manage membership for courses
|
|
|
|
These commands can process multiple courses and `add` and `delete` can process multiple students/teachers.
|
|
```
|
|
gam courses <CourseEntity> add teachers [makefirstteacherowner] <UserTypeEntity>
|
|
gam courses <CourseEntity> add students <UserTypeEntity>
|
|
gam courses <CourseEntity> delete|remove teachers|students <UserTypeEntity>
|
|
gam courses <CourseEntity> clear teachers|students
|
|
gam courses <CourseEntity> sync teachers [addonly|removeonly] [makefirstteacherowner] <UserTypeEntity>
|
|
gam courses <CourseEntity> sync students [addonly|removeonly] <UserTypeEntity>
|
|
```
|
|
When `makefirstteacherowner` is specified, the first/only user in `<UserTypeEntity>` will be updated to be the
|
|
owner of the Course(s).
|
|
|
|
### Clear
|
|
A `clear` operation deletes all of the members of the specified type. The owner teacher will not deleted.
|
|
|
|
### Sync
|
|
A `sync` operation gets the current roster for a course and compares it to the proposed roster.
|
|
|
|
Current/Default:
|
|
* members in the proposed roster that are not in the current roster will be added
|
|
* members in the current roster that are not in the proposed roster will deleted
|
|
|
|
When the `addonly` option is specified:
|
|
* members in the proposed roster that are not in the current roster will be added
|
|
* members in the current roster that are not in the proposed roster will not be deleted
|
|
|
|
When the `removeonly` option is specified:
|
|
* members in the proposed roster that are not in the current roster will not be added
|
|
* members in the current roster that are not in the proposed roster will be deleted
|
|
|
|
## Bulk membership changes
|
|
Suppose you have a CSV file (CourseStudents.csv) with headers: courseId,email
|
|
|
|
Each row contains a course ID and a student email address.
|
|
|
|
The following command will synchronize the membership for all courses.
|
|
```
|
|
gam redirect stdout ./CourseUpdates.txt redirect stderr stdout courses csvkmd CourseStudents.csv keyfield courseId datafield email sync students csvdata email
|
|
```
|
|
You can also do `add` and `delete` in this manner.
|
|
|
|
## Legacy manage membership
|
|
|
|
These commands are for backward compatibility; only one course can be processed and `add` and `delete` can only process a single student/teacher.
|
|
```
|
|
gam course <CourseID> add [makefirstteacherowner] teachers <UserItem>
|
|
gam course <CourseID> add students <UserItem>
|
|
gam course <CourseID> delete|remove teachers|students <UserItem>
|
|
gam course <CourseID> clear teachers|students
|
|
gam course <CourseID> sync teachers [addonly|removeonly] [makefirstteacherowner] <UserTypeEntity>
|
|
gam course <CourseID> sync students [addonly|removeonly] <UserTypeEntity>
|
|
```
|
|
When `makefirstteacherowner` is specified, the only/first user in `<UserItem>` or `<UserTypeEntity>` will be updated to be the
|
|
owner of the Course.
|
|
|
|
## Display course membership
|
|
```
|
|
gam print course-participants [todrive <ToDriveAttribute>*]
|
|
(course|class <CourseID>)*|([teacher <UserItem>] [student <UserItem>]) [states <CourseStateList>]
|
|
[show all|students|teachers] [formatjson [quotechar <Character>]]
|
|
```
|
|
By default, the `print course-participants` command displays participant information about all courses.
|
|
|
|
To get participant information for a specific set of courses, use the following option; it can be repeated to select multiple courses.
|
|
* `(course|class <CourseID>)*` - Display courses with the specified `<CourseID>`.
|
|
|
|
To get participant information for courses based on their having a particular participant, use the following options. Both options can be specified.
|
|
* `teacher <UserItem>` - Display courses with the specified teacher.
|
|
* `student <UserItem>` - Display courses with the specified student.
|
|
|
|
To get participant information for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
|
|
By default, all course states are selected.
|
|
* `states <CourseStateList>` - Display courses with any of the specified states.
|
|
|
|
By default, Gam displays the information as columns of fields; the following option causes the output to be in JSON format,
|
|
* `formatjson` - Display the fields in JSON format.
|
|
|
|
By default, when writing CSV files, Gam uses a quote character of double quote `"`. The quote character is used to enclose columns that contain
|
|
the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled.
|
|
When using the `formatjson` option, double quotes are used extensively in the data resulting in hard to read/process output.
|
|
The `quotechar <Character>` option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output.
|
|
`quotechar` defaults to `gam.cfg/csv_output_quote_char`. When uploading CSV files to Google, double quote `"` should be used.
|
|
|
|
## Display course membership counts
|
|
Display the number of course participants.
|
|
```
|
|
gam print course-participants
|
|
(course|class <CourseID>)*|([teacher <UserItem>] [student <UserItem>]) [states <CourseStateList>]
|
|
[show all|students|teachers]
|
|
showitemcountonly
|
|
```
|
|
Example
|
|
```
|
|
$ gam print course-participants teacher asmith states active show students showitemcountonly
|
|
Getting all Courses that match query (Teacher: asmith@domain.com, Course State: ACTIVE), may take some time on a large Google Workspace Account...
|
|
Got 3 Courses...
|
|
Getting Students for Course: 636981507234 (1/3)
|
|
Got 30 Students...
|
|
Got 43 Students...
|
|
Getting Students for Course: 589346784341 (2/3)
|
|
Got 22 Students...
|
|
Getting Students for Course: 589345535881 (3/3)
|
|
Got 23 Students...
|
|
88
|
|
```
|
|
The `Getting` and `Got` messages are written to stderr, the count is writtem to stdout.
|
|
|
|
To retrieve the count with `showitemcountonly`:
|
|
```
|
|
Linux/MacOS
|
|
count=$(gam print course-participants teacher asmith states active show students showitemcountonly)
|
|
Windows PowerShell
|
|
$count = & gam print course-participants teacher asmith states active show students showitemcountonly
|
|
Windows Command Prompt
|
|
for /f "delims=" %a in ('gam print course-participants teacher asmith states active show students showitemcountonly') do set count=%a
|
|
```
|
|
|
|
## Display course counts for teachers-students
|
|
You can get a count of the number of courses in which a teacher or student is a participant.
|
|
```
|
|
gam print course-counts students|teachers [todrive <ToDriveAttribute>*]
|
|
(course|class <CourseEntity>)*|([teacher <UserItem>] [student <UserItem>] [states <CourseStateList>])
|
|
[mincount <Integer>]
|
|
[formatjson [quotechar <Character>]]
|
|
```
|
|
By default, the `print course-counts` command displays participant counts about all courses.
|
|
|
|
To get participant counts for a specific set of courses, use the following option; it can be repeated to select multiple courses.
|
|
* `(course|class <CourseID>)*` - Display courses with the specified `<CourseID>`.
|
|
|
|
To get participant counts for courses based on their having a particular participant, use the following options. Both options can be specified.
|
|
* `teacher <UserItem>` - Display courses with the specified teacher.
|
|
* `student <UserItem>` - Display courses with the specified student.
|
|
|
|
To get participant counts for courses based on their state, use the following option. This option can be combined with the `teacher` and `student` options.
|
|
By default, all course states are selected.
|
|
* `states <CourseStateList>` - Display courses with any of the specified states.
|
|
|
|
By default, all count values are displayed, use `mincount <Integer>` to limit the display to those counts
|
|
greater that or equal to the specified `<Integer>`.
|
|
|
|
By default, Gam displays the counts as columns of fields; the following option causes the output to be in JSON format,
|
|
* `formatjson` - Display the fields in JSON format.
|
|
|
|
By default, when writing CSV files, Gam uses a quote character of double quote `"`. The quote character is used to enclose columns that contain
|
|
the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled.
|
|
When using the `formatjson` option, double quotes are used extensively in the data resulting in hard to read/process output.
|
|
The `quotechar <Character>` option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output.
|
|
`quotechar` defaults to `gam.cfg/csv_output_quote_char`. When uploading CSV files to Google, double quote `"` should be used.
|
|
|
|
### Example
|
|
For teachers in all active courses, print the number of classes for which they are a participant.
|
|
```
|
|
gam print coursecounts teachers states active
|
|
```
|
|
For teachers in all active courses, print the number of classes (if it is >= 5) for which they are a participant.
|
|
```
|
|
gam print coursecounts teachers states active mincount 5
|
|
```
|