Allegati per tipo di contenuti

Questa è la quarta procedura dettagliata per i componenti aggiuntivi di Classroom di una serie di procedure dettagliate.

In questa procedura dettagliata, interagisci con l'API Google Classroom per creare allegati. Fornisci agli utenti percorsi per visualizzare i contenuti degli allegati. La le visualizzazioni variano a seconda del ruolo dell'utente nel corso. Questa procedura dettagliata illustra allegati di tipo content-type, che non richiedono l'invio di contenuti da parte dello studente.

Nel corso di questa procedura dettagliata, completerai quanto segue:

• Recupera e utilizza i seguenti parametri di query dei componenti aggiuntivi:
  • addOnToken: un token di autorizzazione passato al rilevamento dell'allegato Vista.
  • itemId: un identificatore univoco per CourseWork, CourseWorkMaterial o Annuncio che riceve l'allegato del componente aggiuntivo.
  • itemType: può essere "courseWork", "courseWorkMaterials" o "annuncio".
  • courseId: un identificatore univoco per il corso di Google Classroom in in cui viene creato l'assegnazione.
  • attachmentId: un identificatore univoco assegnato da Google Classroom a un come allegato del componente aggiuntivo dopo la creazione.
• Implementa l'archiviazione permanente per gli allegati di tipo contenuto.
• Fornire percorsi per creare allegati e gestire la vista Insegnante e iframe di visualizzazione studente.
• Invia le seguenti richieste all'API dei componenti aggiuntivi di Google Classroom:
  • Crea un nuovo allegato.
  • Ottieni il contesto del componente aggiuntivo, che identifica se l'utente che ha eseguito l'accesso è un studente o insegnante.

Al termine, puoi creare allegati di tipo contenuto nei compiti tramite nell'interfaccia utente di Google Classroom quando si accede come insegnante. Insegnanti e studenti di anche la classe può visualizzare i contenuti.

Abilitare l'API Classroom

Effettua chiamate all'API Classroom iniziando con questo passaggio. L'API deve abilitare per il tuo progetto Google Cloud prima di potervi chiamare. Naviga alla voce della raccolta dell'API Google Classroom e scegli Abilita.

Gestire i parametri di query della visualizzazione di rilevamento degli allegati

Come affermato in precedenza, Google Classroom passa i parametri di query quando Caricamento della visualizzazione di rilevamento degli allegati nell'iframe:

• courseId: l'ID dell'attuale corso di Classroom.
• itemId: un identificatore univoco per i valori del corso CourseWork, CourseWorkMaterial o Annuncio che riceve l'allegato del componente aggiuntivo.
• itemType: può essere "courseWork", "courseWorkMaterials" o "annuncio".
• addOnToken: un token utilizzato per autorizzare determinati Azioni del componente aggiuntivo di Classroom.
• login_hint: l'ID Google dell'utente corrente.

Questa procedura dettagliata riguarda courseId, itemId, itemType e addOnToken. Conservali e passali quando effettui chiamate all'API Classroom.

Come nel passaggio della procedura dettagliata precedente, memorizza i valori dei parametri di query passati in durante la nostra sessione. È importante farlo quando la vista di rilevamento degli allegati è aperto per la prima volta, poiché questa è l'unica opportunità per passare 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")

Aggiungere spazio di archiviazione permanente per gli allegati di tipo contenuto

Devi avere un record locale di tutti gli allegati creati. Questo ti consente di cercare contenuti selezionati dall'insegnante utilizzando gli identificatori forniti di Classroom.

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

• attachment_id: un identificatore univoco per un allegato. Assegnata da Classroom e restituito nella risposta durante la creazione di un allegato.
• image_filename: il nome 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))

Configura nuove route

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

Aggiungi route per la creazione degli allegati

Sono necessarie pagine in cui l'insegnante possa selezionare i contenuti ed emettere allegati richieste. Implementa il percorso /attachment-options per visualizzare le opzioni dei contenuti che l'insegnante può selezionare. Servono anche modelli per la selezione dei contenuti pagine di conferma della creazione. Gli esempi forniti contengono modelli pertinenti, e può anche visualizzare le richieste e le risposte dei API Classroom.

Tieni presente che in alternativa puoi modificare la visualizzazione di rilevamento degli allegati esistente. pagina di destinazione in modo da visualizzare le opzioni dei contenuti anziché creare la nuova /attachment-options pagina. Ti consigliamo di creare una nuova pagina per questo esercizio per preservare il comportamento SSO implementato nel secondo procedura dettagliata, come la revoca delle autorizzazioni app. Questi dovrebbero dimostrare è utile per creare e testare il componente aggiuntivo.

Un insegnante può scegliere da un piccolo insieme di immagini sottotitolate nel nostro esempio. Abbiamo fornito quattro immagini di punti di riferimento famosi le cui didascalie sono derivati 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,
    )

Problema nelle richieste di creazione degli allegati

Ora che sai quali contenuti desidera allegare, inviare all'API Classroom richieste di creazione di allegati nei nostri compito. Archivia i dettagli dell'allegato nel database dopo aver ricevuto un una risposta dall'API Classroom.

Inizia ottenendo 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 a courses.courseWork.addOnAttachments endpoint. Per ogni immagine selezionata dall'insegnante, innanzitutto crea una 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}",
    }

Almeno i campi teacherViewUri, studentViewUri e title devono essere forniti per ogni allegato. 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'oggetto Endpoint addOnAttachments. Fornisci i courseId, itemId, itemType e addOnToken identificatori per 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 collegamento nel tuo database locale in modo da poterla in seguito caricare i contenuti corretti. Classroom restituisce un valore id univoco nella risposta alla richiesta di creazione, quindi usala come chiave primaria per configurare un database. Inoltre, Classroom trasmette il attachmentId durante l'apertura delle viste 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, considera la possibilità di indirizzare l'utente a una pagina di conferma, confermando di aver creato correttamente gli allegati.

Consentire gli allegati dal componente aggiuntivo

È il momento giusto per aggiungere gli indirizzi appropriati all'allegato consentito Campo Prefissi URI nella sezione 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 per ridurre le possibilità di attacchi man in the middle.

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

Aggiunta di percorsi per le viste insegnanti e studenti

Esistono quattro iframe in cui potrebbe essere caricato un componente aggiuntivo di Google Classroom. Hai creato solo route che pubblicano l'iframe della visualizzazione di rilevamento degli allegati, quindi lontano. In seguito, aggiungi percorsi per pubblicare anche gli iframe della vista Insegnante e Studente.

L'iframe Visualizzazione insegnante è necessario per mostrare un'anteprima dello studente. ma può anche includere ulteriori informazioni o le funzionalità di machine learning.

La Visualizzazione studente è la pagina presentata a ogni studente quando apre di un componente aggiuntivo.

Ai fini di questo esercizio, crea un singolo /load-content-attachment percorso sia per l'insegnante che per lo studente. Utilizzare l'API Classroom metodi per determinare se l'utente è un insegnante o uno studente quando la pagina viene caricato automaticamente.

@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 dovresti anche autenticare l'utente. Tu deve anche gestire il parametro di query login_hint qui e indirizzare l'utente a il flusso di autorizzazione, se necessario. Consulta i dettagli delle indicazioni per l'accesso discussi nelle procedure dettagliate precedenti per saperne di più su questo flusso.

Quindi, invia una richiesta all'endpoint getAddOnContext corrispondente all'elemento di testo.

# 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 in base al suo ruolo. Esattamente uno dei I campi studentContext o teacherContext sono compilati nella risposta . Esaminali per stabilire come rivolgersi all'utente.

In ogni caso, utilizza il valore del parametro di query attachmentId per sapere quale allegato da recuperare dal nostro database. Questo parametro di query viene fornito quando aprire gli URI della vista 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)

Testa il componente aggiuntivo

Completa i seguenti passaggi per testare la creazione degli allegati:

• 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 e seleziona il componente aggiuntivo. L'iframe si apre e il componente aggiuntivo carica l'URI di configurazione dell'allegato che specificato nella pagina Configurazione app dell'SDK Google Workspace Marketplace.
• Scegli un contenuto da allegare al compito.
• Chiudi l'iframe al termine del flusso di creazione dell'allegato.

Dovresti vedere una scheda degli allegati nell'UI di creazione dei compiti su Google. Google Classroom. Fai clic sulla scheda per aprire l'iframe di Visualizzazione insegnante e conferma per visualizzare l'allegato corretto. Fai clic sul pulsante Assegna.

Completa i seguenti passaggi per testare l'esperienza degli studenti:

• Accedi a Classroom come utente di prova dello studente nella stessa come utente di test dell'insegnante.
• Trova il compito di prova nella scheda Lavori del corso.
• Espandi il compito e fai clic sulla scheda dell'allegato per aprire la Vista studente. iframe.

Verifica che venga visualizzato l'allegato corretto per lo studente.

Complimenti! Sei pronto per andare al passaggio successivo: creazione allegati di tipo attività.