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 Sala de Aula.

Visão geral

Os períodos de avaliação são criados para organizar deveres 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. Você também pode 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 configurados a todas as atividades.

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 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 de domínio ou professor.

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

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

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

As solicitações para o 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. Para configurar um, siga as instruções no Guia de início rápido do Python.
  • Adicione 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
  • 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ê precisa das credenciais de um professor para criar ou modificar atividades. Os administradores não podem criar nem modificar atividades 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.

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 corresponda a nenhum outro período 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 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 no momento da criação.

O booleano applyToExistingCoursework é uma configuração persistente que permite organizar atividades 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, a Sala de Aula vai definir automaticamente o gradingPeriodId em todos os trabalhos das turmas 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 no CourseWork, o Google Sala de Aula usará o courseWork.scheduledTime. Se nenhum dos campos estiver presente ou não houver correspondência entre as datas de início e término de um período de avaliação, o CourseWork não será associado a nenhum período.

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

A API Classroom fornece o endpoint userProfiles.checkUserCapability para ajudar você a determinar de forma proativa 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 pode modificar as configurações do período de avaliação em um curso, comece a emitir solicitações para o endpoint UpdateGradingPeriodSettings. Todas as modificações no recurso GradingPeriodSettings são feitas usando o endpoint UpdateGradingPeriodSettings, 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 é definido como True, o que modifica o gradingPeriodId em qualquer atividade que esteja entre as datas de início e término de um período de avaliação. 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

Os GradingPeriodSettings são lidos usando o endpoint GetGradingPeriodSettings. Qualquer usuário, independente 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. 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 ajuda 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.

Confira as 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. Os períodos de avaliação com um ID existente, mas dados modificados, são considerados edições. As propriedades não modificadas permanecem 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 se baseia 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. Os períodos de avaliação que já foram aplicados a atividades não serão removidos. No exemplo anterior, os períodos de avaliação "Semestre 1" e "Semestre 2" já foram aplicados às atividades do curso e não serão removidos se applyToExistingCoursework for 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. Isso significa que, se o booleano foi definido como True em uma chamada de API anterior e não foi alterado, as atualizações subsequentes nos períodos de avaliação serão aplicadas às atividades do curso atuais.

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 aos trabalhos escolares atuais. Nenhuma informação de período de avaliação aplicada a atividades em chamadas de API anteriores quando o booleano foi definido como True será removida. Uma maneira útil de pensar nessa configuração booleana é que ela permite associar atividades a períodos de avaliação configurados, mas não remover associações entre atividades e períodos de avaliação.

Se você excluir ou mudar o título de um período de avaliação, essas mudanças serão propagadas em todas as atividades do curso, 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 "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 no CourseWork atual. 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 aos trabalhos escolares atuais. Agora que esse campo booleano está definido como True, o período de avaliação "Verão" será aplicado a todos os itens do CourseWork 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 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_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 nas atividades

O recurso CourseWork inclui um campo gradingPeriodId. É possível usar os endpoints 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í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 atividades, você pode permitir que o Google Sala de Aula gerencie a associação de períodos de avaliação. Para fazer isso, omita o campo gradingPeriodId da solicitação CourseWork. Em seguida, especifique os campos dueDate ou scheduledTime na solicitação CourseWork. Se a dueDate estiver dentro de um intervalo de datas de período de avaliação, o Google Sala de Aula vai definir o ID desse 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 dos campos for especificado ou se não houver correspondência de intervalo de datas do período de avaliação, nenhum gradingPeriodId 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 daquele que se alinha com dueDate ou scheduledTime, é possível definir manualmente o campo gradingPeriodId ao criar ou atualizar o CourseWork. Se você definir manualmente o gradingPeriodId, o Google Sala de Aula não vai fazer 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 nenhum período de avaliação, inclua também 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 um período de avaliação definido para esse CourseWork. 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 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 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