Manage Course Aliases

You can reference courses by an different name with a Course Alias resource. Course Aliases are a mapping between Google Classroom course identifiers and external course identifiers.

We recommend that anytime you create a course from an SIS or link a course to an SIS, that the SIS’s courseID is used as the course alias. The Classroom API lets you do this directly in course creation by specifying the id parameter of the course as the alias. If the alias already exists, course creation will fail with an ALREADY_EXISTS (409) error. This will prevent the creation of duplicate courses if there is a bug in the sync program.

Aliases come in two flavors: domain-wide and project-wide.

  • Domain-wide aliases use a prefix of d: and can be seen by anybody using the Classroom API.
  • Project-wide aliases use a prefix of p: and can only be seen and used by the application (developer console project) that created them.

Aliases can be used anywhere in the API that expects a course identifier. This means that once an alias is registered using the API, that alias can be used to read and modify courses and roster information.

From the SIS synchronization perspective, this means that the SIS internal identifier for a course can be registered as a domain-wide alias for the course. That way any developer who integrates with both the SIS and classroom can simply use the SIS identifier to interact with Classroom data.

For example, if we assume the SIS name is school and the internal identifier used by the SIS for a particular course is math_101, you could create an alias as d:school_math_101.

Add an alias for a new course

To add an alias for a new course, set course.id to the desired alias when making the courses.create request.

Python

classroom/snippets/snippets.py
alias = 'd:school_math_101'
course = {
    'id': alias,
    'name': 'Math 101',
    'section': 'Period 2',
    'description': 'Course Description',
    'room': '301',
    'ownerId': 'me'
}
try:
    course = service.courses().create(
        body=course).execute()
except errors.HttpError:
    print('Course Creation Failed')

Add an alias for an existing course

To add the alias on an existing course, you can set alias to the desired alias name and use the courses.alias.create method.

Python

classroom/snippets/snippets.py
courseId = '123456'
alias = 'd:school_math_101'
courseAlias = {
    'alias': alias
}
try:
    courseAlias = service.courses().aliases().create(
        courseId=courseId,
        body=courseAlias).execute()
except errors.HttpError:
    print('Alias Creation Failed')

Retrieve course aliases

You can retrieve the aliases for a course using the courses.aliases.list() method, as shown in the following sample:

.NET

            string courseId = "123456";
            string pageToken = null;
            var courseAliases = new List<CourseAlias>();

            do
            {
                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);
                }
            }

Java

String courseId = "123456";
String pageToken = null;
List<CourseAlias> courseAliases = new ArrayList<CourseAlias>();

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());
    }
}

PHP

$courseId = '123456';
$pageToken = NULL;
$courseAliases = array();

do {
  $params = array(
    'pageSize' => 100,
    'pageToken' => $pageToken
  );
  $response = $service->courses_aliases->listCoursesAliases(
      $courseId, $params);
  $courseAliases = array_merge($courseAliases, $response->aliases);
  $pageToken = $response->nextPageToken;
} while (!empty($pageToken));

if (count($courseAliases) == 0) {
  print "No aliases found.\n";
} else {
  print "Aliases:\n";
  foreach ($courseAliases as $courseAlias) {
    printf("%s\n", $courseAlias->alias);
  }
}

Python

classroom/snippets/snippets.py
alias = 'd:school_math_101'
course = {
    'id': alias,
    'name': 'Math 101',
    'section': 'Period 2',
    'description': 'Course Description',
    'room': '301',
    'ownerId': 'me'
}
try:
    course = service.courses().create(
        body=course).execute()
except errors.HttpError:
    print('Course Creation Failed')