Externe Anhänge und abgeben

Dies ist die siebte Anleitung in der Reihe zu Classroom-Add-ons.

In dieser Anleitung fügen Sie einer Webanwendung Verhalten hinzu, um Add-on-Anhänge außerhalb von Google Classroom zu erstellen. Mit diesem Verhalten können Ihre Nutzer Add-on-Anhänge aus Ihrem bestehenden Produkt oder Ihrer Website erstellen. Dies ist auch eine gute Ergänzung für eine CourseWork-Integration, da Sie vorhandenen Traffic zur verbesserten Nutzerfreundlichkeit Ihres Add-ons weiterleiten, ohne den Ablauf zu ändern. Der empfohlene Prozess wird auf unserer Anleitungsseite Anhänge außerhalb von Classroom erstellen beschrieben.

Sie fügen Ihrem Add-on auch Verhalten hinzu, um Aufgaben 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. Dies ist besonders nützlich, um Aufgaben abzugeben, nachdem ein Schüler/Student eine Aktivität abgeschlossen hat. So wird der Lehrkraft signalisiert, dass die zugewiesenen Aufgaben erledigt sind und die Arbeit des Schülers/Studenten überprüft werden kann.

Sie erweitern die endgültige Version Ihres Add-ons, das Anhänge vom Typ „Inhalt“ oder „Aktivität“ unterstützt. In dieser Anleitung wird der Anhang vom Typ „Inhalt“ verwendet.

Wichtig: Bevor Sie diese Anleitung durcharbeiten, müssen Sie die vorherigen Anleitungen der Reihe abgeschlossen haben. In dieser Anleitung wird die Webanwendung erweitert, die in den vorherigen Anleitungen entwickelt wurde. Sie können den vollständigen Quellcode für alle Anleitungen auf der Übersichtsseite herunterladen. Der Code für diese Anleitung befindet sich im Verzeichnis /07-external-attachments/.

OAuth-Bereich für die Aufgabenverwaltung hinzufügen

Ihre Anwendung muss die folgenden Bereiche 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 war bisher nicht erforderlich und wird verwendet, um CourseWork-Aufgaben zu erstellen oder zu ändern. Fügen Sie diesen Bereich den Listen der Bereiche im Google Workspace Marketplace SDK, auf dem OAuth-Zustimmungsbildschirm und in Ihrem 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",
  ]

Aufgabe in Classroom erstellen

**Wichtig** :Ändern Sie in diesem Schritt der Anleitung keine Ihrer iFrame-Umgebungen. Fügen Sie stattdessen Verhalten hinzu, um Add-on-Anhänge von einer Webseite außerhalb von Classroom zu erstellen.

Schaltflächen zu einer Webseite ohne iFrame hinzufügen

Mit dem in dieser Anleitung beschriebenen Ablauf kann ein Nutzer Google Classroom-Aufgaben und ‑Anhänge aus einem Nicht-Google-Produkt erstellen. In der Praxis ist dies wahrscheinlich Ihre bestehende Website oder Anwendung. Für dieses Beispiel müssen Sie eine Mock-Webseite erstellen, die als externe Website dient. Sie benötigen eine Schaltfläche oder einen Link, der beim Klicken eine neue Route öffnet , die den vorgeschlagenen CourseWork Ablauf ausführt, um eine neue Aufgabe zu erstellen.

Außerdem müssen Sie eine Schaltfläche oder einen Link hinzufügen, damit sich der Nutzer anmelden kann , falls noch keine vorhanden sind. Sie benötigen Nutzeranmeldedaten, um die nachfolgenden API-Anfragen zu stellen. Daher muss der OAuth 2.0-Handshake abgeschlossen werden. Eine genaue Anleitung finden Sie in der Anleitung zur Anmeldung Anleitung.

Python

Im bereitgestellten Python-Beispiel wird die Route /index geändert, die im ersten Schritt der Anleitung eingeführt 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, die ein Ziel auf Ihrer Website darstellt. Diese Seite stellt den Inhalt dar, der an Ihre CourseWork-Aufgabe angehängt wird.

<!-- /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 Routen für CourseWork zu verarbeiten. In unserem Beispiel ist das coursework_routes.py. Fügen Sie die folgenden drei Routen hinzu. Einige Inhalte werden später hinzugefügt.

# /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 alle neuen OAuth-Callback-Routen der Liste Autorisierte Weiterleitungs-URIs Ihrer OAuth-Client-ID auf der Seite „Anmeldedaten“ Ihres Google Cloud-Projekts hinzu. Für unser Beispiel sollten Sie https://<<your server>>/index und https://<<your server>>/coursework-assignment-callback.

hinzufügen.

Berechtigung eines Nutzers zum Erstellen von Anhängen prüfen

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 in seinem Namen Add-on-Anhänge erstellen können. Google bietet die userProfiles.checkUserCapability Methode, um zu ermitteln, ob ein Nutzer diese Voraussetzungen erfüllt. Ein Nutzer, der die Voraussetzungen erfüllt, wird als berechtigter Nutzer bezeichnet.

Wichtig: Berechtigungsprüfungen mit der Classroom API befinden sich in der öffentlichen Vorschau und sind in der Vorschauversion V1_20240930_PREVIEW und höher verfügbar. Wenn Sie API-Methoden in der öffentlichen Vorschau verwenden möchten, müssen Sie am Vorschauprogramm für Entwickler*innen von Google Workspace teilnehmen und zusätzliche Einrichtungsschritte vornehmen, die über die typische Nutzung der Classroom API hinausgehen.

Fügen Sie die Berechtigungsprüfung der Implementierung der Route zum Erstellen von CourseWork hinzu. Testen Sie dann das Feld allowed in der Antwort. Folgen Sie für berechtigte Nutzer der Logik, um eine Aufgabe mit Add-on Anhang zu erstellen. Erstellen Sie andernfalls ein Link Material. Sie benötigen die ID des Kurses, in dem der Nutzer eine Aufgabe erstellen möchte. Normalerweise werden Sie den Nutzer auffordern, den Kurs anzugeben. Der Einfachheit halber verwenden wir in diesem Beispiel einen fest codierten Wert.

Wichtiger Hinweis: Erstellen Sie immer Add-on-Anhänge, wenn der Nutzer berechtigt ist. Add-ons bieten eine bessere Nutzer- und Entwicklererfahrung als 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.

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

Wenn der Nutzer berechtigt ist, Add-on-Anhänge zu erstellen, 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 die id der neu erstellten Aufgabe.
3. Erstellen Sie einen neuen CourseWork 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 senden. Die CourseWork-Aufgabe muss erfolgreich erstellt werden, damit der neue Add-on-Anhang mit einer Aufgaben-ID verknüpft 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()
  )

Link-Material erstellen

**Wichtiger Hinweis**: Wenn Ihr Produkt bereits CourseWork Aufgaben erstellt, folgt es wahrscheinlich bereits dem hier beschriebenen Ablauf.

Wenn der Nutzer nicht berechtigt ist, Add-on-Anhänge zu erstellen, erstellen Sie stattdessen ein Link-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 Aufgabe ändern

Wichtiger Hinweis: Ein großer Vorteil von Add-on-Anhängen besteht darin, dass Sie die Möglichkeit haben, API-Anfragen für das übergeordnete Stream-Element auszuführen.

Sie können auf jedes Google Classroom-Stream-Element zugreifen, es ändern, abgeben, zurückfordern oder zurückgeben, das mindestens einen Ihrer Add-on-Anhänge enthält, unabhängig davon, wer das Stream-Element erstellt hat. Stream-Elemente sind alle Announcement, CourseWork Aufgaben oder CourseWorkMaterial.

Um dies zu veranschaulichen, fügen Sie eine Route hinzu, um ein bestimmtes Stream-Element zu ändern. Mit dieser Methode können Sie prüfen, ob Sie auf Stream-Elemente zugreifen und sie ändern können, die von Ihnen mit der API und von einer Lehrkraft über die Google Classroom-UI erstellt wurden.

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

Python

Im bereitgestellten Python-Beispiel wird die Route /index geändert, die zuvor 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 Routen für CourseWork zu verarbeiten. In unserem Beispiel befindet sich diese 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 für Classroom-Add-ons testen. Eine Beschreibung der einzelnen iFrames finden Sie auf unserer Anleitungsseite zu iFrames und Abfrage parametern. Alle Anweisungen in dieser Anleitung gehen davon aus, dass das Add-on im Kontext eines iFrames verwendet werden kann.

Der Einfachheit halber verwenden die bereitgestellten Beispiele fest codierte Kurs- und Aufgaben-IDs. Sie können diese IDs abrufen, indem Sie Anfragen mit den Anmeldedaten der Lehrkraft an die Methoden get und list der Ressourcen courses und courseWork senden. Sie werden auch in der Antwort zurückgegeben, wenn Sie courseWork-Aufgaben erstellen.

Erstellung von Link-Material testen

Führen Sie Ihren Server aus, rufen Sie die Indexseite auf und melden Sie sich als Lehrkraft ohne Google Workspace for Education Teaching &Learning- oder Plus-Lizenz an. Sie können den Lizenzstatus eines Nutzers in der Admin-Konsole Ihrer Testdomain ändern. Klicken Sie auf die Schaltfläche CourseWork-Aufgabe erstellen und öffnen Sie dann die Google Classroom-UI. Prüfen Sie, ob eine Aufgabe mit einem Link-Material-Anhang erstellt wurde. Der Anhang sollte den Titel der verknüpften 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 Google Workspace for Education Teaching & Learning- oder Plus-Lizenz an. Klicken Sie auf die Schaltfläche CourseWork-Aufgabe erstellen und öffnen Sie dann die Google Classroom-UI. Prüfen Sie, ob eine Aufgabe mit einem Add-on-Anhang erstellt wurde. Der Anhang sollte den Namen Ihrer Add-on-Anwendung und den in Ihrem Code angegebenen Titel enthalten.

Aufgabenänderung testen

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

Glückwunsch! Sie haben die Anleitung abgeschlossen.