Classroom API를 사용하여 평가 기간 관리

이 가이드에서는 Google Classroom API에서 평가 기간 엔드포인트를 사용하는 방법을 설명합니다.

개요

평가 기간은 과제, 퀴즈, 프로젝트를 특정 기간으로 정리하기 위해 만듭니다. Classroom API를 사용하면 개발자가 관리자 및 교사를 대신하여 클래스룸에서 평가 기간을 만들고 수정하고 읽을 수 있습니다. Classroom API를 사용하여 CourseWork에서 평가 기간을 설정할 수도 있습니다.

Classroom API는 강의에서 평가 기간 정보를 읽고 쓰는 두 가지 엔드포인트를 제공합니다.

  • GetGradingPeriodSettings: 과정의 평가 기간 설정을 읽을 수 있습니다.
  • UpdateGradingPeriodSettings: 평가 기간을 추가, 수정, 삭제하고 구성된 평가 기간을 모든 기존 과정 과제에 적용하여 과정의 평가 기간 설정을 관리할 수 있습니다.

라이선스 요구사항

강의에서 평가 기간 설정 수정하기

UpdateGradingPeriodSettings 엔드포인트를 사용하여 강의에서 평가 기간을 만들거나 수정하거나 삭제하려면 다음 조건을 충족해야 합니다.

강의의 평가 기간 설정 읽기

도메인 관리자와 강의 교사는 할당된 라이선스와 관계없이 채점 기간 설정을 읽을 수 있습니다. 즉, GetGradingPeriodSettings 엔드포인트에 대한 요청은 모든 도메인 관리자 또는 교사를 대신하여 허용됩니다.

CourseWork에서 평가 기간 ID 설정

과정의 교사는 할당된 라이선스에 관계없이 API를 사용하여 CourseWork를 만들거나 업데이트할 때 gradingPeriodId를 포함할 수 있습니다.

평가 기간을 설정할 수 있는 사용자 자격요건 확인

checkGradingPeriodsSetupEligibility 엔드포인트에 대한 요청은 관리자 또는 교사를 대신하여 허용됩니다. 이를 사용하여 사용자가 과정의 평가 기간을 수정할 수 있는지 여부를 결정합니다.

기본 요건

이 가이드에서는 Python으로 작성된 코드 예시를 제공하며 다음을 이미 완료했다고 가정합니다.

  • Google Cloud 프로젝트 Python 빠른 시작의 안내에 따라 설정할 수 있습니다.
  • 프로젝트의 OAuth 동의 화면에 다음 범위를 추가했습니다.
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • 평가 기간을 수정해야 하는 과정의 ID입니다. 과정 소유자에게 Google Workspace for Education Plus 라이선스가 있어야 합니다.
  • Google Workspace for Education Plus 라이선스를 사용하여 교사 또는 관리자의 사용자 인증 정보에 액세스할 수 있습니다. 강의 자료를 만들거나 수정하려면 교사의 사용자 인증 정보가 필요합니다. 관리자가 강의의 교사가 아닌 경우 강의 과제를 만들거나 수정할 수 없습니다.

GradingPeriodSettings 리소스 관리

GradingPeriodSettings 리소스에는 개별 GradingPeriods 목록과 applyToExistingCoursework라는 불리언 필드가 포함됩니다.

GradingPeriods 목록은 과정의 모든 개별 평가 기간을 나타냅니다. 목록에서 각 개별 평가 기간의 제목, 시작일, 종료일을 지정해야 합니다. 강의의 각 평가 기간에는 고유한 제목이 있어야 하며, 서로 다른 평가 기간의 시작일과 종료일이 겹쳐서는 안 됩니다. 평가 기간마다 클래스룸 API에서 할당된 식별자가 있습니다.

applyToExistingCoursework 불리언은 이전에 생성된 CourseWork를 평가 기간으로 구성할 수 있는 영구 설정으로, 각 CourseWork의 gradingPeriodId를 수정하기 위해 별도의 API를 호출하지 않아도 됩니다. True로 설정하면 courseWork.dueDate가 기존 평가 기간의 시작일과 종료일 내에 포함될 경우 클래스룸에서 기존의 모든 CourseWork에 자동으로 gradingPeriodId를 설정합니다. CourseWork에 마감일이 설정되지 않은 경우 클래스룸은 courseWork.scheduledTime를 사용합니다. 두 필드가 모두 없거나 기존 평가 기간의 시작일과 종료일 내에 일치하는 항목이 없는 경우 CourseWork가 평가 기간과 연결되지 않습니다.

사용자가 강의에서 평가 기간 설정을 수정할 수 있는지 확인하기

Classroom에서 평가 기간을 만들고 수정하는 기능은 특정 라이선스가 있는 사용자만 사용할 수 있으므로 Classroom API는 사용자가 UpdateGradingPeriodSettings 엔드포인트에 요청할 수 있는지 사전에 확인하는 데 도움이 되는 checkGradingPeriodsSetupEligibility 엔드포인트를 제공합니다.

Python

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 엔드포인트를 사용하여 실행됩니다.

Python

다음 예에서는 두 개의 평가 기간을 포함하도록 gradingPeriodSettings 리소스가 수정됩니다. applyToExistingCoursework 부울은 True로 설정됩니다. 이 값은 한 평가 기간의 시작일과 종료일 사이에 있는 기존 CourseWork의 gradingPeriodId를 수정합니다. updateMask에는 두 필드가 모두 포함됩니다. 응답에서 개별 평가 기간의 ID가 반환되면 이를 저장합니다. 필요한 경우 이러한 ID를 사용하여 평가 기간을 업데이트해야 합니다.

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 엔드포인트를 사용하여 읽습니다. 라이선스에 관계없이 모든 사용자가 강의의 평가 기간 설정을 읽을 수 있습니다.

Python

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

목록에 개별 평가 기간 추가

개별 평가 기간은 read-modify-write 패턴에 따라 업데이트해야 합니다. 즉, 다음을 수행해야 합니다.

  1. GetGradingPeriodSettings 엔드포인트를 사용하여 GradingPeriodSettings 리소스 내의 평가 기간 목록을 읽습니다.
  2. 평가 기간 목록에서 선택한 사항을 수정합니다.
  3. UpdateGradingPeriodSettings에 대한 요청으로 새 평가 기간 목록을 전송합니다.

이 패턴을 사용하면 과정의 개별 평가 기간 제목이 고유하고 평가 기간의 시작일과 종료일이 겹치지 않도록 할 수 있습니다.

평가 기간 목록 업데이트에 관한 다음 규칙에 유의하세요.

  1. ID 없이 목록에 추가된 평가 기간은 추가로 간주됩니다.
  2. 목록에서 누락된 평가 기간은 삭제된 것으로 간주됩니다.
  3. 기존 ID가 있지만 데이터가 수정된 평가 기간은 수정으로 간주됩니다. 수정되지 않은 속성은 그대로 유지됩니다.
  4. 새 ID 또는 알 수 없는 ID가 포함된 평가 기간은 오류로 간주됩니다.

Python

다음 코드는 이 가이드의 예를 기반으로 합니다. '여름'이라는 제목의 새 평가 기간이 생성됩니다. applyToExistingCoursework 부울은 요청 본문에서 False로 설정됩니다.

이를 위해 현재 GradingPeriodSettings를 읽고, 새 평가 기간을 목록에 추가하고, applyToExistingCoursework 불리언을 False로 설정합니다. 기존 CourseWork에 이미 적용된 평가 기간은 삭제되지 않습니다. 이전 예에서 'Semester 1' 및 'Semester 2' 평가 기간은 이미 기존 CourseWork에 적용되었으며 후속 요청에서 applyToExistingCoursework가 False로 설정되더라도 CourseWork에서 삭제되지 않습니다.

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 불리언은 유지된다는 점에 유의해야 합니다. 즉, 이전 API 호출에서 불리언이 True로 설정되었고 변경되지 않은 경우 이후 평가 기간 업데이트가 기존 CourseWork에 적용됩니다.

UpdateGradingPeriodSettings 요청에서 이 불리언 값을 True에서 False로 변경하면 GradingPeriodSettings에 적용하는 새 변경사항만 기존 CourseWork에 적용되지 않습니다. 불리언이 True로 설정된 이전 API 호출에서 CourseWork에 적용된 모든 평가 기간 정보는 삭제되지 않습니다. 이 불리언 설정을 이해하는 데 도움이 되는 방법은 기존 CourseWork를 구성된 평가 기간과 연결하는 것을 지원하지만 CourseWork와 구성된 평가 기간 간의 기존 연결을 삭제하는 것은 지원하지 않는다는 것입니다.

평가 기간의 제목을 삭제하거나 변경하면 applyToExistingCoursework 부울 설정과 관계없이 모든 기존 CourseWork에 변경사항이 적용됩니다.

목록에서 개별 평가 기간 업데이트하기

기존 평가 기간과 연결된 일부 데이터를 수정하려면 수정된 데이터가 포함된 목록에 기존 평가 기간의 ID를 포함합니다.

Python

이 예에서는 '여름' 평가 기간 종료일이 수정됩니다. 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

개별 평가 기간 삭제하기

평가 기간을 삭제하려면 목록에서 평가 기간을 생략합니다. 평가 기간이 삭제되면 applyToExistingCoursework 설정과 관계없이 CourseWork의 평가 기간에 대한 모든 참조도 삭제됩니다.

Python

이 가이드의 예시를 계속하려면 평가 기간인 '여름'을 생략하여 삭제합니다.

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

CourseWork에서 gradingPeriodId 필드 관리

CourseWork 리소스에는 gradingPeriodId 필드가 포함됩니다. CourseWork 엔드포인트를 사용하여 CourseWork와 연결된 평가 기간을 읽고 쓸 수 있습니다. 이 연결을 관리하는 방법에는 세 가지가 있습니다.

  • 자동 날짜 기반 평가 기간 연결
  • 관련 평가 기간
  • 평가 기간 연결 없음

1. 날짜 기반 평가 기간 연결

과제를 만들 때 클래스룸에서 채점 기간 연결을 처리하도록 허용할 수 있습니다. 이렇게 하려면 CourseWork 요청에서 gradingPeriodId 필드를 생략합니다. 그런 다음 CourseWork 요청에서 dueDate 또는 scheduledTime 필드를 지정합니다. dueDate가 기존 채점 기간 기간에 해당하는 경우 클래스룸은 과제에 해당 채점 기간 ID를 설정합니다. dueDate 필드를 지정하지 않으면 클래스룸에서 scheduledTime 필드를 기반으로 gradingPeriodId를 결정합니다. 두 필드가 모두 지정되지 않았거나 채점 기간 기간 일치가 없는 경우 CourseWork에 gradingPeriodId가 설정되지 않습니다.

2. 맞춤 연결 평가 기간

dueDate 또는 scheduledTime와 일치하지 않는 평가 기간과 CourseWork를 연결하려면 CourseWork를 만들거나 업데이트할 때 gradingPeriodId 필드를 수동으로 설정하면 됩니다. gradingPeriodId를 수동으로 설정하면 클래스룸에서 자동 날짜 기반 평가 기간 연결을 실행하지 않습니다.

3. 평가 기간 연결 없음

CourseWork가 평가 기간과 전혀 연결되지 않도록 하려면 CourseWork 요청의 gradingPeriodId 필드를 빈 문자열 (gradingPeriodId: "")로 설정합니다.

마감일이 업데이트되면 평가 기간 ID는 어떻게 되나요?

CourseWork dueDate 필드를 업데이트하고 맞춤 또는 평가 기간 연결을 유지하려면 updateMask 및 요청 본문에 dueDate 및 gradingPeriodId를 포함해야 합니다. 이렇게 하면 클래스룸이 새 dueDate와 일치하는 평가 기간으로 gradingPeriodId을 재정의하지 않습니다.

Python

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