您可以使用课程别名资源以其他名称引用课程。课程别名是 Google 课堂课程标识符与外部课程标识符之间的映射。
我们建议您每次通过学生信息系统创建课程或将课程关联到学生信息系统时,都使用学生信息系统的课程 ID 作为课程别名。借助 Google 课堂 API,您可以直接在课程创建过程中执行此操作,只需将课程的 id
参数指定为别名即可。如果别名已存在,课程创建将失败并报出 ALREADY_EXISTS (409)
错误。这样可以防止在同步程序中存在 bug 时创建重复的课程。
别名有两种类型:网域级别名和项目级别名。
- 网域级别别名使用
d:
作为前缀,任何使用 Classroom API 的用户都可以看到。 - 项目级别的别名使用
p:
作为前缀,并且只能由创建它们的应用(Play 管理中心项目)看到和使用。
别名可在 API 中需要课程标识符的任何位置使用。这意味着,使用 API 注册别名后,该别名便可用于读取和修改课程和名单信息。
从 SIS 同步的角度来看,这意味着课程的 SIS 内部标识符可以注册为课程的域名级别别名。这样一来,任何同时集成了 SIS 和 Google 课堂的开发者都可以直接使用 SIS 标识符与 Google 课堂数据进行交互。
例如,假设学生信息系统 (SIS) 的名称为 school
,并且 SIS 为特定课程使用的内部标识符为 math_101
,您可以创建别名 d:school_math_101
。
为新课程添加别名
如需为新课程添加别名,请在发出 courses.create()
请求时将 course.id
设置为所需的别名。
Apps 脚本
classroom/snippets/createAlias.gs
/** * Creates Course with an alias specified */ function createAlias() { let course = { id: 'p:bio_101', name: '10th Grade Biology', section: 'Period 2', descriptionHeading: 'Welcome to 10th Grade Biology', description: 'We\'ll be learning about the structure of living creatures from a combination ' + 'of textbooks, guest lectures, and lab work. Expect to be excited!', room: '301', ownerId: 'me', courseState: 'PROVISIONED' }; try { // Create the course using course details. course = Classroom.Courses.create(course); console.log('Course created: %s (%s)', course.name, course.id); } catch (err) { // TODO (developer) - Handle Courses.create() exception console.log('Failed to create course %s with an error %s', course.name, err.message); } }
Java
classroom/snippets/src/main/java/CreateCourseWithAlias.java
Course course = null; /* Create a new Course with the alias set as the id field. Project-wide aliases use a prefix of "p:" and can only be seen and used by the application that created them. */ Course content = new Course() .setId("p:history_4_2022") .setName("9th Grade History") .setSection("Period 4") .setDescriptionHeading("Welcome to 9th Grade History.") .setOwnerId("me") .setCourseState("PROVISIONED"); try { course = service.courses().create(content).execute(); // Prints the new created course id and name System.out.printf("Course created: %s (%s)\n", course.getName(), course.getId()); } catch (GoogleJsonResponseException e) { // TODO (developer) - handle error appropriately GoogleJsonError error = e.getDetails(); if (error.getCode() == 409) { System.out.printf("The course alias already exists: %s.\n", content.getId()); } else { throw e; } } catch (Exception e) { throw e; } return course;
Python
classroom/snippets/classroom_add_alias_new.py
SCOPES = ["https://www.googleapis.com/auth/classroom.courses"] def classroom_add_alias_new(): """ Creates a course with alias specification the user has access to. The file token.json stores the user's access and refresh tokens, and is created automatically when the authorization flow completes for the first time. Load pre-authorized user credentials from the environment. TODO(developer) - See https://developers.google.com/identity for guides on implementing OAuth2 for the application. """ # pylint: disable=maybe-no-member creds = None if os.path.exists("token.json"): creds = Credentials.from_authorized_user_file("token.json", SCOPES) # If there are no (valid) credentials available, let the user log in. if not creds or not creds.valid: if creds and creds.expired and creds.refresh_token: creds.refresh(Request()) else: flow = InstalledAppFlow.from_client_secrets_file( "credentials.json", SCOPES ) creds = flow.run_local_server(port=0) # Save the credentials for the next run with open("token.json", "w", encoding="utf8") as token: token.write(creds.to_json()) alias = "d:school_physics_333" course = { "id": alias, "name": "English", "section": "Period 2", "description": "Course Description", "room": "301", "ownerId": "me", } try: print("-------------") service = build("classroom", "v1", credentials=creds) course = service.courses().create(body=course).execute() print("====================================") except HttpError as error: print(f"An error occurred: {error}") return course if __name__ == "__main__": # pylint: disable=too-many-arguments # Put the course_id of course whose alias needs to be created. classroom_add_alias_new()
为现有课程添加别名
如需为现有课程添加别名,您可以将 alias
设置为所需的别名名称,然后使用 courses.aliases.create()
方法。
Apps 脚本
classroom/snippets/addAlias.gs
/** * Updates the section and room of Google Classroom. * @param {string} course_id * @see https://developers.google.com/classroom/reference/rest/v1/courses.aliases/create */ function addAlias(course_id) { const alias = { 'alias': 'p:bio_101' }; try { const course_alias = Classroom.Courses.Aliases.create(resource=alias, courseId=course_id); console.log('%s successfully added as an alias!', course_alias.alias); } catch (err) { // TODO (developer) - Handle exception console.log('Request to add alias %s failed with error %s.', alias.alias, err.message); } }
Java
classroom/snippets/src/main/java/AddAliasToCourse.java
/* Create a new CourseAlias object with a project-wide alias. Project-wide aliases use a prefix of "p:" and can only be seen and used by the application that created them. */ CourseAlias content = new CourseAlias().setAlias("p:biology_10"); CourseAlias courseAlias = null; try { courseAlias = service.courses().aliases().create(courseId, content).execute(); System.out.printf("Course alias created: %s \n", courseAlias.getAlias()); } catch (GoogleJsonResponseException e) { // TODO (developer) - handle error appropriately GoogleJsonError error = e.getDetails(); if (error.getCode() == 409) { System.out.printf("The course alias already exists: %s.\n", content); } else { throw e; } } catch (Exception e) { throw e; } return courseAlias;
Python
classroom/snippets/classroom_add_alias_existing.py
def classroom_add_alias_existing(course_id): """ Adds alias to existing course with specific course_id. Load pre-authorized user credentials from the environment. TODO(developer) - See https://developers.google.com/identity for guides on implementing OAuth2 for the application. """ creds, _ = google.auth.default() # pylint: disable=maybe-no-member service = build("classroom", "v1", credentials=creds) alias = "d:school_math_101" course_alias = {"alias": alias} try: course_alias = ( service.courses() .aliases() .create(courseId=course_id, body=course_alias) .execute() ) return course_alias except HttpError as error: print(f"An error occurred: {error}") print("Alias Creation Failed") return course_alias if __name__ == "__main__": # Put the course_id of course whose alias needs to be added. classroom_add_alias_existing(456058313539)
检索课程别名
您可以使用 courses.aliases.list()
方法检索课程的别名,如以下示例所示:
.NET
classroom/snippets/ClassroomSnippets/ListCourseAliases.cs
using System; using System.Collections.Generic; using Google; using Google.Apis.Auth.OAuth2; using Google.Apis.Classroom.v1; using Google.Apis.Classroom.v1.Data; using Google.Apis.Services; namespace ClassroomSnippets { // Class to demonstrate the use of Classroom List Alias API public class ListCourseAliases { /// <summary> /// Retrieve the aliases for a course. /// </summary> /// <param name="courseId">Id of the course.</param> /// <returns>list of course aliases, null otherwise.</returns> public static List<CourseAlias> ClassroomListAliases(string courseId) { try { /* Load pre-authorized user credentials from the environment. TODO(developer) - See https://developers.google.com/identity for guides on implementing OAuth2 for your application. */ GoogleCredential credential = GoogleCredential.GetApplicationDefault() .CreateScoped(ClassroomService.Scope.ClassroomCourses); // Create Classroom API service. var service = new ClassroomService(new BaseClientService.Initializer { HttpClientInitializer = credential, ApplicationName = "Classroom Snippets" }); string pageToken = null; var courseAliases = new List<CourseAlias>(); do { // List of aliases of specified course var request = service.Courses.Aliases.List(courseId); request.PageSize = 100; request.PageToken = pageToken; var response = request.Execute(); courseAliases.AddRange(response.Aliases); pageToken = response.NextPageToken; } while (pageToken != null); if (courseAliases.Count == 0) { Console.WriteLine("No aliases found."); } else { Console.WriteLine("Aliases:"); foreach (var courseAlias in courseAliases) { Console.WriteLine(courseAlias.Alias); } } return courseAliases; } catch (Exception e) { // TODO(developer) - handle error appropriately if (e is AggregateException) { Console.WriteLine("Credential Not found"); } else if (e is GoogleApiException) { Console.WriteLine("Course does not exist."); } else { throw; } } return null; } } }
Java
classroom/snippets/src/main/java/ListCourseAliases.java
String pageToken = null; List<CourseAlias> courseAliases = new ArrayList<>(); try { // List of aliases of specified course do { ListCourseAliasesResponse response = service .courses() .aliases() .list(courseId) .setPageSize(100) .setPageToken(pageToken) .execute(); courseAliases.addAll(response.getAliases()); pageToken = response.getNextPageToken(); } while (pageToken != null); if (courseAliases.isEmpty()) { System.out.println("No aliases found."); } else { System.out.println("Aliases:"); for (CourseAlias courseAlias : courseAliases) { System.out.println(courseAlias.getAlias()); } } } catch (GoogleJsonResponseException e) { // TODO(developer) - handle error appropriately GoogleJsonError error = e.getDetails(); if (error.getCode() == 404) { System.err.println("Course does not exist.\n"); } else { throw e; } } return courseAliases;
Python
classroom/snippets/classroom_list_course_aliases.py
import google.auth from googleapiclient.discovery import build from googleapiclient.errors import HttpError def classroom_list_course_aliases(course_id): """ Prints the list of the aliases of a specified course the user has access to. Load pre-authorized user credentials from the environment. TODO(developer) - See https://developers.google.com/identity for guides on implementing OAuth2 for the application. """ creds, _ = google.auth.default() try: service = build("classroom", "v1", credentials=creds) course_aliases = [] page_token = None while True: response = ( service.courses() .aliases() .list(pageToken=page_token, courseId=course_id) .execute() ) course_aliases.extend(response.get("aliases", [])) page_token = response.get("nextPageToken", None) if not page_token: break if not course_aliases: print("No course aliases found.") print("Course aliases:") for course_alias in course_aliases: print(f"{course_alias.get('alias')}") return course_aliases except HttpError as error: print(f"An error occurred: {error}") return error if __name__ == "__main__": classroom_list_course_aliases("course_id")