Kursaufgaben verwalten

Die Classroom App unterstützt drei Arten von Stream-Elementen: CourseWork, CourseWorkMaterials und Announcements. In dieser Anleitung wird beschrieben, wie Sie CourseWork verwalten. Die APIs für alle Stream-Elemente sind jedoch ähnlich. Weitere Informationen zu den Stream-Elementtypen und ihren Unterschieden finden Sie unter API-Ressourcen.

Die CourseWork-Ressource stellt eine Aufgabe dar, die Schülern oder Studenten in einem bestimmten Kurs zugewiesen wurde. Sie enthält alle zusätzlichen Materialien und Details wie Fälligkeitsdatum oder maximale Punktzahl. Es gibt vier Untertypen von CourseWork: Aufgaben, Aufgaben mit Quiz, Kurzantwortfragen und Multiple-Choice-Fragen. Die Classroom API unterstützt drei dieser Untertypen: Aufgaben, Kurzantwortfragen und Multiple-Choice-Fragen. Diese Typen werden durch das Feld CourseWork.workType dargestellt.

Zusätzlich zur CourseWork-Ressource können Sie erledigte Aufgaben mit der StudentSubmission-Ressource verwalten.

Kursaufgaben erstellen

CourseWork können nur im Namen der Lehrkraft des Kurses erstellt werden. Der Versuch, CourseWork im Namen eines Schülers/Studenten oder eines Domainadministrators zu erstellen, der nicht als Lehrkraft für den Kurs registriert ist, führt zu einem PERMISSION_DENIED-Fehler. Weitere Informationen zu den verschiedenen Rollen in Classroom

Wenn Sie CourseWork mit der Methode courses.courseWork.create erstellen, können Sie Links als materials anhängen, wie im folgenden Beispielcode gezeigt:

Java

classroom/snippets/src/main/java/CreateCourseWork.java

Auf GitHub ansehen

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

Auf GitHub ansehen

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)

Die Felder title und workType sind Pflichtfelder. Alle anderen sind optional. Wenn state nicht angegeben ist, wird CourseWork im Status „Entwurf“ erstellt.

Verwenden Sie eine Link-Ressource mit einem angegebenen Ziel-url, um verknüpfte Materialien in die CourseWork einzufügen. Classroom ruft automatisch die title und die Thumbnail-Bild-URL (thumbnailUrl) ab. Die Classroom API unterstützt auch nativ Google Drive- und YouTube-Materialien, die auf ähnliche Weise mit einer DriveFile-Ressource oder einer YouTubeVideo-Ressource eingebunden werden können.

Wenn Sie ein Fälligkeitsdatum angeben möchten, legen Sie die Felder dueDate und dueTime auf die entsprechende UTC-Zeit fest. Das Fälligkeitsdatum muss in der Zukunft liegen.

Die CourseWork-Antwort enthält eine vom Server zugewiesene Kennung, mit der in anderen API-Anfragen auf die Zuweisung verwiesen werden kann.

CourseWork abrufen

Sie können CourseWork im Namen von Schülern/Studenten und Lehrkräften des entsprechenden Kurses abrufen. Sie können CourseWork auch im Namen von Domainadministratoren abrufen, auch wenn diese keine Lehrkraft im Kurs sind. Verwenden Sie courses.courseWork.get, um eine bestimmte CourseWork abzurufen. Verwenden Sie courses.courseWork.list, um alle CourseWork abzurufen (optional mit bestimmten Kriterien).

Hinweis :Wenn Sie nur an einigen Feldern interessiert sind, sollten Sie Ihre Anfragen auf diese Felder beschränken. Dadurch können Ihre Anfragen erheblich beschleunigt werden. Weitere Informationen finden Sie unter Mit Teilressourcen arbeiten.

Der erforderliche Bereich hängt von der Rolle ab, die der anfragende Nutzer im Kurs hat. Wenn der Nutzer ein Schüler oder Student ist, verwenden Sie einen der folgenden Bereiche:

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

Wenn der Nutzer eine Lehrkraft oder ein Domainadministrator ist, verwenden Sie einen der folgenden Bereiche:

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

Die Berechtigung zum Abrufen eines CourseWork bedeutet nicht, dass Sie auch die Berechtigung zum Zugriff auf Materialien oder Materialmetadaten haben. In der Praxis bedeutet das, dass ein Administrator den Titel einer angehängten Drive-Datei möglicherweise nicht sieht, wenn er kein Mitglied des Kurses ist.

Antworten von Schülern und Studenten verwalten

Eine StudentSubmission-Ressource stellt die Arbeit dar, die ein Schüler oder Student für eine CourseWork erledigt hat. Die Ressource enthält Metadaten zur Aufgabe, z. B. den Status und die Note. Für jeden Schüler wird implizit ein StudentSubmission erstellt, wenn ein neues CourseWork erstellt wird.

Warnung :Einsendungen von Schülern und Studenten dürfen nur von dem Developer Console-Projekt geändert werden, mit dem die entsprechende CourseWork-Ressource erstellt wurde. Dies gilt zusätzlich zu den Berechtigungsbeschränkungen des anfragenden Nutzers. Änderungen können von jedem OAuth2-Client in diesem Projekt vorgenommen werden. Das Feld associatedWithDeveloper gibt an, ob der aktuelle OAuth2-Client eine bestimmte StudentSubmission ändern kann.

In den folgenden Abschnitten werden häufige Aktionen zum Verwalten von Schülerantworten beschrieben.

Antworten der Schüler/Studenten abrufen

Schüler und Studenten können ihre eigenen Einsendungen abrufen, Lehrkräfte die Einsendungen aller Schüler und Studenten in ihren Kursen und Domainadministratoren alle Einsendungen aller Schüler und Studenten in ihrer Domain. Jeder StudentSubmission wird eine Kennung zugewiesen. Wenn Sie die Kennung kennen, verwenden Sie courses.courseWork.studentSubmissions.get, um die Einreichung abzurufen.

Mit der Methode courses.courseWork.studentSubmissions.list können Sie alle StudentSubmission-Ressourcen abrufen, die bestimmten Kriterien entsprechen, wie im folgenden Beispiel gezeigt:

Java

classroom/snippets/src/main/java/ListSubmissions.java

Auf GitHub ansehen

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

Auf GitHub ansehen

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)

Rufen Sie StudentSubmission-Ressourcen ab, die zu einem bestimmten Schüler gehören, indem Sie den Parameter userId angeben, wie im folgenden Beispiel gezeigt:

Java

classroom/snippets/src/main/java/ListStudentSubmissions.java

Auf GitHub ansehen

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

Auf GitHub ansehen

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

Schüler werden durch die eindeutige ID oder E-Mail-Adresse identifiziert, wie in der Ressource Student dargestellt. Der aktuelle Nutzer kann auch mit der Kurzform "me" auf seine eigene ID verweisen.

Es ist auch möglich, die von Schülern/Studenten eingereichten Aufgaben für alle Aufgaben in einem Kurs abzurufen. Verwenden Sie dazu das Literal "-" als courseWorkId, wie im folgenden Beispiel gezeigt:

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

Hinweis :Wenn Sie nur an einigen Feldern interessiert sind, sollten Sie Ihre Anfragen auf diese Felder beschränken. Dadurch können Ihre Anfragen erheblich beschleunigt werden. Weitere Informationen finden Sie unter Mit Teilressourcen arbeiten.

Der erforderliche Bereich hängt von der Rolle ab, die der anfragende Nutzer im Kurs hat. Wenn der Nutzer eine Lehrkraft oder ein Domainadministrator ist, verwenden Sie den folgenden Bereich:

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

Wenn der Nutzer ein Schüler oder Student ist, verwenden Sie den folgenden Bereich:

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

Die Berechtigung zum Abrufen eines StudentSubmission bedeutet nicht, dass Sie auch auf Anhänge oder Metadaten von Anhängen zugreifen dürfen. In der Praxis bedeutet das, dass ein Administrator den Titel einer angehängten Drive-Datei möglicherweise nicht sieht, wenn er kein Mitglied des Kurses ist.

Einer Antwort eines Schülers/Studenten Anhänge hinzufügen

Sie können einer Schülerarbeit Links hinzufügen, indem Sie eine Link-, DriveFile- oder YouTubeVideo-Ressource anhängen. Dies geschieht mit courses.courseWork.studentSubmissions.modifyAttachments, wie im folgenden Beispiel gezeigt:

Java

classroom/snippets/src/main/java/ModifyAttachmentsStudentSubmission.java

Auf GitHub ansehen

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

Auf GitHub ansehen

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

Eine Link-Anlage wird durch das Ziel url definiert. Classroom ruft automatisch die title und das Vorschaubild (thumbnailUrl) ab. Weitere Informationen zu Materialien, die an StudentSubmissions angehängt werden können, finden Sie unter Material.

Die StudentSubmission kann nur von einem Kursleiter oder dem Schüler oder Studenten, dem sie gehört, geändert werden. Sie können Materials nur anhängen, wenn die CourseWorkType des StudentSubmission ASSIGNMENT ist.

Der erforderliche Bereich hängt von der Rolle ab, die der anfragende Nutzer im Kurs hat. Wenn der Nutzer eine Lehrkraft ist, verwenden Sie den folgenden Bereich:

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

Wenn der Nutzer ein Schüler oder Student ist, verwenden Sie den folgenden Bereich:

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