CourseWork را مدیریت کنید

برنامه Classroom از سه نوع آیتم جریانی پشتیبانی می‌کند: CourseWork ، CourseWorkMaterials ، و Announcements . این راهنما نحوه مدیریت CourseWork را توضیح می‌دهد، اما APIهای همه موارد جریان مشابه هستند. برای اطلاعات بیشتر در مورد انواع آیتم های جریانی و تفاوت های آنها به منابع API مراجعه کنید.

منبع CourseWork یک مورد کاری را نشان می‌دهد که در یک دوره خاص به دانش‌آموزان اختصاص داده شده است، شامل هر گونه مطالب و جزئیات اضافی، مانند تاریخ سررسید یا حداکثر امتیاز. چهار نوع فرعی از CourseWork وجود دارد: تکالیف ، تکالیف امتحانی ، سوالات پاسخ کوتاه و سوالات چند گزینه ای . Classroom API از سه مورد از این زیرمجموعه ها پشتیبانی می کند: تکالیف، سؤالات پاسخ کوتاه و سؤالات چند گزینه ای. این انواع با فیلد CourseWork.workType نشان داده می شوند.

علاوه بر منبع CourseWork ، می توانید کارهای تکمیل شده را با منبع StudentSubmission مدیریت کنید.

ایجاد دوره آموزشی

CourseWork فقط می تواند از طرف معلم دوره ایجاد شود. تلاش برای ایجاد CourseWork از طرف یک دانش آموز، یا مدیر دامنه که در این دوره معلم نیست، منجر به خطای PERMISSION_DENIED می شود. برای آشنایی بیشتر با نقش‌های مختلف در Classroom، به انواع کاربر مراجعه کنید.

هنگام ایجاد CourseWork با استفاده از روش courses.courseWork.create ، می توانید پیوندهایی را به عنوان materials پیوست کنید که در کد نمونه زیر نشان داده شده است:

جاوا

classroom/snippets/src/main/java/CreateCourseWork.java
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;

پایتون

classroom/snippets/classroom_create_coursework.py
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 و نشانی اینترنتی تصویر کوچک ( thumbnailUrl ) را واکشی می کند. Classroom API همچنین به طور بومی از مطالب Google Drive و YouTube پشتیبانی می‌کند که می‌توانند به روشی مشابه با منبع DriveFile یا منبع YouTubeVideo اضافه شوند.

برای تعیین تاریخ سررسید، فیلدهای dueDate و dueTime را روی زمان UTC مربوطه تنظیم کنید. تاریخ سررسید باید در آینده باشد.

پاسخ CourseWork شامل یک شناسه اختصاص داده شده به سرور است که می تواند برای ارجاع به انتساب در سایر درخواست های API استفاده شود.

بازیابی 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 است. این منبع شامل ابرداده های مرتبط با کار، مانند وضعیت کار و درجه است. هنگامی که یک CourseWork جدید ایجاد می شود، یک StudentSubmission به طور ضمنی برای هر دانش آموز ایجاد می شود.

بخش‌های زیر اقدامات رایجی را که پاسخ‌های دانش‌آموز را مدیریت می‌کنند توضیح می‌دهند.

بازیابی پاسخ های دانش آموزان

دانش‌آموزان می‌توانند مطالب ارسالی خود را بازیابی کنند، معلمان می‌توانند موارد ارسالی را برای همه دانش‌آموزان در دوره‌های خود بازیابی کنند، و مدیران دامنه می‌توانند همه موارد ارسالی را برای همه دانش‌آموزان در حوزه خود بازیابی کنند. به هر StudentSubmission یک شناسه اختصاص داده می شود. اگر شناسه را می‌شناسید، از courses.courseWork.studentSubmissions.get برای بازیابی مطالب ارسالی استفاده کنید.

همانطور که در نمونه زیر نشان داده شده است، از روش courses.courseWork.studentSubmissions.list برای دریافت همه منابع StudentSubmission که با برخی از معیارها مطابقت دارند، استفاده کنید:

جاوا

classroom/snippets/src/main/java/ListSubmissions.java
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;

پایتون

classroom/snippets/classroom_list_submissions.py
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 بازیابی کنید:

جاوا

classroom/snippets/src/main/java/ListStudentSubmissions.java
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());
    }
  }

پایتون

classroom/snippets/classroom_list_student_submissions.py
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 استفاده کنید:

جاوا

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

پایتون

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 انجام می شود، همانطور که در نمونه زیر نشان داده شده است:

جاوا

classroom/snippets/src/main/java/ModifyAttachmentsStudentSubmission.java
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;

پایتون

classroom/snippets/classroom_add_attachment.py
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 ) را واکشی می کند. برای آشنایی با مطالبی که می‌توانند به StudentSubmissions پیوست شوند، به Material مراجعه کنید.

StudentSubmission فقط می تواند توسط یک معلم دوره یا توسط دانش آموزی که مالک آن است اصلاح شود. فقط در صورتی می توانید Materials ضمیمه کنید که CourseWorkType StudentSubmission ASSIGNMENT باشد.

محدوده مورد نیاز به نقشی که کاربر درخواست کننده در دوره دارد بستگی دارد. اگر کاربر معلم است، از دامنه زیر استفاده کنید:

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

اگر کاربر دانشجو است، از محدوده زیر استفاده کنید:

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