Nesta página, você verá detalhes sobre a implementação da criação de um anexo e do trabalho com os arquivos enviados pelos alunos. Talvez seja necessário fornecer parâmetros relacionados a anexos ao fazer essas solicitações.
Criar um anexo
Crie um anexo emitindo uma solicitação CREATE
para o endpoint courses.*.addOnAttachments.create
apropriado. Sua solicitação precisa incluir uma instância de AddOnAttachment
no corpo da solicitação.
Os campos a seguir são obrigatórios ao criar um anexo:
title
: o nome da string do anexo.teacherViewUri
: o URI da visualização do professor do anexo.studentViewUri
: o URI da visualização do estudante do anexo.studentWorkReviewUri
: o URI para o professor ver o trabalho do estudante no anexo. Esse campo só é obrigatório para anexos do tipo atividade.
Você pode incluir alguns dos seguintes campos opcionais:
dueDate
edueTime
se especificarem a data de entrega do anexo.maxPoints
: a nota máxima do anexo. Precisa ser um valor diferente de zero se você quiser oferecer suporte à transferência de notas. Aplicável apenas a anexos do tipo de atividade.
Consulte a referência do recurso AddOnAttachment
para mais detalhes sobre esses campos.
Detalhes do envio do estudante
Um fluxo de trabalho de envio típico segue estas etapas:
- Um estudante inicia a
studentViewUri
para concluir uma atividade. - O complemento recupera um
submissionId
do métodogetAddOnContext
usando credenciais de alunos. - O
submissionId
e oattachmentId
são armazenados pelo desenvolvedor do complemento como o identificador exclusivo do trabalho do estudante. Caso um professor copie uma atividade no Google Sala de Aula, você poderá usar a chave composta desses dois parâmetros para exibir um novo anexo na atividade copiada. Confira mais detalhes na página sobre conteúdo copiado. - Um professor interessado em revisar o trabalho de um estudante inicia o
studentWorkReviewUri
. A solicitação inclui os seguintes parâmetros de consulta:courseId
,itemId
,itemType
,attachmentId
esubmissionId
. - O desenvolvedor do complemento usa esses quatro IDs para recuperar o trabalho do estudante. Use
o endpoint
courses.courseWork.addOnAttachments.studentSubmissions
para recuperar ou modificar informações sobre o envio de um estudante.
Detectar o estado do envio
Envie uma solicitação GET
para o endpoint courses.courseWork.addOnAttachments.studentSubmissions
para ver detalhes sobre um submissionId
específico. Você recebe um objeto
AddOnAttachmentStudentSubmission
, que contém a nota do envio
(pointsEarned
) e o estado atual (postSubmissionState
). O estado do envio
pode ser um destes valores:
NEW
, se o estudante nunca tiver acessado o envio.CREATED
, se o aluno criou um envio, mas ainda não o enviou.TURNED_IN
, se o estudante tiver enviado o trabalho para o professor.RETURNED
, se o professor tiver devolvido o trabalho para o aluno.RECLAIMED_BY_STUDENT
, se o estudante tiver cancelado o envio do trabalho.
Use este endpoint para detectar o estado do trabalho do estudante no seu complemento. Em seguida, é possível ajustar as visualizações ou opções fornecidas ao estudante dependendo do estado retornado. Isso pode incluir recursos como:
- Mostrando o status de entrega de atividades no seu complemento. Isso pode ajudar os estudantes a evitar possíveis confusões e garantir que eles não deixem de entregar uma atividade por engano.
- Restringindo privilégios de edição de envio. Se a atividade tiver o status
CREATED
ouRECLAIMED_BY_STUDENT
, o estudante poderá ter permissão para editar o envio enviado. Se a atividade tiver o statusTURNED_IN
ouRETURNED
, talvez o aluno não tenha permissão para editar o envio.
Notas e vários anexos
Apenas um anexo de complementos pode ser usado para dar a nota de uma única
atividade. Se um professor criar mais de um anexo de tipo de atividade que forneça um valor maxPoints
, apenas o primeiro anexo poderá definir a nota da atividade. Deixe o valor maxPoints
sem definição ou defina-o como zero para
desativar o passback de notas de um anexo.
Definir a nota de um envio
Para modificar o envio de um estudante, envie uma solicitação PATCH
para o
endpoint courses.courseWork.addOnAttachments.studentSubmissions
. O corpo
da solicitação precisa incluir uma instância de AddOnAttachmentStudentSubmission
com os
valores modificados. Defina o campo pointsEarned
para modificar a nota de um envio.
O valor transmitido em pointsEarned
se torna uma nota temporária visível para o professor na interface do Google Sala de Aula. Os professores podem modificar a nota temporária
antes de devolver a atividade aos estudantes. Consulte Visão geral da avaliação na
interface do Google Sala de Aula para detalhes sobre como as notas são
apresentadas aos professores.
Você só poderá definir a nota com pointsEarned
se o seguinte for
verdadeiro:
- O anexo precisa ter um valor
maxPoints
positivo. - O complemento precisa ter sido o criador original do anexo.
Observe também que é possível modificar o valor maxPoints
de um AddOnAttachment
já criado emitindo uma solicitação PATCH
para o endpoint addOnAttachments
.
Quando definir uma nota
É possível escolher quando uma nota é devolvida para o Google Sala de Aula. A distinção principal é se você optar por armazenar as credenciais de professor, já que apenas ele pode modificar uma nota.
Há dois momentos complementares em que você pode transmitir uma nota para o Google Sala de Aula: quando o estudante conclui o trabalho ou o professor abre o trabalho no iframe "Revisão do trabalho do estudante".
Se você quiser dar notas quando o aluno concluir o trabalho, armazene as credenciais off-line de um professor e, em seguida, recupere e use-as para modificar a nota quando o aluno terminar. Esse método oferece alguns possíveis benefícios:
- Facilite as atualizações de notas. Os professores não precisam fazer nada para que as notas sejam preenchidas na interface do Google Sala de Aula.
- Fornecer insights em tempo real sobre o progresso de uma turma em uma tarefa. Ao definir as notas à medida que os alunos preenchem anexos, os professores podem ter uma ideia do entendimento dos alunos sem precisar abrir cada envio.
Essa abordagem também permite uma abordagem assíncrona para a sincronização
de notas. É possível pesquisar periodicamente o endpoint AddOnAttachmentStudentSubmission
para detectar quando um estudante enviou o trabalho. Após o envio, defina a nota usando as credenciais armazenadas.
Se você não quiser carregar as credenciais do professor durante uma sessão de estudante, use as credenciais do professor ativo quando ele carregar o envio do aluno no iframe "Revisão dos trabalhos dos alunos". No entanto, isso pode não oferecer uma experiência do usuário muito tranquila, já que as notas na interface do Google Sala de Aula não são atualizadas em tempo real e os professores precisam abrir o iframe "Revisão dos trabalhos dos alunos" de todos os envios.
Detectar mudanças nas notas das atividades
os professores podem editar as configurações de notas no Google Sala de Aula após a criação de uma atividade. Essas edições podem incluir:
- Alterando a pontuação atribuída.
- Alterar o valor de
maxPoints
de uma atividade. - Alterar se a tarefa deve receber nota.
Para conferir as configurações de avaliação atuais de uma atividade, recomendamos que você envie
uma solicitação GET
para o endpoint courses.courseWork
. A resposta inclui o valor maxPoints
atual. Uma atividade sem nota tem um valor maxPoints
nulo
ou zero.
Se você transmitiu uma nota para o Google Sala de Aula, use o endpoint courses.courseWork.addOnAttachments.studentSubmissions
para buscar ou alterar a nota de um anexo de complementos. O valor da nota é definido usando o campo pointsEarned
. Verifique e, se necessário, atualize esse valor se o produto permite que os professores editem a pontuação de um estudante para uma atividade específica.