ניהול עבודות

אפליקציית Classroom תומכת בשלושה סוגים של פריטים בפיד: CourseWork,‏ CourseWorkMaterials ו-Announcements. במדריך הזה מוסבר איך לנהל CourseWork, אבל ממשקי ה-API של כל הפריטים בפיד דומים. במאמר משאבי API מוסבר על סוגי הפריטים בפיד ועל ההבדלים ביניהם.

מקור המידע CourseWork מייצג פריט עבודה שהוקצה לתלמידים בקורס מסוים, כולל חומרים ופרטים נוספים, כמו תאריך הגשה או ציון מקסימלי. יש ארבעה סוגי משנה של CourseWork: assignments,‏ quiz assignments,‏ short answer questions ו-multiple-choice questions. ‫Classroom API תומך בשלושה מסוגי המשנה האלה: מטלות, שאלות שיש להשיב עליהן בתשובה קצרה ושאלות אמריקאיות. הסוגים האלה מיוצגים בשדה CourseWork.workType.

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

יצירת עבודה

CourseWork אפשר ליצור רק בשם המורה של הקורס. ניסיון ליצור CourseWork בשם תלמיד או אדמין בדומיין שלא מוגדר כמורה בקורס, יוביל לשגיאה PERMISSION_DENIED. מידע נוסף על התפקידים השונים ב-Classroom זמין במאמר סוגי משתמשים.

כשיוצרים CourseWork באמצעות השיטה courses.courseWork.create, אפשר לצרף קישורים כ-materials, כמו שמוצג בקוד לדוגמה שלמטה:

Java

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;

Python

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 במצב טיוטה.

משתמשים במשאב Link עם יעד מוגדר url כדי לכלול חומרים מקושרים ב-CourseWork. ‫Classroom מאחזר באופן אוטומטי את title ואת כתובת ה-URL של תמונת התצוגה המקדימה (thumbnailUrl). בנוסף, Classroom API תומך באופן מובנה בחומרי לימוד מ-Google Drive ומ-YouTube, שאפשר לכלול אותם במשאב DriveFile או במשאב YouTubeVideo בצורה דומה.

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

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

אחזור של עבודה לכיתה

אתם יכולים לאחזר את 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 כדי לאחזר את השליחה.

כדי לקבל את כל המשאבים מסוג StudentSubmission שתואמים לקריטריונים מסוימים, משתמשים בשיטה courses.courseWork.studentSubmissions.list, כמו בדוגמה הבאה:

Java

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;

Python

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, כמו בדוגמה הבאה:

Java

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

Python

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, כמו בדוגמה הבאה:

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