Gérer les périodes de notation à l'aide de l'API Classroom

Ce guide explique comment utiliser les points de terminaison des périodes de notation dans l'API Google Classroom.

Présentation

Les périodes de notation sont créées pour organiser les devoirs, les questionnaires et les projets dans des plages de dates spécifiques. L'API Classroom permet aux développeurs de créer, modifier et lire des périodes de notation dans Classroom pour le compte d'administrateurs et d'enseignants. Vous pouvez aussi utiliser l'API Classroom pour définir des périodes de notation sur CourseWork.

L'API Classroom propose deux points de terminaison pour lire et écrire les informations sur la période de notation d'un cours:

  • GetGradingPeriodSettings: permet de lire les paramètres de période de notation dans un cours.
  • UpdateGradingPeriodSettings: permet de gérer les paramètres des périodes de notation d'un cours en ajoutant, en modifiant et en supprimant des périodes de notation, et en appliquant les périodes de notation configurées à tous les CourseWork existants.

Exigences concernant les licences

Modifier les paramètres de la période de notation d'un cours

Pour créer, modifier ou supprimer des périodes de notation dans un cours à l'aide du point de terminaison UpdateGradingPeriodSettings, les conditions suivantes doivent être remplies:

Lire les paramètres de période de notation d'un cours

Les administrateurs de domaine et les enseignants d'un cours peuvent lire les paramètres de période de notation, quelle que soit la licence qui leur est attribuée. Cela signifie que les requêtes adressées au point de terminaison GetGradingPeriodSettings sont autorisées pour le compte de tout administrateur ou enseignant de domaine.

Définir un ID de période de notation pour CourseWork

Les enseignants d'un cours peuvent inclure le gradingPeriodId lors de la création ou de la mise à jour de CourseWork à l'aide de l'API, quelle que soit la licence qui leur est attribuée.

Vérifier si un utilisateur peut configurer des périodes de notation

Les requêtes envoyées au point de terminaison checkGradingPeriodsSetupEligibility sont autorisées pour le compte de tout administrateur ou enseignant. Utilisez-le pour déterminer si l'utilisateur peut modifier les périodes de notation d'un cours.

Conditions préalables

Ce guide fournit des exemples de code en Python et suppose que vous avez:

  • Un projet Google Cloud. Vous pouvez en configurer un en suivant les instructions du guide de démarrage rapide pour Python.
  • Ajout des champs d'application suivants à l'écran de consentement OAuth de votre projet :
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • ID d'un cours dans lequel les périodes de notation doivent être modifiées. Le propriétaire du cours doit disposer d'une licence Google Workspace for Education Plus.
  • Accès aux identifiants d'un enseignant ou d'un administrateur disposant d'une licence Google Workspace for Education Plus Vous aurez besoin des identifiants d'un enseignant pour créer ou modifier CourseWork. Les administrateurs ne peuvent pas créer ni modifier CourseWork s'ils ne sont pas enseignants du cours.

Gérer la ressource GradingPeriodSettings

La ressource GradingPeriodSettings comprend une liste de valeurs GradingPeriods individuelles et un champ booléen appelé applyToExistingCoursework.

La liste GradingPeriods représente toutes les périodes de notation individuelles d'un cours. Vous devez spécifier un titre, une date de début et une date de fin pour chaque période de notation de la liste. Chaque période de notation d'un cours doit avoir un titre unique. Les dates de début et de fin de différentes périodes de notation ne peuvent pas se chevaucher. Chaque période de notation sera associée à un identifiant attribué par l'API Classroom.

La valeur booléenne applyToExistingCoursework est un paramètre persistant qui vous permet d'organiser les CourseWork précédemment créés en périodes de notation sans avoir à effectuer un appel d'API distinct pour modifier le gradingPeriodId de chaque CourseWork. S'il est défini sur True, Classroom définit automatiquement la gradingPeriodId de tous les CourseWork existants si l'courseWork.dueDate se situe dans les dates de début et de fin d'une période de notation existante. Si aucune date limite n'a été définie pour le CourseWork, Classroom utilise le courseWork.scheduledTime. Si aucun champ n'est présent ou qu'il n'y a aucune correspondance dans les dates de début et de fin d'une période de notation existante, CourseWork ne sera associé à aucune période de notation.

Déterminer si un utilisateur peut modifier les paramètres de la période de notation d'un cours

Étant donné que seuls les utilisateurs disposant d'une licence spécifique peuvent créer et modifier des périodes de notation dans Classroom, l'API Classroom fournit le point de terminaison checkGradingPeriodsSetupEligibility pour vous aider à déterminer de manière proactive si un utilisateur peut envoyer des requêtes au point de terminaison 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

Ajouter des périodes de notation

Maintenant que vous êtes certain que l'utilisateur dispose de la licence nécessaire pour modifier les paramètres de période de notation d'un cours, vous pouvez commencer à envoyer des requêtes au point de terminaison UpdateGradingPeriodSettings. Toutes les modifications apportées à la ressource GradingPeriodSettings sont effectuées à l'aide du point de terminaison UpdateGradingPeriodSettings, que vous souhaitiez ajouter des périodes de notation individuelles, modifier des périodes de notation existantes ou supprimer une période de notation.

Python

Dans l'exemple suivant, la ressource gradingPeriodSettings est modifiée pour inclure deux périodes de notation. La valeur booléenne applyToExistingCoursework est définie sur True, ce qui modifie le gradingPeriodId de tout CourseWork existant compris entre les dates de début et de fin d'une période de notation. Notez que updateMask inclut les deux champs. Enregistrez les ID des périodes de notation individuelles une fois qu'ils ont été renvoyés dans la réponse. Vous devrez utiliser ces ID pour mettre à jour les périodes de notation si nécessaire.

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

Lire les paramètres de la période de notation

Les GradingPeriodSettings sont lues à l'aide du point de terminaison GetGradingPeriodSettings. Tous les utilisateurs, quelle que soit leur licence, peuvent consulter les paramètres des périodes de notation d'un cours.

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

Ajouter une période de notation individuelle à la liste

Les mises à jour d'une période de notation individuelle doivent être effectuées en suivant un modèle lecture-modification-écriture. Ce que cela implique pour vous :

  1. Lisez la liste des périodes de notation dans la ressource GradingPeriodSettings à l'aide du point de terminaison GetGradingPeriodSettings.
  2. Apportez les modifications souhaitées à la liste des périodes de notation.
  3. Envoyez la nouvelle liste des périodes de notation dans une requête à UpdateGradingPeriodSettings.

Ce modèle vous aidera à vous assurer que les titres des périodes de notation individuelles d'un cours sont distincts, et qu'il n'y a pas de chevauchement entre les dates de début et de fin des périodes de notation.

Tenez compte des règles suivantes concernant la mise à jour de la liste des périodes de notation:

  1. Les périodes de notation ajoutées à la liste sans ID sont considérées comme des ajouts.
  2. Les périodes de notation manquantes dans la liste sont considérées comme des suppressions.
  3. Les périodes de notation avec un ID existant, mais des données modifiées, sont considérées comme des modifications. Les propriétés non modifiées sont laissées telles quelles.
  4. Les périodes de notation associées à des identifiants nouveaux ou inconnus sont considérées comme des erreurs.

Python

Le code suivant s'appuie sur l'exemple de ce guide. Une période de notation est créée avec le titre "Été". La valeur booléenne applyToExistingCoursework est définie sur False dans le corps de la requête.

Pour ce faire, la valeur GradingPeriodSettings actuelle est lue, une nouvelle période de notation est ajoutée à la liste et la valeur booléenne applyToExistingCoursework est définie sur False. Notez que les périodes de notation déjà appliquées à un cours CourseWork existant ne seront pas supprimées. Dans l'exemple précédent, les périodes de notation "Semestre 1" et "Semester 2" ont déjà été appliquées à un cours CourseWork existant et ne seront pas supprimés de CourseWork si applyToExistingCoursework est défini sur "False" dans les requêtes suivantes.

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

Pointeurs utiles concernant le champ booléen applyToExistingCoursework

Il est important de se rappeler que la valeur booléenne applyToExistingCoursework est persistée, ce qui signifie que si la valeur booléenne a été définie sur True dans un appel d'API précédent et qu'elle n'a pas été modifiée, les mises à jour ultérieures des périodes de notation seront appliquées à CourseWork existant.

Notez que si vous remplacez cette valeur booléenne True par False dans une requête pour UpdateGradingPeriodSettings, seules les nouvelles modifications que vous apportez à GradingPeriodSettings ne seront pas appliquées au CourseWork existant. Toutes les informations sur la période de notation appliquées à CourseWork dans les appels d'API précédents lorsque la valeur booléenne était définie sur True ne sont pas supprimées. Ce paramètre booléen est compatible avec l'association de CourseWork existant à vos périodes de notation configurées, mais il ne permet pas de supprimer les associations existantes entre CourseWork et les périodes de notation configurées.

Si vous supprimez ou modifiez le titre d'une période de notation, ces modifications seront appliquées à tous les CourseWork existants, quel que soit le paramètre de la valeur booléenne applyToExistingCoursework.

Modifier une période de notation individuelle dans la liste

Pour modifier certaines données associées à une période de notation existante, incluez l'ID de cette période dans la liste avec les données modifiées.

Python

Dans cet exemple, la date de fin de la période de notation "Été" sera modifiée. Le champ applyToExistingCoursework sera défini sur True. Notez que si vous définissez cette valeur booléenne sur True, toutes les périodes de notation configurées seront appliquées au CourseWork existant. Dans la requête API précédente, la valeur booléenne était définie sur False afin que la période de notation "Summer" (Été) ne soit pas appliquée à un CourseWork existant. Maintenant que ce champ booléen est défini sur True, la période de notation "Summer" (Été) sera appliquée à tous les CourseWork existants qui correspondent.

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

Supprimer une période de notation individuelle

Pour supprimer une période de notation, omettez-la dans la liste. Notez que si une période de notation est supprimée, toute référence à cette période sur CourseWork sera également supprimée, quel que soit le paramètre applyToExistingCoursework.

Python

Pour poursuivre l'exemple de ce guide, omettez la période de notation "Été" afin de la supprimer.

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

Gérer le champ gradingPeriodId dans CourseWork

La ressource CourseWork inclut un champ gradingPeriodId. Vous pouvez utiliser les points de terminaison CourseWork pour lire et écrire la période de notation associée à un CourseWork. Vous pouvez gérer cette association de trois façons:

  • association automatique de périodes de notation basées sur la date
  • période de notation personnalisée associée
  • aucune association à la période de notation

1. Association d'une période de notation basée sur la date

Lorsque vous créez CourseWork, vous pouvez autoriser Classroom à gérer l'association de la période de notation à votre place. Pour ce faire, omettez le champ gradingPeriodId de la requête CourseWork. Spécifiez ensuite les champs dueDate ou scheduledTime dans la requête CourseWork. Si l'dueDate correspond à une période de période de notation existante, Classroom définira cet ID de période de notation pour le cours CourseWork. Si le champ dueDate n'est pas spécifié, Classroom détermine la valeur gradingPeriodId en fonction du champ scheduledTime. Si aucun champ n'est spécifié ou si aucune plage de dates de la période de notation ne correspond, aucun champ gradingPeriodId n'est défini sur le CourseWork.

2. Période de notation personnalisée associée

Si vous souhaitez associer le CourseWork à une période de notation différente de celle qui correspond à dueDate ou scheduledTime, vous pouvez définir manuellement le champ gradingPeriodId lors de la création ou de la mise à jour de CourseWork. Si vous définissez manuellement gradingPeriodId, Classroom n'associera pas automatiquement la période de notation en fonction de la date.

3. Aucune association à la période de notation

Si vous ne souhaitez pas que CourseWork soit associé à une période de notation, définissez le champ gradingPeriodId de la requête CourseWork sur une chaîne vide (gradingPeriodId: "").

Qu'advient-il de l'ID de la période de notation si la date limite est modifiée ?

Si vous mettez à jour le champ dueDate de CourseWork et que vous souhaitez conserver une association de période de notation personnalisée ou inexistante, vous devez inclure dueDate et gradingPeriodId dans le champ updateMask et le corps de la requête. Cela indiquera à Classroom de ne pas remplacer gradingPeriodId par la période de notation qui correspond à la nouvelle 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()