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

Приложение Classroom поддерживает три типа элементов потока: CourseWork , CourseWorkMaterials и Announcements . В этом руководстве описывается управление CourseWork , но API для всех элементов потока схожи. Подробнее о типах элементов потока и их различиях см. в разделе «Ресурсы API».

Ресурс CourseWork представляет собой рабочий элемент, назначенный студентам на определённом курсе, включая любые дополнительные материалы и сведения, такие как дата сдачи или максимальный балл. Существует четыре подтипа CourseWork : задания , тестовые задания , вопросы с кратким ответом и вопросы с несколькими вариантами ответа . API Classroom поддерживает три из этих подтипов: задания, вопросы с кратким ответом и вопросы с несколькими вариантами ответа. Эти типы представлены полем CourseWork.workType .

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

Создать курсовую работу

CourseWork можно создать только от имени преподавателя курса. Попытка создать CourseWork от имени студента или администратора домена, не являющегося преподавателем курса, приводит к ошибке PERMISSION_DENIED . Подробнее о различных ролях в Classroom см. в разделе «Типы пользователей» .

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

Ява

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;

Питон

класс/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)

Поля title и workType обязательны для заполнения. Все остальные поля необязательны. Если state не указано, CourseWork создаётся в состоянии черновика.

Используйте ресурс Link с указанным целевым url для включения связанных материалов в CourseWork . Classroom автоматически получает title и URL-адрес миниатюры ( thumbnailUrl ). API Classroom также изначально поддерживает материалы Google Диска и 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 не подразумевает разрешения на доступ к материалам или метаданным материалов. На практике это означает, что администратор может не видеть название прикрепленного файла на Диске, если он не является участником курса.

Управление ответами студентов

Ресурс StudentSubmission представляет работу, выполненную студентом для CourseWork . Ресурс включает метаданные, связанные с работой, такие как статус работы и оценка. Ресурс StudentSubmission автоматически создаётся для каждого студента при создании новой CourseWork .

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

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

Получить ответы студентов

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

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

Ява

класс/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;

Питон

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

Ява

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

Питон

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

Студенты идентифицируются по уникальному идентификатору или адресу электронной почты, указанному в ресурсе Student . Текущий пользователь также может использовать для обозначения своего идентификатора сокращение "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

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

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

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

Ява

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;

Питон

класс/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")

Вложение- Link определяется целевым url ; Classroom автоматически извлекает title и миниатюру изображения ( thumbnailUrl ). Подробнее о материалах, которые можно прикрепить к StudentSubmissions , см. в разделе « Material ».

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

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

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

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

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