Gerenciar períodos de avaliação usando a API Classroom

Este guia explica como usar os endpoints de períodos de avaliação na API Google Classroom.

Visão geral

Os períodos de avaliação são criados para organizar trabalhos de casa, testes e projetos em períodos específicos. A API Classroom permite que os desenvolvedores criem, modifiquem e leiam os períodos de avaliação no Google Sala de Aula em nome de administradores e professores. Também é possível usar a API Classroom para definir períodos de avaliação no CourseWork.

A API Classroom oferece dois endpoints para ler e gravar informações de períodos de avaliação em um curso:

  • GetGradingPeriodSettings: permite ler as configurações do período de avaliação em um curso.
  • UpdateGradingPeriodSettings: permite gerenciar as configurações de período de avaliação em um curso adicionando, modificando e excluindo períodos de avaliação e aplicando os períodos de avaliação configurados a todas as atividades do CourseWork.

Requisitos de licenciamento e qualificação

Modificar as configurações do período de avaliação em um curso

Para criar, modificar ou excluir períodos de avaliação em um curso usando o endpoint UpdateGradingPeriodSettings, as seguintes condições precisam ser atendidas:

Ler as configurações de período de avaliação em um curso

Os administradores de domínio e os professores de um curso podem ler as configurações do período de avaliação, independentemente da licença atribuída a eles. Isso significa que as solicitações para o endpoint GetGradingPeriodSettings são permitidas em nome de qualquer administrador ou professor do domínio.

Definir um ID de período de avaliação no CourseWork

Os professores de um curso podem incluir o gradingPeriodId ao criar ou atualizar o CourseWork usando a API, independentemente da licença atribuída a eles.

Verificar se um usuário tem qualificação para configurar períodos de avaliação

As solicitações ao endpoint userProfiles.checkUserCapability são permitidas em nome de qualquer administrador ou professor. Use isso para determinar se o usuário pode modificar os períodos de avaliação.

Pré-requisitos

Este guia fornece exemplos de código em Python e pressupõe que você tenha:

  • Um projeto do Google Cloud. Você pode configurar um seguindo as instruções no Guia de início rápido do Python.
  • Adicionou os seguintes escopos à tela de consentimento do OAuth do seu projeto:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • O ID de um curso em que os períodos de avaliação precisam ser modificados. O proprietário do curso precisa ter uma licença do Google Workspace for Education Plus.
  • Acesso às credenciais de um professor ou administrador com uma licença do Google Workspace for Education Plus. Você vai precisar das credenciais de um professor para criar ou modificar o CourseWork. Os administradores não podem criar ou modificar o CourseWork se não forem professores no curso.

Gerenciar o recurso GradingPeriodSettings

O recurso GradingPeriodSettings inclui uma lista de GradingPeriods individuais e um campo booleano chamado applyToExistingCoursework.

Verifique se cada GradingPeriods na lista atende aos seguintes requisitos:

  • Título, data de início e data de término:cada período de avaliação precisa ter um título, uma data de início e uma data de término.
  • Título exclusivo:cada período de avaliação precisa ter um título exclusivo que não seja igual a nenhum outro período de avaliação do curso.
  • Datas não sobrepostas:cada período de avaliação não pode ter datas de início ou término que se sobreponham a outros períodos de avaliação do curso.
  • Ordem cronológica:os períodos de avaliação precisam ser listados em ordem cronológica com base nas datas de início e término.

Cada período de avaliação vai receber um identificador atribuído pela API do Google Sala de Aula na criação.

O booleano applyToExistingCoursework é uma configuração persistente que permite organizar atividades de curso criadas anteriormente em períodos de avaliação sem precisar fazer uma chamada de API separada para modificar o gradingPeriodId de cada atividade de curso. Se ele estiver definido como True, o Google Sala de Aula vai definir automaticamente o gradingPeriodId em todos os trabalhos do CourseWork se o courseWork.dueDate estiver dentro das datas de início e término de um período de avaliação. Se nenhuma data de entrega tiver sido definida no CourseWork, o Google Sala de Aula usará a courseWork.scheduledTime. Se nenhum campo estiver presente ou não houver correspondência nas datas de início e término de um período de avaliação, a atividade não será associada a nenhum período de avaliação.

Determinar se um usuário pode modificar as configurações do período de avaliação em um curso

A API Classroom oferece o endpoint userProfiles.checkUserCapability para ajudar você a determinar proativamente se um usuário pode fazer solicitações para o endpoint UpdateGradingPeriodSettings.

Python

def check_grading_periods_update_capability(classroom_service, course_id):
    """Checks whether a user is able to create and modify grading periods in a course."""
    try:
        capability = classroom_service.userProfiles().checkUserCapability(
          userId="me",
          capability="UPDATE_GRADING_PERIOD_SETTINGS",
           # Required while the checkUserCapability method is available in the Developer Preview Program.
          previewVersion="V1_20240930_PREVIEW"
        ).execute()

        # Retrieve the `allowed` boolean from the response.
        if capability.get("allowed"):
          print("User is allowed to update grading period settings in the course.")
        else:
          print("User is not allowed to update grading period settings in the course.")
    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Adicionar períodos de avaliação

Agora que você tem certeza de que o usuário tem qualificação para modificar as configurações do período de avaliação em um curso, é possível começar a emitir solicitações para o endpoint UpdateGradingPeriodSettings. Todas as modificações no recurso GradingPeriodSettings são realizadas usando o endpoint UpdateGradingPeriodSettings, seja para adicionar períodos de avaliação individuais, modificar períodos de avaliação existentes ou excluir um período de avaliação.

Python

No exemplo abaixo, o recurso gradingPeriodSettings é modificado para incluir dois períodos de avaliação. O booleano applyToExistingCoursework é definido como True, o que modifica o gradingPeriodId em qualquer atividade de curso existente que ocorra entre a data de início e a data de término de um período de avaliação. Observe que o updateMask inclui os dois campos. Salve os IDs dos períodos de avaliação individuais assim que eles forem retornados na resposta. Você vai precisar usar esses IDs para atualizar os períodos de avaliação, se necessário.

def create_grading_periods(classroom_service, course_id):
    """
    Create grading periods in a course and apply the grading periods
    to existing courseWork.
    """
    try:
        body = {
          "gradingPeriods": [
            {
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": True
        }
        gradingPeriodSettingsResponse = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id,
          updateMask='gradingPeriods,applyToExistingCoursework',
          body=body
        ).execute();

        print(f"Grading period settings updated.")
        return gradingPeriodSettingsResponse

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Ler as configurações do período de avaliação

GradingPeriodSettings são lidas usando o endpoint GetGradingPeriodSettings. Qualquer usuário, independente da licença, pode ler as configurações dos períodos de avaliação em um curso.

Python

def get_grading_period_settings(classroom_service, course_id):
    """Read grading periods settings in a course."""
    try:
        gradingPeriodSettings = classroom_service.courses().getGradingPeriodSettings(
          courseId=course_id).execute()
        return gradingPeriodSettings
    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Adicionar um período de avaliação individual à lista

As atualizações de um período de avaliação individual precisam ser feitas seguindo um padrão de leitura, modificação e gravação. Isso significa que você deve:

  1. Leia a lista de períodos de avaliação no recurso GradingPeriodSettings usando o endpoint GetGradingPeriodSettings.
  2. Faça as modificações escolhidas na lista de períodos de avaliação.
  3. Envie a nova lista de períodos de avaliação em uma solicitação para UpdateGradingPeriodSettings.

Esse padrão vai ajudar você a garantir que os títulos dos períodos de avaliação em um curso sejam distintos e que não haja sobreposição entre as datas de início e término dos períodos de avaliação.

Lembre-se das seguintes regras sobre a atualização da lista de períodos de avaliação:

  1. Os períodos de avaliação adicionados à lista sem um ID são considerados adicionais.
  2. Os períodos de avaliação ausentes na lista são considerados exclusões.
  3. Os períodos de avaliação com um ID existente, mas dados modificados, são considerados edições. As propriedades não modificadas são deixadas como estão.
  4. Períodos de avaliação com IDs novos ou desconhecidos são considerados erros.

Python

O código a seguir vai se basear no exemplo deste guia. Um novo período de avaliação é criado com o título "Summer". O booleano applyToExistingCoursework é definido como False no corpo da solicitação.

Para fazer isso, a GradingPeriodSettings atual é lida, um novo período de avaliação é adicionado à lista e o booleano applyToExistingCoursework é definido como False. Os períodos de avaliação que já foram aplicados ao CourseWork não serão removidos. No exemplo anterior, os períodos de avaliação "Semestre 1" e "Semestre 2" já foram aplicados ao trabalho acadêmico e não serão removidos dele se applyToExistingCoursework for definido como falso em solicitações subsequentes.

def add_grading_period(classroom_service, course_id):
    """
    A new grading period is added to the list, but it is not applied to existing courseWork.
    """
    try:
        # Use the `GetGradingPeriodSettings` endpoint to retrieve the existing
        # grading period IDs. You will need to include these IDs in the request
        # body to make sure existing grading periods aren't deleted.
        body = {
          "gradingPeriods": [
            {
              # Specify the ID to make sure the grading period is not deleted.
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              # Specify the ID to make sure the grading period is not deleted.
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            },
            {
              # Does not include an ID because this grading period is an addition.
              "title": "Summer",
              "start_date": {
                "day": 1,
                "month": 6,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 8,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": False
        }

        gradingPeriodSettings = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Orientações úteis sobre o campo booleano applyToExistingCoursework

É importante lembrar que o booleano applyToExistingCoursework é permanecido, o que significa que, se o booleano foi definido como True em uma chamada anterior de API e não foi alterado, as atualizações subsequentes dos períodos de avaliação serão aplicadas ao curso atual.

Se você mudar esse valor booleano de True para False em uma solicitação para UpdateGradingPeriodSettings, apenas as novas mudanças feitas em GradingPeriodSettings não serão aplicadas ao CourseWork. Todas as informações de período de avaliação aplicadas ao CourseWork em chamadas de API anteriores, quando o booleano foi definido como True, não serão removidas. Uma maneira útil de pensar sobre essa configuração booleana é que ela permite associar o CourseWork aos períodos de avaliação configurados, mas não permite remover as associações entre o CourseWork e os períodos de avaliação configurados.

Se você excluir ou mudar o título de um período de avaliação, essas mudanças serão propagadas em todos os trabalhos do CourseWork, independentemente da configuração do booleano applyToExistingCoursework.

Atualizar um período de avaliação individual na lista

Para modificar alguns dados associados a um período de avaliação, inclua o ID do período de avaliação na lista com os dados modificados.

Python

Neste exemplo, a data de término do período de avaliação "Summer" será modificada. O campo applyToExistingCoursework será definido como True. Observação: definir esse booleano como True vai aplicar todos os períodos de avaliação configurados no CourseWork. Na solicitação de API anterior, o booleano foi definido como False para que o período de avaliação "Summer" não fosse aplicado ao curso on-line existente. Agora que esse campo booleano está definido como True, o período de avaliação "Summer" será aplicado a todos os trabalhos do curso correspondentes.

def update_existing_grading_period(classroom_service, course_id):
    """
    An existing grading period is updated.
    """
    try:
        # Use the `GetGradingPeriodSettings` endpoint to retrieve the existing
        # grading period IDs. You will need to include these IDs in the request
        # body to make sure existing grading periods aren't deleted.
        body = {
          "gradingPeriods": [
            {
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            },
            {
              # The end date for this grading period will be modified from August 31, 2024 to September 10, 2024.
              # Include the grading period ID in the request along with the new data.
              "id": "SUMMER_GRADING_PERIOD_ID",
              "title": "Summer",
              "start_date": {
                "day": 1,
                "month": 6,
                "year": 2024
              },
              "end_date": {
                "day": 10,
                "month": 9,
                "year": 2024
              }
            }
          ],
          "applyToExistingCoursework": True
        }

        gradingPeriodSettings = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Excluir um período de avaliação

Para excluir um período de avaliação, omita-o da lista. Se um período de avaliação for excluído, qualquer referência a ele no CourseWork também será excluída, independentemente da configuração applyToExistingCoursework.

Python

Para continuar o exemplo neste guia, omita o período de avaliação, "Summer", para excluí-lo.

def delete_grading_period(classroom_service, course_id):
    """
    An existing grading period is deleted.
    """
    try:
        body = {
          "gradingPeriods": [
            {
              "id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
              "title": "First Semester",
              "start_date": {
                "day": 1,
                "month": 9,
                "year": 2023
              },
              "end_date": {
                "day": 15,
                "month": 12,
                "year": 2023
              }
            },
            {
              "id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
              "title": "Second Semester",
              "start_date": {
                "day": 15,
                "month": 1,
                "year": 2024
              },
              "end_date": {
                "day": 31,
                "month": 5,
                "year": 2024
              }
            }
          ]
        }

        gradingPeriodSettings = classroom_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods').execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Gerenciar o campo gradingPeriodId no CourseWork

O recurso CourseWork inclui um campo gradingPeriodId. É possível usar os endpoints do CourseWork para ler e gravar o período de avaliação associado a um CourseWork. Há três maneiras de gerenciar essa associação:

  • associação automática de períodos de avaliação com base na data
  • período de avaliação associado personalizado
  • nenhuma associação de período de avaliação

1. Associação de período de avaliação com base na data

Ao criar uma atividade, você pode permitir que o Google Sala de Aula gerencie a associação do período de avaliação. Para fazer isso, omita o campo gradingPeriodId da solicitação do CourseWork. Em seguida, especifique os campos dueDate ou scheduledTime na solicitação do CourseWork. Se o dueDate estiver em um período de avaliação existente, o Google Sala de Aula vai definir esse ID de período de avaliação na atividade. Se o campo dueDate não for especificado, o Google Sala de Aula vai determinar o gradingPeriodId com base no campo scheduledTime. Se nenhum campo for especificado ou se não houver correspondência no período de avaliação, o gradingPeriodId não será definido no CourseWork.

2. Período de avaliação associado personalizado

Se você quiser associar o CourseWork a um período de avaliação diferente do que aquele alinhado com o dueDate ou scheduledTime, defina manualmente o campo gradingPeriodId ao criar ou atualizar o CourseWork. Se você definir o gradingPeriodId manualmente, o Google Sala de Aula não vai realizar a associação automática do período de avaliação com base na data.

3. Nenhuma associação de período de avaliação

Se você não quiser que o CourseWork seja associado a nenhum período de avaliação, defina o campo gradingPeriodId na solicitação do CourseWork como uma string vazia (gradingPeriodId: "").

Se você estiver usando a linguagem de programação Go e quiser definir um período sem avaliação, também inclua o campo ForceSendFields no corpo da solicitação. Com a biblioteca de cliente do Go, os valores padrão são omitidos das solicitações de API devido à presença da tag de campo omitempty em todos os campos. O campo ForceSendFields ignora isso e envia a string vazia para indicar que você não quer que nenhum período de avaliação seja definido para esse trabalho. Consulte a documentação da biblioteca de cliente das APIs Google Go para mais informações.

Go

courseWork := &classroom.CourseWork{
  Title: "Homework questions",
  WorkType: "ASSIGNMENT",
  State: "DRAFT",
  // ...other CourseWork fields...
  GradingPeriodId: "",
  ForceSendFields: []string{"GradingPeriodId"},
}

O que acontece com o ID do período de avaliação se a data de entrega for atualizada?

Se você estiver atualizando o campo dueDate do CourseWork e quiser preservar uma associação personalizada ou sem período de avaliação, inclua dueDate e gradingPeriodId na máscara de atualização e no corpo da solicitação. Isso vai informar ao Google Sala de Aula para não substituir o gradingPeriodId com o período de avaliação que corresponde ao novo dueDate.

Python

body = {
  "dueDate": {
    "month": 6,
    "day": 10,
    "year": 2024
  },
  "dueTime": {
    "hours": 7
  },
  "gradingPeriodId": "<INSERT-GRADING-PERIOD-ID-OR-EMPTY-STRING>"
}
courseWork = classroom_service.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId') # include the gradingPeriodId field in the updateMask
.execute()
Anterior
Definir e atualizar notas
Próxima
Limitações