Quản lý giai đoạn chấm điểm bằng API Lớp học

Hướng dẫn này giải thích cách sử dụng các điểm cuối của giai đoạn chấm điểm trong Google Classroom API.

Tổng quan

Giai đoạn chấm điểm được tạo để sắp xếp bài tập về nhà, bài kiểm tra và dự án thành các phạm vi ngày cụ thể. API Lớp học cho phép nhà phát triển tạo, sửa đổi và đọc các giai đoạn chấm điểm trong Lớp học thay mặt cho quản trị viên và giáo viên. Bạn cũng có thể sử dụng API Lớp học để đặt khoảng thời gian chấm điểm cho Bài tập trên lớp.

Classroom API cung cấp 2 điểm cuối để đọc và ghi thông tin về giai đoạn chấm điểm trong một khoá học:

  • GetGradingPeriodSettings: Cho phép bạn đọc các chế độ cài đặt giai đoạn chấm điểm trong một khoá học.
  • UpdateGradingPeriodSettings: Cho phép bạn quản lý chế độ cài đặt giai đoạn chấm điểm trong một khoá học bằng cách thêm, sửa đổi và xoá các giai đoạn chấm điểm, đồng thời áp dụng các giai đoạn chấm điểm đã định cấu hình cho tất cả Bài tập trên lớp hiện có.

Yêu cầu về giấy phép và điều kiện

Sửa đổi chế độ cài đặt giai đoạn chấm điểm trong khoá học

Để tạo, sửa đổi hoặc xoá các giai đoạn chấm điểm trong một khoá học bằng cách sử dụng điểm cuối UpdateGradingPeriodSettings, bạn phải đáp ứng các điều kiện sau:

Đọc chế độ cài đặt giai đoạn chấm điểm trong khoá học

Quản trị viên miền và giáo viên của một khoá học có thể đọc chế độ cài đặt giai đoạn chấm điểm bất kể họ được chỉ định loại giấy phép nào. Điều này có nghĩa là các yêu cầu đến điểm cuối GetGradingPeriodSettings được cho phép thay mặt cho bất kỳ quản trị viên miền hoặc giáo viên nào.

Đặt mã giai đoạn chấm điểm trên CourseWork

Giáo viên của một khoá học có thể thêm gradingPeriodId khi tạo hoặc cập nhật Bài tập trên lớp bằng API, bất kể họ được chỉ định giấy phép nào.

Kiểm tra xem người dùng có đủ điều kiện thiết lập giai đoạn chấm điểm hay không

Các yêu cầu đến điểm cuối userProfiles.checkUserCapability được phép thay mặt cho bất kỳ quản trị viên hoặc giáo viên nào. Sử dụng thông tin này để xác định xem người dùng có thể sửa đổi giai đoạn chấm điểm hay không.

Điều kiện tiên quyết

Hướng dẫn này cung cấp các ví dụ về mã bằng Python và giả định rằng bạn đã:

  • Một dự án trên Google Cloud. Bạn có thể thiết lập một ứng dụng theo hướng dẫn trong bài viết Hướng dẫn nhanh về Python.
  • Thêm các phạm vi sau vào màn hình xin phép bằng OAuth của dự án:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • Mã nhận dạng của một khoá học mà bạn cần sửa đổi các giai đoạn chấm điểm. Chủ sở hữu khoá học phải có giấy phép Google Workspace for Education Plus.
  • Có thông tin đăng nhập của giáo viên hoặc quản trị viên có giấy phép Google Workspace for Education Plus. Bạn sẽ cần thông tin đăng nhập của giáo viên để tạo hoặc sửa đổi Bài tập trên lớp. Quản trị viên không thể tạo hoặc sửa đổi CourseWork nếu họ không phải là giáo viên trong khoá học.

Quản lý tài nguyên GradingPeriodSettings

Tài nguyên GradingPeriodSettings bao gồm danh sách các GradingPeriods riêng lẻ và một trường boolean có tên là applyToExistingCoursework.

Đảm bảo rằng mỗi GradingPeriods trong danh sách đều đáp ứng các yêu cầu sau:

  • Tiêu đề, ngày bắt đầu và ngày kết thúc: Mỗi giai đoạn chấm điểm phải có tiêu đề, ngày bắt đầu và ngày kết thúc.
  • Tiêu đề duy nhất: Mỗi giai đoạn chấm điểm phải có một tiêu đề duy nhất và không trùng với bất kỳ giai đoạn chấm điểm nào khác trong khoá học.
  • Ngày không trùng nhau: Mỗi giai đoạn chấm điểm không được có ngày bắt đầu hoặc ngày kết thúc trùng với bất kỳ giai đoạn chấm điểm nào khác trong khoá học.
  • Thứ tự thời gian: Các giai đoạn chấm điểm phải được liệt kê theo thứ tự thời gian dựa trên ngày bắt đầu và ngày kết thúc.

Mỗi giai đoạn chấm điểm sẽ được chỉ định một giá trị nhận dạng do Classroom API chỉ định khi được tạo.

Giá trị boolean applyToExistingCoursework là một chế độ cài đặt được duy trì, cho phép bạn sắp xếp CourseWork đã tạo trước đó thành các giai đoạn chấm điểm mà không cần thực hiện một lệnh gọi API riêng để sửa đổi gradingPeriodId cho từng CourseWork. Nếu bạn đặt thành True, Lớp học sẽ tự động đặt gradingPeriodId cho tất cả Bài tập trên lớp hiện có nếu courseWork.dueDate nằm trong khoảng thời gian từ ngày bắt đầu đến ngày kết thúc của một kỳ chấm điểm hiện có. Nếu bạn không đặt ngày đến hạn cho CourseWork, thì Lớp học sẽ sử dụng courseWork.scheduledTime. Nếu không có trường nào hoặc không có thông tin nào khớp với ngày bắt đầu và ngày kết thúc của một giai đoạn chấm điểm hiện có, thì CourseWork sẽ không được liên kết với bất kỳ giai đoạn chấm điểm nào.

Xác định xem người dùng có thể sửa đổi chế độ cài đặt giai đoạn chấm điểm trong khoá học hay không

Classroom API cung cấp điểm cuối userProfiles.checkUserCapability để giúp bạn chủ động xác định xem người dùng có thể đưa ra yêu cầu đến điểm cuối UpdateGradingPeriodSettings hay không.

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

Thêm giai đoạn chấm điểm

Giờ đây, khi bạn chắc chắn rằng người dùng đủ điều kiện sửa đổi chế độ cài đặt giai đoạn chấm điểm trong một khoá học, bạn có thể bắt đầu đưa ra yêu cầu đến điểm cuối UpdateGradingPeriodSettings. Mọi nội dung sửa đổi đối với tài nguyên GradingPeriodSettings đều được thực hiện bằng cách sử dụng điểm cuối UpdateGradingPeriodSettings, cho dù bạn đang thêm các khoảng thời gian chấm điểm riêng lẻ, sửa đổi các khoảng thời gian chấm điểm hiện có hay xoá một khoảng thời gian chấm điểm.

Python

Trong ví dụ sau, tài nguyên gradingPeriodSettings được sửa đổi để có 2 giai đoạn chấm điểm. Giá trị boolean applyToExistingCoursework được đặt thành True. Giá trị này sẽ sửa đổi gradingPeriodId trên mọi Bài tập trên lớp hiện có nằm trong khoảng thời gian từ ngày bắt đầu đến ngày kết thúc của một giai đoạn chấm điểm. Xin lưu ý rằng updateMask bao gồm cả hai trường. Lưu mã nhận dạng cho từng giai đoạn chấm điểm sau khi các mã này được trả về trong phản hồi. Bạn cần sử dụng các mã này để cập nhật giai đoạn chấm điểm nếu cần.

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

Đọc chế độ cài đặt giai đoạn chấm điểm

GradingPeriodSettings được đọc bằng cách sử dụng điểm cuối GetGradingPeriodSettings. Bất kỳ người dùng nào, bất kể có giấy phép hay không, đều có thể đọc các chế độ cài đặt về giai đoạn chấm điểm trong một khoá học.

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

Thêm một giai đoạn chấm điểm riêng lẻ vào danh sách

Bạn phải cập nhật từng giai đoạn chấm điểm theo mẫu đọc-sửa đổi-ghi. Điều này có nghĩa là bạn nên:

  1. Đọc danh sách các giai đoạn chấm điểm trong tài nguyên GradingPeriodSettings bằng cách sử dụng điểm cuối GetGradingPeriodSettings.
  2. Thực hiện các thay đổi đã chọn đối với danh sách giai đoạn chấm điểm.
  3. Gửi danh sách giai đoạn chấm điểm mới trong một yêu cầu đến UpdateGradingPeriodSettings.

Mẫu này sẽ giúp bạn đảm bảo rằng từng tiêu đề giai đoạn chấm điểm trong một khoá học là riêng biệt và không có sự trùng lặp giữa ngày bắt đầu và ngày kết thúc của các giai đoạn chấm điểm.

Hãy lưu ý những quy tắc sau đây về việc cập nhật danh sách giai đoạn chấm điểm:

  1. Các giai đoạn chấm điểm được thêm vào danh sách mà không có mã nhận dạng được coi là nội dung bổ sung.
  2. Những khoảng thời gian chấm điểm bị thiếu trong danh sách được coi là bị xoá.
  3. Các khoảng thời gian chấm điểm có mã nhận dạng hiện có nhưng dữ liệu đã được sửa đổi được coi là nội dung chỉnh sửa. Các thuộc tính không được sửa đổi sẽ giữ nguyên.
  4. Các giai đoạn chấm điểm có mã nhận dạng mới hoặc không xác định được coi là lỗi.

Python

Đoạn mã sau đây sẽ dựa trên ví dụ trong hướng dẫn này. Một khoảng thời gian chấm điểm mới được tạo với tiêu đề "Mùa hè". Giá trị boolean applyToExistingCoursework được đặt thành False trong nội dung yêu cầu.

Để làm việc này, GradingPeriodSettings hiện tại sẽ được đọc, một khoảng thời gian chấm điểm mới sẽ được thêm vào danh sách và giá trị boolean applyToExistingCoursework sẽ được đặt thành False. Xin lưu ý rằng mọi giai đoạn chấm điểm đã được áp dụng cho Bài tập trên lớp hiện có sẽ không bị xoá. Trong ví dụ trước, các khoảng thời gian chấm điểm "Học kỳ 1" và "Học kỳ 2" đã được áp dụng cho Bài tập trên lớp hiện có và sẽ không bị xoá khỏi Bài tập trên lớp nếu applyToExistingCoursework được đặt thành False trong các yêu cầu tiếp theo.

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

Các điểm hữu ích về trường boolean applyToExistingCoursework

Điều quan trọng cần lưu ý là giá trị boolean applyToExistingCoursework được duy trì, tức là nếu giá trị boolean được đặt thành True trong một lệnh gọi API trước đó và không thay đổi, thì các nội dung cập nhật tiếp theo cho giai đoạn chấm điểm sẽ được áp dụng cho CourseWork hiện có.

Xin lưu ý rằng nếu bạn thay đổi giá trị boolean này từ True thành False trong một yêu cầu đến UpdateGradingPeriodSettings, thì chỉ những thay đổi mới mà bạn đang thực hiện đối với GradingPeriodSettings sẽ không được áp dụng cho Bài tập hiện có. Mọi thông tin về khoảng thời gian chấm điểm được áp dụng cho Bài tập trong các lệnh gọi API trước đây khi giá trị boolean được đặt thành True sẽ không bị xoá. Một cách hữu ích để xem xét chế độ cài đặt boolean này là chế độ này hỗ trợ việc liên kết CourseWork hiện có với các khoảng thời gian chấm điểm mà bạn đã định cấu hình, nhưng không hỗ trợ việc xoá các mối liên kết hiện có giữa CourseWork và các khoảng thời gian chấm điểm đã định cấu hình.

Nếu bạn xoá hoặc thay đổi tiêu đề của một giai đoạn chấm điểm, những thay đổi đó sẽ được truyền qua tất cả Bài tập hiện có, bất kể chế độ cài đặt của giá trị boolean applyToExistingCoursework.

Cập nhật từng giai đoạn chấm điểm trong danh sách

Để sửa đổi một số dữ liệu liên quan đến một khoảng thời gian chấm điểm hiện có, hãy thêm mã nhận dạng của khoảng thời gian chấm điểm hiện có vào danh sách có dữ liệu đã sửa đổi.

Python

Trong ví dụ này, ngày kết thúc của kỳ chấm điểm "Mùa hè" sẽ được sửa đổi. Trường applyToExistingCoursework sẽ được đặt thành True. Xin lưu ý rằng việc đặt giá trị boolean này thành True sẽ áp dụng tất cả các khoảng thời gian chấm điểm đã định cấu hình cho Bài tập hiện có. Trong yêu cầu API trước đó, giá trị boolean được đặt thành False để khoảng thời gian chấm điểm "Mùa hè" không được áp dụng cho CourseWork hiện có. Giờ đây, khi trường boolean này được đặt thành True, khoảng thời gian chấm điểm "Mùa hè" sẽ được áp dụng cho tất cả CourseWork hiện có phù hợp.

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

Xoá một giai đoạn chấm điểm riêng lẻ

Để xoá một giai đoạn chấm điểm, hãy bỏ giai đoạn chấm điểm đó khỏi danh sách. Xin lưu ý rằng nếu một giai đoạn chấm điểm bị xoá, thì mọi thông tin tham chiếu đến giai đoạn chấm điểm đó trên Bài tập trên lớp cũng sẽ bị xoá, bất kể chế độ cài đặt applyToExistingCoursework.

Python

Để tiếp tục ví dụ trong hướng dẫn này, hãy bỏ qua khoảng thời gian chấm điểm "Mùa hè" để xoá khoảng thời gian đó.

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

Quản lý trường gradingPeriodId trên CourseWork

Tài nguyên CourseWork có một trường gradingPeriodId. Bạn có thể sử dụng các điểm cuối CourseWork để đọc và ghi khoảng thời gian chấm điểm được liên kết với một CourseWork. Có 3 cách để quản lý mối liên kết này:

  • tự động liên kết giai đoạn chấm điểm dựa trên ngày
  • giai đoạn chấm điểm tuỳ chỉnh được liên kết
  • không có mối liên kết với giai đoạn chấm điểm

1. Liên kết giai đoạn chấm điểm dựa trên ngày

Khi tạo Bài tập trên lớp, bạn có thể cho phép Lớp học xử lý việc liên kết giai đoạn chấm điểm cho bạn. Để thực hiện việc này, hãy bỏ qua trường gradingPeriodId trong yêu cầu CourseWork. Sau đó, hãy chỉ định các trường dueDate hoặc scheduledTime trong yêu cầu CourseWork. Nếu dueDate nằm trong phạm vi ngày của một khoảng thời gian chấm điểm hiện có, thì Lớp học sẽ đặt mã khoảng thời gian chấm điểm đó trên CourseWork. Nếu bạn không chỉ định trường dueDate, thì Classroom sẽ xác định gradingPeriodId dựa trên trường scheduledTime. Nếu bạn không chỉ định trường nào hoặc nếu không có phạm vi ngày của kỳ chấm điểm nào trùng khớp, thì sẽ không có gradingPeriodId nào được đặt trên CourseWork.

2. Giai đoạn chấm điểm tuỳ chỉnh được liên kết

Nếu muốn liên kết CourseWork với một khoảng thời gian chấm điểm khác với khoảng thời gian phù hợp với dueDate hoặc scheduledTime, bạn có thể đặt trường gradingPeriodId theo cách thủ công khi tạo hoặc cập nhật CourseWork. Nếu bạn đặt gradingPeriodId theo cách thủ công, Lớp học sẽ không thực hiện việc liên kết tự động giai đoạn chấm điểm dựa trên ngày.

3. Không có mối liên kết với giai đoạn chấm điểm

Nếu bạn không muốn CourseWork được liên kết với bất kỳ khoảng thời gian chấm điểm nào, hãy đặt trường gradingPeriodId trong yêu cầu CourseWork thành một chuỗi trống (gradingPeriodId: "").

Nếu đang sử dụng ngôn ngữ lập trình Go và không muốn đặt khoảng thời gian chấm điểm, bạn cũng nên thêm trường ForceSendFields vào nội dung yêu cầu. Với thư viện ứng dụng Go, các giá trị mặc định sẽ bị bỏ qua trong các yêu cầu API do có thẻ trường omitempty trên tất cả các trường. Trường ForceSendFields bỏ qua bước này và gửi chuỗi trống để cho biết rằng bạn không muốn đặt khoảng thời gian chấm điểm nào cho CourseWork đó. Hãy xem tài liệu về thư viện ứng dụng Go cho API của Google để biết thêm thông tin.

Go

courseWork := &classroom.CourseWork{
  Title: "Homework questions",
  WorkType: "ASSIGNMENT",
  State: "DRAFT",
  // ...other CourseWork fields...
  GradingPeriodId: "",
  ForceSendFields: []string{"GradingPeriodId"},
}

Điều gì sẽ xảy ra với mã giai đoạn chấm điểm nếu ngày đến hạn được cập nhật?

Nếu đang cập nhật trường dueDate CourseWork và muốn giữ lại mối liên kết tuỳ chỉnh hoặc không có giai đoạn chấm điểm, bạn nên thêm dueDate và gradingPeriodId vào updateMask và nội dung yêu cầu. Thao tác này sẽ yêu cầu Lớp học không thay thế gradingPeriodId bằng khoảng thời gian chấm điểm phù hợp với dueDate mới.

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()
Trước
Đặt và cập nhật điểm
Tiếp
Hạn chế