Allegati esterni e consegna

Questo è il settimo tutorial della serie di tutorial sui componenti aggiuntivi di Classroom.

In questa procedura dettagliata, aggiungerai un comportamento a un'applicazione web per creare allegati di componenti aggiuntivi dall'esterno di Google Classroom. Utilizza questo comportamento per consentire ai tuoi utenti di creare componenti aggiuntivi da allegare dal tuo prodotto o sito web esistente. Si tratta anche di un'ottima aggiunta a un'integrazione di CourseWork perché indirizzi il traffico esistente all'esperienza utente migliorata offerta dal tuo componente aggiuntivo senza modificarne il flusso. La procedura suggerita è presentata nella pagina della guida Creare allegati al di fuori di Classroom.

Aggiungi inoltre un comportamento al tuo componente aggiuntivo per modificare un compito con gli allegati del componente aggiuntivo in modo programmatico. Puoi modificare qualsiasi compito che contenga uno dei tuoi allegati del componente aggiuntivo, indipendentemente da chi lo ha creato. Questa funzionalità è particolarmente utile per consegnare i compiti dopo che uno studente ha completato un'attività, segnalando all'insegnante che i compiti assegnati sono stati completati e che il lavoro dello studente è pronto per la revisione.

Espandi la versione finale del componente aggiuntivo che supporta gli allegati content-type o activity-type. L'allegato content-type viene utilizzato in questa guida.

Aggiungi l'ambito OAuth per la gestione dei compiti

Assicurati che la tua applicazione richieda i seguenti ambiti:

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

L'ambito classroom.coursework.students non era necessario in precedenza e viene utilizzato per creare o modificare le assegnazioni CourseWork. Aggiungi questo ambito agli elenchi di ambiti nell' SDK di Google Workspace Marketplace, nella schermata di consenso OAuth e nel codice del server del tuo progetto Cloud.

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",
  ]

Creare un compito in Classroom

Aggiungere pulsanti a una pagina web non in iframe

Il flusso descritto in questa procedura dettagliata consente a un utente di creare compiti e allegati di Google Classroom da un prodotto non Google. In pratica, si tratta probabilmente del tuo sito web o della tua applicazione esistenti. Per questo esempio, devi creare una pagina web simulata che fungerà da sito esterno. Devi avere un pulsante o un link che, quando viene fatto clic, apra un nuovo percorso che esegua il flussoCourseWork suggerito per creare un nuovo compito.

Dovrai anche aggiungere un pulsante o un link per consentire all'utente di accedere, se non ne hai già uno. Per effettuare le richieste API successive, dovrai disporre delle credenziali utente, che devono completare l'handshake OAuth 2.0. Consulta la procedura dettagliata per accedere per indicazioni specifiche.

Python

L'esempio di Python fornito modifica il percorso /index introdotto nel primo passaggio della procedura dettagliata.

<!-- /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>

Aggiungi un modello HTML per rappresentare una destinazione nel tuo sito web. Questa pagina rappresenta i contenuti che verranno allegati al compito CourseWork.

<!-- /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>

Crea un nuovo file del modulo Python per gestire le route relative ai corsi. Si tratta di coursework_routes.py nel nostro esempio fornito. Aggiungi i seguenti tre percorsi. Tieni presente che alcuni contenuti verranno inseriti in un secondo momento.

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

Verificare l'idoneità di un utente alla creazione di allegati

Un utente deve soddisfare diversi prerequisiti prima che tu possa creare per suo conto allegati dei componenti aggiuntivi. Per comodità, Google fornisce il metodo userProfiles.checkUserCapability per determinare se un utente soddisfa questi prerequisiti. Un utente che soddisfa i prerequisiti è definito idoneo.

Aggiungi la verifica di idoneità all'implementazione del percorso di creazione di CourseWork. Testa quindi il campo allowed nella risposta. Per gli utenti idonei, segui la logica per creare un compito con allegato aggiuntivo. In caso contrario, crea un materiale di collegamento. Devi conoscere l'ID del corso in cui l'utente vuole creare un compito. In genere, chiedi all'utente di specificare quale corso utilizzare. Per semplicità, in questo esempio utilizziamo un valore hardcoded.

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.

Creare un compito con allegato di componenti aggiuntivi per gli utenti idonei

Se l'utente è idoneo a creare allegati dei componenti aggiuntivi, procedi nel seguente modo:

  1. Invia una richiesta API per creare un compito courseWork in Google Classroom senza allegati.
  2. Estrai il id del compito appena creato.
  3. Crea un nuovo corsoAddOnAttachment.
  4. Invia una richiesta per creare un allegato del componente aggiuntivo al compito appena creato 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()
  )

Se l'utente non è idoneo alla creazione di allegati di componenti aggiuntivi, crea invece un materiale link seguendo questa procedura:

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

Modificare un compito già creato

Puoi accedere, modificare, consegnare, recuperare o restituire qualsiasi elemento dello stream di Google Classroom che contenga almeno uno dei tuoi allegati del componente aggiuntivo, indipendentemente da chi lo ha creato. Gli elementi dello stream sono qualsiasi Announcement, CourseWork compito o CourseWorkMaterial.

Per dimostrarlo, aggiungerai un percorso per modificare un determinato elemento dello stream. Utilizza questo metodo per verificare di poter accedere e modificare gli elementi dello stream creati da te mediante l'API e creati da un insegnante tramite l'UI di Google Classroom.

Aggiungi un altro link o pulsante alla pagina web che hai modificato per la prima volta in questa procedura dettagliata. Dovrebbe aprirsi un nuovo percorso per modificare un compitoCourseWork.

Python

L'esempio Python fornito modifica il percorso /index modificato in precedenza in questa procedura dettagliata.

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

Crea un nuovo percorso per gestire i percorsi relativi a CourseWork. Questo valore si trova nel coursework_routes.py file nell'esempio fornito.

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

Testare il componente aggiuntivo

Per semplificare, gli esempi forniti utilizzano identificatori di corsi e compiti hardcoded. Puoi ottenere questi identificatori inviando richieste con le credenziali degli insegnanti ai metodi get e list delle risorse courses e courseWork. Vengono restituiti anche nella risposta quando crei compiticourseWork.

Esegui il server, poi vai alla pagina di indice e accedi come utente insegnante senza una licenza Google Workspace for Education Teaching & Learning o Plus. Puoi attivare/disattivare lo stato della licenza di un utente dalla Console di amministrazione del tuo dominio di test.Fai clic sul pulsante Crea un compito, poi apri l'interfaccia utente di Google Classroom e verifica che sia stato creato un compito con un allegato del materiale collegato. L'allegato deve mostrare il titolo della pagina web collegata e un URL.

Testa la creazione dell'allegato del componente aggiuntivo

Torna alla pagina di indice e accedi come utente insegnante con una licenza Teaching & Learning o Plus di Google Workspace for Education. Fai clic sul pulsante Crea un compito di Coursework, quindi apri l'interfaccia utente di Google Classroom e verifica che sia stato creato un compito con un allegato del componente aggiuntivo. L'allegato dovrebbe mostrare il nome dell'applicazione del componente aggiuntivo e il titolo specificato nel codice.

Modifica dell'assegnazione di prova

Torna alla pagina di indice e assicurati di aver eseguito l'accesso come utente insegnante con una licenza Teaching and Learning o Plus. Fai clic sul pulsante Modifica un compito Coursework, poi torna all'interfaccia utente di Google Classroom e verifica che il titolo del compito sia stato modificato.

Complimenti! Hai completato la serie sulla procedura dettagliata.