Управление курсовой работой и оценками

Пользовательский интерфейс Класса поддерживает пять типов Классной работы: Задания, Тестовые задания, Вопросы с кратким ответом, Вопросы с несколькими вариантами ответов и Материалы. API Classroom в настоящее время поддерживает три из этих типов, которые известны как CourseWorkType для API: задания, вопросы с кратким ответом и вопросы с множественным выбором.

Примечание. В пользовательском интерфейсе класса можно создавать Materials как «Задания», однако API поддерживает прикрепление Materials только к ресурсам CourseWorkType : заданиям, вопросам с кратким ответом и вопросам с несколькими вариантами ответов.

Чтобы получить доступ к этой функции, вы можете использовать ресурс CourseWork , который представляет собой задание или вопрос, назначенный учащимся определенного курса, включая любые дополнительные материалы и сведения, такие как срок сдачи или максимальный балл.

Помимо ресурса CourseWork, вы можете управлять выполненными заданиями с помощью ресурса StudentSubmission . В следующих разделах они описаны более подробно.

Создание заданий

Задания можно создавать только от имени преподавателей курса, а попытка создать задания в курсе от имени учащегося приведет к ошибке 403 PERMISSION_DENIED . Аналогично, администраторы домена также не могут создавать задания для курсов, которые они не преподают, и попытка сделать это через API также приведет к ошибке 403 PERMISSION_DENIED .

При создании заданий с помощью метода courses.courseWork.create вы можете прикреплять ссылки в качестве materials , как показано в примере кода ниже:

Джава

класс/фрагменты/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;

Питон

класс/фрагменты/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, используйте ресурс Link , указав целевой URL-адрес. Класс автоматически получает заголовок и миниатюру. API Classroom также изначально поддерживает материалы Google Диска и 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

Наличие разрешения на получение задания или вопроса не подразумевает разрешения на доступ к материалам или метаданным материалов. На практике это означает, что администратор может не видеть название прикрепленного файла на Диске, если он не является участником курса. Если вы хотите предоставить администраторам доступ к файлам пользователей, см. руководство по делегированию на уровне домена .

Управляйте ответами учащихся

Ресурс StudentSubmission представляет проделанную работу и оценку учащегося за задание или вопрос. Ресурс StudentSubmission неявно создается для каждого учащегося при создании нового вопроса или задания.

Материалы учащихся могут быть изменены только проектом Developer Console , в котором создан соответствующий ресурс CourseWork . Это делается в дополнение к проверке наличия у запрашивающего пользователя правильных разрешений. Изменения могут быть внесены любым клиентом OAuth2 в этом проекте; поле associatedWithDeveloper указывает, может ли текущий клиент OAuth2 изменять данный StudentSubmission .

В следующих разделах описаны общие действия по управлению ответами учащихся.

Получить ответы учащихся

Учащиеся могут получать свои собственные материалы, преподаватели могут получать материалы всех учащихся своих курсов, а администраторы домена могут получать все материалы всех учащихся в своем домене. Каждой работе студента присваивается идентификатор; если вы знаете идентификатор, используйте courses.courseWork.studentSubmissions.get , чтобы получить его.

Используйте метод courses.courseWork.studentSubmissions.list чтобы получить ресурсы StudentSubmission , соответствующие некоторым критериям, как показано в следующем примере:

Джава

класс/фрагменты/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;

Питон

класс/фрагменты/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 , как показано в следующем примере:

Джава

класс/фрагменты/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());
    }
  }

Питон

класс/фрагменты/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 , как показано в следующем примере:

Джава

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

Наличие разрешения на получение работ учащихся не подразумевает разрешения на доступ к вложениям или метаданным вложений. На практике это означает, что администратор может не видеть название прикрепленного файла на Диске, если он не является участником курса. Если вы хотите предоставить администраторам доступ к файлам пользователей, см. руководство по делегированию на уровне домена .

Добавление вложений к ответу учащегося

Вы можете прикрепить ссылки к материалам учащихся, прикрепив ресурс Link , DriveFile или YouTubeVideo . Это делается с помощью courses.courseWork.studentSubmissions.modifyAttachments , как показано в следующем примере:

Джава

класс/фрагменты/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;

Питон

класс/фрагменты/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-адресом; Класс автоматически получит заголовок и миниатюру. Вы можете узнать о других материалах на соответствующих справочных страницах.

StudentSubmission может быть изменен только преподавателем курса или студентом, которому он принадлежит. Вы можете прикреплять Materials только в том случае, если CourseWorkType заявки учащегося имеет ASSIGNMENT .

Требуемая область зависит от роли, которую запрашивающий пользователь имеет в курсе. Используйте следующую область, если пользователь является учителем:

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

Используйте следующую область, если пользователь является студентом:

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

Управление состоянием ответов учащихся

Ответ учащегося может быть отменен, сдан или возвращен. Поле состояния в StudentSubmission указывает текущее состояние. Чтобы изменить состояние, вызовите один из следующих методов:

• courses.courseWork.studentSubmissions.turnIn
• courses.courseWork.studentSubmissions.return
• courses.courseWork.studentSubmissions.reclaim

Все эти методы принимают пустое тело. Пример:

Джава

класс/фрагменты/src/main/java/ReturnStudentSubmission.java

Посмотреть на GitHub

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

Питон

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

Только студент, у которого есть StudentSubmission может сдать его или потребовать обратно. Только сданная заявка может быть возвращена. Преподаватели курса могут вернуть только StudentSubmission , который находится в сданном состоянии.

Это не меняет значения assignedGrade or draftGrade . Чтобы отобразить оценку учащемуся, см. раздел «Оценка работы учащегося» .

Ответы учащихся

Ресурс StudentSubmission имеет два поля для хранения оценок: assignedGrade — оценка, сообщаемая учащимся, и draftGrade — предварительная оценка, видимая только учителям. Эти поля обновляются с помощью courses.courseWork.studentSubmissions.patch с маской поля, содержащей соответствующие поля, как показано в следующем примере.

Джава

класс/фрагменты/src/main/java/PatchStudentSubmission.java

Посмотреть на GitHub

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;

Питон

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

При работе с пользовательским интерфейсом Класса преподаватели не могут выставлять оценки, пока не сохранят черновик оценки. Присвоенную оценку затем можно вернуть учащемуся. Приложения должны эмулировать это поведение. Ваше приложение может оценить задание учащегося одним из двух способов:

• Назначьте только draftGrade . Это полезно, например, чтобы позволить учителю вручную проверять оценки перед их окончательной оценкой. Учащиеся не могут видеть черновые оценки.

• Назначьте и draftGrade , и assignedGrade , чтобы полностью оценить задание.

Не устанавливайте assignedGrade без установки draftGrade . Установка только assignedGrade может привести к странному поведению пользовательского интерфейса Класса.

Список присвоенных оценок

Вы можете перечислить все оценки за определенный элемент курсовой работы, изучив объект ответа метода courses.courseWork.studentSubmissions.list :

Джава

класс/фрагменты/src/main/java/ListStudentSubmissions.java

Посмотреть на GitHub

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

Питон

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