Classroom API を使用して採点期間を管理する

このガイドでは、Google Classroom API で成績期間のエンドポイントを使用する方法について説明します。

概要

採点期間は、宿題、小テスト、プロジェクトを特定の日付の範囲に整理するために作成されます。Classroom API を使用すると、デベロッパーは管理者や教師に代わって Classroom の採点期間を作成、変更、読み取ることができます。Classroom API を使用して、CourseWork の採点期間を設定することもできます。

Classroom API には、コースの採点期間情報を読み書きするための 2 つのエンドポイントが用意されています。

  • GetGradingPeriodSettings: コースの採点期間の設定を読み取ることができます。
  • UpdateGradingPeriodSettings: 採点期間の追加、変更、削除、構成済みの採点期間を既存のすべてのコースワークに適用することで、コースの採点期間の設定を管理できます。

ライセンスと利用資格要件

コースの採点期間の設定を変更する

UpdateGradingPeriodSettings エンドポイントを使用してコースの採点期間を作成、変更、削除するには、次の条件を満たす必要があります。

コースの採点期間の設定を読み取る

ドメイン管理者とコースの教師は、割り当てられているライセンスに関係なく、採点期間の設定を読み取ることができます。つまり、GetGradingPeriodSettings エンドポイントへのリクエストは、任意のドメイン管理者または教師に代わって許可されます。

コースワークに採点期間 ID を設定する

コースの教師は、割り当てられているライセンスに関係なく、API を使用して課題を作成または更新するときに 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 を自動的に設定します。課題に期限が設定されていない場合、Classroom は courseWork.scheduledTime を使用します。どちらのフィールドも存在しない場合、または既存の採点期間の開始日と終了日の間に一致するものがない場合、課題はどの採点期間にも関連付けられません。

ユーザーがコースの採点期間の設定を変更できるかどうかを判断する

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

次の例では、2 つの成績期間を含むように gradingPeriodSettings リソースが変更されています。applyToExistingCoursework ブール値が True に設定され、1 つの採点期間の開始日から終了日までの間にある既存の 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

リストに個別の採点期間を追加する

個々の採点期間の更新は、読み取り、変更、書き込みのパターンに従って行う必要があります。このためには、次のことが必要になります。

  1. GetGradingPeriodSettings エンドポイントを使用して、GradingPeriodSettings リソース内の採点期間のリストを読み取ります。
  2. 選択した変更を成績期間のリストに反映します。
  3. UpdateGradingPeriodSettings へのリクエストで新しい採点期間のリストを送信します。

このパターンを使用すると、コース内の個々の採点期間のタイトルが重複せず、採点期間の開始日と終了日が重複しないようにすることができます。

成績期間のリストを更新する際は、次のルールに注意してください。

  1. ID なしでリストに追加された成績期間は、追加とみなされます。
  2. リストにない採点期間は削除とみなされます。
  3. 既存の ID があるが、データが変更されている成績期間は、編集とみなされます。変更されていないプロパティはそのまま残ります。
  4. 新しい ID または不明な ID を含む成績期間は、エラーと見なされます。

Python

次のコードは、このガイドの例を基に作成されています。「Summer」というタイトルの新しい採点期間が作成されます。リクエストの本文で applyToExistingCoursework ブール値が False に設定されている。

そのため、現在の GradingPeriodSettings が読み取られ、新しい採点期間がリストに追加され、applyToExistingCoursework ブール値が False に設定されます。既存の課題にすでに適用されている成績期間は削除されません。前の例では、「Semester 1」と「Semester 2」の成績期間が既存の課題にすでに適用されているため、後続のリクエストで 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 に設定され、変更されていない場合、成績期間の以降の更新は既存の CourseWork に適用されます。

UpdateGradingPeriodSettings へのリクエストでこのブール値を True から False に変更した場合、GradingPeriodSettings に加えた新しい変更のみが既存の CourseWork に適用されません。ブール値が True に設定されている場合、以前の API 呼び出しで CourseWork に適用された成績期間情報は削除されません。このブール値の設定は、既存の CourseWork を構成済みの成績期間に関連付けることはできますが、CourseWork と構成済みの成績期間の既存の関連付けを削除することはできない、と考えるとわかりやすいでしょう。

採点期間のタイトルを削除または変更すると、applyToExistingCoursework ブール値の設定に関係なく、既存のすべての課題にその変更が反映されます。

リスト内の個々の採点期間を更新する

既存の採点期間に関連付けられたデータを変更するには、変更されたデータを含むリストに既存の採点期間の ID を含めます。

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

個々の採点期間を削除する

採点期間を削除するには、リストから採点期間を省略します。採点期間を削除すると、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

CourseWork の gradingPeriodId フィールドを管理する

CourseWork リソースには gradingPeriodId フィールドが含まれます。CourseWork エンドポイントを使用すると、CourseWork に関連付けられた採点期間の読み取りと書き込みを行うことができます。この関連付けを管理する方法は 3 つあります。

  • 日付に基づく採点期間の自動関連付け
  • カスタムの関連付けられた採点期間
  • 採点期間の関連付けがない

1. 日付ベースの採点期間の関連付け

課題を作成する際に、Classroom で採点期間の関連付けを自動的に処理するように設定できます。これを行うには、CourseWork リクエストから gradingPeriodId フィールドを省略します。次に、CourseWork リクエストで dueDate フィールドまたは scheduledTime フィールドを指定します。dueDate が既存の採点期間の日付範囲に含まれる場合、Classroom はその採点期間 ID を CourseWork に設定します。dueDate フィールドが指定されていない場合、Classroom は scheduledTime フィールドに基づいて gradingPeriodId を決定します。どちらのフィールドも指定されていない場合、または成績期間の日付範囲が一致しない場合、CourseWork に gradingPeriodId は設定されません。

2. カスタムの関連付けられた採点期間

dueDate または scheduledTime に対応する採点期間とは異なる採点期間にコースワークを関連付ける場合は、コースワークの作成時または更新時に gradingPeriodId フィールドを手動で設定できます。gradingPeriodId を手動で設定した場合、Classroom は日付ベースの採点期間の自動関連付けを行いません。

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 を含める必要があります。これにより、Classroom は新しい 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()
前へ
成績を設定、更新する
次へ
制限事項