إنشاء المعلّمين والطلاب وإدارتهم

يمثّل دور الطالب ودور المعلّم في Google Classroom دور المستخدم في أحد المقررات الدراسية. يمكن تعيين مستخدم كمعلّم في دورة تدريبية وكطالب في دورة تدريبية أخرى. يشير التصنيف "طالب" أو "معلّم" إلى مجموعة من الأذونات لمستخدم معيّن في دورة تدريبية معيّنة.

الطلاب

يمثّل مورد Student مستخدمًا مسجّلاً كطالب

في دورة تدريبية محدّدة يُسمح للطلاب بالاطّلاع على تفاصيل الدورة التدريبية وأسماء المعلّمين فيها.

المعلمون

يمثّل المورد Teacher مستخدمًا يدرّس دورة تدريبية معيّنة. يُسمح للمعلّمين بعرض تفاصيل الدورة التدريبية وتغييرها، وعرض المعلّمين والطلاب، وإدارة المعلّمين والطلاب الإضافيين. تتضمّن كل دورة تدريبية معلّمًا أساسيًا أو مالكًا للدورة التدريبية، وهو معلّم يمكنه إدارة الإعدادات، مثل نقل ملكية الدورة التدريبية.

يتم تحديد الطلاب والمعلّمين من خلال المعرّف الفريد أو عنوان البريد الإلكتروني للمستخدم، كما هو معروض في Directory API. يمكن للمستخدم الحالي أيضًا الإشارة إلى رقم التعريف الخاص به باستخدام الاختصار "me".

أذونات الإدارة المباشرة باستخدام Classroom API

يتمتع المشرفون والطلاب والمعلّمون بأذونات مختلفة عند إضافة مستخدمين إلى الدورات التدريبية أو إزالتهم منها مباشرةً باستخدام Classroom API.

المشرفون

يُسمح لمشرفي النطاق بتخطّي عملية الدعوة وإضافة الطلاب والمعلّمين مباشرةً إلى دورة تدريبية في حال استيفاء الشروط التالية:

  • المستخدم الذي تتم إضافته هو جزء من نطاق المشرف.
  • يجب أن يكون المعلّم الأساسي للدورة التدريبية أو مالكها جزءًا من نطاق المشرف.

بالنسبة إلى المستخدمين أو الدورات التدريبية خارج نطاق المشرف، يجب أن تحصل التطبيقات على موافقة المستخدم من خلال إرسال دعوة باستخدام طريقة invitations.create.

الطلاب

يمكن للطلاب إضافة أنفسهم إلى دورة تدريبية من خلال استدعاء students.create وتحديد enrollmentCode الخاصة بالدورة التدريبية. enrollmentCode هو معرّف فريد للدورة التدريبية المضمّنة في مرجع Course. في تطبيق Classroom على الويب، يتوفّر الرمز enrollmentCode في علامة التبويب "ساحة المشاركات" وصفحة تفاصيل الدورة التدريبية.

المعلمون

لا يمكن للمعلّمين إضافة مستخدمين إلى دورة تدريبية مباشرةً، بل عليهم استخدام طريقة invitations.create لدعوة الطلاب والمعلّمين الآخرين إلى الدورة التدريبية.

يوضّح الجدول التالي المستخدم المسموح له بتقديم طلبات إلى الطريقتَين create وdelete للموردَين Teacher وStudent.

المشرف معلّم طالب
CreateTeacher ✔️ ✖️ ✖️
DeleteTeacher ✔️ ✔️ ✖️
CreateStudent ✔️ ✖️ ✔️ 1
DeleteStudent ✔️ ✔️ ✔️ 2

1 يمكن للطالب إضافة نفسه إلى دورة تدريبية فقط.

2 يمكن للطالب فقط حذف نفسه من الدورة التدريبية.

إدارة المعلّمين

يمكن لمشرفي النطاق إضافة المعلّمين مباشرةً إلى الدورات التدريبية ضمن نطاقهم باستخدام teachers.create، كما هو موضّح في المثال التالي:

NET.

classroom/snippets/ClassroomSnippets/AddTeacher.cs
using Google.Apis.Auth.OAuth2;
using Google.Apis.Classroom.v1;
using Google.Apis.Classroom.v1.Data;
using Google.Apis.Services;
using System;
using System.Net;
using Google;

namespace ClassroomSnippets
{
    // Class to demonstrate the use of Classroom Create Teacher API
    public class AddTeacher
    {
       /// <summary>
       /// Add teacher to the Course
       /// </summary>
       /// <param name="courseId"></param>
       /// <param name="teacherEmail"></param>
       /// <returns></returns>
        public static Teacher ClassroomAddTeacher( string courseId,
                 string teacherEmail)
         {
             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.ClassroomRosters);

                 // Create Classroom API service.
                 var service = new ClassroomService(new BaseClientService.Initializer
                 {
                     HttpClientInitializer = credential,
                     ApplicationName = "Classroom API Snippet"
                 });

                 var teacher = new Teacher
                 {
                     UserId = teacherEmail
                 };
                 // Add the teacher to the course.
                 teacher = service.Courses.Teachers.Create(teacher, courseId).Execute();
                     Console.WriteLine(
                         "User '{0}' was added as a teacher to the course with ID '{1}'.\n",
                         teacher.Profile.Name.FullName, courseId);
                     return teacher;
             }
             catch (Exception e)
             {
                 // TODO(developer) - handle error appropriately
                 if (e is AggregateException)
                 {
                     Console.WriteLine("Credential Not found");
                 }
                 else if (e is GoogleApiException)
                 {
                     Console.WriteLine("Failed to Add the teacher. Error message: {0}", e.Message);
                 }
                 else
                 {
                     throw;
                 }
             }

             return null;
         }


    }

}

جافا

classroom/snippets/src/main/java/AddTeacher.java
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.classroom.Classroom;
import com.google.api.services.classroom.ClassroomScopes;
import com.google.api.services.classroom.model.Teacher;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.ArrayList;
import java.util.Arrays;

/* Class to demonstrate the use of Classroom Add Teacher API */
public class AddTeacher {

  /* Scopes required by this API call. If modifying these scopes, delete your previously saved
  tokens/ folder. */
  static ArrayList<String> SCOPES =
      new ArrayList<>(Arrays.asList(ClassroomScopes.CLASSROOM_ROSTERS));

  /**
   * Add teacher to a specific course.
   *
   * @param courseId - Id of the course.
   * @param teacherEmail - Email address of the teacher.
   * @return newly created teacher
   * @throws IOException - if credentials file not found.
   * @throws GeneralSecurityException - if a new instance of NetHttpTransport was not created.
   */
  public static Teacher addTeacher(String courseId, String teacherEmail)
      throws GeneralSecurityException, IOException {

    // Create the classroom API client.
    final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
    Classroom service =
        new Classroom.Builder(
                HTTP_TRANSPORT,
                GsonFactory.getDefaultInstance(),
                ClassroomCredentials.getCredentials(HTTP_TRANSPORT, SCOPES))
            .setApplicationName("Classroom samples")
            .build();

    Teacher teacher = new Teacher().setUserId(teacherEmail);
    try {
      // Add a teacher to a specified course
      teacher = service.courses().teachers().create(courseId, teacher).execute();
      // Prints the course id with the teacher name
      System.out.printf(
          "User '%s' was added as a teacher to the course with ID '%s'.\n",
          teacher.getProfile().getName().getFullName(), courseId);
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      GoogleJsonError error = e.getDetails();
      if (error.getCode() == 409) {
        System.out.printf("User '%s' is already a member of this course.\n", teacherEmail);
      } else if (error.getCode() == 403) {
        System.out.println("The caller does not have permission.\n");
      } else {
        throw e;
      }
    }
    return teacher;
  }
}

PHP

classroom/snippets/src/ClassroomAddTeacher.php
<?php
use Google\Client;
use Google\Service\Classroom;
use Google\Service\Classroom\Teacher;
use Google\service\Exception;

function addTeacher($courseId, $teacherEmail)
{
    /* Load pre-authorized user credentials from the environment.
    TODO (developer) - See https://developers.google.com/identity for
     guides on implementing OAuth2 for your application. */
    $client = new Client();
    $client->useApplicationDefaultCredentials();
    $client->addScope("https://www.googleapis.com/auth/classroom.profile.photos");
    $service = new Classroom($client);
    $teacher = new Teacher([
        'userId' => $teacherEmail
    ]);
    try {
        //  calling create teacher
        $teacher = $service->courses_teachers->create($courseId, $teacher);
        printf("User '%s' was added as a teacher to the course with ID '%s'.\n",
            $teacher->profile->name->fullName, $courseId);
    } catch (Exception $e) {
        if ($e->getCode() == 409) {
            printf("User '%s' is already a member of this course.\n", $teacherEmail);
        } else {
            throw $e;
        }
    }
    return $teacher;
}

Python

classroom/snippets/classroom_add_teacher.py
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def classroom_add_teacher(course_id):
  """
  Adds a teacher to a 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)

  teacher_email = "gduser1@workspacesamples.dev"
  teacher = {"userId": teacher_email}

  try:
    teachers = service.courses().teachers()
    teacher = teachers.create(courseId=course_id, body=teacher).execute()
    print(
        "User %s was added as a teacher to the course with ID %s"
        % (teacher.get("profile").get("name").get("fullName"), course_id)
    )
  except HttpError as error:
    print('User "{%s}" is already a member of this course.' % teacher_email)
    return error
  return teachers


if __name__ == "__main__":
  # Put the course_id of course for which Teacher needs to be added.
  classroom_add_teacher(453686957652)

يمكن للمعلّمين المساعدين إزالة معلّمين آخرين من دورة تدريبية باستخدام طريقة teachers.delete. يؤدي هذا الإجراء إلى إزالة المعلّم المحدّد من الدورة التدريبية فقط، ولا يؤثر في تعيينه لدورات تدريبية أخرى أو في ملفه الشخصي.

إدارة مالكي الدورات التدريبية

يمكن لمشرفي النطاق نقل ملكية الدورات التدريبية بين المعلّمين. راجِع قسم تعديل مالك الدورة التدريبية للاطّلاع على التفاصيل المهمة.

إدارة الطلاب

يمكن لمشرفي النطاق إضافة الطلاب مباشرةً داخل نطاقهم باستخدام طريقة students.create. إذا كان الطالب يضيف نفسه مباشرةً إلى دورة تدريبية، يجب توفير enrollmentCode.

NET.

classroom/snippets/ClassroomSnippets/AddStudent.cs
using Google.Apis.Auth.OAuth2;
using Google.Apis.Classroom.v1;
using Google.Apis.Classroom.v1.Data;
using Google.Apis.Services;
using System;
using System.Net;
using Google;

namespace ClassroomSnippets
{
    // Class to demonstrate the use of Classroom Create Student API
    public class AddStudent
    {
        public static Student ClassroomAddStudent(string courseId, string enrollmentCode)
        {
            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.ClassroomRosters);
                var service = new ClassroomService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Classroom API .NET Quickstart"
                });

                var student = new Student
                {
                    UserId = "me"
                };

                var request = service.Courses.Students.Create(student, courseId);
                request.EnrollmentCode = enrollmentCode;
                student = request.Execute();
                Console.WriteLine(
                    "User '{0}' was enrolled  as a student in the course with ID '{1}'.\n",
                    student.Profile.Name.FullName, courseId);
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else if (e is GoogleApiException)
                {
                    Console.WriteLine("Failed to Add the Student. Error message: {0}", e.Message);
                }
                else
                {
                    throw;
                }
            }

            return null;
        }
    }

}

جافا

classroom/snippets/src/main/java/AddStudent.java
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.classroom.Classroom;
import com.google.api.services.classroom.ClassroomScopes;
import com.google.api.services.classroom.model.Student;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.ArrayList;
import java.util.Arrays;

/* Class to demonstrate the use of Classroom Add Student API */
public class AddStudent {

  /* Scopes required by this API call. If modifying these scopes, delete your previously saved
  tokens/ folder. */
  static ArrayList<String> SCOPES =
      new ArrayList<>(Arrays.asList(ClassroomScopes.CLASSROOM_ROSTERS));

  /**
   * Add a student in a specified course.
   *
   * @param courseId - Id of the course.
   * @param enrollmentCode - Code of the course to enroll.
   * @return newly added student
   * @throws IOException - if credentials file not found.
   * @throws GeneralSecurityException - if a new instance of NetHttpTransport was not created.
   */
  public static Student addStudent(String courseId, String enrollmentCode, String studentId)
      throws GeneralSecurityException, IOException {

    // Create the classroom API client.
    final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
    Classroom service =
        new Classroom.Builder(
                HTTP_TRANSPORT,
                GsonFactory.getDefaultInstance(),
                ClassroomCredentials.getCredentials(HTTP_TRANSPORT, SCOPES))
            .setApplicationName("Classroom samples")
            .build();

    Student student = new Student().setUserId(studentId);
    try {
      // Enrolling a student to a specified course
      student =
          service
              .courses()
              .students()
              .create(courseId, student)
              .setEnrollmentCode(enrollmentCode)
              .execute();
      // Prints the course id with the Student name
      System.out.printf(
          "User '%s' was enrolled as a student in the course with ID '%s'.\n",
          student.getProfile().getName().getFullName(), courseId);
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      GoogleJsonError error = e.getDetails();
      if (error.getCode() == 409) {
        System.out.println("You are already a member of this course.");
      } else if (error.getCode() == 403) {
        System.out.println("The caller does not have permission.\n");
      } else {
        throw e;
      }
    }
    return student;
  }
}

PHP

classroom/snippets/src/ClassroomAddStudent.php
<?php
use Google\Client;
use Google\Service\Classroom;
use Google\Service\Classroom\Student;
use Google\Service\Exception;

function enrollAsStudent($courseId,$enrollmentCode)
{
    /* Load pre-authorized user credentials from the environment.
    TODO (developer) - See https://developers.google.com/identity for
     guides on implementing OAuth2 for your application. */
    $client = new Client();
    $client->useApplicationDefaultCredentials();
    $client->addScope("https://www.googleapis.com/auth/classroom.profile.emails");
    $service = new Classroom($client);
    $student = new Student([
        'userId' => 'me'
    ]);
    $params = [
        'enrollmentCode' => $enrollmentCode
    ];
    try {
        $student = $service->courses_students->create($courseId, $student, $params);
        printf("User '%s' was enrolled  as a student in the course with ID '%s'.\n",
            $student->profile->name->fullName, $courseId);
    } catch (Exception $e) {
        if ($e->getCode() == 409) {
            print "You are already a member of this course.\n";
        } else {
            throw $e;
        }
    }
    return $student;
}

Python

classroom/snippets/classroom_add_student.py
import os

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

SCOPES = ["https://www.googleapis.com/auth/classroom.coursework.students"]


def classroom_add_student_new(course_id):
  """
  Adds a student to a course, the teacher 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.
  """

  creds = None
  # 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.
  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())

  enrollment_code = "abc-def"
  student = {"userId": "gduser1@workspacesamples.dev"}
  try:
    service = build("classroom", "v1", credentials=creds)
    student = (
        service.courses()
        .students()
        .create(
            courseId=course_id, enrollmentCode=enrollment_code, body=student
        )
        .execute()
    )
    print(
        '''User {%s} was enrolled as a student in
                   the course with ID "{%s}"'''
        % (student.get("profile").get("name").get("fullName"), course_id)
    )
    return student
  except HttpError as error:
    print(error)
    return error


if __name__ == "__main__":
  # Put the course_id of course for which student needs to be added.
  classroom_add_student_new(478800920837)

تؤدي إزالة طالب من دورة تدريبية باستخدام طريقة students.delete إلى إزالته من الدورة التدريبية المحدّدة فقط، ولا تؤثّر في تسجيله في دورات تدريبية أخرى أو في ملفه الشخصي.

استرداد دورات تدريبية خاصة بمستخدم

لاسترداد قائمة بالدورات التدريبية لطالب أو معلّم، اتّصِل بالدالة courses.list وقدِّم studentId أو teacherId الخاص بالمستخدم المعنيّ.

لا يمكنك ضبط كل من studentId وteacherId في طلب courses.list() واحد. لاسترداد قائمة بالدورات التدريبية التي تم تسجيل معلّم وطالب محدّدين فيها، عليك إجراء طلبات courses.list() منفصلة لكل مستخدم. بعد ذلك، ابحث عن التقاطع بين مجموعتَي النتائج.

استرداد ملف شخصي لمستخدم

لاسترداد الملف الشخصي لمستخدم، بما في ذلك المعرّف والاسم، يمكنك طلب userProfiles.get باستخدام معرّف المستخدم أو عنوان بريده الإلكتروني أو "me" للمستخدم الذي يرسل الطلب. لاسترداد الحقل emailAddress، يجب تضمين النطاق classroom.profile.emails.

يتوافق id الذي يتم عرضه مع مصدر Directory API Users الذي يحتوي على studentId أو teacherId المطابق.

التالي
إنشاء دعوات الدورات التدريبية وإدارتها