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 quiz et les projets dans des plages de dates spécifiques. L'API Classroom permet aux développeurs de créer, de modifier et de lire des périodes de notation dans Classroom au nom des administrateurs et des enseignants. Vous pouvez également utiliser l'API Classroom pour définir des périodes de notation dans CourseWork.

L'API Classroom propose deux points de terminaison pour lire et écrire des informations sur les périodes de notation dans 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 de période de notation dans 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 devoirs existants.

Exigences concernant les licences

Modifier les paramètres de période de notation dans 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 la 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 au nom de tout administrateur de domaine ou enseignant.

Définir un ID de période de notation dans 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 est autorisé à configurer des périodes de notation

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

Prérequis

Ce guide fournit des exemples de code en Python et suppose que vous disposez des éléments suivants:

  • Un projet Google Cloud. Vous pouvez en configurer un en suivant les instructions du guide de démarrage rapide pour Python.
  • Vous avez ajouté les champs d'application suivants à l'écran d'autorisation OAuth de votre projet :
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • ID du cours pour 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 des cours. Les administrateurs ne peuvent pas créer ni modifier de cours CourseWork s'ils ne sont pas enseignants du cours.

Gérer la ressource GradingPeriodSettings

La ressource GradingPeriodSettings inclut une liste de GradingPeriods individuels 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, et les dates de début et de fin des différentes périodes de notation ne doivent pas se chevaucher. Chaque période de notation aura son propre identifiant attribué par l'API Classroom.

La valeur booléenne applyToExistingCoursework est un paramètre persistant qui vous permet d'organiser les cours créés précédemment en périodes de notation sans avoir à effectuer un appel d'API distinct pour modifier le gradingPeriodId de chaque cours. Si elle est définie sur True, Classroom définira automatiquement gradingPeriodId sur tous les cours existants si courseWork.dueDate se situe entre 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 cours, Classroom utilisera courseWork.scheduledTime. Si aucun champ n'est présent ou s'il n'y a pas de correspondance entre les dates de début et de fin d'une période de notation existante, le cours ne sera associé à aucune période de notation.

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

Étant donné que la possibilité de créer et de modifier des périodes de notation dans Classroom n'est disponible que pour les utilisateurs disposant d'une licence spécifique, 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 requise pour modifier les paramètres de période de notation dans un cours, vous pouvez commencer à envoyer des requêtes au point de terminaison UpdateGradingPeriodSettings. Toute modification apportée à la ressource GradingPeriodSettings est effectuée à l'aide du point de terminaison UpdateGradingPeriodSettings, que vous ajoutiez des périodes de notation individuelles, modifiiez des périodes de notation existantes ou supprimiez 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 la valeur gradingPeriodId de tout devoir existant compris entre la date de début et la date 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 sont 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 des périodes de notation

Les GradingPeriodSettings sont lus à l'aide du point de terminaison GetGradingPeriodSettings. Tous les utilisateurs, quelle que soit leur licence, peuvent lire les paramètres des périodes de notation dans 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 selon un modèle de 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 choisies à 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 dont les données ont été modifiées, sont considérées comme des modifications. Les propriétés non modifiées restent telles quelles.
  4. Les périodes de notation avec des ID nouveaux ou inconnus sont considérées comme des erreurs.

Python

Le code suivant s'appuie sur l'exemple de ce guide. Une nouvelle 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, l'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 aux devoirs existants ne seront pas supprimées. Dans l'exemple précédent, les périodes de notation "Semester 1" (Semestre 1) et "Semester 2" (Semestre 2) ont déjà été appliquées aux cours existants et ne seront pas supprimées de CourseWork si applyToExistingCoursework est défini sur "False" (Faux) 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

Conseils utiles sur le champ booléen applyToExistingCoursework

Il est important de se rappeler que la valeur booléenne applyToExistingCoursework est persistante, ce qui signifie que si elle 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 aux cours existants.

Notez que si vous remplacez cette valeur booléenne de True par False dans une requête envoyée à UpdateGradingPeriodSettings, seules les nouvelles modifications que vous apportez à GradingPeriodSettings ne seront pas appliquées aux cours existants. 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 seront pas supprimées. Pour comprendre ce paramètre booléen, sachez qu'il permet d'associer des cours existants à vos périodes de notation configurées, mais qu'il ne permet pas de supprimer les associations existantes entre les cours et les périodes de notation configurées.

Si vous supprimez ou modifiez le titre d'une période de notation, ces modifications seront propagées dans tous les cours 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 la période de notation existante 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 s'appliqueront aux cours existants. Dans la requête API précédente, la valeur booléenne était définie sur False afin que la période de notation "Été" ne soit pas appliquée aux cours existants. Maintenant que ce champ booléen est défini sur True, la période de notation "Été" sera appliquée à tous les cours 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, ne l'incluez pas 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, quelle que soit la valeur du paramètre applyToExistingCoursework.

Python

Pour poursuivre l'exemple de ce guide, omettez la période de notation "Été" pour 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 cours. Il existe trois façons de gérer cette association:

  • Association automatique des devoirs à une période de notation en fonction de la date
  • période de notation associée personnalisée
  • aucune association de période de notation

1. Association de la période de notation en fonction de la date

Lorsque vous créez un devoir, vous pouvez autoriser Classroom à gérer l'association de la période de notation. 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 dueDate se situe dans une plage de dates de période de notation existante, Classroom définira cet ID de période de notation sur le cours. Si le champ dueDate n'est pas spécifié, Classroom déterminera le gradingPeriodId en fonction du champ scheduledTime. Si aucun champ n'est spécifié ou si aucune correspondance de période de notation n'est trouvée, aucun gradingPeriodId n'est défini sur le cours.

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

Si vous souhaitez associer le devoir à une période de notation différente de celle qui correspond à dueDate ou scheduledTime, vous pouvez définir manuellement le champ gradingPeriodId lorsque vous créez ou mettez à jour le devoir. Si vous définissez manuellement gradingPeriodId, Classroom n'effectue pas l'association automatique des périodes de notation en fonction de la date.

3. Aucune association de période de notation

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

Que se passe-t-il avec 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 personnalisée ou aucune association de période de notation, vous devez inclure dueDate et gradingPeriodId dans updateMask et le corps de la requête. Classroom ne remplacera pas gradingPeriodId par la période de notation correspondant au nouvel élément 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()
Précédent
Définir et mettre à jour les notes
Suivant
Limites