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

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

Обзор

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

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

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

Требования к лицензированию и квалификации

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

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

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

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

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

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

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

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

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

Предпосылки

В этом руководстве приведены примеры кода на 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 в списке соответствует следующим требованиям:

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

При создании каждого оценочного периода ему будет присвоен идентификатор, присвоенный API класса.

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

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

API Classroom предоставляет конечную точку userProfiles.checkUserCapability , которая поможет вам заблаговременно определить, может ли пользователь отправлять запросы к конечной точке UpdateGradingPeriodSettings .

Внимание: Конечная точка userProfiles.checkUserCapability оценивает только право пользователя использовать определённую возможность, например, изменять оценочные периоды. Она не предоставляет никакой информации о роли на курсе. Например, даже если у пользователя есть возможность UPDATE_GRADING_PERIOD_SETTINGS , но он является студентом курса, запрос к конечной точке 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

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

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

Питон

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

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

Прочитать настройки оценочного периода

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

Питон

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

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

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

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_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

Полезные советы по булевому полю applyToExistingCoursework

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

Обратите внимание, что если вы измените это логическое значение с True на False в запросе к UpdateGradingPeriodSettings , то к существующему CourseWork не будут применены только новые изменения, вносимые в GradingPeriodSettings . Любая информация о периоде оценки, примененная к 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_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

Удалить отдельный период оценки

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

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

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

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

1. Ассоциация оценочных периодов на основе даты

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

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

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

3. Нет связи с периодом обучения

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

Если вы используете язык программирования Go и не хотите устанавливать период оценки, вам также следует включить поле ForceSendFields в тело запроса. При использовании клиентской библиотеки Go значения по умолчанию опускаются в запросах API из-за наличия тега omitempty во всех полях. Поле ForceSendFields обходит это и отправляет пустую строку, указывая, что вы не хотите устанавливать период оценки для данной курсовой работы. Подробнее см. в документации по клиентской библиотеке Go API Google .

Идти

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

Важно: при использовании языка программирования Go включите поле ForceSendFields в тело запроса, чтобы клиентская библиотека могла отправлять значения по умолчанию.

Что происходит с идентификатором периода обучения, если дата сдачи обновляется?

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

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