Kursaufgaben verwalten

Die Classroom App unterstützt drei Arten von Streamelementen: CourseWork, CourseWorkMaterials und Announcements. In diesem Leitfaden wird beschrieben, wie du CourseWork verwaltest. Die APIs für alle Streamelemente sind jedoch ähnlich. Weitere Informationen zu den Streamelementtypen und ihren Unterschieden findest du unter API-Ressourcen.

Die CourseWork-Ressource stellt ein Arbeitselement dar, das Schülern oder Studenten in einem bestimmten Kurs zugewiesen wurde, einschließlich aller zusätzlichen Materialien und Details wie Abgabetermin oder maximale Punktzahl. Es gibt vier Untertypen von CourseWork: Aufgaben, Aufgaben mit Quiz, Fragen mit Kurzantwort und Multiple-Choice-Fragen. Die Classroom API unterstützt drei dieser Untertypen: Aufgaben, Fragen mit Kurzantwort und Multiple-Choice-Fragen. Diese Typen werden durch das Feld CourseWork.workType dargestellt.

Zusätzlich zur Ressource CourseWork können Sie abgeschlossene Arbeit mit der Ressource StudentSubmission verwalten.

Kursaufgaben erstellen

CourseWork kann nur im Namen der Lehrkraft des Kurses erstellt werden. Der Versuch, CourseWork im Namen eines Schülers oder Studenten oder eines Domainadministrators zu erstellen, der keine Lehrkraft im Kurs ist, führt zu einem PERMISSION_DENIED-Fehler. Weitere Informationen zu den verschiedenen Rollen in Classroom finden Sie unter Nutzertypen.

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 Linkressource mit einem angegebenen Zielurl, um verknüpfte Materialien in die CourseWork aufzunehmen. In Classroom werden die title und die Thumbnail-Bild-URL (thumbnailUrl) automatisch abgerufen. Die Classroom API unterstützt auch nativ Google Drive- und YouTube-Materialien, die auf ähnliche Weise in einer DriveFile-Ressource oder YouTubeVideo-Ressource eingefügt werden können.

Wenn Sie ein Abgabedatum angeben möchten, legen Sie in den Feldern dueDate und dueTime 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 Sie in anderen API-Anfragen auf die Zuweisung verweisen können.

Kursarbeit 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 nicht als Lehrkräfte im Kurs tätig sind. Wenn Sie eine bestimmte CourseWork abrufen möchten, verwenden Sie courses.courseWork.get. Verwenden Sie courses.courseWork.list, um alle CourseWork abzurufen, die optional bestimmten Kriterien entsprechen.

Hinweis :Wenn Sie nur an bestimmten 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 teilweisen Ressourcen arbeiten.

Der erforderliche Umfang 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 Gültigkeitsbereiche:

• 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 Gültigkeitsbereich:

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

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

Antworten von Schülern/Studenten verwalten

Eine StudentSubmission-Ressource stellt die von einem Schüler/Studenten für eine CourseWork geleistete Arbeit dar. Die Ressource enthält Metadaten zur Arbeit, z. B. den Arbeitsstatus und die Note. Wenn eine neue CourseWork erstellt wird, wird für jeden Schüler/Studenten implizit eine StudentSubmission erstellt.

Warnung: Die Einreichungen von Schülern und Studenten dürfen nur über das Developer Console-Projekt geändert werden, in 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 gängige Aktionen zum Verwalten von Antworten von Schülern und Studenten beschrieben.

Antworten der Schüler/Studenten abrufen

Schüler und Studenten können ihre eigenen Einreichungen abrufen, Lehrkräfte können Einreichungen für alle Schüler und Studenten in ihren Kursen abrufen und Domainadministratoren können alle Einreichungen für alle Schüler und Studenten in ihrer Domain abrufen. Jedem 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)

Sie können StudentSubmission-Ressourcen abrufen, die einem bestimmten Schüler oder Studenten 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/Studenten werden anhand der eindeutigen ID oder E-Mail-Adresse identifiziert, die in der Ressource Student angegeben ist. Der aktuelle Nutzer kann sich auch mit der Kurzform "me" auf seine eigene ID beziehen.

Es ist auch möglich, die von Schülern oder 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 bestimmten 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 teilweisen Ressourcen arbeiten.

Der erforderliche Umfang 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 Umfang:

• 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 Umfang:

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

Die Berechtigung zum Abrufen einer StudentSubmission impliziert keine Berechtigungen zum Zugriff auf Anhänge oder Anhängemetadaten. In der Praxis bedeutet das, dass ein Administrator den Titel einer angehängten Drive-Datei möglicherweise nicht sehen kann, wenn er kein Mitglied des Kurses ist.

Antworten von Schülern/Studenten Anhänge hinzufügen

Sie können Links zu einer Einreichung von Schülern oder Studenten anhängen, indem Sie eine Link-, DriveFile- oder YouTubeVideo-Ressource anhängen. Dazu wird courses.courseWork.studentSubmissions.modifyAttachments verwendet, 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")

Ein Link-Anhang wird durch das Ziel url definiert. Classroom ruft automatisch die title und das Thumbnail-Bild (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 vom Schüler oder Studenten geändert werden, der der Inhaber ist. Sie können Materials nur anhängen, wenn die CourseWorkType des StudentSubmission ASSIGNMENT ist.

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

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

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

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