Управляйте оценочными периодами с помощью Classroom API

В этом руководстве объясняется, как использовать конечные точки оценивания в API Google Classroom.

Обзор

Оценочные периоды создаются для организации домашних заданий, тестов и проектов по определенным диапазонам дат. API Classroom позволяет разработчикам создавать, изменять и читать оценочные периоды в Classroom от имени администраторов и преподавателей. Вы также можете использовать API Classroom для установки периодов оценивания в CourseWork.

API Classroom предлагает две конечные точки для чтения и записи информации об оцениваемых периодах в курсе:

• GetGradingPeriodSettings : позволяет прочитать настройки оценочного периода в курсе.
• UpdateGradingPeriodSettings : позволяет управлять настройками оценочных периодов в курсе, добавляя, изменяя и удаляя оценочные периоды, а также применяя настроенные оценочные периоды ко всем существующим курсам.

Лицензионные требования

Изменение настроек оценочного периода в курсе

Чтобы создавать, изменять или удалять оценочные периоды в курсе с помощью конечной точки UpdateGradingPeriodSettings , должны быть выполнены следующие условия:

• Пользователю, отправляющему запрос, назначена лицензия Google Workspace for Education Plus .
• Владельцу курса назначена лицензия Google Workspace for Education Plus .

Чтение настроек оценочного периода в курсе

Администраторы домена и преподаватели курса могут читать настройки учебного периода независимо от того, какая лицензия им назначена. Это означает, что запросы к конечной точке GetGradingPeriodSettings разрешены от имени любого администратора домена или преподавателя.

Установите идентификатор оценочного периода в CourseWork

Преподаватели курса могут включать gradingPeriodId при создании или обновлении CourseWork с помощью API независимо от того, какая лицензия им назначена.

Проверка права пользователя на настройку оценочных периодов

Запросы к конечной точке checkGradingPeriodsSetupEligibility разрешены от имени любого администратора или преподавателя. Используйте это, чтобы определить, может ли пользователь изменять оценочные периоды в курсе.

Предварительные условия

В этом руководстве представлены примеры кода на Python и предполагается, что у вас есть:

• Проект Google Cloud. Вы можете настроить его, следуя инструкциям в кратком руководстве по Python .
• На экран согласия OAuth вашего проекта добавлены следующие области:
  • https://www.googleapis.com/auth/classroom.courses
  • https://www.googleapis.com/auth/classroom.coursework.students
• Идентификатор курса, в котором необходимо изменить периоды оценивания. Владелец курса должен иметь лицензию Google Workspace for Education Plus .
• Доступ к учетным данным преподавателя или администратора с помощью лицензии Google Workspace for Education Plus . Для создания или изменения CourseWork вам потребуются учетные данные преподавателя. Администраторы не могут создавать или изменять CourseWork, если они не являются преподавателями курса.

Управление ресурсом GradingPeriodSettings

Ресурс GradingPeriodSettings включает список отдельных GradingPeriods и логическое поле с именем applyToExistingCoursework .

Список GradingPeriods представляет все отдельные периоды оценки в курсе. Вы должны указать название, дату начала и дату окончания для каждого отдельного оценочного периода в списке. Каждый оценочный период в курсе должен иметь уникальное название, а даты начала и окончания разных оценочных периодов не могут перекрываться. Каждому оценочному периоду будет присвоен собственный идентификатор, присвоенный Classroom API.

Логическое значение applyToExistingCoursework — это постоянный параметр, который позволяет организовать ранее созданные CourseWork по оценочным периодам без необходимости выполнять отдельный вызов API для изменения gradingPeriodId для каждого CourseWork. Если для него установлено значение True , Classroom автоматически установит gradingPeriodId для всех существующих курсов CourseWork, если courseWork.dueDate попадает в пределы дат начала и окончания существующего оценочного периода. Если для CourseWork не была установлена ​​дата сдачи, Classroom будет использовать courseWork.scheduledTime . Если ни одно из полей не присутствует или нет совпадений в датах начала и окончания существующего оценочного периода, CourseWork не будет связана ни с каким оценочным периодом.

Определите, может ли пользователь изменять настройки оценочного периода в курсе.

Поскольку возможность создавать и изменять оценочные периоды в Классе доступна только пользователям с определенной лицензией, API Класса предоставляет конечную точку checkGradingPeriodsSetupEligibility , которая помогает заранее определить, может ли пользователь отправлять запросы к конечной точке 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

Добавить оценочные периоды

Теперь, когда вы уверены, что у пользователя есть необходимая лицензия для изменения настроек оценочного периода в курсе, вы можете начать отправлять запросы к конечной точке UpdateGradingPeriodSettings . Любые изменения ресурса GradingPeriodSettings выполняются с использованием конечной точки UpdateGradingPeriodSettings независимо от того, добавляете ли вы отдельные оценочные периоды, изменяете существующие оценочные периоды или удаляете оценочный период.

Питон

В следующем примере ресурс gradingPeriodSettings изменяется и включает два оценочных периода. Для логического значения applyToExistingCoursework установлено значение True , что приведет к изменению gradingPeriodId для любой существующей CourseWork, которая находится между датой начала и окончания одного оценочного периода. Обратите внимание, что updateMask включает оба поля. Сохраните идентификаторы отдельных периодов оценивания, как только они будут возвращены в ответе. При необходимости вам потребуется использовать эти идентификаторы для обновления оценочных периодов.

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

Чтение настроек оценочного периода

GradingPeriodSettings считывается с помощью конечной точки GetGradingPeriodSettings . Любой пользователь, независимо от лицензии, может просмотреть настройки учебных периодов в курсе.

Питон

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

Добавить в список отдельный оценочный период

Обновления отдельного оценочного периода должны выполняться по схеме «чтение-изменение-запись». Это означает, что вам следует:

1. Прочтите список оценочных периодов в ресурсе GradingPeriodSettings , используя конечную точку GetGradingPeriodSettings .
2. Внесите выбранные изменения в список оценочных периодов.
3. Отправьте новый список оценочных периодов в запросе к UpdateGradingPeriodSettings .

Этот шаблон поможет вам гарантировать, что названия отдельных оценочных периодов в курсе будут различимы, а даты начала и окончания оценочных периодов не будут перекрываться.

Помните о следующих правилах обновления списка оценочных периодов:

1. Оценочные периоды , добавленные в список без идентификатора, считаются дополнениями .
2. Оценочные периоды , отсутствующие в списке, считаются исключениями .
3. Периоды оценивания с существующим идентификатором, но измененными данными считаются изменениями . Немодифицированные свойства остаются как есть.
4. Оценочные периоды с новыми или неизвестными идентификаторами считаются ошибками .

Важно: Убедитесь, что вы включили идентификаторы всех оценочных периодов, которые вы не хотите удалять, в запрос UpdateGradingPeriodSettings .

Питон

Следующий код будет основан на примере из этого руководства. Создается новый оценочный период с названием «Лето». В тексте запроса логическому значению applyToExistingCoursework присвоено значение False .

Для этого считывается текущий GradingPeriodSettings , в список добавляется новый оценочный период, а логическому значению applyToExistingCoursework присваивается значение False . Обратите внимание, что любые оценочные периоды, которые уже были применены к существующим курсам CourseWork, не будут удалены. В предыдущем примере периоды оценивания «Семестр 1» и «Семестр 2» уже были применены к существующему CourseWork и не будут удалены из CourseWork, если в последующих запросах для applyToExistingCoursework установлено значение False.

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

Полезные советы о логическом поле applyToExistingCoursework

Важно помнить, что логическое значение applyToExistingCoursework сохраняется. Это означает, что если для этого логического значения было установлено значение True в предыдущем вызове API и оно не было изменено, последующие обновления оценочных периодов будут применяться к существующему CourseWork.

Обратите внимание: если вы измените это логическое значение с True на False в запросе к UpdateGradingPeriodSettings , только новые изменения, которые вы вносите в GradingPeriodSettings не будут применены к существующему CourseWork. Любая информация об оценочном периоде, примененная к CourseWork в предыдущих вызовах API, когда для логического значения было установлено True , не будет удалена. Полезный способ подумать об этом логическом параметре заключается в том, что он поддерживает связь существующего CourseWork с настроенными вами оценочными периодами, но не поддерживает удаление существующих связей между CourseWork и настроенными оценочными периодами.

Если вы удалите или измените название оценочного периода, эти изменения будут распространены на все существующие CourseWork, независимо от настройки логического значения applyToExistingCoursework .

Важно: установка для поля applyToExistingCoursework значения False не приведет к удалению ранее существовавших оценочных периодов и связей CourseWork. Удаление или изменение названия оценочного периода будет распространяться на все CourseWork независимо от параметра applyToExistingCoursework .

Обновление отдельного оценочного периода в списке

Чтобы изменить некоторые данные, связанные с существующим оценочным периодом, включите идентификатор существующего оценочного периода в список с измененными данными.

Питон

В этом примере дата окончания «Летнего» оценочного периода будет изменена. Поле applyToExistingCoursework будет установлено в значение True . Обратите внимание, что если задать для этого логического значения значение True все настроенные периоды оценки будут применены к существующему CourseWork. В предыдущем запросе API для логического значения было установлено значение False поэтому оценочный период «Летний» не применялся к существующим курсам CourseWork. Теперь, когда для этого логического поля установлено значение True , оценочный период «Летний» будет применяться ко всем существующим соответствующим курсам CourseWork.

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

Удаление отдельного оценочного периода

Чтобы удалить оценочный период, исключите его из списка. Обратите внимание: если оценочный период будет удален, любая ссылка на оценочный период в CourseWork также будет удалена независимо от параметра 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

Управление полем gradingPeriodId в CourseWork

Ресурс CourseWork включает поле gradingPeriodId . Вы можете использовать конечные точки CourseWork для чтения и записи оценочного периода, связанного с CourseWork. Существует три способа управления этой ассоциацией:

• автоматическая привязка оценочного периода на основе даты
• настраиваемый оценочный период
• ассоциация без оценочного периода

1. Привязка оценочного периода на основе даты

При создании CourseWork вы можете разрешить Classroom обрабатывать за вас связь с оценочным периодом. Для этого опустите поле gradingPeriodId в запросе CourseWork. Затем укажите поля dueDate или scheduledTime в запросе CourseWork. Если dueDate попадает в существующий диапазон дат оценочного периода, Classroom установит этот идентификатор оценочного периода в CourseWork. Если поле dueDate не указано, Класс определит gradingPeriodId на основе поля scheduledTime . Если ни одно поле не указано или диапазон дат оценочного периода не соответствует, в CourseWork не будет установлен gradingPeriodId .

2. Пользовательский оценочный период

Если вы хотите связать CourseWork с другим оценочным периодом, отличным от того, который соответствует dueDate или scheduledTime , вы можете вручную установить поле gradingPeriodId при создании или обновлении CourseWork. Если вы вручную зададите gradingPeriodId , Класс не будет выполнять автоматическую привязку оценочного периода на основе даты.

3. Отсутствие ассоциации с оценочным периодом

Если вы вообще не хотите, чтобы CourseWork был связан с каким-либо оценочным периодом, установите для поля gradingPeriodId в запросе CourseWork пустую строку ( gradingPeriodId : "" ).

Что произойдет с идентификатором оценочного периода, если дата сдачи будет обновлена?

Если вы обновляете поле dueDate CourseWork и хотите сохранить настраиваемую связь с оценочным периодом или без нее, вам следует включить dueDate и gradingPeriodId в updateMask и тело запроса. Это позволит Классу не переопределять gradingPeriodId периодом оценивания, соответствующим новому 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()

Важно! При обновлении поля dueDate в CourseWork включите поле gradingPeriodId в updateMask и текст запроса, чтобы сохранить пользовательскую связь или не иметь ее. Это гарантирует, что Класс не переопределит поле gradingPeriodId полем, соответствующим новому dueDate .