Управляйте оценочными периодами с помощью 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 при создании или обновлении учебных материалов с помощью 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 . Для создания или изменения учебных материалов вам потребуются учетные данные преподавателя. Администраторы не могут создавать или изменять учебные материалы, если они не являются преподавателями данного курса.

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

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

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

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

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

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

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

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

Python 

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 независимо от того, добавляете ли вы отдельные периоды оценивания, изменяете существующие периоды оценивания или удаляете период оценивания.

Python

В следующем примере ресурс gradingPeriodSettings изменен таким образом, чтобы включить два периода оценивания. Логическое значение applyToExistingCoursework установлено в True , что изменит gradingPeriodId для любой существующей работы, которая попадает в период между началом и концом одного из периодов оценивания. Обратите внимание, что 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 . Любой пользователь, независимо от лицензии, может считывать настройки периодов оценивания в курсе.

Python 

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. Оценочные периоды с новыми или неизвестными идентификаторами считаются ошибками .

Python

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

Для этого считывается текущий объект GradingPeriodSettings , в список добавляется новый период оценивания, а логическая переменная applyToExistingCoursework устанавливается в значение False . Обратите внимание, что любые периоды оценивания, которые уже были применены к существующим записям CourseWork, не будут удалены. В предыдущем примере периоды оценивания «Семестр 1» и «Семестр 2» уже были применены к существующим записям 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 сохраняется , то есть, если в предыдущем вызове API оно было установлено в True и не изменено, последующие обновления периодов оценивания будут применяться к существующим записям курсов.

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

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

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

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

Python

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

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 .

Python

Чтобы продолжить пример из этого руководства, опустите период оценивания «Лето», чтобы удалить его.

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. Привязка периода выставления оценок к дате.

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

2. Индивидуально подобранный период оценки.

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

3. Отсутствие привязки к периодам выставления оценок.

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

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

Идти 

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

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

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

Python 

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()
Назад
Устанавливайте и обновляйте оценки
Далее
Ограничения