Inhaltstyp-Anhänge

Dies ist die vierte Schritt-für-Schritt-Anleitung für Classroom-Add-ons. Schritt-für-Schritt-Anleitung.

In dieser Schritt-für-Schritt-Anleitung interagieren Sie mit der Google Classroom API, um Anhänge. Sie geben Nutzern die Möglichkeit, sich den Inhalt des Anhangs anzusehen. Die Ansichten unterscheiden sich je nach der Rolle des Nutzers in der Klasse. Diese Schritt-für-Schritt-Anleitung behandelt Inhaltstypenanhänge, die nicht von den Schülern/Studenten eingereicht werden müssen.

Im Verlauf dieser Schritt-für-Schritt-Anleitung führen Sie folgende Schritte aus:

• Rufen Sie die folgenden Add-on-Abfrageparameter ab und verwenden Sie sie:
  • addOnToken: Ein Autorisierungstoken, das an die Anhangserkennung übergeben wird. Ansicht.
  • itemId: Eine eindeutige Kennung für KursWork, CourseWorkMaterial oder Ankündigung, die den Add-on-Anhang empfängt.
  • itemType: entweder „courseWork“ oder „courseWorkMaterials“ oder "Ankündigung".
  • courseId: Eine eindeutige Kennung für den Google Classroom-Kurs in in dem die Aufgabe erstellt wird.
  • attachmentId: Eine eindeutige Kennung, die einer Person in Google Classroom zugewiesen wird. Add-on-Anhangs nach der Erstellung.
• Implementieren Sie dauerhaften Speicher für Inhaltstyp-Anhänge.
• Routen zur Erstellung von Anhängen und für die Lehrkräfte-Ansicht und iFrames für die Schüler-/Studentenansicht
• Senden Sie die folgenden Anfragen an die Google Classroom Add-ons API:
  • Erstellen Sie einen neuen Anhang.
  • Add-on-Kontext abrufen, der ermittelt, ob der angemeldete Nutzer ein Schüler/Student oder Lehrkraft.

Wenn Sie fertig sind, können Sie inhaltsbezogene Anhänge zu Aufgaben über über die Benutzeroberfläche von Google Classroom, wenn Sie als Lehrkraft angemeldet sind. Lehrkräfte und Lernende in können sich die Kursinhalte auch ansehen.

Wichtig: Schließen Sie die vorherigen Schritt-für-Schritt-Anleitungen ab, bevor Sie diese Schritt-für-Schritt-Anleitung befolgen. in der Reihe. Diese Schritt-für-Schritt-Anleitung erweitert die im vorherigen Schritt entwickelte Web-App Schritt-für-Schritt-Anleitungen. Sie können den vollständigen Quellcode für alle Schritt-für-Schritt-Anleitungen herunterladen. auf der Übersichtsseite. Den Code für diese Schritt-für-Schritt-Anleitung finden Sie unter dem Verzeichnis /04-content-attachments/.

Classroom API aktivieren

Rufen Sie die Classroom API auf, beginnend mit diesem Schritt. Die API muss für Ihr Google Cloud-Projekt aktiviert werden, bevor Sie Aufrufe an das Projekt senden können. Navigieren in den Bibliothekseintrag der Google Classroom API und wählen Sie Aktivieren aus.

Wichtig :Die Google Classroom API-Bibliothek muss aktiviert sein, bevor

Abfrageparameter für die Ansicht zur Anhangssuche verarbeiten

Wie bereits besprochen, übergibt Google Classroom Abfrageparameter, wenn Laden der Ansicht zur Anhangerkennung im iFrame:

• courseId: Die ID des aktuellen Classroom-Kurses.
• itemId: Eine eindeutige Kennung für KursWork, CourseWorkMaterial oder Ankündigung, die den Add-on-Anhang empfängt.
• itemType: entweder „courseWork“ oder „courseWorkMaterials“ oder „Ankündigung“.
• addOnToken: Ein Token, mit dem bestimmte Aktionen für Classroom-Add-ons.
• login_hint: Die Google-ID des aktuellen Nutzers.

Diese Schritt-für-Schritt-Anleitung richtet sich an courseId, itemId, itemType und addOnToken. Sie können sie aufbewahren und übergeben, wenn Sie Aufrufe an die Classroom API senden.

Speichern Sie wie im vorherigen Schritt-für-Schritt-Schritt die übergebenen Abfrageparameterwerte in unserer Sitzung. Das ist wichtig, wenn die Ansicht für die Anhangssuche da dies die einzige Möglichkeit ist, diese Suchparameter übergeben.

Python

Hinweis: Ab dieser Schritt-für-Schritt-Anleitung werden die sind auf mehrere Dateien aufgeteilt.

• attachment_discovery_routes.py definiert Routen für den Anhang die in den vorherigen Schritt-für-Schritt-Anleitungen entwickelt wurden.
• attachment_routes.py definiert Routen für die Lehreransicht und Ansicht für Schüler/Studenten. Es stellt auch Routen für die Ansicht zur Anhangserkennung bereit. was das Erstellen von Anhängen betrifft.
• credential_handler.py bietet eine Singleton-Klasse zum Verwalten von Nutzeranmeldedaten.

Wichtig: Wenn Sie das angegebene Beispiel verwenden, achten Sie darauf, hat /discovery-callback und /attachment-callback Ihren autorisierten Weiterleitungs-URIs. Rufen Sie in Google Cloud Ihre OAuth-Anmeldedaten auf und klicken Sie auf das Symbol „Bearbeiten“ neben Ihren Anmeldedaten, um die autorisierte Weiterleitung zu ändern URIs.

Gehen Sie zu Ihrer Flask-Serverdatei, die Routen für den Anhang bereitstellt. Discovery-Ansicht (attachment-discovery-routes.py, wenn Sie unseren Beispiel). Oben auf Ihrer zusätzlichen Landingpage (in unserem Beispiel /classroom-addon) abrufen und speichern. courseId, itemId, itemType und addOnToken.

# Retrieve the itemId, courseId, and addOnToken query parameters.
if flask.request.args.get("itemId"):
    flask.session["itemId"] = flask.request.args.get("itemId")
if flask.request.args.get("itemType"):
    flask.session["itemType"] = flask.request.args.get("itemType")
if flask.request.args.get("courseId"):
    flask.session["courseId"] = flask.request.args.get("courseId")
if flask.request.args.get("addOnToken"):
    flask.session["addOnToken"] = flask.request.args.get("addOnToken")

Schreiben Sie diese Werte nur in die Sitzung, wenn sie vorhanden sind. sie sind nicht Wird erneut übergeben, wenn der Nutzer zufällig zur Ansicht für die Anhangserkennung zurückkehrt. ohne den iFrame zu schließen.

Dauerhaften Speicher für Inhaltstyp-Anhänge hinzufügen

Sie benötigen einen lokalen Datensatz für alle erstellten Anhänge. So können Sie die Inhalte, die die Lehrkraft anhand von IDs ausgewählt hat, die von Google Classroom:

Richten Sie ein Datenbankschema für ein Attachment ein. In unserem Beispiel Anhänge mit einem Bild und einer Bildunterschrift. Ein Attachment enthält den folgende Attribute:

• attachment_id: Eine eindeutige Kennung für einen Anhang. Zugewiesen von Classroom erstellt und in der Antwort zurückgegeben wird, wenn ein Anhang.
• image_filename: Der lokale Dateiname des Bildes, das angezeigt werden soll.
• image_caption: Der Untertitel, der mit dem Bild angezeigt werden soll.

Hinweis: Diese Attribute sind Stringtypen.

Python

Erweitern Sie die SQLite- und flask_sqlalchemy-Implementierung aus den vorherigen Schritten.

Rufen Sie die Datei auf, in der Sie Ihre Nutzertabelle definiert haben (models.py). wenn Sie sich an unser Beispiel halten. Fügen Sie unten Folgendes hinzu: der Datei unter der Klasse User.

class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

Importieren Sie die neue Anhangsklasse in die Serverdatei mit Ihrem Anhang. die Routen verarbeiten.

Neue Routen einrichten

Beginnen Sie diesen Schritt, indem Sie einige neue Seiten in unserer Anwendung einrichten. Damit können Nutzer Inhalte über unser Add-on erstellen und ansehen.

Routen zur Anhangerstellung hinzufügen

Sie benötigen Seiten, auf denen die Lehrkraft Inhalte auswählen und Anhänge erstellen kann -Anfragen. /attachment-options-Route zum Anzeigen von Inhaltsoptionen implementieren die die Lehrkraft auswählen kann. Außerdem benötigen Sie Vorlagen für die Inhaltsauswahl Bestätigungsseiten für die Erstellung. Unsere Beispiele enthalten Vorlagen dafür, Außerdem können Sie hier die Anfragen und Antworten Classroom API

Sie können alternativ die vorhandene Ansicht für die Anhangserkennung ändern. Landingpage, um die Inhaltsoptionen anzuzeigen, anstatt eine neue Landingpage zu erstellen. /attachment-options Seite. Wir empfehlen, eine neue Seite zu erstellen, damit das im zweiten Schritt implementierte SSO-Verhalten beibehalten wird. , wie z. B. das Widerrufen der App-Berechtigungen. Diese sollten beweisen, wenn Sie Ihr Add-on erstellen und testen.

Lehrkräfte haben die Möglichkeit, aus einer Reihe von Bildern mit Untertiteln in der bereitgestellten Beispiel. Wir haben vier Bilder berühmter Sehenswürdigkeiten bereitgestellt, deren Bildunterschriften die aus den Dateinamen abgeleitet werden.

Python

In unserem Beispiel befindet sich dies in der Datei webapp/attachment_routes.py.

@app.route("/attachment-options", methods=["GET", "POST"])
def attachment_options():
    """
    Render the attachment options page from the "attachment-options.html"
    template.

    This page displays a grid of images that the user can select using
    checkboxes.
    """

    # A list of the filenames in the static/images directory.
    image_filenames = os.listdir(os.path.join(app.static_folder, "images"))

    # The image_list_form_builder method creates a form that displays a grid
    # of images, checkboxes, and captions with a Submit button. All images
    # passed in image_filenames will be shown, and the captions will be the
    # title-cased filenames.

    # The form must be built dynamically due to limitations in WTForms. The
    # image_list_form_builder method therefore also returns a list of
    # attribute names in the form, which will be used by the HTML template
    # to properly render the form.
    form, var_names = image_list_form_builder(image_filenames)

    # If the form was submitted, validate the input and create the attachments.
    if form.validate_on_submit():

        # Build a dictionary that maps image filenames to captions.
        # There will be one dictionary entry per selected item in the form.
        filename_caption_pairs = construct_filename_caption_dictionary_list(
            form)

        # Check that the user selected at least one image, then proceed to
        # make requests to the Classroom API.
        if len(filename_caption_pairs) > 0:
            return create_attachments(filename_caption_pairs)
        else:
            return flask.render_template(
                "create-attachment.html",
                message="You didn't select any images.",
                form=form,
                var_names=var_names)

    return flask.render_template(
        "attachment-options.html",
        message=("You've reached the attachment options page. "
                "Select one or more images and click 'Create Attachment'."),
        form=form,
        var_names=var_names,
    )

Dadurch wird eine "Anhänge erstellen"- die in etwa so aussieht:

Die Lehrkraft kann mehrere Bilder auswählen. Einen Anhang für jedes Bild erstellen die die Lehrkraft in der Methode create_attachments ausgewählt hat.

Anfragen zum Erstellen von Anhängen senden

Jetzt wissen Sie, welche Inhalte die Lehrkraft anhängen möchte. senden wir Anfragen an die Classroom API, um Anhänge in unserem Zuweisen. Speichern Sie die Anhangsdetails in Ihrer Datenbank, nachdem Sie eine von der Classroom API erhalten.

Rufen Sie zuerst eine Instanz des Classroom-Dienstes ab:

Python

In unserem Beispiel befindet sich dies in der Datei webapp/attachment_routes.py.

def create_attachments(filename_caption_pairs):
    """
    Create attachments and show an acknowledgement page.

    Args:
        filename_caption_pairs: A dictionary that maps image filenames to
            captions.
    """
    # Get the Google Classroom service.
    classroom_service = googleapiclient.discovery.build(
        serviceName="classroom",
        version="v1",
        credentials=credentials)

Senden Sie eine CREATE-Anfrage an courses.courseWork.addOnAttachments. Endpunkt. Erstellen Sie für jedes von der Lehrkraft ausgewählte Bild zuerst ein AddOnAttachment-Objekt:

Python

In unserem Beispiel ist dies eine Fortsetzung von create_attachments. .

# Create a new attachment for each image that was selected.
attachment_count = 0
for key, value in filename_caption_pairs.items():
    attachment_count += 1

    # Create a dictionary with values for the AddOnAttachment object fields.
    attachment = {
        # Specifies the route for a teacher user.
        "teacherViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True),
        },
        # Specifies the route for a student user.
        "studentViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True)
        },
        # The title of the attachment.
        "title": f"Attachment {attachment_count}",
    }

Mindestens die Felder teacherViewUri, studentViewUri und title müssen Folgendes sein: die für jeden Anhang zur Verfügung stehen. teacherViewUri und studentViewUri stellen die URLs dar, die geladen werden, wenn der Anhang mit dem jeweiligen Nutzertyp.

Senden Sie das Objekt AddOnAttachment im Text einer Anfrage an den entsprechenden Endpunkt addOnAttachments. Geben Sie courseId, itemId, itemType und addOnToken-IDs mit jeder Anfrage.

Python

In unserem Beispiel ist dies eine Fortsetzung von create_attachments. .

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

# Issue a request to create the attachment.
resp = parent.addOnAttachments().create(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    addOnToken=flask.session["addOnToken"],
    body=attachment).execute()

Wichtig :Achten Sie darauf, die Antwort auf diese Erstellungsanfrage zu erfassen.

Erstellen Sie einen Eintrag für diesen Anhang in Ihrer lokalen Datenbank, damit Sie später um den richtigen Inhalt zu laden. Classroom gibt einen eindeutigen id-Wert zurück in der Antwort auf die Anfrage zur Erstellung an. Verwenden Sie diesen Schlüssel daher als Primärschlüssel in unserem Datenbank. Beachten Sie auch, dass Classroom die attachmentId besteht. Suchparameter beim Öffnen der Ansicht für Lehrkräfte und Schüler/Studenten:

Python

In unserem Beispiel ist dies eine Fortsetzung von create_attachments. .

# Store the value by id.
new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value)
db.session.add(new_attachment)
db.session.commit()

Leiten Sie den Nutzer an dieser Stelle auf eine Bestätigungsseite weiter, ob Anhänge erfolgreich erstellt wurden.

Anhänge aus Ihrem Add-on zulassen

Jetzt ist ein guter Zeitpunkt, dem zugelassenen Anhang alle entsprechenden Adressen hinzuzufügen. Feld „URI-Präfixe“ in der App-Konfiguration des Google Workspace Marketplace SDK Seite. Das Add-on kann Anhänge nur mit einem der URI-Präfixe erstellen die auf dieser Seite aufgeführt sind. Dies ist eine Sicherheitsmaßnahme, von Man-in-the-Middle-Angriffen.

Am einfachsten ist es, wenn Sie in diesem Feld Ihre Top-Level-Domain angeben, Beispiel https://example.com. https://localhost:<your port number>/ würde wenn Ihr lokaler Computer als Webserver fungiert.

Warnung: Fügen Sie der App-Konfiguration vor dem Testen alle Präfixe hinzu für Ihr Add-on. Sie erhalten eine Fehlermeldung, wenn Sie versuchen, Anhänge aus einer URL zu erstellen das zu keinem der aufgeführten Präfixe gehört.

Routen für die Ansicht für Lehrkräfte und Schüler/Studenten hinzufügen

Es gibt vier iFrames, in denen ein Google Classroom-Add-on geladen werden kann. Sie haben nur Routen erstellt, die den iFrame der Anhangserkennungsansicht bereitstellen. weit entfernt. Fügen Sie als Nächstes Routen hinzu, die auch den iFrames in der Ansicht für Lehrkräfte und Schüler/Studenten angezeigt werden sollen.

Der iFrame von Teacher View ist erforderlich, um eine Vorschau des Schülers/Studenten zu sehen Erfahrung, kann aber optional zusätzliche Informationen oder Bearbeitungen Funktionen.

Die Ansicht für Schüler/Studenten ist die Seite, die die Schüler oder Studenten sehen, wenn sie die Seite öffnen. eines Add-on-Anhangs.

Erstellen Sie für diese Übung eine einzelne /load-content-attachment für die Ansicht für Lehrkräfte und für Schüler/Studenten. Classroom API verwenden um zu ermitteln, ob der Nutzer eine Lehrkraft oder ein Schüler ist, wenn die Seite geladen wird.

Python

In unserem Beispiel befindet sich dies in der Datei webapp/attachment_routes.py.

@app.route("/load-content-attachment")
def load_content_attachment():
    """
    Load the attachment for the user's role."""

    # Since this is a landing page for the Teacher and Student View iframes, we
    # need to preserve the incoming query parameters.
    if flask.request.args.get("itemId"):
        flask.session["itemId"] = flask.request.args.get("itemId")
    if flask.request.args.get("itemType"):
        flask.session["itemType"] = flask.request.args.get("itemType")
    if flask.request.args.get("courseId"):
        flask.session["courseId"] = flask.request.args.get("courseId")
    if flask.request.args.get("attachmentId"):
        flask.session["attachmentId"] = flask.request.args.get("attachmentId")

Vergessen Sie nicht, dass Sie den Nutzer an diesem Punkt auch authentifizieren sollten. Ich sollte hier auch den Abfrageparameter login_hint verarbeiten und den Nutzer an folgende URL weiterleiten: Autorisierungsprozess durchlaufen. Weitere Informationen vorherigen Schritt-für-Schritt-Anleitungen finden Sie weitere Informationen zu diesem Vorgang.

Senden Sie dann eine Anfrage an den Endpunkt getAddOnContext, die mit dem Element übereinstimmt Typ.

Python

In unserem Beispiel ist dies eine Fortsetzung des load_content_attachment-Methode.

# Create an instance of the Classroom service.
classroom_service = googleapiclient.discovery.build(
    serviceName="classroom"
    version="v1",
    credentials=credentials)

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

addon_context_response = parent.getAddOnContext(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"]).execute()

Diese Methode gibt Informationen zur Rolle des aktuellen Nutzers in der Klasse zurück. Die für den Nutzer angezeigte Ansicht je nach Rolle ändern. Genau eines der Die Felder studentContext oder teacherContext werden in der Antwort ausgefüllt Objekt. Untersuchen Sie diese, um zu ermitteln, wie Sie die Nutzenden ansprechen können.

Verwenden Sie in jedem Fall den Wert des Abfrageparameters attachmentId, um zu wissen, welche aus unserer Datenbank abrufen können. Dieser Suchparameter wird bereitgestellt, wenn indem Sie entweder den URI für die Lehrkraft- oder Schüler-/Studentenansicht öffnen.

Python

In unserem Beispiel ist dies eine Fortsetzung des load_content_attachment-Methode.

# Determine which view we are in by testing the returned context type.
user_context = "student" if addon_context_response.get(
    "studentContext") else "teacher"

# Look up the attachment in the database.
attachment = Attachment.query.get(flask.session["attachmentId"])

# Set the text for the next page depending on the user's role.
message_str = f"I see that you're a {user_context}! "
message_str += (
    f"I've loaded the attachment with ID {attachment.attachment_id}. "
    if user_context == "teacher" else
    "Please enjoy this image of a famous landmark!")

# Show the content with the customized message text.
return flask.render_template(
    "show-content-attachment.html",
    message=message_str,
    image_filename=attachment.image_filename,
    image_caption=attachment.image_caption,
    responses=response_strings)

Add-on testen

Wichtig: Zu diesem Zeitpunkt der Entwicklung können Sie Ihre Anwendung nur in die iFrames für Classroom-Add-ons. Lesen Sie unseren iFrame und unsere Abfrage Parameter auf. Dort finden Sie eine Beschreibung der einzelnen iFrames. Alle Anleitungen in dieser Schritt-für-Schritt-Anleitung beschrieben. Dabei wird vorausgesetzt, dass das Add-on im Kontext eines iFrame.

Führen Sie die folgenden Schritte aus, um das Erstellen von Anhängen zu testen:

• Melden Sie sich in [Google Classroom] an als einer Ihrer Lehrkräfte: Testnutzer.
• Gehen Sie zum Tab Kursaufgaben und erstellen Sie eine neue Aufgabe.
• Klicken Sie unter dem Textbereich auf die Schaltfläche Add-ons und wählen Sie das gewünschte Add-on aus. Der iFrame wird geöffnet und das Add-on lädt den URI für die Anhangseinrichtung, die auf der Seite App-Konfiguration des Google Workspace Marketplace SDK angegeben sind.
• Wählen Sie einen Inhalt aus, der an die Aufgabe angehängt werden soll.
• Schließen Sie den iFrame, nachdem der Anhang erstellt wurde.

In der Google-Benutzeroberfläche zur Aufgabenerstellung sollte nun eine Karte für Anhänge zu sehen sein. Google Classroom Klicken Sie auf die Karte, um den iFrame „Lehreransicht“ zu öffnen, und bestätigen Sie die Auswahl damit der richtige Anhang erscheint. Klicken Sie auf die Schaltfläche Zuweisen.

So testen Sie die Funktionen für Schüler/Studenten:

• Melden Sie sich dann als Testnutzer in Classroom an. mit der Klasse als Lehrkraft-Testnutzer.
• Suchen Sie auf dem Tab „Kursaufgaben“ nach der Testaufgabe.
• Maximieren Sie die Aufgabe und klicken Sie auf die Karte „Anhang“, um die Ansicht für Schüler/Studenten zu öffnen. iFrame.

Prüfen Sie, ob der richtige Anhang für den Schüler/Studenten angezeigt wird.

Glückwunsch! Sie können nun mit dem nächsten Schritt fortfahren: Erstellen Anhänge vom Typ „Aktivität“.