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

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

개요

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

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

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

라이선스 및 자격 요건

수업에서 평가 기간 설정 수정하기

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

강의의 평가 기간 설정 읽기

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

CourseWork에 평가 기간 ID 설정

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

사용자가 성적 기간을 설정할 수 있는지 확인

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

기본 요건

이 가이드에서는 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가 다음 요구사항을 충족하는지 확인합니다.

  • 제목, 시작일, 종료일: 각 평가 기간에는 제목, 시작일, 종료일이 있어야 합니다.
  • 고유한 제목: 각 평가 기간에는 강의의 다른 평가 기간과 일치하지 않는 고유한 제목이 있어야 합니다.
  • 중복되지 않는 날짜: 각 평가 기간의 시작일 또는 종료일이 과정의 다른 평가 기간과 중복되어서는 안 됩니다.
  • 시간순: 평가 기간은 시작일과 종료일을 기준으로 시간순으로 나열해야 합니다.

각 성적 기간에는 생성 시 Classroom API 할당 식별자가 할당됩니다.

applyToExistingCoursework 불리언은 이전에 생성된 CourseWork를 각 CourseWork의 gradingPeriodId를 수정하기 위해 별도의 API 호출을 하지 않고도 성적 기간으로 정리할 수 있는 지속 설정입니다. True로 설정된 경우 courseWork.dueDate가 기존 성적 기간의 시작일과 종료일 사이에 속하면 Classroom에서 모든 기존 CourseWork에 gradingPeriodId을 자동으로 설정합니다. CourseWork에 마감일이 설정되지 않은 경우 Classroom에서는 courseWork.scheduledTime을 사용합니다. 두 필드가 모두 없거나 기존 성적 기간의 시작일과 종료일 사이에 일치하는 항목이 없으면 CourseWork가 성적 기간과 연결되지 않습니다.

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

Classroom API는 사용자가 UpdateGradingPeriodSettings 엔드포인트에 요청을 할 수 있는지 사전에 확인할 수 있도록 userProfiles.checkUserCapability 엔드포인트를 제공합니다.

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로 설정되어 하나의 평가 기간의 시작일과 종료일 사이에 있는 기존 CourseWork의 gradingPeriodId가 수정됩니다. updateMask에는 두 필드가 모두 포함됩니다. 개별 성적 기간의 ID를 응답에 반환되면 저장합니다. 필요한 경우 이러한 ID를 사용하여 평가 기간을 업데이트해야 합니다.

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

목록에 개별 평가 기간 추가

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

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

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

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

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

Python

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

이렇게 하려면 현재 GradingPeriodSettings를 읽고 새 성적 기간을 목록에 추가하고 applyToExistingCoursework 불리언을 False로 설정합니다. 이미 기존 CourseWork에 적용된 성적 기간은 삭제되지 않습니다. 이전 예시에서 '1학기' 및 '2학기' 성적 기간은 이미 기존 CourseWork에 적용되었으며 후속 요청에서 applyToExistingCoursework가 False로 설정된 경우 CourseWork에서 삭제되지 않습니다.

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로 설정되었고 변경되지 않은 경우 성적 기간에 대한 후속 업데이트가 기존 CourseWork에 적용됩니다.

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

평가 기간의 제목을 삭제하거나 변경하면 applyToExistingCoursework 불리언의 설정과 관계없이 모든 기존 수업에 이러한 변경사항이 전파됩니다.

목록에서 개별 성적 기간 업데이트

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

Python

이 예에서는 '여름' 성적 기간 종료일이 수정됩니다. applyToExistingCoursework 필드는 True으로 설정됩니다. 이 불리언을 True로 설정하면 기존 CourseWork에 구성된 모든 성적 기간이 적용됩니다. 이전 API 요청에서는 불리언이 False로 설정되어 기존 CourseWork에 'Summer' 성적 기간이 적용되지 않았습니다. 이제 이 불리언 필드가 True로 설정되었으므로 일치하는 모든 기존 CourseWork에 'Summer' 성적 기간이 적용됩니다.

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

개별 평가 기간 삭제

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

Python

이 가이드의 예시를 계속하려면 평가 기간 'Summer'를 생략하여 삭제하세요.

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

  • 날짜 기반 평가 기간 자동 연결
  • 맞춤 연결된 평가 기간
  • 평가 기간 연결 없음

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

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

2. 맞춤 연결 평가 기간

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

3. 평가 기간 연결 없음

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

Go 프로그래밍 언어를 사용하고 평가 기간을 설정하지 않으려면 요청 본문에 ForceSendFields 필드도 포함해야 합니다. Go 클라이언트 라이브러리를 사용하면 모든 필드에 omitempty 필드 태그가 있으므로 API 요청에서 기본값이 생략됩니다. ForceSendFields 필드는 이를 우회하고 빈 문자열을 전송하여 해당 CourseWork에 설정된 성적 기간을 원하지 않음을 나타냅니다. 자세한 내용은 Google API Go 클라이언트 라이브러리 문서를 참고하세요.

Go

courseWork := &classroom.CourseWork{
  Title: "Homework questions",
  WorkType: "ASSIGNMENT",
  State: "DRAFT",
  // ...other CourseWork fields...
  GradingPeriodId: "",
  ForceSendFields: []string{"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_service.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId') # include the gradingPeriodId field in the updateMask
.execute()
이전
성적 설정 및 업데이트
다음
제한사항