Notas de anexo e passback da nota

Este é o sexto tutorial da série sobre os complementos do Google Sala de Aula.

Neste tutorial, você vai modificar o exemplo da etapa anterior para produzir um anexo de atividade com nota. Você também pode devolver uma nota ao Google Sala de Aula de forma programática, que aparece no boletim do professor como uma nota provisória.

Este tutorial é um pouco diferente dos outros da série porque apresenta duas abordagens possíveis para enviar notas de volta ao Classroom. Ambos têm impactos distintos nas experiências do desenvolvedor e do usuário. Considere os dois ao criar seu complemento do Google Sala de Aula. Leia nossa página do guia "Como interagir com anexos" para mais detalhes sobre as opções de implementação.

Os recursos de classificação na API são opcionais. Eles podem ser usados com qualquer anexo de tipo de atividade.

Neste tutorial, você vai fazer o seguinte:

• Modifique as solicitações anteriores de criação de anexos para a API Classroom e defina também o denominador da nota do anexo.
• Atribua uma nota de forma programática ao envio do estudante e defina o numerador da nota do anexo.
• Implemente duas abordagens para transmitir a nota da atividade ao Google Sala de Aula usando credenciais de professor on-line ou off-line.

Quando a avaliação termina, as notas aparecem no diário de classe do Google Sala de Aula depois que o comportamento de devolução é acionado. O momento exato em que isso acontece depende da abordagem de implementação.

Para este exemplo, reutilize a atividade do tutorial anterior, em que um estudante vê uma imagem de um ponto de referência famoso e precisa inserir o nome dele. Atribua a nota máxima ao anexo se o estudante inserir o nome correto. Caso contrário, atribua zero.

Importante: antes de seguir este tutorial, conclua os tutoriais anteriores da série. Este tutorial detalhado expande o app da Web desenvolvido nos tutoriais detalhados anteriores. Você pode fazer o download do código-fonte completo de todos os tutoriais na página "Visão geral". O código deste tutorial específico pode ser encontrado no diretório /06-grade-passback/.

Entenda o recurso de avaliação da API de complementos do Google Sala de Aula

O complemento pode definir o numerador e o denominador da nota de um anexo. Eles são definidos usando os valores pointsEarned e maxPoints na API. Um card de anexo na interface do Google Sala de Aula mostra o valor de maxPoints quando ele é definido.

Figura 1. A interface de criação de atividades com três cards de anexos de complementos que têm maxPoints definido.

Com a API de complementos do Google Sala de Aula, é possível configurar as definições e definir a nota recebida para as avaliações de anexos. Elas não são iguais às notas das atividades. No entanto, as configurações de nota da atividade seguem as configurações de nota do anexo que tem o rótulo Sincronização de notas no card do anexo. Quando o anexo "Sincronização de notas" define pointsEarned para o envio de um estudante, ele também define a nota provisória do estudante para a atividade.

Normalmente, o primeiro anexo adicionado à atividade que define maxPoints recebe o rótulo "Sincronização de notas". Confira o exemplo da interface de criação de atividades mostrado na Figura 1 para ver um exemplo do rótulo "Sincronização de notas". O card "Anexo 1" tem o rótulo "Sincronização de notas", e a nota da atividade na caixa vermelha foi atualizada para 50 pontos. Embora a Figura 1 mostre três cards de anexos, apenas um deles tem o rótulo "Sincronização de notas". Esta é uma limitação importante da implementação atual: apenas um anexo pode ter o rótulo "Sincronização de notas".

Importante: apenas um anexo pode ter o rótulo "Sincronização de notas". Recomendamos que você informe claramente aos professores o comportamento esperado caso eles adicionem mais de um anexo compatível com a devolução de notas.

Se houver vários anexos com maxPoints definido, remover o anexo com a sincronização de notas não vai ativar a sincronização de notas em nenhum dos anexos restantes. Adicionar outro anexo que defina maxPoints ativa a Sincronização de notas no novo anexo, e a nota máxima da atividade é ajustada para corresponder. Não há um mecanismo para ver por programação qual anexo tem o rótulo "Sincronização de notas" nem quantos anexos uma determinada atividade tem.

Definir a nota máxima de um anexo

Esta seção descreve como definir o denominador de uma nota de atividade, ou seja, a pontuação máxima possível que todos os estudantes podem alcançar nas atividades enviadas. Para isso, defina o valor maxPoints do anexo.

Basta uma pequena modificação na nossa implementação atual para ativar os recursos de classificação. Ao criar um anexo, adicione o valor maxPoints no mesmo objeto AddOnAttachment que contém os campos studentWorkReviewUri, teacherViewUri e outros campos de anexo.

A pontuação máxima padrão para uma nova atividade é 100. Sugerimos definir maxPoints como um valor diferente de 100 para verificar se as notas estão sendo definidas corretamente. Defina maxPoints como 50 para demonstração:

Python

Adicione o campo maxPoints ao construir o objeto attachment, logo antes de emitir uma solicitação CREATE para o endpoint courses.courseWork.addOnAttachments. Você pode encontrar isso no arquivo webapp/attachment_routes.py se seguir o exemplo fornecido.

attachment = {
    # Specifies the route for a teacher user.
    "teacherViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True),
    },
    # Specifies the route for a student user.
    "studentViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True)
    },
    # Specifies the route for a teacher user when the attachment is
    # loaded in the Classroom grading view.
    "studentWorkReviewUri": {
        "uri":
            flask.url_for(
                "view_submission", _scheme='https', _external=True)
    },
    # Sets the maximum points that a student can earn for this activity.
    # This is the denominator in a fractional representation of a grade.
    "maxPoints": 50,
    # The title of the attachment.
    "title": f"Attachment {attachment_count}",
}

Para fins desta demonstração, também armazenamos o valor maxPoints no banco de dados local de anexos. Isso evita a necessidade de fazer uma chamada de API adicional mais tarde, ao corrigir as atividades dos estudantes. No entanto, é possível que os professores alterem as configurações de nota da atividade de forma independente do seu complemento. Envie uma solicitação GET para o endpoint courses.courseWork e confira o valor maxPoints no nível da atribuição. Ao fazer isso, transmita o itemId no campo CourseWork.id.

Agora atualize o modelo de banco de dados para também armazenar o valor maxPoints do anexo. Recomendamos usar o valor maxPoints da resposta CREATE:

Python

Primeiro, adicione um campo max_points à tabela Attachment. Você pode encontrar isso no arquivo webapp/models.py se seguir o exemplo fornecido.

# Database model to represent an attachment.
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))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

Volte para a solicitação courses.courseWork.addOnAttachments CREATE. Armazene o valor maxPoints retornado na resposta.

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,
    # Store the maxPoints value returned in the response.
    max_points=int(resp.get("maxPoints")))
db.session.add(new_attachment)
db.session.commit()

O anexo agora tem uma nota máxima. Agora você pode testar esse comportamento. Adicione um anexo a uma nova atividade e observe que o card do anexo mostra o rótulo "Sincronização de notas" e o valor de "Pontos" da atividade muda.

Definir uma nota para o envio de um estudante no Google Sala de Aula

Esta seção descreve como definir o numerador de uma nota de anexo, ou seja, a pontuação de um estudante individual para o anexo. Para isso, defina o valor pointsEarned de um envio de anexo de estudante.

Agora você precisa tomar uma decisão importante: como seu complemento deve emitir uma solicitação para definir pointsEarned?

O problema é que a configuração de pointsEarned requer o teacher escopo OAuth. Não conceda o escopo teacher a estudantes. Isso pode resultar em comportamentos inesperados quando eles interagem com seu complemento, como carregar o iframe da visualização do professor em vez do iframe da visualização do estudante. Portanto, você tem duas opções para definir pointsEarned:

• Usando as credenciais do professor conectado.
• Usar credenciais de professor armazenadas (off-line).

As seções a seguir discutem as vantagens e desvantagens de cada abordagem antes de demonstrar cada implementação. Os exemplos fornecidos demonstram ambas as abordagens para transmitir uma nota ao Google Sala de Aula. Consulte as instruções específicas do idioma abaixo para saber como selecionar uma abordagem ao executar os exemplos fornecidos:

Python

Encontre a declaração SET_GRADE_WITH_LOGGED_IN_USER_CREDENTIALS na parte de cima do arquivo webapp/attachment_routes.py. Defina esse valor como True para transmitir notas usando as credenciais do professor conectado. Defina esse valor como False para transmitir as notas usando credenciais armazenadas quando o estudante enviar a atividade.

Definir notas usando as credenciais do professor conectado

Atenção: embora seja mais fácil de implementar, essa abordagem para definir notas tem impactos significativos na experiência do usuário professor. O feedback coletado pela pesquisa de experiência do usuário do Google indica que essa abordagem não é preferida pelos usuários finais. Os professores relataram que acham que um complemento está "quebrado" ou que estão usando de forma incorreta.

Leia esta e as seções a seguir com atenção antes de decidir uma abordagem de implementação.

Use as credenciais do usuário conectado para emitir a solicitação de definição de pointsEarned. Isso parece bastante intuitivo, já que reflete o restante da implementação até agora e exige pouco esforço para ser percebido.

No entanto, considere que o professor só interage com o envio do estudante no iframe de revisão de trabalhos dos estudantes. Isso tem algumas implicações importantes:

• As notas não aparecem no Google Sala de Aula até que o professor tome medidas na interface do Google Sala de Aula.
• Um professor pode precisar abrir o envio de cada estudante para preencher todas as notas.
• Há um pequeno atraso entre o recebimento da nota pelo Google Sala de Aula e a exibição dela na interface. O atraso é normalmente de 5 a 10 segundos, mas pode chegar a 30 segundos.

A combinação desses fatores significa que os professores podem ter que fazer um trabalho manual considerável e demorado para preencher totalmente as notas de uma turma.

Observação: uma possível melhoria é devolver todas as notas dos estudantes quando um professor visualiza qualquer envio de um determinado anexo. No entanto, isso pode não resolver o problema e pode ser caro do ponto de vista computacional. Considere que nem todas as notas dos estudantes podem estar disponíveis quando o recurso é acionado pela primeira vez, exigindo que o professor abra várias atividades enviadas para preencher totalmente o boletim.

Uma alternativa para transmitir notas automaticamente é fornecer um botão "Devolver tudo" no iframe da revisão de trabalhos dos estudantes ou da visualização do professor. Isso permite que o professor controle quando o boletim de notas é preenchido, mas ainda exige uma ação manual.

Para implementar essa abordagem, adicione mais uma chamada de API à sua rota Student Work Review.

Depois de buscar os registros de envio e anexos do estudante, avalie o envio e armazene a nota resultante. Defina a nota no campo pointsEarned de um objeto AddOnAttachmentStudentSubmission. Por fim, envie uma solicitação PATCH para o endpoint courses.courseWork.addOnAttachments.studentSubmissions com a instância AddOnAttachmentStudentSubmission no corpo da solicitação. Também precisamos especificar pointsEarned no updateMask na solicitação PATCH:

Python

Observação: no exemplo em Python fornecido, defina SET_GRADE_WITH_LOGGED_IN_USER_CREDENTIALS como True em webapp/attachment_routes.py para executar o exemplo usando essa abordagem.

# Look up the student's submission in our database.
student_submission = Submission.query.get(flask.session["submissionId"])

# Look up the attachment in the database.
attachment = Attachment.query.get(student_submission.attachment_id)

grade = 0

# See if the student response matches the stored name.
if student_submission.student_response.lower(
) == attachment.image_caption.lower():
    grade = attachment.max_points

# Create an instance of the Classroom service.
classroom_service = ch._credential_handler.get_classroom_service()

# Build an AddOnAttachmentStudentSubmission instance.
add_on_attachment_student_submission = {
    # Specifies the student's score for this attachment.
    "pointsEarned": grade,
}

# Issue a PATCH request to set the grade numerator for this attachment.
patch_grade_response = classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

Definir notas usando credenciais de professores off-line

Importante: essa abordagem oferece uma experiência do usuário muito melhor do que a anterior, mas exige muito mais trabalho de implementação. Recomendamos muito usar essa abordagem para definir notas.

Leia esta seção e as anteriores com atenção antes de decidir uma abordagem de implementação.

A segunda abordagem para definir notas exige o uso de credenciais armazenadas do professor que criou o anexo. Essa implementação exige que você crie credenciais usando os tokens de atualização e de acesso de um professor autorizado anteriormente e, em seguida, use essas credenciais para definir pointsEarned.

Uma vantagem importante dessa abordagem é que as notas são preenchidas sem exigir ações do professor na interface do Google Sala de Aula, evitando os problemas mencionados acima. O resultado é que os usuários finais percebem a experiência de avaliação como perfeita e eficiente. Além disso, essa abordagem permite escolher o momento em que você vai devolver as notas, como quando os estudantes terminam a atividade ou de forma assíncrona.

Importante: antes de continuar, verifique se você está solicitando tokens off-line ao autorizar o usuário. Consulte o tutorial de login do usuário e o guia de implementação do Google Identity para mais informações sobre como solicitar tokens off-line.

Conclua as seguintes tarefas para implementar essa abordagem:

1. Modifique os registros do banco de dados de usuários para armazenar um token de acesso.
2. Modifique os registros do banco de dados de anexos para armazenar um ID do professor.
3. Recupere as credenciais do professor e, opcionalmente, crie uma nova instância do serviço do Google Sala de Aula.
4. Defina a nota de um envio.

Para fins desta demonstração, defina a nota quando o estudante concluir a atividade, ou seja, quando ele enviar o formulário na rota da visualização do estudante.

Modificar registros do banco de dados de usuários para armazenar o token de acesso

Dois tokens exclusivos são necessários para fazer chamadas de API: o token de atualização e o token de acesso. Se você seguiu a série de tutoriais até agora, o esquema da tabela User já deve armazenar um token de atualização. Armazenar o token de atualização é suficiente quando você só faz chamadas de API com o usuário conectado, já que você recebe um token de acesso como parte do fluxo de autenticação.

No entanto, agora você precisa fazer chamadas como alguém diferente do usuário conectado, o que significa que o fluxo de autenticação não está disponível. Portanto, é necessário armazenar o token de acesso junto com o token de atualização. Atualize o esquema da tabela User para incluir um token de acesso:

Python

No exemplo fornecido, isso está no arquivo webapp/models.py.

# Database model to represent a user.
class User(db.Model):
    # The user's identifying information:
    id = db.Column(db.String(120), primary_key=True)
    display_name = db.Column(db.String(80))
    email = db.Column(db.String(120), unique=True)
    portrait_url = db.Column(db.Text())

    # The user's refresh token, which will be used to obtain an access token.
    # Note that refresh tokens will become invalid if:
    # - The refresh token has not been used for six months.
    # - The user revokes your app's access permissions.
    # - The user changes passwords.
    # - The user belongs to a Google Cloud organization
    #   that has session control policies in effect.
    refresh_token = db.Column(db.Text())

    # An access token for this user.
    access_token = db.Column(db.Text())

Em seguida, atualize qualquer código que crie ou atualize um registro User para também armazenar o token de acesso:

Python

No exemplo fornecido, isso está no arquivo webapp/credential_handler.py.

def save_credentials_to_storage(self, credentials):
    # Issue a request for the user's profile details.
    user_info_service = googleapiclient.discovery.build(
        serviceName="oauth2", version="v2", credentials=credentials)
    user_info = user_info_service.userinfo().get().execute()
    flask.session["username"] = user_info.get("name")
    flask.session["login_hint"] = user_info.get("id")

    # See if we have any stored credentials for this user. If they have used
    # the add-on before, we should have received login_hint in the query
    # parameters.
    existing_user = self.get_credentials_from_storage(user_info.get("id"))

    # If we do have stored credentials, update the database.
    if existing_user:
        if user_info:
            existing_user.id = user_info.get("id")
            existing_user.display_name = user_info.get("name")
            existing_user.email = user_info.get("email")
            existing_user.portrait_url = user_info.get("picture")

        if credentials and credentials.refresh_token is not None:
            existing_user.refresh_token = credentials.refresh_token
            # Update the access token.
            existing_user.access_token = credentials.token

    # If not, this must be a new user, so add a new entry to the database.
    else:
        new_user = User(
            id=user_info.get("id"),
            display_name=user_info.get("name"),
            email=user_info.get("email"),
            portrait_url=user_info.get("picture"),
            refresh_token=credentials.refresh_token,
            # Store the access token as well.
            access_token=credentials.token)

        db.session.add(new_user)

    db.session.commit()

Modificar registros do banco de dados de anexos para armazenar um ID de professor

Para definir uma nota para uma atividade, faça uma chamada para definir pointsEarned como um professor no curso. Há várias maneiras de fazer isso:

• Armazene um mapeamento local de credenciais de professores para IDs de cursos. No entanto, o mesmo professor nem sempre está associado a um curso específico.
• Envie solicitações GET para o endpoint courses da API Classroom para receber os professores atuais. Em seguida, consulte os registros de usuários locais para encontrar credenciais de professores correspondentes.
• Ao criar um anexo de complemento, armazene um ID de professor no banco de dados de anexos local. Em seguida, recupere as credenciais do professor do attachmentId transmitido para o iframe da Visão do estudante.

Este exemplo demonstra a última opção, já que você está definindo notas quando o estudante conclui um anexo de atividade.

Adicione um campo de ID do professor à tabela Attachment do banco de dados:

Python

No exemplo fornecido, isso está no arquivo webapp/models.py.

# Database model to represent an attachment.
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))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

    # The ID of the teacher that created the attachment.
    teacher_id = db.Column(db.String(120))

Em seguida, atualize qualquer código que crie ou atualize um registro Attachment para também armazenar o ID do criador:

Python

No exemplo fornecido, isso está no método create_attachments do arquivo webapp/attachment_routes.py.

# Store the attachment 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,
    max_points=int(resp.get("maxPoints")),
    teacher_id=flask.session["login_hint"])
db.session.add(new_attachment)
db.session.commit()

Recuperar as credenciais do professor

Encontre a rota que atende ao iframe da Visualização do estudante. Imediatamente após armazenar a resposta do estudante no banco de dados local, recupere as credenciais do professor no armazenamento local. Isso deve ser simples, considerando a preparação nas duas etapas anteriores. Você também pode usar esses dados para criar uma nova instância do serviço do Google Sala de Aula para o usuário professor:

Python

No exemplo fornecido, isso está no método load_activity_attachment do arquivo webapp/attachment_routes.py.

# Create an instance of the Classroom service using the tokens for the
# teacher that created the attachment.

# We're assuming that there are already credentials in the session, which
# should be true given that we are adding this within the Student View
# route; we must have had valid credentials for the student to reach this
# point. The student credentials will be valid to construct a Classroom
# service for another user except for the tokens.
if not flask.session.get("credentials"):
    raise ValueError(
        "No credentials found in session for the requested user.")

# Make a copy of the student credentials so we don't modify the original.
teacher_credentials_dict = deepcopy(flask.session.get("credentials"))

# Retrieve the requested user's stored record.
teacher_record = User.query.get(attachment.teacher_id)

# Apply the user's tokens to the copied credentials.
teacher_credentials_dict["refresh_token"] = teacher_record.refresh_token
teacher_credentials_dict["token"] = teacher_record.access_token

# Construct a temporary credentials object.
teacher_credentials = google.oauth2.credentials.Credentials(
    **teacher_credentials_dict)

# Refresh the credentials if necessary; we don't know when this teacher last
# made a call.
if teacher_credentials.expired:
    teacher_credentials.refresh(Request())

# Request the Classroom service for the specified user.
teacher_classroom_service = googleapiclient.discovery.build(
    serviceName=CLASSROOM_API_SERVICE_NAME,
    version=CLASSROOM_API_VERSION,
    credentials=teacher_credentials)

Definir a nota de um envio

O procedimento a partir daqui é idêntico ao de usar as credenciais do professor conectado. No entanto, faça a chamada com as credenciais do professor recuperadas na etapa anterior:

Python

Observação: no exemplo em Python fornecido, defina SET_GRADE_WITH_LOGGED_IN_USER_CREDENTIALS como False em webapp/attachment_routes.py para executar o exemplo usando essa abordagem.

# Issue a PATCH request as the teacher to set the grade numerator for this
# attachment.
patch_grade_response = teacher_classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

Testar o complemento

Importante: nesta fase de desenvolvimento, só é possível testar o aplicativo nos iframes dos complementos do Google Sala de Aula. Leia nossa página de guia sobre parâmetros de consulta e iframe para ver uma descrição de cada iframe. Todas as instruções fornecidas neste tutorial pressupõem que o complemento pode ser usado no contexto de um iframe.

Semelhante ao tutorial anterior, crie uma atividade com um anexo do tipo atividade como professor, envie uma resposta como estudante e abra o envio no iframe de revisão de trabalhos dos estudantes. A nota vai aparecer em momentos diferentes, dependendo da sua abordagem de implementação:

• Se você escolheu devolver uma nota quando o estudante concluiu a atividade, a nota provisória dele já vai aparecer na interface antes de abrir o iframe "Revisão do trabalho do estudante". Ele também aparece na lista de estudantes ao abrir a atividade e na caixa "Nota" ao lado do iframe de revisão do trabalho do estudante.
• Se você escolheu transmitir uma nota quando o professor abrir o iframe de revisão de trabalhos dos estudantes, ela vai aparecer na caixa "Nota" logo após o carregamento do iframe. Conforme mencionado acima, isso pode levar até 30 segundos. Depois disso, a nota do estudante específico também vai aparecer nas outras visualizações do diário de classe do Google Sala de Aula.

Confirme se a nota correta aparece para o estudante.

Parabéns! Agora você pode passar para a próxima etapa: criar anexos fora do Google Sala de Aula.