您可以使用課程別名資源，以其他名稱參照課程。課程別名是 Google Classroom 課程 ID 與外部課程 ID 之間的對應項目。
建議您每次從學生資訊系統建立課程或將課程連結至學生資訊系統時，都使用學生資訊系統的課程 ID 做為課程別名。您可以透過 Classroom API 直接在建立課程時，將課程的 id 參數指定為別名，如果別名已存在，課程建立作業就會失敗，並顯示 ALREADY_EXISTS (409) 錯誤。這樣一來，如果同步程式發生錯誤，就不會建立重複的課程。
別名有兩種形式：全網域和全專案。
- 全網域別名會使用
d:做為前置字串，任何使用 Classroom API 的使用者都能看到。 - 專案全域別名會使用前置字串
p:，且只能由建立這些別名的應用程式 (開發人員控制台專案) 查看及使用。
別名可用於 API 中任何需要課程 ID 的位置。也就是說，一旦使用 API 註冊別名，即可用於讀取及修改課程和學生名單資訊。
從學生資訊系統同步處理的角度來看，這表示課程的學生資訊系統內部 ID 可註冊為課程的網域別名。如此一來，任何同時整合 SIS 和 Classroom 的開發人員，都能使用 SIS ID 與 Classroom 資料互動。
舉例來說，假設 SIS 名稱為 school，而 SIS 針對特定課程使用的內部 ID 為 math_101，您可以建立別名 d:school_math_101。
為新課程新增別名
如要為新課程新增別名，請在提出 courses.create() 要求時，將 course.id 設為所需別名。
Apps Script
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 Script
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")