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, de modifier et de lire des périodes de notation dans Classroom au nom des administrateurs et des 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 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:

• L'utilisateur qui envoie la demande dispose d'une licence Google Workspace for Education Plus.
• Le propriétaire du cours dispose d'une licence Google Workspace for Education Plus.

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 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 adressées au point de terminaison checkGradingPeriodsSetupEligibility sont autorisées au nom de n'importe quel administrateur ou enseignant. Utilisez-le pour déterminer si l'utilisateur peut modifier les périodes de notation d'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 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, 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 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. 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.

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. Toutes les modifications apportées à la ressource GradingPeriodSettings sont effectuées à 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.

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.

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.

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.

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.

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 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 la date dueDate se situe dans une 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 à la période de notation

Si vous ne souhaitez pas que le cours soit associé à une période de notation, définissez le champ gradingPeriodId de la requête CourseWork 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 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. Classroom ne remplacera pas gradingPeriodId par la période de notation correspondant à la nouvelle dueDate.

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