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

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

개요

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

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

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

라이선스 요구사항

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

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

• 요청하는 사용자에게 Google Workspace for Education Plus 라이선스가 할당되어 있습니다.
• 과정 소유자에게 Google Workspace for Education Plus 라이선스가 할당되었습니다.

강의에서 평가 기간 설정 읽기

과정의 도메인 관리자와 교사는 할당된 라이선스에 관계없이 평가 기간 설정을 읽을 수 있습니다. 즉, 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 라이선스로 교사 또는 관리자의 사용자 인증 정보에 액세스할 수 있습니다. CourseWork를 만들거나 수정하려면 교사의 사용자 인증 정보가 필요합니다 관리자는 과정의 교사가 아닌 경우 CourseWork를 만들거나 수정할 수 없습니다.

GradingPeriodSettings 리소스 관리

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

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

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

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

클래스룸에서 평가 기간을 만들고 수정하는 기능은 특정 라이선스가 있는 사용자만 사용할 수 있으므로 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

목록에 개별 평가 기간 추가하기

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

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

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

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

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

중요: UpdateGradingPeriodSettings 요청에 삭제하지 않을 평가 기간의 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에 변경사항이 적용됩니다.

중요: applyToExistingCoursework 필드를 False로 설정해도 기존 평가 기간 및 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

개별 평가 기간 삭제하기

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

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를 생성할 때 클래스룸에서 평가 기간 연결을 처리하도록 허용할 수 있습니다. 이렇게 하려면 CourseWork 요청에서 gradingPeriodId 필드를 생략합니다. 그런 다음 CourseWork 요청에서 dueDate 또는 scheduledTime 필드를 지정합니다. dueDate이 기존 평가 기간 기간에 해당하는 경우 클래스룸은 CourseWork에 해당 평가 기간 ID를 설정합니다. dueDate 필드가 지정되지 않으면 클래스룸은 scheduledTime 필드에 따라 gradingPeriodId를 결정합니다. 두 필드가 모두 지정되지 않거나 일치하는 평가 기간 기간이 없으면 CourseWork에 gradingPeriodId가 설정되지 않습니다.

2. 관련 평가 기간

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

3. 평가 기간 연결 없음

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

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

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

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

중요: CourseWork의 dueDate 필드를 업데이트할 때 updateMask 및 요청 본문에 gradingPeriodId 필드를 포함하여 커스텀 연결을 유지하거나 아예 연결하지 않습니다. 이렇게 하면 클래스룸이 gradingPeriodId 필드를 새 dueDate와 일치하는 필드로 재정의하지 않습니다.