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

En esta guía, se explica cómo usar los extremos de los 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 configurar períodos de calificación en CourseWork.

La API de Classroom ofrece dos extremos para leer y escribir información del período 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. Para ello, agrega, modifica y borra períodos de calificación, y aplica los períodos de calificación configurados a todos los trabajos del curso existentes.

Requisitos de licencias

Modifica la configuración del período de calificación en un curso

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

Cómo leer la configuración del período de calificación en un curso

Los administradores de dominios 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 las solicitudes al extremo GetGradingPeriodSettings están permitidas en nombre de cualquier administrador o profesor de dominio.

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

Los profesores de un curso pueden incluir gradingPeriodId cuando crean o actualizan trabajos 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 solicitudes al extremo checkGradingPeriodsSetupEligibility en nombre de cualquier administrador o profesor. Úsalo para determinar si el usuario puede modificar los períodos de calificación en un curso.

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.
  • Agregaste 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
  • Un 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.

La lista GradingPeriods representa todos los períodos de calificación individuales de un curso. Debes especificar un título, una fecha de inicio y una fecha de finalización para cada período de calificación individual de la lista. Cada período de calificación de un curso debe tener un título único, y las fechas de inicio y finalización de diferentes períodos de calificación no pueden superponerse. Cada período de calificación tendrá su propio identificador asignado por la API de Classroom.

El booleano applyToExistingCoursework es un parámetro de configuración persistente que te permite organizar CourseWork creado con anterioridad en períodos de calificación sin tener que hacer una llamada a la API separada para modificar el gradingPeriodId para cada CourseWork. Si se establece en True, Classroom establecerá automáticamente gradingPeriodId en todas las actividades de curso existentes si 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 límite en la tarea, Classroom usará courseWork.scheduledTime. Si ninguno de los campos está presente o si no hay una coincidencia entre las fechas de inicio y finalización de un período de calificación existente, 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 de un curso

Debido a que la capacidad de crear y modificar períodos de calificación en Classroom solo está disponible para los usuarios con una licencia específica, la API de Classroom providece el extremo checkGradingPeriodsSetupEligibility para ayudarte a determinar de forma proactiva si un usuario puede realizar solicitudes al extremo 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

Agrega períodos de calificación

Ahora que tienes la certeza de que el usuario tiene la licencia requerida para modificar la configuración del período de calificación en un curso, puedes comenzar a enviar solicitudes al extremo UpdateGradingPeriodSettings. Cualquier modificación en el recurso GradingPeriodSettings se realiza con el extremo UpdateGradingPeriodSettings, ya sea que agregues períodos de calificación individuales, modifiques los existentes o borres un período de calificación.

Python

En el siguiente ejemplo, el recurso gradingPeriodSettings se modifica para incluir dos períodos de calificación. El valor booleano applyToExistingCoursework se establece en True, lo que modificará el gradingPeriodId en cualquier trabajo del curso existente que se encuentre entre la fecha de inicio y la 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, 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

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

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

Agrega 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 y 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 asegurarte de que los títulos de los períodos de calificación individuales de un curso sean distintos y 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 que se agregan 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 no modificadas 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 GradingPeriodSettings actual, se agrega un nuevo período de calificación a la lista y el valor booleano applyToExistingCoursework se establece en False. Ten en cuenta que no se quitarán los períodos de calificación que ya se hayan aplicado a la carga académica existente. En el ejemplo anterior, los períodos de calificación “Semester 1” y “Semester 2” ya se aplicaron a CourseWork existente y no se quitarán de CourseWork si applyToExistingCoursework se establece como False en solicitudes posteriores.

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

Punteros útiles sobre el campo booleano applyToExistingCoursework

Es importante recordar que el valor booleano applyToExistingCoursework se conserva, lo que significa que, si se configuró en True en una llamada a la API anterior y no se cambió, las actualizaciones posteriores de los períodos de calificación se aplicarán a la carga de trabajo 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 a la tarea académica 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 configuró en True. Una forma útil de pensar en esta configuración booleana es que admite la asociación de CourseWork existente con los períodos de calificación configurados, pero no admite quitar las 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 todas las actividades de CourseWork existentes, independientemente de la configuración del valor booleano applyToExistingCoursework.

Cómo actualizar 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 trabajo de curso existente. En la solicitud anterior a la API, el valor booleano se estableció en False para que no se aplicara el período de calificación "Verano" a la carga académica existente. Ahora que este campo booleano se estableció en True, el período de calificación “Verano” se aplicará a todas las actividades de curso existentes que coincidan.

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

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 de la 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, 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

Administrar 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 con 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 del período de calificación basado en la fecha

Cuando creas CourseWork, puedes permitir que Classroom se encargue de 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 CourseWork. Si dueDate corresponde a un período de calificación existente, Classroom establecerá el ID de ese período de calificación en 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 si 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 CourseWork con un período de calificación diferente al que se alinea con dueDate o scheduledTime, puedes configurar manualmente el campo gradingPeriodId cuando crees o actualices CourseWork. Si configuras gradingPeriodId de forma manual, Classroom no realizará la asociación automática de períodos de calificación según la fecha.

3. Sin asociación de período de calificación

Si no quieres que CourseWork se asocie con ningún período de calificación, configura el campo gradingPeriodId en la solicitud de CourseWork como una cadena vacía (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 de período de calificación personalizada o sin una, debes incluir dueDate y gradingPeriodId en updateMask y 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 dueDate nuevo.

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()