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

Este guia explica como usar os endpoints dos 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 intervalos de datas 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 em tarefas.

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 de 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 configurados a todas as tarefas atuais.

Requisitos de licenciamento e qualificação

Modificar as configurações de 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 de período de avaliação, independentemente da licença atribuída a eles. Isso significa que as solicitações ao endpoint GetGradingPeriodSettings são permitidas em nome de qualquer administrador de domínio ou professor.

Definir um ID de período de avaliação em tarefas

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

Verificar a qualificação de um usuário 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 na nuvem do Google. É possível configurar um seguindo as instruções no guia de início rápido do Python.
  • Adicionado os seguintes escopos à tela de permissão OAuth do seu projeto:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • Um 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 tarefas. Os administradores não podem criar ou modificar tarefas 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 individual 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 corresponda a nenhum outro período de avaliação no 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 no 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 Classroom após a criação.

O booleano applyToExistingCoursework é uma configuração persistente que permite organizar tarefas criadas anteriormente em períodos de avaliação sem precisar fazer uma chamada de API separada para modificar o gradingPeriodId de cada tarefa. Se estiver definido como True, o Google Sala de Aula vai definir automaticamente o gradingPeriodId em todas as tarefas atuais 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 na tarefa, o Google Sala de Aula vai usar o courseWork.scheduledTime. Se nenhum dos campos estiver presente ou não houver correspondência nas datas de início e término de um período de avaliação, a tarefa não será associada a nenhum período de avaliação.

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

A API Classroom fornece o endpoint userProfiles.checkUserCapability para ajudar você a determinar proativamente se um usuário pode fazer solicitações ao 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 está qualificado para modificar as configurações de período de avaliação em um curso, comece a emitir solicitações para o endpoint UpdateGradingPeriodSettings. Todas as modificações no GradingPeriodSettings recurso são realizadas usando o UpdateGradingPeriodSettings endpoint, seja para adicionar períodos de avaliação individuais, modificar períodos de avaliação atuais 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 está definido como True, o que vai modificar o gradingPeriodId em qualquer tarefa atual que esteja entre a data de início e 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 de período de avaliação

GradingPeriodSettings são lidos usando o endpoint GetGradingPeriodSettings. Qualquer usuário, independentemente da licença, pode ler as configurações de 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-gravação. Isso significa que você deve:

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

Esse padrão vai ajudar a garantir que os títulos de períodos de avaliação individuais 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.

Tenha em mente as 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 adições.
  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 atual , mas dados modificados, são considerados edições. As propriedades não modificadas são deixadas no estado em que se encontram.
  4. Os 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 "Verão". O booleano applyToExistingCoursework está 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. Os períodos de avaliação que já foram aplicados às tarefas atuais não serão removidos. No exemplo anterior, os períodos de avaliação "Semestre 1" e "Semestre 2" já foram aplicados às tarefas atuais e não serão removidos das tarefas se applyToExistingCoursework estiver definido como "False" 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

Dicas ú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 de API anterior e não foi alterado, as atualizações subsequentes dos períodos de avaliação serão aplicadas às tarefas atuais.

Se você alterar 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 às tarefas atuais. As informações do período de avaliação aplicadas às tarefas em chamadas de API anteriores, quando o booleano estava definido como True, não serão removidas. Uma maneira útil de pensar nessa configuração booleana é que ela oferece suporte à associação de tarefas atuais aos períodos de avaliação configurados, mas não oferece suporte à remoção de associações atuais entre tarefas e períodos de avaliação configurados.

Se você excluir ou alterar o título de um período de avaliação, essas mudanças serão propagadas por todas as tarefas atuais, 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 atual, inclua o ID do período de avaliação atual 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. Definir esse booleano como True vai aplicar todos os períodos de avaliação configurados nas tarefas atuais. 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 às tarefas atuais. Agora que esse campo booleano está definido como True, o período de avaliação "Verão" será aplicado a todas as tarefas atuais 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 individual

Para excluir um período de avaliação, omita o período de avaliação da lista. Se um período de avaliação for excluído, qualquer referência ao período de avaliação na tarefa também será excluída, independentemente 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_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 em tarefas

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

  • associação automática de período 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 tarefas, você pode permitir que o Google Sala de Aula processe a associação de período de avaliação. Para fazer isso, omita o campo gradingPeriodId da solicitação de tarefa. Em seguida, especifique os campos dueDate ou scheduledTime na solicitação de tarefa. Se o dueDate estiver em um período de avaliação, o Google Sala de Aula vai definir o ID do período de avaliação na tarefa. Se o campo dueDate não for especificado, o Google Sala de Aula vai determinar o gradingPeriodId com base no campo scheduledTime. Se nenhum dos campos for especificado ou se não houver correspondência de período de avaliação, nenhum gradingPeriodId será definido na tarefa.

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

Se você quiser associar a tarefa a um período de avaliação diferente daquele que está alinhado ao dueDate ou scheduledTime, defina manualmente o campo gradingPeriodId ao criar ou atualizar a tarefa. Se você definir manualmente o gradingPeriodId, o Google Sala de Aula não vai realizar a associação automática de 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 a tarefa seja associada a nenhum período de avaliação, defina o campo gradingPeriodId na solicitação de tarefa como uma string vazia (gradingPeriodId: "").

Se você estiver usando a linguagem de programação Go e quiser definir nenhum período de avaliação, inclua também o campo ForceSendFields no corpo da solicitação. Com a biblioteca de cliente 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 nenhum período de avaliação definido para essa tarefa. Consulte a documentação da biblioteca de cliente Go das APIs do Google 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 da tarefa e quiser preservar uma associação personalizada ou sem período de avaliação, inclua o dueDate e o gradingPeriodId no updateMask e no corpo da solicitação. Isso vai informar ao Google Sala de Aula para não substituir o gradingPeriodId pelo 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
Avançar
Limitações