Externe Anhänge und abgeben

Dies ist die siebte Schritt-für-Schritt-Anleitung der Serie zu Classroom-Add-ons.

In dieser Schritt-für-Schritt-Anleitung fügen Sie einer Webanwendung die Funktion hinzu, um Add-on-Anhänge außerhalb von Google Classroom zu erstellen. Verwenden Sie dieses Verhalten, damit Ihre Nutzer Add-on-Anhänge zu Ihrem vorhandenen Produkt oder Ihrer Website erstellen können. Dies ist auch eine gute Ergänzung zu einer CourseWork-Integration, da Sie vorhandenen Traffic auf die verbesserte Nutzererfahrung Ihres Add-ons weiterleiten, ohne den Ablauf zu ändern. Eine entsprechende Anleitung finden Sie auf der Seite Anhänge außerhalb von Classroom erstellen.

Außerdem können Sie Ihrem Add-on ein Verhalten hinzufügen, um eine Aufgabe mit Add-on-Anhängen programmatisch zu ändern. Sie können jede Aufgabe ändern, die einen Ihrer Add-on-Anhänge enthält, unabhängig davon, wer die Aufgabe erstellt hat. Das ist besonders nützlich, um Aufgaben abzugeben, nachdem ein Schüler/Student eine Aktivität abgeschlossen hat. So wird dem Lehrer signalisiert, dass die zugewiesenen Aufgaben erledigt sind und die Arbeit des Schülers/Studenten zur Überprüfung bereit ist.

Sie erweitern die finale Version Ihres Add-ons, sodass es Anhänge vom Inhaltstyp oder Aktivitätstyp unterstützt. In diesem Leitfaden wird der Inhaltstyp „Anhang“ verwendet.

Wichtig :Bevor Sie diese Anleitung befolgen, müssen Sie die vorherigen Anleitungen in dieser Reihe durcharbeiten. In dieser Anleitung wird die in den vorherigen Anleitungen entwickelte Webanwendung erweitert. Auf der Übersichtsseite können Sie den vollständigen Quellcode für alle Schritt-für-Schritt-Anleitungen herunterladen. Den Code für diese Demo finden Sie im Verzeichnis /07-external-attachments/.

OAuth-Bereich für die Aufgabenverwaltung hinzufügen

Ihre Anwendung muss die folgenden Berechtigungen anfordern:

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

Der Bereich classroom.coursework.students wurde zuvor nicht benötigt und wird verwendet, um CourseWork-Zuweisungen zu erstellen oder zu ändern. Fügen Sie diesen Umfang den Listen der Bereiche im Google Workspace Marketplace SDK, im OAuth-Einwilligungsdialog und im Servercode Ihres Cloud-Projekts hinzu.

Python

  SCOPES = [
    "https://www.googleapis.com/auth/classroom.addons.teacher",
    "https://www.googleapis.com/auth/classroom.addons.student",
    "https://www.googleapis.com/auth/classroom.coursework.students",
  ]

Aufgaben in Classroom erstellen

Wichtig :Ändern Sie in diesem Schritt keine Ihrer iframe-Inhalte. Stattdessen können Sie die Funktion zum Erstellen von Add-on-Anhängen über eine Webseite außerhalb von Classroom einrichten.

Schaltflächen zu einer Webseite ohne iFrames hinzufügen

Mit dem in dieser Anleitung beschriebenen Ablauf können Nutzer Aufgaben und Anhänge in Google Classroom über ein Drittanbieterprodukt erstellen. In der Praxis ist das wahrscheinlich Ihre bestehende Website oder Anwendung. Für dieses Beispiel müssen Sie eine Mock-Webseite erstellen, die als externe Website dient. Zum Erstellen einer neuen Zuweisung benötigen Sie eine Schaltfläche oder einen Link, der beim Anklicken eine neue Route öffnet und den vorgeschlagenen CourseWork-Vorgang ausführt.

Außerdem müssen Sie eine Schaltfläche oder einen Link hinzufügen, über den sich der Nutzer anmelden kann, falls Sie noch keine haben. Für die nachfolgenden API-Anfragen sind Nutzeranmeldedaten erforderlich. Daher muss der OAuth 2.0-Handshake abgeschlossen werden. Eine genaue Anleitung findest du in der Anleitung zum Anmelden.

Python

Im bereitgestellten Python-Beispiel wird die Route /index geändert, die im ersten Schritt der Anleitung vorgestellt wurde.

<!-- /webapp/templates/index.html -->
<a href="clear-credentials.html">Logout</a>
<a href="start-auth-flow.html">Login</a>

<br>

<a href="create-coursework-assignment.html">Create a CourseWork Assignment</a>

Fügen Sie eine HTML-Vorlage hinzu, um ein Ziel auf Ihrer Website darzustellen. Auf dieser Seite sehen Sie die Inhalte, die an Ihre CourseWork-Aufgabe angehängt werden.

<!-- /webapp/templates/example-coursework-assignment.html -->
<h1>CourseWork assignment loaded!</h1>
<p>You've loaded a CourseWork assignment! It was created from an external web page.</p>

Erstellen Sie eine neue Python-Moduldatei, um die zu Kursen gehörenden Routen zu verarbeiten. In unserem Beispiel ist das coursework_routes.py. Fügen Sie die folgenden drei Routen hinzu. Einige Inhalte füllen Sie später aus.

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """

  # Check that the user is signed in. If not, perform the OAuth 2.0
  # authorization flow.
  credentials = get_credentials()

  if not credentials:
    return start_auth_flow("coursework_assignment_callback")

  # Construct the Google Classroom service.
  classroom_service = get_classroom_service()

  pass  # To be completed later.

@app.route("/example-coursework-assignment/<assignment_type>")
def example_coursework_assignment(assignment_type):
  """
  Renders the "example-coursework-assignment.html" template.
  """
  return flask.render_template(
      "example-coursework-assignment.html", assignment_type=assignment_type
  )

@app.route("/coursework-assignment-callback")
def coursework_assignment_callback():
  """
  Completes the OAuth 2.0 handshake and stores credentials in the session.
  This is identical to the callback introduced in the sign-in walkthrough,
  but redirects the user to the index page instead of the attachment
  discovery page.
  """
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE,
      scopes=SCOPES,
      state=flask.session["state"],
      redirect_uri=flask.url_for("coursework_assignment_callback", _external=True),
  )

  flow.fetch_token(authorization_response=flask.request.url)

  credentials = flow.credentials
  flask.session["credentials"] = session_credentials_to_dict(
      credentials
  )

  # Close the current window and redirect the user to the index page.
  return flask.render_template("close-me.html", redirect_destination="index")

Wichtig: Fügen Sie Ihrer OAuth-Client-ID alle neuen OAuth-Callback-Routen hinzu. Unter Autorisierte Weiterleitungs-URIs auf der Seite „Anmeldedaten“ Ihres Google Cloud-Projekts. Für unser Beispiel sollten Sie https://<<your server>>/index und https://<<your server>>/coursework-assignment-callback hinzufügen.

Prüfen, ob ein Nutzer Anhänge erstellen darf

Wichtiger Hinweis :Prüfen Sie immer, ob ein Nutzer berechtigt ist, Add-on-Anhänge zu erstellen, bevor Sie versuchen, Add-on-Anhänge zu erstellen. Die Berechtigung variiert je nach Nutzer und anfragendem Google Cloud-Projekt und kann sich im Laufe der Zeit ändern.

Es gibt mehrere Voraussetzungen, die ein Nutzer erfüllen muss, bevor Sie Add-on-Anhänge in seinem Namen erstellen können. Google bietet die Methode userProfiles.checkUserCapability an, um zu ermitteln, ob ein Nutzer diese Voraussetzungen erfüllt. Ein Nutzer, der die Voraussetzungen erfüllt, wird als berechtigter Nutzer bezeichnet.

Wichtig :Die Berechtigungsprüfungen mit der Classroom API befinden sich in der öffentlichen Vorschau und sind ab der Vorabversion V1_20240930_PREVIEW verfügbar. Wenn Sie API-Methoden in der öffentlichen Vorschau verwenden möchten, müssen Sie am Google Workspace-Entwicklervorschauprogramm teilnehmen und über die typische Nutzung der Classroom API hinaus zusätzliche Einrichtungsschritte durchführen.

Fügen Sie der Implementierung des CourseWork-Erstellungs-Routings die Berechtigungsprüfung hinzu. Testen Sie dann das Feld allowed in der Antwort. Wenn es sich um einen berechtigten Nutzer handelt, folgen Sie der Logik, um eine Zuweisung mit Add-on-Anhang zu erstellen. Andernfalls erstellen Sie ein Link-Material. Sie benötigen die ID des Kurses, in dem der Nutzer eine Aufgabe erstellen möchte. Normalerweise bitten Sie den Nutzer, anzugeben, welchen Kurs er verwenden möchte. Zur Vereinfachung verwenden wir in diesem Beispiel einen hartcodierten Wert.

Wichtiger Hinweis :Erstellen Sie immer Add-on-Anhänge, wenn der Nutzer die Voraussetzungen erfüllt. Add-ons bieten eine bessere Nutzer- und Entwicklerfreundlichkeit für Link-Materialien.

Python

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """
  # ... Check that the user is signed in and get the Classroom service ...

  # Check whether the user can create add-on attachments.
  eligibility_response = (
      classroom_service.userProfiles()
      .checkUserCapability(
        userId="me",
        capability="CREATE_ADD_ON_ATTACHMENT",
        # The previewVersion is necessary while the method is available in the
        # Workspace Developer Preview Program.
        previewVersion="V1_20240930_PREVIEW",
      ).execute()
  )
  is_create_attachment_eligible = eligibility_response.get("allowed")

  if is_create_attachment_eligible:
    # See the "Create an assignment with add-on attachment for eligible users" section for implementation.
  if not is_create_attachment_eligible:
    # See the "Create a Link Material" section for implementation.

Aufgaben mit Add-on-Anhang für berechtigte Nutzer erstellen

Wenn der Nutzer Add-on-Anhänge erstellen darf, gehen Sie so vor:

1. Senden Sie eine API-Anfrage, um eine courseWork-Aufgabe in Google Classroom ohne Anhänge zu erstellen.
2. Extrahieren Sie den id der neu erstellten Zuweisung.
3. Erstellen Sie eine neue Kursarbeit AddOnAttachment.
4. Senden Sie eine Anfrage, um einen Add-on-Anhang für die neu erstellte Aufgabe in Google Classroom zu erstellen.

Wichtiger Hinweis :Sie müssen die beiden Anfragen separat stellen. Die CourseWork-Aufgabe muss erfolgreich erstellt werden, damit der neue Add-on-Anhang einer Aufgaben-ID zugeordnet werden kann.

Python

# The ID of the course to which the assignment will be added.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

# /webapp/coursework_routes.py
if is_create_attachment_eligible:
  # Create an assignment.
  coursework = {
      "title": "My CourseWork Assignment with Add-on Attachment",
      "description": "Created using the Classroom CourseWork API.",
      "workType": "ASSIGNMENT",
      "state": "DRAFT",  # Set to 'PUBLISHED' to assign to students.
  }

  # Issue a request to create the assignment.
  create_assignment_response = (
      classroom_service.courses()
      .courseWork()
      .create(courseId=course_id, body=coursework)
      .execute()
  )

  # Create an add-on attachment that links to the selected content and
  # associate it with the new assignment.
  content_url = flask.url_for(
      "example_coursework_assignment",
      assignment_type="add-on-attachment",
      _scheme="https",
      _external=True,
  )

  # Construct an AddOnAttachment instance.
  attachment = {
      "teacherViewUri": {"uri": content_url},
      "studentViewUri": {"uri": content_url},
      "title": f'Test Attachment for Assignment {create_assignment_response.get("id")}',
  }

  # Issue a request to create the attachment.
  add_on_attachment_response = (
      classroom_service.courses()
      .courseWork()
      .addOnAttachments()
      .create(
          courseId=course_id,
          itemId=create_assignment_response.get("id"),  # ID of the new assignment.
          body=attachment,
      )
      .execute()
  )

Linkmaterial erstellen

Wichtiger Hinweis: Wenn für dein Produkt bereits CourseWork-Zuweisungen erstellt wurden, folgt es wahrscheinlich schon dem hier beschriebenen Ablauf.

Wenn der Nutzer nicht berechtigt ist, Add-on-Anhänge zu erstellen, erstellen Sie stattdessen ein verlinktes Material. Gehen Sie dazu so vor:

Python

# The ID of the course to which the assignment will be added.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

if not is_create_attachment_eligible:
    coursework = {
        "title": "My CourseWork Assignment with Link Material",
        "description": "Created using the Classroom CourseWork API.",
        "workType": "ASSIGNMENT",
        "state": "DRAFT",  # Set to 'PUBLISHED' to assign to students.
        # Specify the URL for your content as a Link Material.
        "materials": [
            {
                "link": {
                    "url": flask.url_for(
                        "example_coursework_assignment",
                        assignment_type="link-material",
                        _scheme="https",
                        _external=True,
                    )
                }
            }
        ],
    }

    # Issue a request to create the assignment.
    assignment_response = (
        classroom_service.courses()
        .courseWork()
        .create(courseId=course_id, body=coursework)
        .execute()
    )

Bereits erstellte Aufgaben ändern

Wichtig: Ein großer Vorteil von Add-on-Anhängen ist, dass du damit API-Anfragen an das übergeordnete Streamelement senden kannst.

Sie können auf jedes Google Classroom-Stream-Element mit mindestens einem Ihrer Add-on-Anhänge zugreifen, es ändern, abgeben, zurückfordern oder zurückgeben. Dabei spielt es keine Rolle, wer das Streamelement erstellt hat. Zu den Stream-Elementen gehören alle Announcement-, CourseWork-Aufgaben und CourseWorkMaterial.

Zur Veranschaulichung fügen Sie eine Route zum Ändern eines bestimmten Stream-Elements hinzu. Mit dieser Methode können Sie prüfen, ob Sie auf Streamelemente zugreifen und diese ändern können, die Sie mit der API und von einem Lehrer über die Google Classroom-Benutzeroberfläche erstellt haben.

Fügen Sie der Webseite, die Sie in dieser Anleitung zuerst bearbeitet haben, einen weiteren Link oder eine weitere Schaltfläche hinzu. Es sollte ein neuer Pfad geöffnet werden, um eine CourseWork-Aufgabe zu ändern.

Python

Im bereitgestellten Python-Beispiel wird die Route /index geändert, die früher in dieser Anleitung geändert wurde.

<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>

Erstellen Sie eine neue Route, um die zu Kursarbeiten gehörenden Routen zu verarbeiten. Sie befindet sich in unserem Beispiel in der Datei coursework_routes.py.

# Check that the user is signed in.
credentials = get_credentials()

if not credentials:
  return start_auth_flow("coursework_assignment_callback")

# Get the Google Classroom service.
classroom_service = get_classroom_service()

# The ID of the course to which the assignment will be added.
# Ordinarily, you'll prompt the user to specify which course to use. For
# simplicity, we use a hard-coded value in this example.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.
assignment_id = 1234567890  # TODO(developer) Replace with an actual assignment ID.

# Retrieve details about the CourseWork assignment.
get_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .get(courseId=course_id, id=assignment_id)
    .execute()
)

# Alter the current title.
assignment_title = f"{get_coursework_response.get('title')} (Modified by API request)"

# Issue a request to modify the assignment.
modify_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .patch(
        courseId=course_id,
        id=assignment_id,
        updateMask="title",
        body={"title": assignment_title},
    )
    .execute()
)

Add-on testen

Wichtig :In dieser Phase der Entwicklung können Sie Ihre Anwendung nur in den IFrames der Classroom-Add-ons testen. Eine Beschreibung der einzelnen iFrames finden Sie in unserem Leitfaden zu iFrames und Abfrageparametern. Bei allen Anleitungen in dieser Schritt-für-Schritt-Anleitung wird davon ausgegangen, dass das Add-on im Kontext eines Iframes verwendet werden kann.

Zur Vereinfachung werden in den Beispielen hartcodierte Kurs- und Aufgaben-IDs verwendet. Sie können diese IDs abrufen, indem Sie mit den Anmeldedaten eines Lehrers Anfragen an die Methoden get und list der Ressourcen courses und courseWork senden. Sie werden auch in der Antwort zurückgegeben, wenn courseWork-Zuweisungen erstellt werden.

Testlink-Material erstellen

Starten Sie Ihren Server, rufen Sie Ihre Indexseite auf und melden Sie sich als Lehrkraft ohne Google Workspace for Education-Lizenz für das Lehren und Lernen oder Plus an. Sie können den Lizenzstatus eines Nutzers in der Admin-Konsole Ihrer Testdomain aktivieren oder deaktivieren.Klicken Sie auf die Schaltfläche Aufgabe für Kursarbeit erstellen, öffnen Sie die Google Classroom-Benutzeroberfläche und prüfen Sie, ob eine Aufgabe mit einem angehängten Link zu Material erstellt wurde. Der Anhang sollte den Titel der verlinkten Webseite und eine URL enthalten.

Erstellung von Add-on-Anhängen testen

Kehren Sie zur Indexseite zurück und melden Sie sich als Lehrkraft mit einer Lizenz für Google Workspace for Education Teaching and Learning oder Plus an. Klicken Sie auf die Schaltfläche Kursarbeit – Aufgabe erstellen, öffnen Sie die Google Classroom-Benutzeroberfläche und prüfen Sie, ob eine Aufgabe mit einem Add-on-Anhang erstellt wurde. Der Anhang sollte den Namen der Add-on-Anwendung und den im Code angegebenen Titel enthalten.

Testzuweisung ändern

Kehren Sie zur Indexseite zurück und prüfen Sie, ob Sie als Lehrkraft mit einer Teaching and Learning- oder Plus-Lizenz angemeldet sind. Klicken Sie auf die Schaltfläche Coursework-Aufgabe ändern und kehren Sie dann zur Google Classroom-Benutzeroberfläche zurück. Prüfen Sie, ob der Titel der Aufgabe geändert wurde.

Glückwunsch! Sie haben die Schritt-für-Schritt-Anleitung abgeschlossen.