Interagir com anexos

Esta página discute os detalhes de implementação para criar um anexo e trabalhar com os envios dos alunos. Talvez seja necessário fornecer parâmetros relacionados a anexos ao fazer essas solicitações.

Criar um anexo

Crie um anexo enviando 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 seguintes campos 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.

É recomendável incluir alguns dos seguintes campos opcionais:

  • dueDate e dueTime, se você especificar a data de entrega do anexo.
  • maxPoints: a nota máxima do anexo. Precisa ser um valor diferente de zero se você quiser apoiar a passagem de notas. Aplicável apenas a anexos do tipo de atividade.

Consulte a referência de recurso AddOnAttachment para mais detalhes sobre esses campos.

Detalhes do envio do estudante

Um fluxo de trabalho típico de envio segue estas etapas:

  1. Um estudante inicia o studentViewUri para concluir uma atividade.
  2. O complemento recupera um submissionId do método getAddOnContext usando credenciais de estudante.
  3. O submissionId e o attachmentId são armazenados pelo desenvolvedor do complemento como o identificador exclusivo do trabalho do estudante. Se um professor copiar 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. Consulte nossa página sobre conteúdo copiado para saber mais.
  4. Um professor interessado em revisar os trabalhos dos estudantes inicia o studentWorkReviewUri. A solicitação inclui os seguintes parâmetros de consulta: courseId, itemId, itemType, attachmentId e submissionId.
  5. 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 de envio

Emita 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 dos seguintes valores:

  • NEW, se o estudante nunca tiver acessado o envio.
  • CREATED, se o estudante criou um envio, mas ainda não o enviou.
  • TURNED_IN, se o estudante enviou o trabalho para o professor.
  • RETURNED, se o professor tiver devolvido o envio 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. Depois, você pode ajustar as visualizações ou opções fornecidas ao estudante, dependendo do estado retornado. Isso pode incluir recursos como:

  • Mostrando o status de entrega das atividades no complemento. Isso pode ajudar os alunos a evitar possíveis confusões e garantir que não deixem de entregar uma atividade por engano.
  • Restringindo os privilégios de edição do envio. Se o status da atividade for CREATED ou RECLAIMED_BY_STUDENT, o estudante poderá editar o envio. Se o status da atividade for TURNED_IN ou RETURNED, talvez o estudante não tenha permissão para editar o envio.

Notas e vários anexos

Apenas um anexo de complemento pode ser usado para definir a nota de uma única atividade. Se um professor criar mais de um anexo de tipo de atividade que fornece um valor maxPoints, só o primeiro desses anexos poderá definir a nota da tarefa. Não defina o valor maxPoints ou defina-o como zero para desativar o passback de notas de um anexo.

Definir a nota de um envio

Você pode modificar o envio de um estudante enviando 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 no método pointsEarned se torna um rascunho de nota 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 das notas na IU do Google Sala de Aula para ver detalhes sobre como as notas são apresentadas aos professores.

Você só poderá definir a nota com pointsEarned se as seguintes condições forem verdadeiras:

  • O anexo precisa ter um valor maxPoints positivo.
  • O complemento precisa ser 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 a nota é devolvida para o Google Sala de Aula. A diferença principal é se você quer armazenar as credenciais do professor, já que só ele pode modificar uma nota.

Há dois momentos complementares em que você pode enviar uma nota para o Google Sala de Aula: quando o estudante conclui o trabalho ou quando o professor abre o trabalho do estudante no iframe de avaliação dos trabalhos.

Se quiser definir notas quando o estudante concluir o trabalho, armazene as credenciais off-line dele e as use para modificar a nota quando ele terminar. Esse método oferece alguns possíveis benefícios:

  • Fornecer atualizações de notas simples. Os professores não precisam fazer nada especial para que as notas sejam preenchidas na interface do Google Sala de Aula.
  • Ofereça insights em tempo real sobre o progresso da turma com uma atividade. Ao definir as notas conforme os estudantes preenchem anexos, os professores podem ter uma noção da compreensão deles sem abrir todos os envios.

Essa abordagem também permite uma abordagem assíncrona para a sincronização de notas. Você pode pesquisar periodicamente o endpoint AddOnAttachmentStudentSubmission para detectar quando um aluno enviou o trabalho. Depois do envio, defina a nota usando as credenciais armazenadas.

Se você não quiser carregar as credenciais do professor durante uma sessão de alunos, poderá usar as credenciais do professor ativo quando ele carregar o envio do aluno no iframe de avaliação dos trabalhos dos alunos. No entanto, isso talvez não ofereça uma experiência do usuário especialmente 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 de avaliação dos trabalhos dos alunos de todas as inscrições.

Detectar mudanças nas notas das atividades

os professores podem editar as configurações de notas no Google Sala de Aula depois que uma atividade é criada. Essas edições podem incluir:

  • Mudar a pontuação atribuída
  • Mudando o valor maxPoints de uma atividade.
  • alterar se a tarefa deve ou não ser corrigida;

Para acessar 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 atribuição sem nota tem um valor de maxPoints nulo ou zero.

Se você devolveu 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 complemento. O valor da nota é definido usando o campo pointsEarned. Verifique e, se necessário, atualize esse valor se o produto permitir que os professores editem a pontuação de um estudante em uma atividade específica.