Zarządzanie materiałami dydaktycznymi

Aplikacja Classroom obsługuje 3 typy elementów strumienia: CourseWork, CourseWorkMaterialsAnnouncements. Ten przewodnik opisuje, jak zarządzać CourseWork, ale interfejsy API wszystkich elementów strumienia są podobne. Więcej informacji o typach elementów strumienia i ich różnicach znajdziesz w sekcji Zasoby interfejsu API.

CourseWork reprezentuje element pracy przypisany do uczniów na konkretnym kursie, w tym wszelkie dodatkowe materiały i szczegóły, takie jak termin lub maksymalna liczba punktów. Istnieją 4 podtypy CourseWork: projekty, projekty – testy, pytania z krótką odpowiedzią i pytania wielokrotnego wyboru. Interfejs Classroom API obsługuje 3 z tych podtypów: projekty, pytania z krótką odpowiedzią i pytania jednokrotnego wyboru. Te typy są reprezentowane przez pole CourseWork.workType.

Oprócz zasobu CourseWork możesz zarządzać ukończoną pracą za pomocą zasobu StudentSubmission.

Tworzenie zadania

CourseWork można utworzyć tylko w imieniu nauczyciela kursu. Próba utworzenia CourseWork w imieniu ucznia lub administratora domeny, który nie jest nauczycielem na kursie, powoduje błąd PERMISSION_DENIED. Więcej informacji o różnych rolach w Classroom znajdziesz w artykule Typy użytkowników.

Podczas tworzenia CourseWork za pomocą metody courses.courseWork.create możesz dołączać linki jako materials, jak pokazano w poniższym przykładowym kodzie:

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)

Pola title i workType są wymagane. Wszystkie pozostałe pola są opcjonalne. Jeśli nie podasz wartości state, element CourseWork zostanie utworzony w stanie wersji roboczej.

Użyj zasobu Link z określonym celem url, aby uwzględnić połączone materiały w CourseWork. Classroom automatycznie pobiera title i adres URL obrazu miniatury (thumbnailUrl). Interfejs Classroom API natywnie obsługuje też materiały z Dysku Google i YouTube, które można dołączyć w podobny sposób za pomocą zasobu DriveFile lub zasobu YouTubeVideo.

Aby określić termin, ustaw pola dueDatedueTime na odpowiedni czas UTC. Termin musi przypadać w przyszłości.

Odpowiedź CourseWork zawiera identyfikator przypisany przez serwer, którego można używać do odwoływania się do przypisania w innych żądaniach API.

Pobieranie zadania

Możesz pobrać CourseWork w imieniu uczniów i nauczycieli odpowiedniego kursu. Możesz też pobierać CourseWork w imieniu administratorów domeny, nawet jeśli nie są nauczycielami na zajęciach. Aby pobrać konkretny CourseWork, użyj courses.courseWork.get. Aby pobrać wszystkie elementyCourseWork (opcjonalnie pasujące do określonych kryteriów), użyjcourses.courseWork.list.

Wymagany zakres zależy od roli użytkownika wysyłającego żądanie w kursie. Jeśli użytkownik jest uczniem, użyj jednego z tych zakresów:

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

Jeśli użytkownik jest nauczycielem lub administratorem domeny, użyj jednego z tych zakresów:

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

Posiadanie uprawnień do pobierania CourseWork nie oznacza uprawnień do dostępu do materiałów ani metadanych materiałów. W praktyce oznacza to, że administrator może nie widzieć tytułu załączonego pliku na Dysku, jeśli nie jest użytkownikiem zajęć.

Zarządzanie odpowiedziami uczniów

Zasób StudentSubmission reprezentuje pracę wykonaną przez ucznia w ramach CourseWork. Zasób zawiera metadane związane z pracą, takie jak stan pracy i ocena. Dla każdego ucznia jest automatycznie tworzony StudentSubmission, gdy tworzony jest nowy CourseWork.

W sekcjach poniżej znajdziesz opis typowych działań związanych z zarządzaniem odpowiedziami uczniów.

Pobieranie odpowiedzi uczniów

Uczniowie mogą pobierać własne przesłane projekty, nauczyciele mogą pobierać przesłane projekty wszystkich uczniów na swoich kursach, a administratorzy domeny mogą pobierać wszystkie przesłane projekty wszystkich uczniów w domenie. Każdemu StudentSubmission przypisywany jest identyfikator. Jeśli znasz identyfikator, użyj courses.courseWork.studentSubmissions.get, aby pobrać zgłoszenie.

Użyj metody courses.courseWork.studentSubmissions.list, aby pobrać wszystkie zasoby StudentSubmission, które spełniają określone kryteria, jak pokazano w tym przykładzie:

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)

Pobierz zasoby StudentSubmission należące do konkretnego ucznia, podając parametr userId, jak pokazano w tym przykładzie:

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

Uczniowie są identyfikowani na podstawie unikalnego identyfikatora lub adresu e-mail, jak to przedstawiono w zasobie Student. Bieżący użytkownik może też odwoływać się do własnego identyfikatora za pomocą skrótu "me".

Możesz też pobrać przesłane przez uczniów projekty ze wszystkich projektów w ramach kursu. W tym celu użyj literału "-" jako courseWorkId, jak pokazujemy w tym przykładzie:

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

Wymagany zakres zależy od roli użytkownika wysyłającego żądanie w kursie. Jeśli użytkownik jest nauczycielem lub administratorem domeny, użyj tego zakresu:

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

Jeśli użytkownik jest uczniem, użyj tego zakresu:

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

Uprawnienie do pobierania StudentSubmission nie oznacza uprawnień do dostępu do załączników ani metadanych załączników. W praktyce oznacza to, że administrator może nie widzieć tytułu załączonego pliku na Dysku, jeśli nie jest użytkownikiem zajęć.

Dodawanie załączników do odpowiedzi ucznia

Możesz dołączyć linki do przesłanego przez ucznia zadania, dodając zasób Link, DriveFile lub YouTubeVideo. Możesz to zrobić za pomocą elementu courses.courseWork.studentSubmissions.modifyAttachments, jak pokazano w tym przykładzie:

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 załącznik jest określany przez element docelowy url; Classroom automatycznie pobiera title i miniaturę (thumbnailUrl). Więcej informacji o materiałach, które można dołączyć do StudentSubmissions, znajdziesz w artykule Material.

StudentSubmission może modyfikować tylko nauczyciel prowadzący kurs lub uczeń, który jest jego właścicielem. Możesz dołączyć Materials tylko wtedy, gdy CourseWorkType StudentSubmission ma wartość ASSIGNMENT.

Wymagany zakres zależy od roli użytkownika wysyłającego żądanie w kursie. Jeśli użytkownik jest nauczycielem, użyj tego zakresu:

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

Jeśli użytkownik jest uczniem, użyj tego zakresu:

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