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 de un curso.
• UpdateGradingPeriodSettings: Te permite administrar la configuración de los períodos de calificación en un curso, ya que puedes agregar, modificar y borrar períodos de calificación, y aplicar los períodos de calificación configurados a todos los trabajos de curso existentes.

Requisitos de licencias

Cómo modificar la configuración del período de calificación de 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:

• El usuario que realiza la solicitud tiene asignada una licencia de Google Workspace for Education Plus.
• El propietario del curso tiene asignada una licencia de Google Workspace for Education Plus.

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

Los administradores de dominio y los profesores de un curso pueden leer la configuración de los períodos de calificación sin importar la licencia que tengan asignada. Esto significa que las solicitudes al extremo GetGradingPeriodSettings se permiten en nombre de cualquier administrador o profesor de dominio.

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

Los profesores de un curso pueden incluir gradingPeriodId cuando crean o actualizan CourseWork con la API, independientemente de la licencia que tengan asignada.

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

Las solicitudes al extremo checkGradingPeriodsSetupEligibility se permiten en nombre de cualquier administrador o profesor. Úsalo para determinar si el usuario puede modificar los períodos de calificación de un curso.

Requisitos previos

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

• Un proyecto de Google Cloud, Para configurar una, sigue 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
• 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 está configurado como True, Classroom establecerá automáticamente el gradingPeriodId en todos los CourseWork 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 CourseWork, Classroom usará el courseWork.scheduledTime. Si no hay ninguno de los campos o 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

Dado que la capacidad de crear y modificar períodos de calificación en Classroom solo está disponible para los usuarios que tienen una licencia específica, la API de Classroom proporciona 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

Agregar períodos de calificación

Ahora que te aseguraste de que el usuario tiene la licencia necesaria para modificar la configuración del período de calificación en un curso, puedes comenzar a emitir 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 de cualquier CourseWork existente que se encuentre entre las fechas de inicio y 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

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

Las 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 según 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 en el recurso GradingPeriodSettings con el extremo GetGradingPeriodSettings.
2. Realiza las modificaciones que elijas en la lista de períodos de calificación.
3. Envía la lista nueva de períodos de calificación en una solicitud a UpdateGradingPeriodSettings.

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

Ten en cuenta las siguientes reglas sobre la actualización de 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 mantienen como están.
4. Los períodos de calificación con IDs nuevos o desconocidos se consideran errores.

Importante: Asegúrate de incluir los IDs de los períodos de calificación que no quieras borrar en la solicitud UpdateGradingPeriodSettings.

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 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á ningún período de calificación que ya se haya aplicado a los trabajos de curso existentes. En el ejemplo anterior, los períodos de calificación de “semestre 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 booleano applyToExistingCoursework es persiste, lo que significa que, si el booleano se configuró como True en una llamada a la API anterior y no se modificó, las actualizaciones posteriores de los períodos de calificación se aplicarán a los CourseWork existentes.

Ten en cuenta que, si cambias este valor booleano de True a False en una solicitud a UpdateGradingPeriodSettings, solo los cambios nuevos que hagas en GradingPeriodSettings no se aplicarán a CourseWork existente. No se quitará la información del período de calificación aplicada 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 tus 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 través de todos los CourseWork existentes, independientemente de la configuración del booleano applyToExistingCoursework.

Importante: Si configuras el campo applyToExistingCoursework como False, no se quitará ningún período de calificación ni asociaciones de CourseWork preexistentes. Si borras o cambias el título de un período de calificación, se propagará por todo CourseWork, independientemente del parámetro de configuración applyToExistingCoursework.

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

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

Python

En este ejemplo, se modificará la fecha de finalización del período de calificación de “Verano”. El campo applyToExistingCoursework se establecerá en True. Ten en cuenta que configurar este valor booleano en True aplicará todos los períodos de calificación configurados en los CourseWork existentes. En la solicitud a la API anterior, el valor booleano se estableció en False, por lo que el período de calificación de “Verano” no se aplicó a CourseWork existente. Ahora que este campo booleano se configuró como True, el período de calificación “Verano” se aplicará a todos los CourseWork 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 al período de calificación en CourseWork, sin importar el 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, 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 basados en fechas
• período de calificación personalizado asociado
• sin asociación con el 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 una coincidencia de período de 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 al que se alinea con dueDate o scheduledTime, puedes configurar el campo gradingPeriodId de forma manual cuando crees o actualices CourseWork. Si configuras gradingPeriodId de forma manual, Classroom no realizará la asociación automática del período de calificación basado en la fecha.

3. Sin asociación con el 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 CourseWork como una string vacía (gradingPeriodId: "").

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

Si estás actualizando el campo dueDate de CourseWork y quieres conservar una asociación de período de calificación personalizado o nulo, debes incluir la dueDate y la gradingPeriodId en el cuerpo de la solicitud y updateMask. 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.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()

Importante: Cuando actualices el campo dueDate de un CourseWork, incluye el campo gradingPeriodId en updateMask y el cuerpo de la solicitud para conservar una asociación personalizada o ninguna. Esto garantizará que Classroom no anule el campo gradingPeriodId por uno que coincida con el nuevo dueDate.