Zarządzanie zadaniami i ocenami

Interfejs Classroom obsługuje 5 typów zadań: Projekty, Testy, Pytania z krótką odpowiedzią, Pytania jednokrotnego wyboru i Materiały. Interfejs Classroom API obecnie obsługuje 3 typy tych typów – CourseWorkType w przypadku interfejsu API: Projekty, pytania z krótką odpowiedzią i pytania jednokrotnego wyboru.

Materials do zasobów: CourseWorkType, projekty, pytania z krótką odpowiedzią i pytania jednokrotnego wyboru.

Aby uzyskać dostęp do tej funkcji, możesz skorzystać z zasobu CourseWork, który reprezentuje projekt lub pytanie przypisane uczniom na danym kursie, wraz z wszelkimi dodatkowymi materiałami i informacjami, takimi jak termin oddania czy maksymalna liczba punktów.

Ukończonymi projektami możesz zarządzać nie tylko za pomocą zasobu CourseWork, ale też za pomocą zasobu StudentSubmission. Poniżej znajdziesz więcej informacji.

Tworzenie projektów

Projekty można tworzyć tylko w imieniu nauczycieli na zajęciach. Próba utworzenia projektów na zajęciach w imieniu ucznia spowoduje wystąpienie błędu 403 PERMISSION_DENIED. Administratorzy domen również nie mogą tworzyć projektów dla zajęć, których nie uczą, a próba ich utworzenia za pomocą interfejsu API również spowoduje wystąpienie błędu 403 PERMISSION_DENIED.

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

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)

Wynik zawiera identyfikator przypisany przez serwer, który może służyć do odwoływania się do przypisania w innych żądaniach do interfejsu API.

Aby dołączyć połączone materiały w projekcie utworzonym za pomocą interfejsu Classroom API, użyj zasobu linku, podając docelowy adres URL. Classroom automatycznie pobierze tytuł i miniaturę. Interfejs Classroom API natywnie obsługuje też materiały z Dysku Google i YouTube, które w podobny sposób można dodać do zasobów DriveFile lub YouTubeVideo.

Aby określić termin, ustaw w polach dueDate i dueTime odpowiedni czas UTC. Termin musi przypadać w przyszłości.

Pobierz projekty i pytania

Możesz pobrać projekty i pytania dla uczniów i nauczycieli odpowiadających im zajęć lub przez administratora domeny. Aby pobrać konkretny projekt lub pytanie, użyj polecenia projects.courseWork.get. Aby pobrać wszystkie projekty lub pytania (opcjonalnie spełniające niektóre kryteria), użyj plikucourses.courseWork.list.

Wymagany zakres zależy od roli, jaką użytkownik wysyłający żądanie pełni na zajęciach. 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, zastosuj jeden z tych zakresów:

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

Posiadanie uprawnień do pobrania projektu lub pytania nie oznacza uprawnień do korzystania z materiałów lub metadanych materiałów. W praktyce oznacza to, że administrator może nie zobaczyć nazwy załączonego pliku z Dysku, jeśli nie jest uczestnikiem zajęć. Jeśli chcesz zezwolić administratorom na dostęp do plików użytkowników, zapoznaj się z przewodnikiem po przekazywaniu dostępu w całej domenie.

Zarządzanie odpowiedziami uczniów

Zasób StudentSubmission reprezentuje pracę i ocenę ucznia związaną z projektem lub pytaniem. Zasób StudentSubmission jest domyślnie tworzony dla każdego ucznia po utworzeniu nowego pytania lub zadania.

W poniższych sekcjach opisano typowe czynności związane z zarządzaniem odpowiedziami uczniów.

Pobieranie odpowiedzi uczniów

Uczniowie mogą pobierać własne prace, nauczyciele mogą pobierać projekty dotyczące wszystkich uczniów biorących udział w tych zajęciach, a administratorzy domen mogą pobierać wszystkie prace wszystkich uczniów w ich domenie. Do każdego zadania jest przypisywany identyfikator. Jeśli znasz identyfikator, użyj courses.courseWork.studentSubmissions.get, aby go pobrać.

Użyj metody courses.courseWork.studentSubmissions.list, aby uzyskać StudentSubmission zasoby spełniające określone kryteria, jak 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)

Aby pobrać zasoby StudentSubmission należące do określonego ucznia, określ parametr userId, jak 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 użytkownika zwracanego przez pakiet Google Admin SDK. Bieżący użytkownik może też powołać się na własny identyfikator, korzystając ze skrótu "me".

Możesz też pobierać prace przesłane przez uczniów do wszystkich projektów w ramach zajęć. Aby to zrobić, użyj literału "-" jako właściwości courseWorkId, jak 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, jaką użytkownik wysyłający żądanie pełni na zajęciach. 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

Posiadanie uprawnień do pobierania zadań przesłanych przez ucznia nie oznacza uprawnień do korzystania z załączników lub metadanych załączników. W praktyce oznacza to, że administrator może nie zobaczyć nazwy załączonego pliku z Dysku, jeśli nie jest uczestnikiem zajęć. Jeśli chcesz zezwolić administratorom na dostęp do plików użytkowników, przeczytaj przewodnik po przekazywaniu dostępu w całej domenie.

Dodawanie załączników do odpowiedzi uczniów

Do zadań przesłanych przez ucznia możesz dołączyć linki, dołączając zasoby Link, DriveFile lub YouTubeVideo. Należy to zrobić w polu courses.courseWork.studentSubmissions.modifyAttachments, jak widać 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")

Załącznik z linkiem jest zdefiniowany przez docelowy adres URL. Classroom automatycznie pobierze tytuł i obraz miniatury. Informacje o pozostałych materiałach znajdziesz na odpowiednich stronach referencyjnych.

Element StudentSubmission może modyfikować tylko nauczyciel zajęć lub uczeń, do którego należy. Możesz załączyć plik Materials tylko wtedy, gdy wartość CourseWorkType zadania przesłanego przez ucznia to ASSIGNMENT.

Wymagany zakres zależy od roli, jaką użytkownik wysyłający żądanie pełni na zajęciach. Jeśli użytkownik jest nauczycielem, użyj następującego 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

Zarządzanie stanem odpowiedzi uczniów

Odpowiedź ucznia może być nieprzesłana, oddana lub zwrócona. Pole stanu w StudentSubmission wskazuje aktualny stan. Aby zmienić stan, wywołaj jedną z tych metod:

Wszystkie te metody przyjmują pustą treść. Przykład:

Java

classroom/snippets/src/main/java/ReturnStudentSubmission.java
try {
  service
      .courses()
      .courseWork()
      .studentSubmissions()
      .classroomReturn(courseId, courseWorkId, id, null)
      .execute();
} 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;
}

Python

service.courses().courseWork().studentSubmission().turnIn(
    courseId=<course ID or alias>,
    courseWorkId=<courseWork ID>,
    id=<studentSubmission ID>,
    body={}).execute()

Tylko uczeń, który jest właścicielem StudentSubmission, może je oddać lub odzyskać. Można odzyskać tylko oddane przez siebie zadania. Nauczyciele zajęć mogą zwrócić tylko StudentSubmission, który jest oddany.

Ocenianie odpowiedzi uczniów

Zasób StudentSubmission ma 2 pola do przechowywania ocen: assignedGrade, czyli ocena przekazywana uczniom, i draftGrade, która jest oceną wstępną widoczną tylko dla nauczycieli. Te pola są aktualizowane za pomocą courses.courseWork.studentSubmissions.patch z maską pola zawierającą odpowiednie pola, jak pokazano w poniższym przykładzie.

Java

classroom/snippets/src/main/java/PatchStudentSubmission.java
StudentSubmission studentSubmission = null;
try {
  // Updating the draftGrade and assignedGrade fields for the specific student submission.
  StudentSubmission content =
      service
          .courses()
          .courseWork()
          .studentSubmissions()
          .get(courseId, courseWorkId, id)
          .execute();
  content.setAssignedGrade(90.00);
  content.setDraftGrade(80.00);

  // The updated studentSubmission object is returned with the new draftGrade and assignedGrade.
  studentSubmission =
      service
          .courses()
          .courseWork()
          .studentSubmissions()
          .patch(courseId, courseWorkId, id, content)
          .set("updateMask", "draftGrade,assignedGrade")
          .execute();

  /* Prints the updated student submission. */
  System.out.printf(
      "Updated student submission draft grade (%s) and assigned grade (%s).\n",
      studentSubmission.getDraftGrade(), studentSubmission.getAssignedGrade());
} 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

studentSubmission = {
  'assignedGrade': 99,
  'draftGrade': 80
}
service.courses().courseWork().studentSubmissions().patch(
    courseId=<course ID or alias>,
    courseWorkId=<courseWork ID>,
    id=<studentSubmission ID>,
    updateMask='assignedGrade,draftGrade',
    body=studentSubmission).execute()

Podczas korzystania z interfejsu Classroom nauczyciele nie mogą wystawiać ocen, dopóki nie zapiszą najpierw oceny roboczej. Przypisaną ocenę można następnie zwrócić uczniowi. Aplikacje muszą emulować to zachowanie. Aplikacja może ocenić projekty uczniów na 2 sposoby:

  • Przypisz tylko: draftGrade. Jest to przydatne na przykład wtedy, gdy nauczyciel może ręcznie sprawdzić oceny przed ich ukończeniem. Uczniowie nie widzą ocen roboczych.

  • Aby w pełni ocenić projekt, przypisz zarówno draftGrade, jak i assignedGrade.

Wyświetlanie listy przypisanych ocen

Aby wyświetlić wszystkie oceny z danego elementu zadania, przejrzyj obiekt odpowiedzi metody courses.courseWork.studentSubmissions.list:

Java

classroom/snippets/src/main/java/ListStudentSubmissions.java
  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 submissions found.");
} else {
  for (StudentSubmission submission : studentSubmissions) {
    System.out.printf(
        "User ID %s, Assigned grade: %s\n",
        submission.getUserId(), submission.getAssignedGrade());
  }
}

Python

response = coursework.studentSubmissions().list(
    courseId=course_id,
    courseWorkId=coursework_id,
    pageSize=10).execute()
submissions.extend(response.get('studentSubmissions', []))

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

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