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

Neste guia, explicamos como usar os endpoints dos períodos de avaliação na API Google Classroom.

Visão geral

Períodos de avaliação são criados para organizar dever 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 do período 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 do período de avaliação em um curso adicionando, modificando e excluindo esses períodos e aplicando os períodos configurados a todos os trabalhos atuais.

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 do período de avaliação em um curso

Os administradores do 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. Isso significa que as solicitações para o endpoint GetGradingPeriodSettings são permitidas em nome de qualquer administrador ou professor do domínio.

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

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

Verificar se um usuário pode 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 fornece 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.
  • Os seguintes escopos foram adicionados à tela de permissão OAuth do seu projeto:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • 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 do professor para criar ou modificar o CourseWork. Os administradores não podem criar nem modificar o CourseWork se não forem professores do curso.

Gerenciar o recurso GradingPeriodSettings

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

A lista de 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 dos períodos diferentes não podem se sobrepor. Cada período de avaliação terá um identificador atribuído pela API Classroom.

O booleano applyToExistingCoursework é uma configuração persistente que permite organizar trabalhos criados anteriormente em períodos de avaliação sem precisar fazer uma chamada de API separada para modificar o gradingPeriodId de cada curso. Se ele for definido como True, o Google Sala de Aula vai definir automaticamente a gradingPeriodId em todos os CourseWorks se o courseWork.dueDate se enquadrar nas datas de início e término de um período de avaliação. Se nenhuma data de entrega tiver sido definida, o Google Sala de Aula vai usar 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 atual, o CourseWork não será associado 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 fornece 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, comece a enviar solicitações para o endpoint UpdateGradingPeriodSettings. Qualquer modificação no recurso GradingPeriodSettings será realizada usando o endpoint UpdateGradingPeriodSettings, esteja você adicionando períodos de avaliação individuais, modificando os atuais ou excluindo um período.

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 vai modificar o gradingPeriodId em qualquer CourseWork existente entre as datas de início e término de um período de avaliação. Observe que 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 dos 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 ajudará a garantir que os títulos individuais do período de avaliação em um curso sejam distintos e 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 adições.
  2. Os períodos de avaliação ausentes na lista são considerados exclusões.
  3. Períodos de avaliação com um ID atual, mas com dados modificados, são considerados edições. As propriedades não modificadas são deixadas como estão.
  4. Os períodos de avaliação com IDs novos ou desconhecidos são considerados erros.

Python

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

Para fazer isso, o GradingPeriodSettings atual é lido, um novo período de avaliação é adicionado à lista e o booleano applyToExistingCoursework é definido como False. Observe que os períodos de avaliação que já foram aplicados a um curso não serão removidos. No exemplo anterior, os períodos de avaliação do "Semester 1" e "Semester 2" já foram aplicados ao CourseWork e não serão removidos do CourseWork se applyToExistingCoursework for definido como "False" nas 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

Ponteiros úteis sobre o campo booleano applyToExistingCoursework

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

Se você mudar esse valor booleano de True para False em uma solicitação para UpdateGradingPeriodSettings, somente as novas mudanças em GradingPeriodSettings não serão aplicadas ao CourseWork. As informações do período de avaliação aplicadas ao CourseWork em chamadas de API anteriores quando o booleano era definido como True não serão removidas. Uma maneira útil de pensar sobre essa configuração booleana é que ela oferece suporte à associação do CourseWork atual aos períodos de avaliação configurados, mas não da remoção de associações atuais 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 específico na lista

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

Python

Neste exemplo, a data de término do período de avaliação "Verão" será modificada. O campo applyToExistingCoursework será definido como True. Ao definir esse booleano como True, todos os períodos de avaliação configurados serão aplicados aos cursos existentes. Na solicitação de API anterior, o booleano foi definido como False para que o período de avaliação "Verão" não fosse aplicado ao Cursos existentes. Agora que esse campo booleano está definido como True, o período de avaliação "Verão" será aplicado a todos os cursos existentes correspondentes.

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 específico

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 o exemplo neste guia, omita o período de avaliação, "Verão", 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. Você pode 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 do período 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 do período de avaliação com base na data

Ao criar o curso, você pode permitir que o Google Sala de Aula processe a associação do período de avaliação para você. 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 fizer parte de um período de avaliação atual, o Google Sala de Aula vai definir o ID desse período no CourseWork. 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 de período do período de avaliação, nenhum gradingPeriodId vai ser definido no CourseWork.

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

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

3. Sem associação ao 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 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 de período de avaliação personalizada ou nenhuma, inclua dueDate e gradingPeriodId no updateMask e no corpo da solicitação. Isso fará com que o Google Sala de Aula não substitua gradingPeriodId pelo período de avaliação correspondente 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()