Externe Anhänge und abgeben

Dies ist die siebte Anleitung in der Reihe von Anleitungen 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 Nutzer Add‑on-Anhänge über Ihr bestehendes Produkt oder Ihre Website erstellen. Das ist auch eine großartige Ergänzung für eine CourseWork-Integration, da Sie vorhandenen Traffic auf die verbesserte Nutzerfreundlichkeit Ihres Add-ons umleiten können, ohne den Ablauf zu ändern. Der vorgeschlagene Prozess wird auf der Hilfeseite Anhänge außerhalb von Classroom erstellen beschrieben.

Außerdem fügen Sie Ihrem Add‑on Verhalten hinzu, um Aufgaben mit Add‑on-Anhängen programmatisch zu ändern. Sie können jede Aufgabe mit einem Ihrer Add-on-Anhänge bearbeiten, 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 überprüft werden kann.

Sie erweitern die endgültige Version Ihres Add‑ons, die content-type- oder activity-type-Anhänge unterstützt. Die Content-Type-Anlage wird in diesem Leitfaden verwendet.

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 zum Erstellen oder Ändern von CourseWork-Zuweisungen verwendet. Fügen Sie diesen Bereich den Listen der Bereiche im Google Workspace Marketplace SDK, OAuth-Zustimmungsbildschirm und 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

Schaltflächen auf einer Webseite ohne iFrame einfügen

Der in dieser Anleitung beschriebene Ablauf ermöglicht es einem Nutzer, Google Classroom-Aufgaben und ‑Anhänge aus einem Nicht-Google-Produkt zu 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 fungiert. Sie benötigen eine Schaltfläche oder einen Link, über den eine neue Route geöffnet wird, die den vorgeschlagenen CourseWork-Ablauf zum Erstellen einer neuen Zuweisung ausführt.

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

Python

Im bereitgestellten Python-Beispiel wird die /index-Route 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, um ein Ziel auf Ihrer Website darzustellen. Auf dieser Seite werden die Inhalte angezeigt, die Ihrer 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 für die Verarbeitung der CourseWork-bezogenen Routen. In unserem Beispiel ist das coursework_routes.py. Fügen Sie die folgenden drei Routen hinzu. Einige Inhalte werden später ausgefüllt.

# /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")

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

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

Fügen Sie die Berechtigungsprüfung in die Implementierung des CourseWork-Erstellungspfads ein. 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 müssen die ID des Kurses kennen, in dem der Nutzer eine Aufgabe erstellen möchte. Normalerweise fordern Sie den Nutzer auf, den zu verwendenden Kurs anzugeben. Zur Vereinfachung verwenden wir in diesem Beispiel einen fest codierten Wert.

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 eine neue CourseWork AddOnAttachment.
  4. Senden Sie eine Anfrage zum Erstellen eines Add‑on-Anhangs für die neu erstellte Aufgabe in Google Classroom.

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

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

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

Um das zu demonstrieren, fügen Sie eine Route hinzu, um ein bestimmtes Stream-Element zu ändern. Mit dieser Methode können Sie prüfen, ob Sie auf von Ihnen mit der API erstellte Stream-Elemente und auf von einem Kursleiter über die Google Classroom-Benutzeroberfläche erstellte Stream-Elemente zugreifen und diese ändern können.

Fügen Sie der Webseite, die Sie zuerst bearbeitet haben, einen weiteren Link oder eine weitere Schaltfläche hinzu. Dadurch sollte eine neue Route geöffnet werden, über die Sie eine CourseWork-Aufgabe bearbeiten können.

Python

Im bereitgestellten Python-Beispiel wird die Route /index geändert, die bereits 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 für die Verarbeitung der CourseWork-bezogenen Routen. Dies ist in der Datei coursework_routes.py in unserem Beispiel enthalten.

# 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

Der Einfachheit halber werden in den bereitgestellten Beispielen fest codierte Kurs- und Aufgabenkennungen verwendet. Sie können diese Kennungen abrufen, indem Sie Anfragen mit Lehreranmeldedaten an die Methoden get und list der Ressourcen courses und courseWork senden. Sie werden auch in der Antwort zurückgegeben, wenn courseWork-Aufgaben erstellt werden.

Starten Sie den Server, 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 ein- und ausschalten.Klicken Sie auf die Schaltfläche Aufgabe für Kursarbeit erstellen, öffnen Sie dann die Google Classroom-Benutzeroberfläche und prüfen Sie, ob eine Aufgabe mit einer Link-Materialanlage erstellt wurde. Im Anhang sollten der Titel der verlinkten Webseite und eine URL angezeigt werden.

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 Aufgabe für Kursarbeit erstellen, öffnen Sie dann die Google Classroom-Benutzeroberfläche und prüfen Sie, ob eine Aufgabe mit einer Add-on-Anlage erstellt wurde. Im Anhang sollten der Name Ihrer Add-on-Anwendung und der in Ihrem Code angegebene Titel zu sehen sein.

Testzuweisung ändern

Kehren Sie zur Indexseite zurück und vergewissern Sie sich, dass Sie als Lehrkraft mit einer Teaching & Learning- oder Plus-Lizenz angemeldet sind. Klicken Sie auf die Schaltfläche Modify a CourseWork Assignment (Aufgabe für Kursarbeit ändern). Kehren Sie dann zur Google Classroom-Benutzeroberfläche zurück und prüfen Sie, ob der Titel der Aufgabe geändert wurde.

Glückwunsch! Sie haben die Walkthrough-Reihe abgeschlossen.