تتوفّر الآن إضافات Google Classroom بشكل عام للمطوّرين. يُرجى الاطّلاع على مستندات الإضافات للحصول على مزيد من المعلومات.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إدارة "المهام الدراسية"

يتيح تطبيق Classroom ثلاثة أنواع من عناصر ساحة المشاركات: CourseWork وCourseWorkMaterials وAnnouncements. يوضّح هذا الدليل كيفية إدارة CourseWork، ولكن واجهات برمجة التطبيقات الخاصة بجميع عناصر البث متشابهة. يمكنك الاطّلاع على مراجع واجهة برمجة التطبيقات لمعرفة المزيد عن أنواع عناصر البث واختلافاتها.

يمثّل المورد CourseWork مهمة تم تعيينها للطلاب في صف معيّن، بما في ذلك أي مواد وتفاصيل إضافية، مثل تاريخ التسليم أو الحد الأقصى للنتيجة. هناك أربعة أنواع فرعية من CourseWork: المهام ومهام الاختبارات وأسئلة الإجابات القصيرة وأسئلة الخيارات المتعددة. تتيح Classroom API ثلاثة من هذه الأنواع الفرعية، وهي: المهام والأسئلة ذات الإجابات القصيرة والأسئلة ذات الخيارات المتعدّدة. يتم تمثيل هذه الأنواع من خلال الحقل CourseWork.workType.

بالإضافة إلى المرجع CourseWork، يمكنك إدارة العمل المكتمل باستخدام المرجع StudentSubmission.

Create CourseWork

لا يمكن إنشاء CourseWork إلا نيابةً عن معلّم الدورة التدريبية. ستؤدي محاولة إنشاء CourseWork نيابةً عن طالب أو مشرف نطاق ليس معلّمًا في الدورة التدريبية إلى ظهور الخطأ PERMISSION_DENIED. اطّلِع على أنواع المستخدمين لمعرفة المزيد عن الأدوار المختلفة في Classroom.

عند إنشاء CourseWork باستخدام طريقة courses.courseWork.create، يمكنك إرفاق روابط كـ materials، كما هو موضّح في نموذج الرمز البرمجي أدناه:

Java

classroom/snippets/src/main/java/CreateCourseWork.java

عرض على GitHub

CourseWork courseWork = null;
try {
  // Create a link to add as a material on course work.
  Link articleLink =
      new Link()
          .setTitle("SR-71 Blackbird")
          .setUrl("https://www.lockheedmartin.com/en-us/news/features/history/blackbird.html");

  // Create a list of Materials to add to course work.
  List<Material> materials = Arrays.asList(new Material().setLink(articleLink));

  /* Create new CourseWork object with the material attached.
  Set workType to `ASSIGNMENT`. Possible values of workType can be found here:
  https://developers.google.com/classroom/reference/rest/v1/CourseWorkType
  Set state to `PUBLISHED`. Possible values of state can be found here:
  https://developers.google.com/classroom/reference/rest/v1/courses.courseWork#courseworkstate */
  CourseWork content =
      new CourseWork()
          .setTitle("Supersonic aviation")
          .setDescription(
              "Read about how the SR-71 Blackbird, the world’s fastest and "
                  + "highest-flying manned aircraft, was built.")
          .setMaterials(materials)
          .setWorkType("ASSIGNMENT")
          .setState("PUBLISHED");

  courseWork = service.courses().courseWork().create(courseId, content).execute();

  /* Prints the created courseWork. */
  System.out.printf("CourseWork created: %s\n", courseWork.getTitle());
} catch (GoogleJsonResponseException e) {
  // TODO (developer) - handle error appropriately
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf("The courseId does not exist: %s.\n", courseId);
  } else {
    throw e;
  }
  throw e;
} catch (Exception e) {
  throw e;
}
return courseWork;

Python

classroom/snippets/classroom_create_coursework.py

عرض على GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def classroom_create_coursework(course_id):
  """
  Creates the coursework 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()
  # pylint: disable=maybe-no-member

  try:
    service = build("classroom", "v1", credentials=creds)
    coursework = {
        "title": "Ant colonies",
        "description": """Read the article about ant colonies
                              and complete the quiz.""",
        "materials": [
            {"link": {"url": "http://example.com/ant-colonies"}},
            {"link": {"url": "http://example.com/ant-quiz"}},
        ],
        "workType": "ASSIGNMENT",
        "state": "PUBLISHED",
    }
    coursework = (
        service.courses()
        .courseWork()
        .create(courseId=course_id, body=coursework)
        .execute()
    )
    print(f"Assignment created with ID {coursework.get('id')}")
    return coursework

  except HttpError as error:
    print(f"An error occurred: {error}")
    return error


if __name__ == "__main__":
  # Put the course_id of course whose coursework needs to be created,
  # the user has access to.
  classroom_create_coursework(453686957652)

يجب ملء الحقلَين title وworkType. جميع الحقول الأخرى اختيارية. إذا لم يتم تحديد state، سيتم إنشاء CourseWork في حالة مسودة.

استخدِم مرجع رابط مع هدف محدّد url لتضمين مواد مرتبطة في CourseWork. يجلب Classroom تلقائيًا title وعنوان URL الخاص بالصورة المصغّرة (thumbnailUrl). تتوافق Classroom API أيضًا بشكلٍ أصلي مع مواد Google Drive وYouTube، والتي يمكن تضمينها باستخدام مورد DriveFile أو مورد YouTubeVideo بطريقة مماثلة.

لتحديد تاريخ استحقاق، اضبط الحقلَين dueDate وdueTime على وقت التوقيت العالمي المنسق (UTC) المناسب. يجب أن يكون تاريخ الاستحقاق في المستقبل.

يتضمّن الرد CourseWork معرّفًا يحدّده الخادم ويمكن استخدامه للإشارة إلى عملية التعيين في طلبات أخرى من واجهة برمجة التطبيقات.

استرداد CourseWork

يمكنك استرداد CourseWork نيابةً عن الطلاب والمعلّمين في الدورة التدريبية المعنية. يمكنك أيضًا استرداد CourseWork نيابةً عن مشرفي النطاق، حتى إذا لم يكونوا معلّمين في الدورة التدريبية. لاسترداد CourseWork معيّن، استخدِم courses.courseWork.get. لاسترداد جميع CourseWork (مع مطابقة بعض المعايير اختياريًا)، استخدِم courses.courseWork.list.

يعتمد النطاق المطلوب على الدور الذي يملكه المستخدم الذي يقدّم الطلب في الدورة التدريبية. إذا كان المستخدم طالبًا، استخدِم أحد النطاقات التالية:

https://www.googleapis.com/auth/classroom.coursework.me.readonly
https://www.googleapis.com/auth/classroom.coursework.me

إذا كان المستخدم معلّمًا أو مشرف نطاق، استخدِم أحد النطاقات التالية:

https://www.googleapis.com/auth/classroom.coursework.students.readonly
https://www.googleapis.com/auth/classroom.coursework.students

إنّ الحصول على إذن باسترداد CourseWork لا يعني الحصول على أذونات للوصول إلى المواد أو البيانات الوصفية الخاصة بها. يعني ذلك عمليًا أنّه قد لا يظهر عنوان ملف Drive مرفق للمشرف إذا لم يكن عضوًا في الدورة التدريبية.

إدارة ردود الطلاب

يمثّل مرجع StudentSubmission العمل الذي أنجزه الطالب في CourseWork. يتضمّن المرجع بيانات وصفية ذات صلة بالعمل، مثل حالة العمل والدرجة. يتم إنشاء StudentSubmission ضمنيًا لكل طالب عند إنشاء CourseWork جديد.

توضّح الأقسام التالية الإجراءات الشائعة التي تدير ردود الطلاب.

استرداد ردود الطلاب

يمكن للطلاب استرداد المهام التي أرسلوها، ويمكن للمعلّمين استرداد المهام التي أرسلها جميع الطلاب في دوراتهم التدريبية، ويمكن لمشرفي النطاق استرداد جميع المهام التي أرسلها جميع الطلاب في نطاقهم. يتم تخصيص معرّف لكل StudentSubmission. إذا كنت تعرف المعرّف، استخدِم courses.courseWork.studentSubmissions.get لاسترداد الطلب.

استخدِم طريقة courses.courseWork.studentSubmissions.list للحصول على جميع موارد StudentSubmission التي تتطابق مع بعض المعايير، كما هو موضّح في المثال التالي:

Java

classroom/snippets/src/main/java/ListSubmissions.java

عرض على GitHub

List<StudentSubmission> studentSubmissions = new ArrayList<>();
String pageToken = null;

try {
  do {
    ListStudentSubmissionsResponse response =
        service
            .courses()
            .courseWork()
            .studentSubmissions()
            .list(courseId, courseWorkId)
            .setPageToken(pageToken)
            .execute();

    /* Ensure that the response is not null before retrieving data from it to avoid errors. */
    if (response.getStudentSubmissions() != null) {
      studentSubmissions.addAll(response.getStudentSubmissions());
      pageToken = response.getNextPageToken();
    }
  } while (pageToken != null);

  if (studentSubmissions.isEmpty()) {
    System.out.println("No student submission found.");
  } else {
    for (StudentSubmission submission : studentSubmissions) {
      System.out.printf(
          "Student id (%s), student submission id (%s)\n",
          submission.getUserId(), submission.getId());
    }
  }
} catch (GoogleJsonResponseException e) {
  // TODO (developer) - handle error appropriately
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf(
        "The courseId (%s) or courseWorkId (%s) does not exist.\n", courseId, courseWorkId);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return studentSubmissions;

Python

classroom/snippets/classroom_list_submissions.py

عرض على GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def classroom_list_submissions(course_id, coursework_id):
  """
  Creates the courses 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()
  # pylint: disable=maybe-no-member
  submissions = []
  page_token = None

  try:
    service = build("classroom", "v1", credentials=creds)
    while True:
      coursework = service.courses().courseWork()
      response = (
          coursework.studentSubmissions()
          .list(
              pageToken=page_token,
              courseId=course_id,
              courseWorkId=coursework_id,
              pageSize=10,
          )
          .execute()
      )
      submissions.extend(response.get("studentSubmissions", []))
      page_token = response.get("nextPageToken", None)
      if not page_token:
        break

    if not submissions:
      print("No student submissions found.")

    print("Student Submissions:")
    for submission in submissions:
      print(
          "Submitted at:"
          f"{(submission.get('id'), submission.get('creationTime'))}"
      )

  except HttpError as error:
    print(f"An error occurred: {error}")
    submissions = None
  return submissions


if __name__ == "__main__":
  # Put the course_id and coursework_id of course whose list needs to be
  # submitted.
  classroom_list_submissions(453686957652, 466086979658)

يمكنك استرداد موارد StudentSubmission تخص طالبًا معيّنًا من خلال تحديد المَعلمة userId، كما هو موضّح في المثال التالي:

Java

classroom/snippets/src/main/java/ListStudentSubmissions.java

عرض على GitHub

List<StudentSubmission> studentSubmissions = new ArrayList<>();
String pageToken = null;

try {
  do {
    // Set the userId as a query parameter on the request.
    ListStudentSubmissionsResponse response =
        service
            .courses()
            .courseWork()
            .studentSubmissions()
            .list(courseId, courseWorkId)
            .setPageToken(pageToken)
            .set("userId", userId)
            .execute();

    /* Ensure that the response is not null before retrieving data from it to avoid errors. */
    if (response.getStudentSubmissions() != null) {
      studentSubmissions.addAll(response.getStudentSubmissions());
      pageToken = response.getNextPageToken();
    }
  } while (pageToken != null);

  if (studentSubmissions.isEmpty()) {
    System.out.println("No student submission found.");
  } else {
    for (StudentSubmission submission : studentSubmissions) {
      System.out.printf("Student submission: %s.\n", submission.getId());
    }
  }

Python

classroom/snippets/classroom_list_student_submissions.py

عرض على GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def classroom_list_student_submissions(course_id, coursework_id, user_id):
  """
  Creates the courses 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()
  # pylint: disable=maybe-no-member
  submissions = []
  page_token = None

  try:
    service = build("classroom", "v1", credentials=creds)
    while True:
      coursework = service.courses().courseWork()
      response = (
          coursework.studentSubmissions()
          .list(
              pageToken=page_token,
              courseId=course_id,
              courseWorkId=coursework_id,
              userId=user_id,
          )
          .execute()
      )
      submissions.extend(response.get("studentSubmissions", []))
      page_token = response.get("nextPageToken", None)
      if not page_token:
        break

    if not submissions:
      print("No student submissions found.")

    print("Student Submissions:")
    for submission in submissions:
      print(
          "Submitted at:"
          f"{(submission.get('id'), submission.get('creationTime'))}"
      )

  except HttpError as error:
    print(f"An error occurred: {error}")
  return submissions


if __name__ == "__main__":
  # Put the course_id, coursework_id and user_id of course whose list needs
  # to be submitted.
  classroom_list_student_submissions(453686957652, 466086979658, "me")

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

يمكن أيضًا استرداد المهام التي أرسلها الطلاب لجميع المهام الدراسية ضمن إحدى الدورات التدريبية. لإجراء ذلك، استخدِم القيمة الحرفية "-" كـ courseWorkId، كما هو موضّح في المثال التالي:

Java

service.courses().courseWork().studentSubmissions()
    .list(courseId, "-")
    .set("userId", userId)
    .execute();

Python

service.courses().courseWork().studentSubmissions().list(
    courseId=<course ID or alias>,
    courseWorkId='-',
    userId=<user ID>).execute()

يعتمد النطاق المطلوب على الدور الذي يملكه المستخدم الذي يقدّم الطلب في الدورة التدريبية. إذا كان المستخدم معلّمًا أو مشرف نطاق، استخدِم النطاق التالي:

https://www.googleapis.com/auth/classroom.coursework.students.readonly
https://www.googleapis.com/auth/classroom.coursework.students

إذا كان المستخدم طالبًا، استخدِم النطاق التالي:

https://www.googleapis.com/auth/classroom.coursework.me.readonly
https://www.googleapis.com/auth/classroom.coursework.me

لا يعني الحصول على إذن باسترداد StudentSubmission توفّر أذونات للوصول إلى المرفقات أو البيانات الوصفية الخاصة بها. يعني ذلك عمليًا أنّه قد لا يظهر عنوان ملف Drive مرفق للمشرف إذا لم يكن عضوًا في الدورة التدريبية.

إضافة مرفقات إلى ردّ الطالب

يمكنك إرفاق روابط بمهمة أرسلها طالب من خلال إرفاق مرجع Link أو DriveFile أو YouTubeVideo. يتم ذلك باستخدام courses.courseWork.studentSubmissions.modifyAttachments، كما هو موضّح في المثال التالي:

Java

classroom/snippets/src/main/java/ModifyAttachmentsStudentSubmission.java

عرض على GitHub

StudentSubmission studentSubmission = null;
try {
  // Create ModifyAttachmentRequest object that includes a new attachment with a link.
  Link link = new Link().setUrl("https://en.wikipedia.org/wiki/Irrational_number");
  Attachment attachment = new Attachment().setLink(link);
  ModifyAttachmentsRequest modifyAttachmentsRequest =
      new ModifyAttachmentsRequest().setAddAttachments(Arrays.asList(attachment));

  // The modified studentSubmission object is returned with the new attachment added to it.
  studentSubmission =
      service
          .courses()
          .courseWork()
          .studentSubmissions()
          .modifyAttachments(courseId, courseWorkId, id, modifyAttachmentsRequest)
          .execute();

  /* Prints the modified student submission. */
  System.out.printf(
      "Modified student submission attachments: '%s'.\n",
      studentSubmission.getAssignmentSubmission().getAttachments());
} catch (GoogleJsonResponseException e) {
  // TODO (developer) - handle error appropriately
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf(
        "The courseId (%s), courseWorkId (%s), or studentSubmissionId (%s) does "
            + "not exist.\n",
        courseId, courseWorkId, id);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return studentSubmission;

Python

classroom/snippets/classroom_add_attachment.py

عرض على GitHub

def classroom_add_attachment(course_id, coursework_id, submission_id):
  """
  Adds attachment 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
  request = {
      "addAttachments": [
          {"link": {"url": "http://example.com/quiz-results"}},
          {"link": {"url": "http://example.com/quiz-reading"}},
      ]
  }

  try:
    service = build("classroom", "v1", credentials=creds)
    while True:
      coursework = service.courses().courseWork()
      coursework.studentSubmissions().modifyAttachments(
          courseId=course_id,
          courseWorkId=coursework_id,
          id=submission_id,
          body=request,
      ).execute()

  except HttpError as error:
    print(f"An error occurred: {error}")


if __name__ == "__main__":
  # Put the course_id, coursework_id and submission_id of course in which
  # attachment needs to be added.
  classroom_add_attachment("course_id", "coursework_id", "me")

يتم تحديد المرفق Link من خلال الهدف url، ويجلب Classroom تلقائيًا title والصورة المصغّرة (thumbnailUrl). راجِع Material للتعرّف على المواد التي يمكن إرفاقها بـ StudentSubmissions.

لا يمكن تعديل StudentSubmission إلا من قِبل معلّم الدورة التدريبية أو الطالب الذي يملكها. لا يمكنك إرفاق Materials إلا إذا كانت CourseWorkType الخاصة بـ StudentSubmission هي ASSIGNMENT.

يعتمد النطاق المطلوب على الدور الذي يملكه المستخدم الذي يقدّم الطلب في الدورة التدريبية. إذا كان المستخدم معلّمًا، استخدِم النطاق التالي:

https://www.googleapis.com/auth/classroom.coursework.students

إذا كان المستخدم طالبًا، استخدِم النطاق التالي:

https://www.googleapis.com/auth/classroom.coursework.me

إنشاء المواضيع وإدارتها

إدارة "المهام الدراسية" تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

Create CourseWork

Java

Python

استرداد CourseWork

إدارة ردود الطلاب

استرداد ردود الطلاب

Java

Python

Java

Python

Java

Python

إضافة مرفقات إلى ردّ الطالب

Java

Python

إدارة "المهام الدراسية"