Interagir com anexos

Nesta página, discutimos detalhes da implementação para criar um anexo, ações recomendadas quando os usuários abrem anexos e como trabalhar com envios dos estudantes. 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. Este campo é obrigatório apenas para anexos do tipo atividade.

Você pode incluir alguns dos seguintes campos opcionais:

  • dueDate e dueTime se você estiver especificando quando o anexo deve ser entregue.
  • maxPoints: a nota máxima para o anexo. Precisa ser um valor diferente de zero se você quiser oferecer suporte ao retorno de notas. Aplicável somente a anexos de tipo de atividade.

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

Validar as credenciais e a função do usuário

Os iframes da visualização do estudante, da revisão de atividades do estudante e da visualização do professor foram criados para apresentar conteúdo ao usuário, e não para modificar uma atividade do Google Sala de Aula. Considere fazer o seguinte quando uma dessas visualizações for aberta:

  • Receba as credenciais OAuth do usuário.
  • Faça uma solicitação courseWork.getAddOnContext, courseWorkMaterials.getAddOnContext ou announcements.getAddOnContext com base no itemType para validar a função do usuário.
  • Inspecione a resposta para ver se TeacherContext ou StudentContext estão presentes. Só é possível retornar um, correspondente à função do usuário no curso.
  • Se o usuário atual for um estudante e o itemType for courseWork, registre o submissionId da resposta com o trabalho do estudante. A correspondência submissionIds em iframes de complementos é necessária para transmitir notas e mostrar o trabalho dos estudantes aos professores na ferramenta de avaliação.
  • Se o complemento já conhecer o attachmentId, mostre a interface de anexo apropriada.
  • Caso contrário, o anexo precisa ter sido copiado de outro item do stream ou curso. Consulte o guia Como lidar com conteúdo copiado para recomendações sobre esse cenário.

Detalhes do envio dos estudantes

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

  1. Um estudante inicia o studentViewUri para concluir uma atividade.
  2. O complemento recupera um submissionId do método getAddOnContext usando as credenciais do estudante.
  3. O submissionId e o attachmentId 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, use a chave composta desses dois parâmetros para mostrar um novo anexo na atividade copiada. Consulte nossa página sobre conteúdo copiado para mais detalhes.
  4. Um professor interessado em revisar o trabalho 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 ponto de extremidade courses.courseWork.addOnAttachments.studentSubmissions para recuperar ou modificar informações sobre um envio de estudante.

Detectar o estado de envio

Envie uma solicitação GET para o endpoint courses.courseWork.addOnAttachments.studentSubmissions e receba detalhes sobre um submissionId específico. Você recebe um objeto AddOnAttachmentStudentSubmission, que contém a nota da atividade (pointsEarned) e o estado atual (postSubmissionState). O estado da atividade pode ser um dos seguintes valores:

  • NEW, se o estudante nunca tiver acessado o envio.
  • CREATED, se o estudante tiver criado um envio, mas ainda não o tiver enviado.
  • TURNED_IN, se o estudante tiver enviado o trabalho ao professor.
  • RETURNED, se o professor devolveu a atividade para o estudante.
  • RECLAIMED_BY_STUDENT, se o estudante tiver "não enviado" o trabalho.

Use esse endpoint para detectar o estado do trabalho do estudante no seu complemento. Em seguida, ajuste as visualizações ou opções fornecidas ao estudante dependendo do estado retornado. Isso pode incluir recursos como:

  • Mostrar o status de entrega das atividades no complemento. Isso pode ajudar os estudantes a evitar confusões e garantir que eles não deixem de entregar uma atividade por engano.
  • Restringir privilégios de edição de envios. Se a atividade tiver o status CREATED ou RECLAIMED_BY_STUDENT, o estudante poderá editar o envio. Se a atividade tiver o status TURNED_IN ou RETURNED, o estudante talvez não possa editar o envio.

Notas e vários anexos

Só é possível usar um anexo de complemento para definir a nota de uma única atividade. Se um professor criar mais de um anexo de atividade que forneça um valor maxPoints, apenas o primeiro anexo poderá definir a nota da atividade. Deixe o valor maxPoints sem definir ou defina como zero para desativar a devolução de notas em um anexo.

Definir a nota de um envio

É possível modificar uma atividade enviada por um estudante enviando uma solicitação PATCH ao 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 uma atividade. O valor transmitido em pointsEarned se torna uma nota provisória visível para o professor na interface do 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 saber como as notas são apresentadas aos professores.

Só é possível 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.

Também é possível modificar o valor maxPoints de um AddOnAttachment já criado enviando uma solicitação PATCH ao endpoint addOnAttachments.

Quando atribuir uma nota

Você pode escolher quando uma nota é enviada de volta para o Google Sala de Aula. A distinção fundamental é se você escolhe armazenar as credenciais do professor, já que apenas ele pode modificar uma nota.

Há dois momentos em que você pode transferir 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 revisão de trabalhos dos estudantes.

Se você quiser definir notas quando o estudante concluir o trabalho, armazene as credenciais off-line de um professor, recupere e use-as para modificar a nota quando o estudante concluir o trabalho. Esse método oferece alguns benefícios em potencial:

  • Fornecer atualizações de notas sem problemas. Os professores não precisam fazer nada de especial para que as notas sejam preenchidas na interface do Sala de Aula.
  • Fornecer insights em tempo real sobre o progresso de uma turma em uma atividade. Ao definir notas à medida que os estudantes concluem os anexos, os professores podem ter uma ideia do nível de compreensão dos estudantes sem abrir cada envio.

Essa abordagem também permite uma abordagem assíncrona para a sincronização de notas. Você pode consultar periodicamente o endpoint AddOnAttachmentStudentSubmission para detectar quando um estudante enviou o trabalho. Depois que ele for enviado, defina a nota da atividade usando as credenciais armazenadas.

Se você não quiser carregar as credenciais do professor durante uma sessão do estudante, use as credenciais do professor ativo quando ele carregar o envio do estudante no iframe de revisão de trabalhos dos estudantes. No entanto, isso pode não proporcionar 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 de revisão de trabalhos dos estudantes de cada envio.

Detectar mudanças nas notas das atividades

É possível que os professores editem as configurações de nota no Google Sala de Aula depois que uma atividade é criada. Essas edições podem incluir:

  • Mudar a pontuação atribuída.
  • Mudar o valor maxPoints de uma atribuição.
  • Mudar se a atividade deve ser avaliada.

Para conferir as configurações atuais de avaliação de uma atividade, recomendamos enviar uma solicitação GET para o endpoint courses.courseWork. A resposta inclui o valor maxPoints atual. Uma atividade sem nota tem um valor nulo ou zero maxPoints.

Se você tiver enviado 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 nota de um estudante em uma atividade específica.