ניהול עבודות

ממשק המשתמש של Classroom תומך בחמישה סוגים של עבודות: מטלות, בחנים, שאלות שיש להשיב עליהן בתשובה קצרה, שאלות אמריקאיות וחומרים. כרגע, Classroom API תומך בשלושה מהסוגים האלה, שנקראים CourseWorkType ב-API: מטלות, שאלות עם תשובה קצרה ושאלות אמריקאיות.

הערה: אפשר ליצור Materials כ'עבודות' בממשק המשתמש של Classroom, אבל ה-API תומך רק בקישור של Materials למשאבים של CourseWorkType: מטלות, שאלות עם תשובה קצרה ושאלות אמריקאיות.

כדי לגשת לפונקציונליות הזו, אפשר להשתמש במשאב CourseWork, שמייצג מטלה או שאלה שהוקצו לתלמידים בקורס מסוים, כולל חומרים ופרטים נוספים, כמו תאריך הגשה או ציון מקסימלי.

בנוסף למשאב CourseWork, אפשר לנהל מטלות שהוגשו באמצעות המשאב StudentSubmission. בקטעים הבאים מוסבר בהרחבה על הנושאים האלה.

יצירת מטלות

אפשר ליצור מטלות רק בשם המורים של הקורס. ניסיון ליצור מטלות בקורס בשם תלמיד יוביל לשגיאה 403 PERMISSION_DENIED. באופן דומה, אדמינים בדומיין לא יכולים ליצור מטלות לקורסים שהם לא מלמדים, וניסיון לעשות זאת דרך ה-API יוביל גם לשגיאה 403 PERMISSION_DENIED.

כשיוצרים מטלות באמצעות השיטה 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)

התוצאה כוללת מזהה שהוקצה על ידי השרת, שאפשר להשתמש בו כדי להפנות למטלה בבקשות API אחרות.

השדות title ו-workType הם חובה. כל שאר השדות הם אופציונליים. אם לא מציינים את state, נוצרת טיוטה של מטלה.

כדי לכלול חומרים מקושרים במטלה שנוצרה באמצעות Classroom API, צריך להשתמש במשאב קישור ולציין את כתובת ה-URL של היעד. מערכת Classroom מאחזרת את השם ואת התמונה הממוזערת באופן אוטומטי. ממשק Classroom API תומך גם באופן מקורי בחומרים מ-Google Drive ומ-YouTube. אפשר לכלול אותם במשאב DriveFile או במשאב YouTubeVideo באופן דומה.

כדי לציין מועד הגשה, מגדירים את השדות dueDate ו-dueTime לשעה המתאימה לפי UTC. תאריך היעד חייב להיות בעתיד.

אחזור מטלות ושאלות

תלמידים ומורים בקורס הרלוונטי או אדמינים בדומיין יכולים לאחזר מטלות ושאלות. כדי לאחזר מטלה או שאלה ספציפית, משתמשים ב-courses.courseWork.get. כדי לאחזר את כל המטלות או השאלות (אופציונלי בהתאם לקריטריונים מסוימים), משתמשים ב-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

הרשאה לאחזר מטלה או שאלה לא מובילה להרשאות גישה לחומרים או למטא-נתונים שלהם. בפועל, המשמעות היא שאדמינים לא יכולים לראות את השם של קובץ מצורף ב-Drive אם הם לא רשומים לקורס. אם אתם רוצים לתת לאדמינים גישה לקובצי המשתמשים, תוכלו לעיין במדריך בנושא הענקת גישה ברמת הדומיין.

ניהול התשובות של התלמידים

משאב StudentSubmission מייצג את העבודה והציון של תלמיד או תלמידה במטלה או בשאלה. משאב StudentSubmission נוצר באופן משתמע לכל תלמיד או תלמידה כשיוצרים שאלה או מטלה חדשה.

רק הפרויקט במסוף הפיתוח שבו נוצר המשאב CourseWork התואם יכול לשנות את המטלות שהתלמידים שלחו. בנוסף, צריך לבדוק שלמשתמש המבקש יש את ההרשאות הנכונות. כל לקוח OAuth2 בפרויקט יכול לבצע שינויים. השדה associatedWithDeveloper מציין אם לקוח OAuth2 הנוכחי יכול לשנות 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")

התלמידים מזוהים לפי המזהה הייחודי או כתובת האימייל של המשתמש, כפי שהם מוחזרים על ידי Google Admin SDK. המשתמש הנוכחי יכול גם להפנות למזהה שלו באמצעות הקיצור "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

הרשאה לאחזר מטלה שהוגשה על ידי תלמיד/ה לא מובילה להרשאות גישה לקבצים המצורפים או למטא-נתונים שלהם. בפועל, המשמעות היא שאדמינים לא יכולים לראות את השם של קובץ ב-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")

קובץ מצורף מסוג קישור מוגדר לפי כתובת ה-URL של היעד. מערכת Classroom תאחזר באופן אוטומטי את הכותרת ואת התמונה הממוזערת. מידע על החומרים האחרים זמין בדפי העזרה הרלוונטיים.

רק מורה הקורס או התלמיד/ה שבבעלותם הקישור יכולים לשנות את StudentSubmission. אפשר לצרף את Materials רק אם הערך של CourseWorkType בעבודה של התלמיד/ה הוא ASSIGNMENT.

ההיקף הנדרש תלוי בתפקיד של המשתמש המבקש בקורס. אם המשתמש הוא מורה, צריך להשתמש בהיקף הבא:

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

אם המשתמש הוא תלמיד/ה, צריך להשתמש בהיקף הבא:

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