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

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

概要

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

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

  • 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 ライセンスを持つ教師または管理者の認証情報へのアクセス。CourseWork を作成または変更するには、教師の認証情報が必要です。管理者がコースの教師でない場合、CourseWork を作成または変更することはできません。

GradingPeriodSettings リソースを管理する

GradingPeriodSettings リソースには、個々の GradingPeriods のリストと applyToExistingCoursework というブール値フィールドが含まれています。

GradingPeriods リストは、コース内の個々の採点期間を表します。リスト内の個々の評価期間ごとに、タイトル、開始日、終了日を指定する必要があります。コース内の各採点期間には一意のタイトルを付ける必要があります。また、異なる採点期間の開始日と終了日が重複することはできません。各評価期間には、Classroom API によって割り当てられた独自の ID があります。

applyToExistingCoursework ブール値は永続的な設定で、以前に作成した CourseWork を採点期間に整理できます。これにより、個々の CourseWork の gradingPeriodId を変更するために個別の API 呼び出しを行う必要がなくなります。True に設定されている場合、courseWork.dueDate が既存の採点期間の開始日と終了日の間にある場合、Classroom は既存のすべての課題に gradingPeriodId を自動的に設定します。CourseWork に期限が設定されていない場合、Classroom は 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

次の例では、2 つの採点期間が含まれるように gradingPeriodSettings リソースを変更しています。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 または不明な ID の採点期間は、エラーと見なされます。

Python

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

これを行うには、現在の GradingPeriodSettings が読み取られ、新しい採点期間がリストに追加され、applyToExistingCoursework ブール値が False に設定されます。既存の課題にすでに適用されている採点期間は削除されません。上の例では、「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 に設定されていたため、「夏」の採点期間が既存の課題に適用されませんでした。このブール値フィールドが 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 を含める必要があります。これにより、新しい dueDate に一致する採点期間で gradingPeriodId をオーバーライドしないように Classroom に指示します。

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