Interagir com anexos

Esta página discute detalhes de implementação para criar um anexo, ações recomendadas quando os usuários abrem anexos e como trabalhar com envios de 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 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.

Talvez você queira incluir alguns dos seguintes campos opcionais:

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

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

Validar as credenciais e o papel do usuário

O iframe da visualização do estudante, o iframe de revisão do trabalho do estudante e o iframe da visualização do professor são destinados a apresentar conteúdo ao usuário, em vez de modificar uma atividade do Google Sala de Aula. Considere fazer o seguinte quando uma dessas visualizações for aberta:

  • Receber as credenciais OAuth do usuário.
  • Faça uma courseWork.getAddOnContext, courseWorkMaterials.getAddOnContext ou announcements.getAddOnContext solicitação com base no itemType para validar o papel do usuário.
  • Inspecione a resposta para ver se TeacherContext ou StudentContext estão presentes. Somente um pode ser retornado, correspondente ao papel 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. Os submissionIds correspondem aos iframes do complemento e são necessários para retornar notas e mostrar o trabalho do estudante aos professores na ferramenta de classificação.
  • Se o attachmentId já for conhecido pelo complemento, mostre a interface do anexo apropriada.
  • Caso contrário, esse anexo precisa ter sido copiado de outro item ou curso do stream. Consulte o guia Como lidar com conteúdo copiado para recomendações sobre esse cenário.

Detalhes do envio do estudante

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, você poderá usar 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 do estudante 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 courses.courseWork.addOnAttachments.studentSubmissions endpoint para recuperar ou modificar informações sobre um envio do estudante.

Detectar o estado de envio

Emita uma solicção GET para o courses.courseWork.addOnAttachments.studentSubmissions endpoint para receber 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 de envio 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 tiver devolvido o envio ao estudante.
  • RECLAIMED_BY_STUDENT, se o estudante tiver "cancelado o envio" do 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 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.
  • Restringir os privilégios de edição de envio. 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 não poderá editar o envio.

Notas e vários anexos

Somente um anexo de complemento pode ser usado para definir a nota de uma única atividade. Se um professor criar mais de um anexo do tipo atividade que forneça um valor maxPoints, apenas o primeiro anexo poderá definir a nota da atividade. Deixe o valor maxPoints não definido ou defina-o como zero para desativar o retorno de notas de um anexo.

Definir a nota de um envio

É possível modificar um envio do estudante enviando uma solicitação PATCH para o courses.courseWork.addOnAttachments.studentSubmissions endpoint. 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 de rascunho visível para o professor na interface do Google Sala de Aula. Os professores podem modificar a nota de rascunho antes de devolver a atividade aos estudantes. Consulte Visão geral da classificação na interface do Google Sala de Aula para detalhes sobre 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 ter sido o criador original do anexo.

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

Quando definir uma nota

Você tem algumas opções sobre quando uma nota é retornada ao Google Sala de Aula. A distinção fundamental é se você escolhe armazenar as credenciais do professor, já que apenas o professor pode modificar uma nota.

Há dois momentos de complemento em que você pode transmitir 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 do trabalho do estudante.

Se você quiser definir notas quando o estudante concluir o trabalho, armazene as credenciais off-line de um professor e, em seguida, 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 realizar nenhuma ação especial para que as notas sejam preenchidas na interface do Google Sala de Aula.
  • Fornecer insights em tempo real sobre a progressão de uma turma em uma atividade. Ao definir notas à medida que os estudantes concluem os anexos, os professores podem ter uma ideia da 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. Quando ele for enviado, defina a nota do envio usando as credenciais armazenadas.

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

Detectar mudanças nas notas das atividades

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

  • Alterar o valor dos pontos atribuídos.
  • Alterar o valor maxPoints de uma atividade.
  • Alterar se a atividade precisa ser classificada.

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

Se você tiver retornado uma nota ao 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. Considere verificar e, se necessário, atualizar esse valor se o produto permitir que os professores editem a pontuação de um estudante para uma atividade específica.