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 consulter 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 : vous permet de lire les paramètres des périodes de notation dans un cours.
• UpdateGradingPeriodSettings : permet de gérer les paramètres des périodes de notation dans un cours en ajoutant, modifiant et supprimant des périodes de notation, et en appliquant les périodes de notation configurées à tous les devoirs existants.

Conditions d'éligibilité et de licence

Modifier les paramètres des périodes 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 doit être un enseignant du cours ou un administrateur.
• 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 des périodes de notation dans un cours

Les administrateurs de domaine et les enseignants d'un cours peuvent lire les paramètres des périodes de notation, quelle que soit la licence qui leur est attribuée. Cela signifie que les requêtes envoyé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 sur un devoir

Les enseignants d'un cours peuvent inclure gradingPeriodId lorsqu'ils créent ou mettent à jour des devoirs à 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 userProfiles.checkUserCapability sont autorisées au nom de tout administrateur ou enseignant. Utilisez cette option pour déterminer si l'utilisateur peut modifier les périodes de notation.

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.
• Les champs d'application suivants ont été ajoutés à l'écran d'autorisation 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 des devoirs. Les administrateurs ne peuvent pas créer ni modifier des devoirs s'ils ne sont pas enseignants dans le cours.

Gérer la ressource GradingPeriodSettings

La ressource GradingPeriodSettings inclut une liste de GradingPeriods individuels et un champ booléen appelé applyToExistingCoursework.

Assurez-vous que chaque GradingPeriods de la liste répond aux exigences suivantes :

• Titre, date de début et date de fin : chaque période de notation doit comporter un titre, une date de début et une date de fin.
• Titre unique : chaque période de notation doit avoir un titre unique qui ne correspond à aucune autre période de notation du cours.
• Dates non chevauchantes : les dates de début et de fin de chaque période de notation ne doivent pas chevaucher celles d'une autre période de notation du cours.
• Ordre chronologique : les périodes de notation doivent être listées dans l'ordre chronologique en fonction des dates de début et de fin.

Chaque période de notation se verra attribuer un identifiant Classroom API lors de sa création.

Le booléen applyToExistingCoursework est un paramètre persistant qui vous permet d'organiser les devoirs créés précédemment dans des périodes de notation sans avoir à effectuer un appel d'API distinct pour modifier le gradingPeriodId de chaque devoir. Si la valeur est définie sur True, Classroom définit automatiquement la gradingPeriodId sur tous les devoirs existants si la 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 devoir, Classroom utilisera courseWork.scheduledTime. Si aucun de ces champs n'est présent ou s'il n'y a aucune correspondance avec les dates de début et de fin d'une période de notation existante, le devoir ne sera associé à aucune période de notation.

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

L'API Classroom fournit le point de terminaison userProfiles.checkUserCapability pour vous aider à déterminer de manière proactive si un utilisateur est en mesure d'envoyer des requêtes au point de terminaison UpdateGradingPeriodSettings.

def check_grading_periods_update_capability(classroom_service, course_id):
    """Checks whether a user is able to create and modify grading periods in a course."""
    try:
        capability = classroom_service.userProfiles().checkUserCapability(
          userId="me",
          capability="UPDATE_GRADING_PERIOD_SETTINGS",
           # Required while the checkUserCapability method is available in the Developer Preview Program.
          previewVersion="V1_20240930_PREVIEW"
        ).execute()

        # Retrieve the `allowed` boolean from the response.
        if capability.get("allowed"):
          print("User is allowed to update grading period settings in the course.")
        else:
          print("User is not allowed to update grading period settings in the course.")
    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 est autorisé à modifier les paramètres des périodes 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, que vous modifiiez des périodes de notation existantes ou que vous supprimiez une période de notation.

def create_grading_periods(classroom_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id,
          updateMask='gradingPeriods,applyToExistingCoursework',
          body=body
        ).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 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.

def get_grading_period_settings(classroom_service, course_id):
    """Read grading periods settings in a course."""
    try:
        gradingPeriodSettings = classroom_service.courses().getGradingPeriodSettings(
          courseId=course_id).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 modifications apportées à une période de notation individuelle doivent suivre 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 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_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

Conseils utiles concernant le champ booléen applyToExistingCoursework

Il est important de se rappeler que le booléen applyToExistingCoursework est conservé. Cela signifie que si le booléen a été défini sur True lors d'un appel d'API précédent et qu'il n'a pas été modifié, les mises à jour ultérieures des périodes de notation seront appliquées aux devoirs existants.

Notez que si vous remplacez cette valeur booléenne de True par False dans une requête adressée à UpdateGradingPeriodSettings, seules les nouvelles modifications que vous apportez à GradingPeriodSettings ne seront pas appliquées aux devoirs existants. Les informations sur la période de notation appliquées aux devoirs dans les appels d'API précédents lorsque le booléen était défini sur True ne seront pas supprimées. Pour mieux comprendre ce paramètre booléen, sachez qu'il permet d'associer des devoirs existants aux périodes de notation que vous avez configurées, mais pas de supprimer les associations existantes entre les devoirs 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 à tous les devoirs existants, quel que soit le paramètre du booléen 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_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').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 dans Travaux et devoirs sera également supprimée, quel que soit le paramètre applyToExistingCoursework.

def delete_grading_period(classroom_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods').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 Devoirs

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. Il existe trois façons de gérer cette association :

• Association automatique des périodes de notation en fonction des dates
• période de notation associée personnalisée
• aucune association de période de notation

1. Association de périodes de notation basées sur des dates

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

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 modifiez le devoir. Si vous définissez manuellement la gradingPeriodId, Classroom n'associera pas automatiquement les devoirs aux périodes de notation en fonction de leur date.

3. Aucune période de notation associée

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

Si vous utilisez le langage de programmation Go et que vous ne souhaitez définir aucune période de notation, vous devez également inclure le champ ForceSendFields dans le corps de la requête. Avec la bibliothèque cliente Go, les valeurs par défaut sont omises des requêtes API en raison de la présence du tag de champ omitempty sur tous les champs. Le champ ForceSendFields permet de contourner cette étape et d'envoyer la chaîne vide pour indiquer que vous ne souhaitez définir aucune période de notation pour ce devoir. Pour en savoir plus, consultez la documentation de la bibliothèque cliente des API Google pour Go.

courseWork := &classroom.CourseWork{
  Title: "Homework questions",
  WorkType: "ASSIGNMENT",
  State: "DRAFT",
  // ...other CourseWork fields...
  GradingPeriodId: "",
  ForceSendFields: []string{"GradingPeriodId"},
}

Que devient l'ID de la période de notation si la date limite est modifiée ?

Si vous mettez à jour le champ dueDate CourseWork et que vous souhaitez conserver une association personnalisée ou sans période de notation, vous devez inclure dueDate et gradingPeriodId dans le corps de la requête et updateMask. Classroom ne remplacera pas le gradingPeriodId par la période de notation correspondant au nouveau dueDate.

body = {
  "dueDate": {
    "month": 6,
    "day": 10,
    "year": 2024
  },
  "dueTime": {
    "hours": 7
  },
  "gradingPeriodId": "<INSERT-GRADING-PERIOD-ID-OR-EMPTY-STRING>"
}
courseWork = classroom_service.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId') # include the gradingPeriodId field in the updateMask
.execute()