Administra períodos de calificación con la API de Classroom

En esta guía, se explica cómo usar los extremos de períodos de calificación en la API de Google Classroom.

Descripción general

Los períodos de calificación se crean para organizar las tareas, los cuestionarios y los proyectos en períodos específicos. La API de Classroom permite que los desarrolladores creen, modifiquen y lean períodos de calificación en Classroom en nombre de los administradores y profesores. También puedes usar la API de Classroom para establecer períodos de calificación en CourseWork.

La API de Classroom ofrece dos endpoints para leer y escribir información sobre los períodos de calificación en un curso:

  • GetGradingPeriodSettings: Te permite leer la configuración del período de calificación en un curso.
  • UpdateGradingPeriodSettings: Te permite administrar la configuración de los períodos de calificación en un curso agregando, modificando y borrando períodos de calificación, y aplicando los períodos de calificación configurados a todos los elementos existentes de CourseWork.

Requisitos de licencias y elegibilidad

Cómo modificar la configuración de los períodos de calificación en un curso

Para crear, modificar o borrar períodos de calificación en un curso con el extremo de UpdateGradingPeriodSettings, se deben cumplir las siguientes condiciones:

Leer la configuración de los períodos de calificación de un curso

Los administradores del dominio y los profesores de un curso pueden leer la configuración del período de calificación, independientemente de la licencia que se les asigne. Esto significa que se permiten las solicitudes al extremo GetGradingPeriodSettings en nombre de cualquier administrador de dominio o profesor.

Establece un ID de período de calificación en CourseWork

Los profesores de un curso pueden incluir el gradingPeriodId cuando crean o actualizan CourseWork con la API, independientemente de la licencia que se les asigne.

Verifica la elegibilidad de un usuario para configurar períodos de calificación

Se permiten las solicitudes al extremo userProfiles.checkUserCapability en nombre de cualquier administrador o profesor. Se usa para determinar si el usuario puede modificar los períodos de calificación.

Requisitos previos

En esta guía, se proporcionan ejemplos de código en Python y se supone que tienes lo siguiente:

  • Un proyecto de Google Cloud, Puedes configurar uno siguiendo las instrucciones de la guía de inicio rápido de Python.
  • Se agregaron los siguientes permisos a la pantalla de consentimiento de OAuth de tu proyecto:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • ID de un curso en el que se deben modificar los períodos de calificación. El propietario del curso debe tener una licencia de Google Workspace for Education Plus.
  • Acceso a las credenciales de un profesor o administrador con una licencia de Google Workspace for Education Plus Necesitarás las credenciales de un profesor para crear o modificar CourseWork. Los administradores no pueden crear ni modificar CourseWork si no son profesores del curso.

Administra el recurso GradingPeriodSettings

El recurso GradingPeriodSettings incluye una lista de GradingPeriods individuales y un campo booleano llamado applyToExistingCoursework.

Asegúrate de que cada GradingPeriods individual de la lista cumpla con los siguientes requisitos:

  • Título, fecha de inicio y fecha de finalización: Cada período de calificación debe tener un título, una fecha de inicio y una fecha de finalización.
  • Título único: Cada período de calificación debe tener un título único que no coincida con ningún otro período de calificación del curso.
  • Fechas sin superposición: Cada período de calificación no debe tener fechas de inicio ni de finalización que se superpongan con otros períodos de calificación del curso.
  • Orden cronológico: Los períodos de calificación deben aparecer en orden cronológico según las fechas de inicio y finalización.

A cada período de calificación se le asignará un identificador de la API de Classroom en el momento de su creación.

El booleano applyToExistingCoursework es un parámetro de configuración persistente que te permite organizar los trabajos del curso creados anteriormente en períodos de calificación sin tener que realizar una llamada a la API independiente para modificar el gradingPeriodId de cada trabajo del curso. Si se establece en True, Classroom establecerá automáticamente el gradingPeriodId en todos los CourseWork existentes si el courseWork.dueDate se encuentra dentro de las fechas de inicio y finalización de un período de calificación existente. Si no se estableció una fecha de entrega en el curso, Classroom usará courseWork.scheduledTime. Si ninguno de los campos está presente o no hay coincidencias dentro de las fechas de inicio y finalización de un período de calificación existente, el objeto CourseWork no se asociará con ningún período de calificación.

Determina si un usuario puede modificar la configuración del período de calificación en un curso

La API de Classroom proporciona el extremo userProfiles.checkUserCapability para ayudarte a determinar de forma proactiva si un usuario puede realizar solicitudes al extremo 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

Cómo agregar períodos de calificación

Ahora que tienes la certeza de que el usuario es apto para modificar la configuración del período de calificación en un curso, puedes comenzar a enviar solicitudes al extremo UpdateGradingPeriodSettings. Todas las modificaciones en el recurso GradingPeriodSettings se realizan con el extremo UpdateGradingPeriodSettings, ya sea que agregues períodos de calificación individuales, modifiques períodos de calificación existentes o borres un período de calificación.

Python

En el siguiente ejemplo, se modifica el recurso gradingPeriodSettings para incluir dos períodos de calificación. El valor booleano applyToExistingCoursework se establece en True, lo que modificará el gradingPeriodId en cualquier CourseWork existente que se encuentre entre la fecha de inicio y la fecha de finalización de un período de calificación. Ten en cuenta que updateMask incluye ambos campos. Guarda los IDs de los períodos de calificación individuales una vez que se muestren en la respuesta. Deberás usar estos IDs para actualizar los períodos de calificación si es necesario.

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

Leer la configuración del período de calificación

Los GradingPeriodSettings se leen con el extremo GetGradingPeriodSettings. Cualquier usuario, independientemente de la licencia, puede leer la configuración de los períodos de calificación en un 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

Cómo agregar un período de calificación individual a la lista

Las actualizaciones de un período de calificación individual deben realizarse siguiendo un patrón de lectura-modificación-escritura. Esto significa que debes hacer lo siguiente:

  1. Lee la lista de períodos de calificación dentro del recurso GradingPeriodSettings con el extremo GetGradingPeriodSettings.
  2. Realiza las modificaciones elegidas en la lista de períodos de calificación.
  3. Envía la nueva lista de períodos de calificación en una solicitud a UpdateGradingPeriodSettings.

Este patrón te ayudará a garantizar que los títulos de los períodos de calificación individuales de un curso sean distintos y que no haya superposición entre las fechas de inicio y finalización de los períodos de calificación.

Ten en cuenta las siguientes reglas para actualizar la lista de períodos de calificación:

  1. Los períodos de calificación agregados a la lista sin un ID se consideran adiciones.
  2. Los períodos de calificación que faltan en la lista se consideran eliminaciones.
  3. Los períodos de calificación con un ID existente, pero con datos modificados, se consideran ediciones. Las propiedades sin modificar se dejan como están.
  4. Los períodos de calificación con IDs nuevos o desconocidos se consideran errores.

Python

El siguiente código se basará en el ejemplo de esta guía. Se crea un nuevo período de calificación con el título "Verano". El valor booleano applyToExistingCoursework se establece en False en el cuerpo de la solicitud.

Para ello, se lee el objeto GradingPeriodSettings actual, se agrega un nuevo período de calificación a la lista y se establece el valor booleano applyToExistingCoursework en False. Ten en cuenta que no se quitarán los períodos de calificación que ya se hayan aplicado a los CourseWork existentes. En el ejemplo anterior, los períodos de calificación "Semestre 1" y "Semestre 2" ya se aplicaron a CourseWork existente y no se quitarán de CourseWork si applyToExistingCoursework se establece en False en solicitudes posteriores.

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

Sugerencias útiles sobre el campo booleano applyToExistingCoursework

Es importante recordar que el valor booleano applyToExistingCoursework se conserva, lo que significa que, si se estableció en True en una llamada a la API anterior y no se cambió, las actualizaciones posteriores a los períodos de calificación se aplicarán al CourseWork existente.

Ten en cuenta que, si cambias este valor booleano de True a False en una solicitud a UpdateGradingPeriodSettings, solo los cambios nuevos que realices en GradingPeriodSettings no se aplicarán al CourseWork existente. No se quitará la información del período de calificación que se aplicó a CourseWork en llamadas a la API anteriores cuando el valor booleano se estableció en True. Una forma útil de pensar en este parámetro de configuración booleano es que admite la asociación de CourseWork existente con los períodos de calificación configurados, pero no admite la eliminación de asociaciones existentes entre CourseWork y los períodos de calificación configurados.

Si borras o cambias el título de un período de calificación, esos cambios se propagarán a todos los CourseWork existentes, independientemente del parámetro de configuración del valor booleano applyToExistingCoursework.

Actualiza un período de calificación individual en la lista

Para modificar algunos datos asociados con un período de calificación existente, incluye el ID del período de calificación existente en la lista con los datos modificados.

Python

En este ejemplo, se modificará la fecha de finalización del período de calificación "Verano". El campo applyToExistingCoursework se establecerá en True. Ten en cuenta que, si configuras este valor booleano como True, se aplicarán todos los períodos de calificación configurados en el CourseWork existente. En la solicitud anterior a la API, el valor booleano se estableció en False para que el período de calificación "Verano" no se aplicara a los CourseWork existentes. Ahora que este campo booleano está establecido en True, el período de calificación "Verano" se aplicará a todos los elementos de CourseWork existentes que coincidan.

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

Cómo borrar un período de calificación individual

Para borrar un período de calificación, omítelo de la lista. Ten en cuenta que, si se borra un período de calificación, también se borrará cualquier referencia a él en CourseWork, independientemente del parámetro de configuración de applyToExistingCoursework.

Python

Para continuar con el ejemplo de esta guía, omite el período de calificación, "Verano", para borrarlo.

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

Administra el campo gradingPeriodId en CourseWork

El recurso CourseWork incluye un campo gradingPeriodId. Puedes usar los extremos de CourseWork para leer y escribir el período de calificación asociado a un CourseWork. Existen tres formas de administrar esta asociación:

  • Asociación automática de períodos de calificación según la fecha
  • período de calificación asociado personalizado
  • No hay asociación de período de calificación

1. Asociación de períodos de calificación basados en la fecha

Cuando creas CourseWork, puedes permitir que Classroom controle la asociación del período de calificación por ti. Para ello, omite el campo gradingPeriodId de la solicitud CourseWork. Luego, especifica los campos dueDate o scheduledTime en la solicitud de CourseWork. Si el dueDate se encuentra dentro del rango de fechas de un período de calificación existente, Classroom establecerá el ID de ese período de calificación en el CourseWork. Si no se especifica el campo dueDate, Classroom determinará el gradingPeriodId en función del campo scheduledTime. Si no se especifica ninguno de los campos o no hay coincidencias en el período de calificación, no se establecerá ningún gradingPeriodId en CourseWork.

2. Período de calificación asociado personalizado

Si deseas asociar el CourseWork con un período de calificación diferente del que se alinea con dueDate o scheduledTime, puedes establecer manualmente el campo gradingPeriodId cuando crees o actualices el CourseWork. Si estableces el gradingPeriodId manualmente, Classroom no realizará la asociación automática del período de calificación según la fecha.

3. No hay asociación de período de calificación

Si no quieres que el elemento CourseWork se asocie con ningún período de calificación, establece el campo gradingPeriodId en la solicitud de CourseWork como una cadena vacía (gradingPeriodId: "").

Si usas el lenguaje de programación Go y no deseas establecer un período de calificación, también debes incluir el campo ForceSendFields en el cuerpo de la solicitud. Con la biblioteca cliente de Go, los valores predeterminados se omiten en las solicitudes de API debido a la presencia de la etiqueta de campo omitempty en todos los campos. El campo ForceSendFields omite este paso y envía la cadena vacía para indicar que no quieres establecer ningún período de calificación para ese CourseWork. Consulta la documentación de la biblioteca cliente de las APIs de Google para Go para obtener más información.

Go

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

¿Qué sucede con el ID del período de calificación si se actualiza la fecha límite?

Si actualizas el campo dueDate de CourseWork y deseas conservar una asociación personalizada o sin período de calificación, debes incluir dueDate y gradingPeriodId en updateMask y en el cuerpo de la solicitud. Esto le indicará a Classroom que no anule el gradingPeriodId con el período de calificación que coincida con el nuevo 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
Cómo establecer y actualizar las calificaciones
Siguiente
Limitaciones