Kursaufgaben verwalten

In Classroom gibt es fünf Arten von Kursaufgaben: Aufgaben, Quizaufgaben, Fragen (Kurzantwort und Multiple-Choice-Fragen) und Materialien. Mit der Classroom API können Entwickler derzeit drei dieser Typen lesen und schreiben: Aufgaben, Fragen und Materialien.

Für den Zugriff auf diese Funktion können Sie die CourseWork-Ressource verwenden. Sie stellt eine Aufgabe oder Frage dar, die Schülern in einem bestimmten Kurs zugewiesen wurde, einschließlich zusätzlicher Materialien und Details wie Abgabetermin oder maximaler Punktzahl.

Neben der Kurs-Ressource können Sie abgeschlossene Aufgaben mit der Ressource StudentSubmission verwalten. In den folgenden Abschnitten wird dies ausführlicher beschrieben.

Aufgaben erstellen

Aufgaben können nur im Namen der Lehrkraft erstellt werden. Wenn Sie versuchen, Aufgaben im Namen eines Schülers oder Studenten zu erstellen, wird der Fehler 403 PERMISSION_DENIED angezeigt. Ebenso können Domain-Administratoren keine Zuweisungen für Kurse erstellen, die sie nicht unterrichten. Wenn Sie dies über die API tun, wird außerdem der Fehler 403 PERMISSION_DENIED ausgegeben.

Wenn Sie Zuweisungen erstellen, können Sie Links als materials anhängen, wie im Beispielcode unten gezeigt:

Python

Kursraum/Ausschnitte/classroom_create_coursework.py

Auf GitHub ansehen

from __future__ import print_function

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)

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

Die Felder title und workType sind Pflichtfelder. Alle anderen sind optional. Wenn state nicht angegeben ist, wird ein Aufgabenentwurf erstellt.

Wenn Sie verknüpfte Materialien in eine Aufgabe einbinden möchten, die Sie über die Classroom API erstellt haben, verwenden Sie eine Linkressource und geben Sie die Ziel-URL an. Classroom ruft automatisch den Titel und das Thumbnail ab. Die Classroom API unterstützt nativ auch Drive- und YouTube-Materialien, die auf ähnliche Weise mit einer DriveFile-Ressource oder einer YouTubeVideo-Ressource verknüpft 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.

Aufgaben und Fragen abrufen

Sie können Aufgaben und Fragen für Schüler und Lehrkräfte des entsprechenden Kurses oder von einem Domainadministrator abrufen. Verwenden Sie die Datei „courses.courseWork.get“, um eine bestimmte Aufgabe oder Frage abzurufen. Mit {0}courses.courseWork.list{/1} können Sie alle Zuweisungen oder Fragen abrufen (optional mit bestimmten Kriterien).

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 Umfang hängt von der Rolle ab, die der anfragende Nutzer im Kurs hat. Wenn der Nutzer 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

Wenn Sie die Berechtigung zum Abrufen einer Aufgabe oder Frage haben, bedeutet dies nicht, dass Sie 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. Wenn Sie Administratoren Zugriff auf Nutzerdateien gewähren möchten, finden Sie entsprechende Informationen unter Domainweite Delegierung.

Antworten von Schülern/Studenten verwalten

Eine StudentSubmission-Ressource stellt die erledigte Aufgabe und die Note eines Schülers/Studenten für eine Aufgabe oder Frage dar. Für jeden Teilnehmer wird implizit eine StudentSubmission-Ressource erstellt, wenn eine neue Frage oder Aufgabe erstellt wird.

Aufgaben von Schülern oder Studenten können nur von dem Entwicklerkonsolenprojekt bearbeitet werden, das die entsprechende CourseWork-Ressource erstellt hat. Außerdem wird geprüft, ob der anfragende Nutzer die richtigen Berechtigungen hat. Jeder OAuth2-Client in diesem Projekt kann Änderungen vornehmen. Das Feld associatedWithDeveloper gibt an, ob der aktuelle OAuth2-Client einen bestimmten StudentSubmission ändern kann.

In den folgenden Abschnitten werden häufige Aktionen erläutert, mit denen die Antworten von Schülern oder Studenten verwaltet werden können.

Antworten der Schüler oder Studenten abrufen

Schüler oder Studenten können ihre eigenen Arbeiten abrufen, Lehrkräfte können Beiträge für alle Teilnehmer in ihren Kursen abrufen und Domainadministratoren können alle abgegebenen Aufgaben für alle Teilnehmer in ihrer Domain abrufen. Jeder Schüler/Student erhält eine Kennung. Wenn Sie die Kennung kennen, können Sie sie mit „courses.courseWork.studentSubmissions.get“ abrufen.

Verwenden Sie die Datei „courses.courseWork.studentSubmissions.list“, um StudentSubmission abzurufen, die einigen Kriterien entspricht, wie im folgenden Beispiel gezeigt:

Python

Kursraum/Ausschnitte/Classroom_list_submissions.py

Auf GitHub ansehen

from __future__ import print_function

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(f"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 Aufgaben von Schülern oder Studenten ab, die zu einem bestimmten Schüler oder Studenten gehören. Geben Sie dazu den Parameter „userId“ an, wie im folgenden Beispiel gezeigt:

Python

Kursraum/Ausschnitte/Classroom_list_student_submissions.py

Auf GitHub ansehen

from __future__ import print_function

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

Kursteilnehmer werden anhand der eindeutigen ID oder E-Mail-Adresse des Nutzers identifiziert, die vom Google Admin SDK zurückgegeben wird. Der aktuelle Nutzer kann sich mit dem Kurzbefehl "me" auch auf seine eigene ID beziehen.

Es ist auch möglich, abgegebene Aufgaben für alle Aufgaben in einem Kurs zu erhalten. Verwenden Sie dazu das Literal "-" als „courseWorkId“, wie im folgenden Beispiel gezeigt:

Python

service.courses().courseWork().studentSubmissions().list(
    courseId=<course ID or alias>,
    courseWorkId='-',
    userId=<user ID>).execute()

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 Umfang hängt von der Rolle ab, die der anfragende Nutzer im Kurs hat. Verwenden Sie den folgenden Bereich, wenn der Nutzer eine Lehrkraft oder ein Domainadministrator ist:

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

Verwenden Sie den folgenden Bereich, wenn der Nutzer Student ist:

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

Die Berechtigung zum Abrufen einer abgegebenen Aufgabe von Schülern oder Studenten beinhaltet keine Berechtigungen für den Zugriff auf Anhänge oder Metadaten von Anhängen. 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. Informationen dazu, wie Sie Administratoren Zugriff auf Nutzerdateien gewähren, finden Sie im Leitfaden zur domainweiten Delegierung.

Einer Schüler-/Studentenantwort Anhänge hinzufügen

Sie können Links an eine abgegebene Aufgabe 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:

Python

Kursraum/Auszüge/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 Linkanhang wird durch die Ziel-URL definiert. Classroom ruft automatisch den Titel und das Thumbnail ab. Informationen zu den anderen Materialien findest du auf den jeweiligen Referenzseiten.

Materialien können von einer Kurslehrerin oder von einem Schüler oder Studenten erstellt werden, dem die abgegebenen Arbeiten gehören, aber nur für die Einreichung mit einem courseWorkType von "ASSIGNMENT".

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

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

Verwenden Sie den folgenden Bereich, wenn der Nutzer Student ist:

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

Antwortstatus von Schülern oder Studenten verwalten

Eine Schüler-/Studentenantwort kann zurückgezogen, abgegeben oder zurückgegeben werden. Das Statusfeld in StudentSubmission gibt den aktuellen Status an. Rufen Sie zum Ändern des Status eine der folgenden Methoden auf:

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

Alle diese Methoden haben einen leeren Textkörper. Beispiel:

Python

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

Nur der Schüler, der Inhaber einer StudentSubmission ist, kann diese abgeben oder zurückfordern. Nur eine abgegebene Aufgabe kann zurückgefordert werden. Lehrkräfte können nur eine StudentSubmission zurückgeben, die sich im Abgabestatus befindet.

Dies ändert nicht den Wert von assignedGrade or draftGrade. Informationen dazu, wie Sie dem Schüler oder Studenten eine Note mitteilen, finden Sie im Abschnitt Aufgaben benoten.

Schüler/Studenten benoten

Die Ressource StudentSubmission hat zwei Felder zum Speichern von Noten: assignedGrade (die für Schüler/Studenten gemeldete Note) und draftGrade (eine vorläufige Note, die nur für Lehrkräfte sichtbar ist). Diese Felder werden mit courses.courseWork.studentSubmissions.patch mit einer Feldmaske aktualisiert, die die entsprechenden Felder enthält, wie im folgenden Beispiel gezeigt.

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

Wenn Lehrkräfte die Classroom-UI verwenden, können sie erst benoten, wenn sie zuvor einen Notenentwurf gespeichert haben. Die benotete Note kann dann an einen Schüler/Studenten zurückgegeben werden. Anwendungen müssen dieses Verhalten emulieren. Es gibt zwei Möglichkeiten, die Aufgabe eines Schülers oder Studenten zu benoten:

• Weisen Sie nur draftGrade zu. Das ist z. B. hilfreich, um die Lehrkraft die Noten manuell überprüfen zu lassen, bevor sie sie fertigstellen können. Schüler oder Studenten können sich Notenentwürfe nicht ansehen.

• Weisen Sie sowohl draftGrade als auch assignedGrade zu, um eine Aufgabe vollständig zu benoten.

Legen Sie assignedGrade nicht fest, ohne auch draftGrade festzulegen. Wenn Sie nur „assignedGrade“ festlegen, kann dies zu seltsamem Verhalten in der Classroom-UI führen.