Allegati per tipo di contenuti

Questa è la quarta procedura dettagliata della serie di procedure dettagliate sui componenti aggiuntivi di Classroom.

In questa procedura dettagliata, interagisci con l'API Google Classroom per creare allegati. Fornisci percorsi per consentire agli utenti di visualizzare i contenuti degli allegati. Le visualizzazioni variano in base al ruolo dell'utente nel corso. Questa procedura dettagliata riguarda gli allegati di tipo contenuto, che non richiedono l'invio di un compito da parte dello studente.

Nel corso di questa procedura dettagliata, completerai le seguenti operazioni:

• Recupera e utilizza i seguenti parametri di query del componente aggiuntivo:
  • addOnToken: un token di autorizzazione passato alla visualizzazione Rilevamento allegati.
  • itemId: un identificatore univoco per il compito, il materiale del corso o l'annuncio che riceve l'allegato del componente aggiuntivo.
  • itemType: "courseWork", "courseWorkMaterials" o "announcement".
  • courseId: Un identificatore univoco per il corso di Google Classroom in cui viene creato il compito.
  • attachmentId: un identificatore univoco assegnato da Google Classroom a un allegato del componente aggiuntivo dopo la creazione.
• Implementa l'archiviazione permanente per gli allegati di tipo di contenuto.
• Fornisci percorsi per creare allegati e per pubblicare gli iframe della visualizzazione insegnante e della visualizzazione studente.
• Invia le seguenti richieste all'API Google Classroom Add-ons:
  • Crea un nuovo allegato.
  • Ottieni il contesto del componente aggiuntivo, che identifica se l'utente che ha eseguito l'accesso è uno studente o un insegnante.

Al termine, puoi creare allegati di tipo contenuto nei compiti tramite l'interfaccia utente di Google Classroom quando accedi come insegnante. Anche gli insegnanti e gli studenti del corso possono visualizzare i contenuti.

Abilita l'API Classroom

Esegui chiamate all'API Classroom a partire da questo passaggio. L'API deve essere abilitata per il tuo progetto Google Cloud prima di poter effettuare chiamate. Vai alla voce della libreria dell'API Google Classroom e scegli Abilita.

Gestire i parametri di query della visualizzazione Rilevamento allegati

Come spiegato in precedenza, Google Classroom passa i parametri di query durante il caricamento della visualizzazione di rilevamento degli allegati nell'iframe:

• courseId: l'ID del corso Classroom corrente.
• itemId: un identificatore univoco per il compito, il materiale del corso o l'annuncio che riceve l'allegato del componente aggiuntivo.
• itemType: "courseWork", "courseWorkMaterials" o "announcement".
• addOnToken: un token utilizzato per autorizzare determinate azioni dei componenti aggiuntivi di Classroom.
• login_hint: L'ID Google dell'utente corrente.

Questa procedura dettagliata riguarda courseId, itemId, itemType e addOnToken. Conserva e trasmetti questi valori quando effettui chiamate all'API Classroom.

Come nel passaggio precedente della procedura dettagliata, memorizza i valori dei parametri di query passati nella nostra sessione. È importante farlo quando viene aperta per la prima volta la visualizzazione di rilevamento degli allegati, in quanto è l'unica opportunità per Classroom di trasmettere questi parametri di query.

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

Aggiungi spazio di archiviazione persistente per gli allegati di tipo di contenuti

Devi avere una registrazione locale di tutti gli allegati creati. In questo modo, puoi cercare i contenuti selezionati dall'insegnante utilizzando gli identificatori forniti da Classroom.

Configura uno schema del database per un Attachment. L'esempio fornito presenta allegati che mostrano un'immagine e una didascalia. Un Attachment contiene i seguenti attributi:

• attachment_id: un identificatore univoco per un allegato. Assegnato da Classroom e restituito nella risposta durante la creazione di un allegato.
• image_filename: il nome del file locale dell'immagine da visualizzare.
• image_caption: La didascalia da mostrare con l'immagine.

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

Configurare nuovi itinerari

Inizia questa procedura dettagliata impostando alcune nuove pagine nella nostra applicazione. Questi consentono a un utente di creare e visualizzare contenuti tramite il nostro componente aggiuntivo.

Aggiungere route di creazione degli allegati

Devi creare pagine in cui l'insegnante possa selezionare i contenuti ed emettere richieste di creazione di allegati. Implementa la route /attachment-options per visualizzare le opzioni dei contenuti che l'insegnante può selezionare. Ti servono anche i modelli per le pagine di selezione dei contenuti e di conferma della creazione. Gli esempi forniti contengono modelli per questi elementi e possono anche visualizzare le richieste e le risposte dell'API Classroom.

Tieni presente che in alternativa puoi modificare la pagina di destinazione della visualizzazione di rilevamento degli allegati esistente per visualizzare le opzioni dei contenuti anziché creare la nuova pagina /attachment-options. Ti consigliamo di creare una nuova pagina per questo esercizio, in modo da conservare il comportamento SSO implementato nel secondo passaggio della procedura dettagliata, ad esempio la revoca delle autorizzazioni dell'app. Questi dovrebbero rivelarsi utili durante la creazione e il test del componente aggiuntivo.

Un insegnante può scegliere tra un piccolo insieme di immagini con sottotitoli codificati nell'esempio fornito. Abbiamo fornito quattro immagini di punti di riferimento famosi le cui didascalie sono derivate dai nomi dei file.

@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,
    )

Richieste di creazione di allegati ai problemi

Ora che sai quali contenuti l'insegnante vuole allegare, invia richieste all'API Classroom per creare allegati al nostro compito. Memorizza i dettagli dell'allegato nel database dopo aver ricevuto una risposta dall'API Classroom.

Inizia recuperando un'istanza del servizio Classroom:

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)

Invia una richiesta CREATE all'endpoint courses.courseWork.addOnAttachments. Per ogni immagine selezionata dall'insegnante, crea prima un oggetto AddOnAttachment:

# 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}",
    }

Per ogni allegato devono essere forniti almeno i campi teacherViewUri, studentViewUri e title. teacherViewUri e studentViewUri rappresentano gli URL caricati quando l'allegato viene aperto dal rispettivo tipo di utente.

Invia l'oggetto AddOnAttachment nel corpo di una richiesta all'endpoint addOnAttachments appropriato. Fornisci gli identificatori courseId, itemId, itemType e addOnToken con ogni richiesta.

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

Crea una voce per questo allegato nel database locale in modo da poter caricare in un secondo momento i contenuti corretti. Classroom restituisce un valore id univoco nella risposta alla richiesta di creazione, quindi utilizzalo come chiave primaria nel nostro database. Tieni presente inoltre che Classroom passa il parametro di query attachmentId quando apre le visualizzazioni Insegnante e Studente:

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

A questo punto, valuta la possibilità di indirizzare l'utente a una pagina di conferma, per comunicare che ha creato correttamente gli allegati.

Consenti allegati dal componente aggiuntivo

Ora è un buon momento per aggiungere eventuali indirizzi appropriati al campo Prefissi URI allegati consentiti nella pagina Configurazione app dell'SDK Google Workspace Marketplace. Il componente aggiuntivo può creare allegati solo da uno dei prefissi URI elencati in questa pagina. Si tratta di una misura di sicurezza che contribuisce a ridurre la possibilità di attacchi man-in-the-middle.

L'approccio più semplice è fornire il dominio di primo livello in questo campo, ad esempio https://example.com. https://localhost:<your port number>/ funzionerebbe se utilizzi la tua macchina locale come server web.

Aggiungere percorsi per le visualizzazioni Insegnante e Studente

Esistono quattro iframe in cui potrebbe essere caricato un componente aggiuntivo di Google Classroom. Finora hai creato solo route che pubblicano l'iframe della visualizzazione di rilevamento degli allegati. Successivamente, aggiungi anche le route per pubblicare gli iframe delle visualizzazioni Insegnante e Studente.

L'iframe Visualizzazione insegnante è necessario per mostrare un'anteprima dell'esperienza dello studente, ma può includere facoltativamente informazioni aggiuntive o funzionalità di modifica.

La Visualizzazione studente è la pagina che viene mostrata a ogni studente quando apre un allegato del componente aggiuntivo.

Ai fini di questo esercizio, crea un'unica /load-content-attachment route che mostri sia la visualizzazione insegnante che quella studente. Utilizza i metodi dell'API Classroom per determinare se l'utente è un insegnante o uno studente quando la pagina viene caricata.

@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")

Tieni presente che a questo punto devi anche autenticare l'utente. Qui devi anche gestire il parametro di query login_hint e indirizzare l'utente al flusso di autorizzazione, se necessario. Per ulteriori informazioni su questo flusso, consulta i dettagli delle linee guida per l'accesso descritti nelle procedure dettagliate precedenti.

Poi invia una richiesta all'endpoint getAddOnContext che corrisponde al tipo di elemento.

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

Questo metodo restituisce informazioni sul ruolo dell'utente corrente nella classe. Modificare la visualizzazione presentata all'utente a seconda del suo ruolo. Nel oggetto risposta viene compilato esattamente uno dei campi studentContext o teacherContext. Esamina questi dati per determinare come rivolgerti all'utente.

In ogni caso, utilizza il valore del parametro di query attachmentId per sapere quale allegato recuperare dal nostro database. Questo parametro di query viene fornito quando vengono aperti gli URI della visualizzazione insegnante o studente.

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

Testare il componente aggiuntivo

Per testare la creazione di allegati, completa i seguenti passaggi:

• Accedi a [Google Classroom] come uno dei tuoi utenti di test insegnanti.
• Vai alla scheda Lavori del corso e crea un nuovo Compito.
• Fai clic sul pulsante Componenti aggiuntivi sotto l'area di testo, quindi seleziona il componente aggiuntivo. L'iframe si apre e il componente aggiuntivo carica l'URI di configurazione degli allegati che hai specificato nella pagina Configurazione app dell'SDK di Google Workspace Marketplace.
• Scegli un contenuto da allegare al compito.
• Chiudi l'iframe al termine del flusso di creazione dell'allegato.

Dovresti visualizzare una scheda allegato nell'interfaccia utente di creazione dei compiti in Google Google Classroom. Fai clic sulla scheda per aprire l'iframe della visualizzazione dell'insegnante e verifica che venga visualizzato l'allegato corretto. Fai clic sul pulsante Assegna.

Per testare l'esperienza degli studenti, completa i seguenti passaggi:

• Poi accedi a Classroom come utente di test studente nella stessa classe dell'utente di test insegnante.
• Trova il compito di test nella scheda Lavori del corso.
• Espandi il compito e fai clic sulla scheda dell'allegato per aprire l'iframe della visualizzazione dello studente.

Verifica che lo studente visualizzi l'allegato corretto.

Complimenti! Ora puoi procedere al passaggio successivo: creare allegati di tipo attività.