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

Neste guia, explicamos 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. Com a API Classroom, os desenvolvedores podem criar, modificar e ler 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

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 condições de configurar períodos de avaliação

As solicitações para o endpoint checkGradingPeriodsSetupEligibility 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 em um curso.

Pré-requisitos

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

  • Um projeto do Google Cloud. É possível configurar uma 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.

A lista GradingPeriods representa todos os períodos de avaliação individuais em um curso. É necessário especificar um título e uma data de início e de término para cada período de avaliação na lista. Cada período de avaliação em um curso precisa ter um título exclusivo, e as datas de início e término de períodos de avaliação diferentes não podem se sobrepor. Cada período de avaliação terá o próprio identificador atribuído pela API do Google Sala de Aula.

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. 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

Como a capacidade de criar e modificar períodos de avaliação no Google Sala de Aula está disponível apenas para usuários com uma licença específica, a API Classroom oferece o endpoint checkGradingPeriodsSetupEligibility para ajudar você a determinar proativamente se um usuário pode fazer solicitações para o endpoint UpdateGradingPeriodSettings.

Python

def check_grading_period_setup_eligibility(classroom, course_id):
    """Checks whether a user is able to create and modify grading periods in a course."""
    try:
        grading_period_eligibility_response = classroom.courses().checkGradingPeriodsSetupEligibility(
          courseId=course_id, previewVersion="V1_20240401_PREVIEW").execute()

        # Retrieve the isGradingPeriodsSetupEligible boolean from the response.
        # If the boolean is `True`, the user is able to modify grading period settings in the course.
        is_grading_periods_eligible = grading_period_eligibility_response.get("isGradingPeriodsSetupEligible")
        return is_grading_periods_eligible
    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 a licença necessária 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 a seguir, 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, 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.courses().updateGradingPeriodSettings(
          courseId=course_id,
          updateMask='gradingPeriods,applyToExistingCoursework',
          body=body,
          previewVersion="V1_20240401_PREVIEW"
        ).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, course_id):
    """Read grading periods settings in a course."""
    try:
        gradingPeriodSettings = classroom.courses().getGradingPeriodSettings(
          courseId=course_id, previewVersion="V1_20240401_PREVIEW").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 leitura-modificação-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 diferentes e que não haja sobreposição entre as datas de início e término dos períodos de avaliação.

Siga estas regras para atualizar a 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 mantidas 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 escolar e não serão removidos dele se applyToExistingCoursework for definido como Falso em solicitações subsequentes.

def add_grading_period(classroom, 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.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework',
          previewVersion="V1_20240401_PREVIEW").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 é persistente, o que significa que, se o booleano foi definido como True em uma chamada anterior da API e não foi alterado, as atualizações subsequentes dos períodos de avaliação serão aplicadas ao CourseWork 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 por todo o CourseWork, independente 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 que correspondem.

def update_existing_grading_period(classroom, 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.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework',
          previewVersion="V1_20240401_PREVIEW").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, independente da configuração applyToExistingCoursework.

Python

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

def delete_grading_period(classroom, 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.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods',
          previewVersion="V1_20240401_PREVIEW").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
  • sem associação ao período de avaliação

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

Ao criar um trabalho, 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 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: "").

O que vai acontecer 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 no updateMask 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.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId', # include the gradingPeriodId field in the updateMask
  previewVersion="V1_20240401_PREVIEW").execute()