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

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

概要

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

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

• 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 リストは、コース内の個々の採点期間をすべて表します。リスト内の個々の採点期間ごとに、タイトル、開始日、終了日を指定する必要があります。コース内の各採点期間には一意のタイトルを付ける必要があります。異なる採点期間の開始日と終了日を重複させることはできません。各採点期間には、Classroom API によって割り当てられた独自の識別子があります。

applyToExistingCoursework ブール値は永続的な設定です。この設定を使用すると、以前に作成した CourseWork を採点期間に整理できます。CourseWork ごとに gradingPeriodId を変更する個別の API 呼び出しを行う必要はありません。True に設定した場合、courseWork.dueDate が既存の採点期間の開始日から終了日内であれば、既存のすべての CourseWork に gradingPeriodId が自動的に設定されます。CourseWork で期限が設定されていない場合は、courseWork.scheduledTime が使用されます。いずれのフィールドも存在しない場合や、既存の採点期間の開始日と終了日の間に一致しない場合、CourseWork は採点期間に関連付けられません。

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

Classroom で採点期間を作成、変更できるのは特定のライセンスを持つユーザーのみであるため、Classroom API には checkGradingPeriodsSetupEligibility エンドポイントが用意されているため、ユーザーが UpdateGradingPeriodSettings エンドポイントにリクエストできるかどうかを事前に確認できます。

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

重要: UpdateGradingPeriodSettings リクエストには、削除しない採点期間の ID を必ず含めてください。

Python

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

これを行うには、現在の GradingPeriodSettings が読み取られ、新しい採点期間がリストに追加され、applyToExistingCoursework ブール値が False に設定されます。既存の CourseWork にすでに適用されている採点期間は削除されません。前の例では、「学期 1」と「学期 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 の採点期間に「Summer」の採点期間が適用されます。

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

このガイドの例を続けるには、採点期間「Summer」を省略して削除します。

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 に関連付けられた採点期間の読み取りと書き込みを行うことができます。この関連付けを管理するには、次の 3 つの方法があります。

• 日付ベースの採点期間の自動関連付け
• 関連するカスタムの採点期間
• 採点期間の関連付けはありません

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

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

2. 関連するカスタムの採点期間

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

3. 採点期間が関連付けられていません

CourseWork をどの採点期間にも関連付けたくない場合は、CourseWork リクエストの gradingPeriodId フィールドを空の文字列（gradingPeriodId: ""）に設定します。

期限が更新されると、採点期間 ID はどうなりますか？

CourseWork の dueDate フィールドを更新するときに、採点期間の関連付けをカスタムにするか、何もしないかを維持するには、updateMask とリクエスト本文に dueDate と gradingPeriodId を含める必要があります。これにより、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.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 フィールドを含めて、関連付けを維持するか、関連付けを行わないかを指定します。これにより、Classroom が新しい dueDate と一致するフィールドで gradingPeriodId フィールドをオーバーライドすることがなくなります。