إدارة الأسماء البديلة للدورة التدريبية

يمكنك الإشارة إلى الدورات التعليمية باسم مختلف باستخدام اسم مستعار للدورة التعليمية . يمكن أن تكون الأسماء المستعارة للدورات التعليمية بمثابة ربط بين معرّفات دورات Google Classroom ومعرّفات الدورات الخارجية. على سبيل المثال، يمكنك ضبط اسم مستعار للدورة التعليمية ليتطابق مع رقم تعريف الدورة التعليمية من نظام معلومات الطالب (SIS).

يتخذ الاسم المستعار للدورة التعليمية شكلَين: على مستوى النطاق وعلى مستوى المشروع.

  • تستخدم الأسماء المستعارة على مستوى النطاق البادئة d: ويمكن لأي مستخدم استخدام Classroom API الاطّلاع عليها. تكون مساحة اسم النطاق مفيدة لإنشاء أسماء مستعارة يحتاج جميع المستخدمين إلى الوصول إليها، ولكنها ليست خاصة بأي برنامج واحد. على سبيل المثال، يجب إنشاء قوائم بديلة لدورة تعليمية، مثل MATH 127 وCOMSCI 127، في مساحة اسم النطاق. لا يمكن لمشرفي النطاق فقط إنشاء أسماء مستعارة في مساحة اسم النطاق، ولكن يمكن لجميع المستخدمين في النطاق الاطّلاع عليها.

  • تستخدم الأسماء المستعارة على مستوى المشروع البادئة p: ولا يمكن لمشروع Google Cloud الذي أنشأها إلا الاطّلاع عليها واستخدامها. تكون مساحة اسم مشروع المطوّر مفيدة لإدارة الأسماء المستعارة الخاصة بتطبيق معيّن. على سبيل المثال، يمكن لتطبيق يستخدم معرّفات بديلة للدورات التعليمية إنشاء أسماء مستعارة لربط المعرّف الخاص به بدورات Classroom. ترتبط الأسماء المستعارة التي يتم إنشاؤها في مساحة الاسم هذه بمشروع معيّن على Google Cloud. يمكن لأي مستخدم لتطبيق معيّن إنشاء الأسماء المستعارة وعرضها في مساحة الاسم الخاصة بمشروع المطوّر لهذا التطبيق.

يمكن استخدام اسم مستعار للدورة التعليمية بدلاً من رقم تعريف دورة Classroom لأي نقطة نهاية في Classroom API. وهذا يعني أنّه يمكن استخدام الاسم المستعار لقراءة الدورات التعليمية ومعلومات قائمة الطلاب المسجّلين وتعديلها.

استخدام اسم مستعار للمزامنة مع أنظمة معلومات الطالب

يمكن تسجيل المعرّف الداخلي لنظام معلومات الطالب لدورة تعليمية كاسم مستعار على مستوى النطاق للدورة التعليمية. وبهذه الطريقة، يمكن لأي مطوّر يدمج كلاً من نظام معلومات الطالب وClassroom استخدام معرّف نظام معلومات الطالب للتفاعل مع بيانات Classroom.

إذا أنشأت دورة تعليمية من نظام معلومات الطالب أو ربطت دورة تعليمية بنظام معلومات الطالب، ننصحك باستخدام رقم تعريف الدورة التعليمية في نظام معلومات الطالب كاسم مستعار للدورة التعليمية. عند إنشاء دورة تعليمية باستخدام طريقة courses.create()، يمكنك تحديد الاسم المستعار في الحقل id للطلب. إذا كان الاسم المستعار موجودًا من قبل، سيتعذّر إنشاء الدورة التعليمية وسيظهر الخطأ 409 ALREADY_EXISTS. يمنع ذلك إنشاء دورات تعليمية مكرّرة إذا حدثت مشكلة في برنامج المزامنة.

على سبيل المثال، إذا افترضنا أنّ اسم نظام معلومات الطالب هو school وأنّ المعرّف الداخلي الذي يستخدمه نظام معلومات الطالب لدورة تعليمية معيّنة هو math_101، يمكنك إنشاء اسم مستعار على النحو التالي: d:school_math_101.

إضافة اسم مستعار لدورة تعليمية جديدة

لإضافة اسم مستعار لدورة تعليمية جديدة، اضبط course.id على اسم مستعار عند إجراء طلب courses.create().

برمجة التطبيقات

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

جافا

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

برمجة التطبيقات

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

جافا

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

جافا

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