Quản lý bí danh khoá học

Bạn có thể tham chiếu các khoá học bằng một tên khác với tài nguyên Bí danh khoá học. Bí danh khoá học là mối liên kết giữa giá trị nhận dạng khoá học trong Google Lớp học và giá trị nhận dạng khoá học bên ngoài.

Bất cứ khi nào tạo khoá học từ SIS hoặc liên kết một khoá học với SIS, bạn nên dùng mã khoá học của SIS làm bí danh khoá học. API Lớp học cho phép bạn thực hiện việc này ngay trong quá trình tạo khoá học bằng cách chỉ định tham số id của khoá học làm bí danh. Nếu bí danh đã tồn tại, quá trình tạo khoá học sẽ không thành công kèm theo lỗi ALREADY_EXISTS (409). Việc này sẽ ngăn việc tạo các khoá học trùng lặp nếu chương trình đồng bộ hoá có lỗi.

Bí danh có hai phiên bản: toàn miền và toàn dự án.

• Bí danh trên toàn miền sử dụng tiền tố d: và bất kỳ ai sử dụng API Lớp học đều có thể nhìn thấy email đại diện đó.
• Bí danh trên toàn dự án sử dụng tiền tố p: và chỉ ứng dụng (dự án bảng điều khiển dành cho nhà phát triển) đã tạo ra bí danh mới có thể nhìn thấy và sử dụng.

Bạn có thể sử dụng bí danh ở bất kỳ nơi nào trong API dự kiến có giá trị nhận dạng khoá học. Điều này có nghĩa là sau khi một bí danh được đăng ký bằng API, bí danh đó có thể được dùng để đọc và sửa đổi các khoá học cũng như thông tin về danh sách.

Từ góc độ đồng bộ hoá SIS, điều này có nghĩa là bạn có thể đăng ký mã nhận dạng nội bộ SIS cho một khoá học làm email đại diện trên toàn miền cho khoá học. Nhờ đó, bất kỳ nhà phát triển nào tích hợp cả hệ thống thông tin học sinh và Lớp học đều chỉ cần sử dụng giá trị nhận dạng của hệ thống thông tin học sinh đó để tương tác với dữ liệu của Lớp học.

Ví dụ: nếu chúng tôi giả định tên SIS là school và giá trị nhận dạng nội bộ mà SIS đó sử dụng cho một khoá học cụ thể là math_101, thì bạn có thể tạo một bí danh là d:school_math_101.

Thêm tên đại diện cho khoá học mới

Để thêm bí danh cho một khoá học mới, hãy đặt course.id thành bí danh mong muốn khi đưa ra yêu cầu courses.create().

Apps Script

classroom/snippets/createAlias.gs

Xem trên GitHub

/**
 * 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

Xem trên GitHub

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

Xem trên GitHub

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

Thêm email đại diện cho một khoá học hiện có

Để thêm bí danh trên một khoá học hiện có, bạn có thể đặt alias thành tên bí danh mong muốn và sử dụng phương thức courses.aliases.create().

Apps Script

classroom/snippets/addAlias.gs

Xem trên GitHub

/**
 * 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

Xem trên GitHub

/* 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

Xem trên GitHub

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)

Truy xuất bí danh khoá học

Bạn có thể truy xuất bí danh của một khoá học bằng cách sử dụng phương thức courses.aliases.list(), như trong mẫu sau:

.NET

classroom/snippets/ClassroomSnippets/ListCourseAliases.cs

Xem trên GitHub

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

Xem trên GitHub

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

Xem trên GitHub

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")