Zarządzanie okresami oceniania przy użyciu interfejsu Classroom API

Z tego przewodnika dowiesz się, jak używać punktów końcowych okresów oceniania w interfejsie Google Classroom API.

Przegląd

Okresy oceniania są tworzone w celu uporządkowania zadań domowych, testów i projektów według określonych zakresów dat. Interfejs Classroom API umożliwia programistom tworzenie, modyfikowanie i odczytywanie okresów oceniania w Classroom w imieniu administratorów i nauczycieli. Możesz też używać interfejsu Classroom API do ustawiania okresów oceniania w CourseWork.

Interfejs Classroom API udostępnia 2 punkty końcowe umożliwiające odczytywanie i zapisywanie informacji o okresie oceniania w ramach zajęć:

  • GetGradingPeriodSettings: umożliwia odczytanie ustawień okresu oceniania w ramach zajęć.
  • UpdateGradingPeriodSettings: pozwala zarządzać ustawieniami okresu oceniania w ramach zajęć przez dodawanie, modyfikowanie i usuwanie okresów oceniania oraz stosowanie skonfigurowanych okresów oceniania do wszystkich istniejących zadań.

Wymagania dotyczące licencji

Zmienianie ustawień okresu oceniania w ramach zajęć

Aby tworzyć, modyfikować lub usuwać okresy oceniania na zajęciach przy użyciu punktu końcowego UpdateGradingPeriodSettings, muszą być spełnione te warunki:

Odczytywanie ustawień okresu oceniania w ramach zajęć

Administratorzy domeny i nauczyciele zajęć mogą odczytywać ustawienia okresu oceniania niezależnie od przypisanej licencji. Oznacza to, że żądania wysyłane do punktu końcowego GetGradingPeriodSettings są dozwolone w imieniu każdego administratora domeny lub nauczyciela.

Ustawianie identyfikatora okresu oceniania w CourseWork

Nauczyciele mogą dodawać gradingPeriodId podczas tworzenia lub aktualizowania zadań za pomocą interfejsu API, niezależnie od przypisanej licencji.

Sprawdź, czy użytkownik spełnia wymagania, aby skonfigurować okresy oceniania

Żądania do punktu końcowego checkGradingPeriodsSetupEligibility są dozwolone w imieniu każdego administratora lub nauczyciela. Określa, czy użytkownik może modyfikować okresy oceniania w ramach zajęć.

Wymagania wstępne

Ten przewodnik zawiera przykłady kodu w Pythonie. Zakładamy w nim, że masz:

  • Projekt Google Cloud. Możesz to zrobić, postępując zgodnie z instrukcjami w krótkim wprowadzeniu do Pythona.
  • Do ekranu zgody OAuth Twojego projektu dodaliśmy te zakresy:
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • Identyfikator zajęć, w ramach których należy zmodyfikować okresy oceniania. Właściciel zajęć musi mieć licencję Google Workspace for Education Plus.
  • Dostęp do danych logowania nauczyciela lub administratora z licencją na Google Workspace for Education Plus. Aby utworzyć lub zmodyfikować CourseWork, potrzebujesz danych logowania nauczyciela. Administratorzy nie mogą tworzyć ani modyfikować zadania CourseWork, jeśli nie są nauczycielami.

Zarządzaj zasobem GradingPeriodSettings

Zasób GradingPeriodSettings zawiera listę poszczególnych elementów GradingPeriods i pole wartości logicznej applyToExistingCoursework.

Lista GradingPeriods zawiera wszystkie okresy oceniania w danych zajęciach. Musisz podać tytuł, datę rozpoczęcia i datę zakończenia każdego okresu oceniania na liście. Każdy okres oceniania w ramach kursu musi mieć unikalny tytuł, a daty rozpoczęcia i zakończenia różnych okresów oceniania nie mogą się pokrywać. Każdy okres oceniania będzie miał własny identyfikator przypisany do interfejsu API Classroom.

Wartość logiczna applyToExistingCoursework jest niezmiennym ustawieniem, które umożliwia porządkowanie utworzonych wcześniej narzędzi CourseWork w okresy oceniania bez konieczności tworzenia osobnego wywołania interfejsu API w celu modyfikacji gradingPeriodId dla każdego obiektu CourseWork. Jeśli wartość to True, Classroom automatycznie ustawi gradingPeriodId we wszystkich istniejących zadaniach CourseWork, jeśli courseWork.dueDate mieści się w datach rozpoczęcia i zakończenia bieżącego okresu oceniania. Jeśli w zadaniu nie ma ustawionego terminu, Classroom użyje courseWork.scheduledTime. Jeśli nie ma żadnego z tych pól lub nie ma dopasowania w zakresie dat rozpoczęcia i zakończenia bieżącego okresu oceniania, zadanie CourseWork nie zostanie powiązane z żadnym okresem oceniania.

Określanie, czy użytkownik może modyfikować ustawienia okresu oceniania w ramach zajęć

Tworzenie i modyfikowanie okresów oceniania w Classroom jest dostępne tylko dla użytkowników z określoną licencją, dlatego interfejs Classroom API udostępnia punkt końcowy checkGradingPeriodsSetupEligibility, który pomaga aktywnie określić, czy użytkownik może wysyłać żądania do punktu końcowego 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

Dodaj okresy oceniania

Gdy masz pewność, że użytkownik ma licencję wymaganą do modyfikowania ustawień okresu oceniania w ramach zajęć, możesz zacząć wysyłać żądania do punktu końcowego UpdateGradingPeriodSettings. Wszelkie zmiany w zasobie GradingPeriodSettings są wprowadzane przy użyciu punktu końcowego UpdateGradingPeriodSettings niezależnie od tego, czy dodajesz poszczególne okresy oceniania, zmieniasz istniejące okresy oceniania czy usuwasz okres oceniania.

Python

W poniższym przykładzie zasób gradingPeriodSettings został zmodyfikowany tak, aby zawierał 2 okresy oceniania. Wartość logiczna applyToExistingCoursework jest ustawiona na True. Powoduje to modyfikację pola gradingPeriodId w istniejących zadaniach edukacyjnych, które mieszczą się w datach rozpoczęcia i zakończenia danego okresu oceniania. Pamiętaj, że updateMask zawiera oba pola. Zapisz identyfikatory poszczególnych okresów oceniania po ich zwróceniu w odpowiedzi. W razie potrzeby użyj tych identyfikatorów, aby zaktualizować okresy oceniania.

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

Odczytywanie ustawień okresu oceniania

Obiekty GradingPeriodSettings są odczytywane przy użyciu punktu końcowego GetGradingPeriodSettings. Każdy użytkownik, bez względu na licencję, może odczytywać ustawienia okresów oceniania w ramach zajęć.

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

Dodaj do listy pojedynczy okres oceniania

Aktualizacje poszczególnych okresów oceniania należy przeprowadzać zgodnie ze wzorcem odczyt, modyfikacja i zapis. Oznacza to, że trzeba przestrzegać pewnych zaleceń.

  1. Odczytaj listę okresów oceniania w zasobie GradingPeriodSettings za pomocą punktu końcowego GetGradingPeriodSettings.
  2. Wprowadź wybrane zmiany na liście okresów oceniania.
  3. Wyślij listę nowych okresów oceniania w prośbie na adres UpdateGradingPeriodSettings.

Pomoże Ci to zadbać o to, aby tytuły poszczególnych okresów oceniania w ramach poszczególnych zajęć były różne, a data rozpoczęcia i zakończenia okresów oceniania nie będą się pokrywać.

Pamiętaj o tych regułach dotyczących aktualizowania listy okresów oceniania:

  1. Okresy oceniania dodane do listy bez identyfikatora są traktowane jako dodatki.
  2. Okresy oceniania, których nie ma na liście, są uznawane za usunięcia.
  3. Okresy oceniania z dotychczasowym identyfikatorem, ale zmodyfikowane dane, są uznawane za zmiany. Niezmodyfikowane właściwości pozostają bez zmian.
  4. Okresy oceniania z nowymi lub nieznanymi identyfikatorami są uznawane za błędy.

Python

Kod poniżej będzie opierać się na przykładzie w tym przewodniku. Zostanie utworzony nowy okres oceniania o nazwie „Lato”. Wartość logiczna applyToExistingCoursework jest ustawiona w treści żądania na False.

Aby to zrobić, odczytywany jest bieżący GradingPeriodSettings, do listy dodawany jest nowy okres oceniania, a wartość logiczna applyToExistingCoursework jest ustawiona na False. Pamiętaj, że żadne okresy oceniania, które zostały już zastosowane do istniejących zadań CourseWork, nie zostaną usunięte. W poprzednim przykładzie okresy oceniania „Semester 1” i „Semester 2” zostały już zastosowane do istniejących zadań CourseWork i nie zostaną usunięte z CourseWork, jeśli w kolejnych prośbach ustawienie applyToExistingCoursework ma wartość Fałsz.

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

Przydatne wskazówki dotyczące pola wartości logicznej applyToExistingCoursework

Pamiętaj, że wartość logiczna applyToExistingCoursework jest zachowana, co oznacza, że jeśli wartość logiczna została ustawiona na True w poprzednim wywołaniu interfejsu API i nie została zmieniona, późniejsze aktualizacje okresów oceniania zostaną zastosowane do istniejącego obiektu CourseWork.

Pamiętaj, że jeśli zmienisz tę wartość logiczną z True na False w żądaniu utworzonym na UpdateGradingPeriodSettings, tylko nowe zmiany, które wprowadzisz w GradingPeriodSettings, nie zostaną zastosowane do istniejących plików CourseWork. Informacje o okresie oceniania zastosowane do CourseWork w poprzednich wywołaniach interfejsu API, gdy wartość logiczna była ustawiona na True, nie zostaną usunięte. Warto myśleć o tym ustawieniu wartości logicznej, że obsługuje ono łączenie istniejących CourseWork ze skonfigurowanymi okresami oceniania, ale nie obsługuje usuwania istniejących powiązań między CourseWork i skonfigurowanymi okresami oceniania.

Jeśli usuniesz lub zmienisz nazwę okresu oceniania, zmiany te zostaną zastosowane we wszystkich istniejących zadaniach CourseWork, niezależnie od ustawienia wartości logicznej applyToExistingCoursework.

Aktualizowanie okresu oceniania na liście

Aby zmodyfikować niektóre dane powiązane z istniejącym okresem oceniania, umieść na liście ze zmodyfikowanymi danymi jego identyfikator.

Python

W tym przykładzie data zakończenia okresu oceniania „Lato” zostanie zmieniona. Pole applyToExistingCoursework zostanie ustawione na True. Pamiętaj, że ustawienie tej wartości logicznej na True spowoduje zastosowanie wszystkich skonfigurowanych okresów oceniania w istniejących zajęciach CourseWork. W poprzednim żądaniu do interfejsu API wartość logiczna została ustawiona na False, więc okres oceniania „Lato” nie został zastosowany do istniejącego obiektu CourseWork. Gdy to pole wartości logicznej jest ustawione na True, okres oceniania „Lato” zostanie zastosowany do wszystkich istniejących elementów CourseWork, które pasują.

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

Usuwanie pojedynczego okresu oceniania

Aby usunąć okres oceniania, pomiń go na liście. Pamiętaj, że usunięcie okresu oceniania spowoduje też usunięcie wszelkich odwołań do tego okresu w CourseWork (bez względu na ustawienie applyToExistingCoursework).

Python

Jeśli chcesz kontynuować przykład z tego przewodnika, pomiń okres oceniania „Lato”, aby go usunąć.

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

Zarządzanie polem gradingPeriodId w CourseWork

Zasób CourseWork zawiera pole gradingPeriodId. Za pomocą punktów końcowych CourseWork możesz odczytywać i zapisywać okres oceniania powiązany z danym zadaniem. Powiązaniem możesz zarządzać na 3 sposoby:

  • automatyczne powiązanie okresu oceniania na podstawie daty.
  • niestandardowy powiązany okres oceniania
  • brak powiązania okresu oceniania

1. Powiązanie okresu oceniania opartego na dacie

Tworząc CourseWork, możesz zezwolić Classroom na zarządzanie powiązaniem okresu oceniania. Aby to zrobić, pomiń pole gradingPeriodId w żądaniu CourseWork. Następnie określ pola dueDate lub scheduledTime w żądaniu CourseWork. Jeśli dueDate należy do istniejącego zakresu dat okresu oceniania, Classroom ustawi identyfikator tego okresu na stronie CourseWork. Jeśli pole dueDate nie jest określone, Classroom określi gradingPeriodId na podstawie pola scheduledTime. Jeśli żadne z tych pól nie zostanie określone lub nie ma pasującego zakresu dat okresu oceniania, w zadaniu CourseWork nie zostanie ustawiony żaden element gradingPeriodId.

2. Niestandardowy powiązany okres oceniania

Jeśli chcesz powiązać CourseWork z innym okresem oceniania niż ten, który jest zgodny z dueDate lub scheduledTime, możesz ręcznie ustawić pole gradingPeriodId podczas tworzenia lub aktualizowania obiektu CourseWork. Jeśli ręcznie ustawisz gradingPeriodId, Classroom nie utworzy automatycznego powiązania okresu oceniania na podstawie daty.

3. Brak powiązania okresu oceniania

Jeśli nie chcesz, aby obiekt CourseWork był powiązany z jakimkolwiek okresem oceniania, ustaw pole gradingPeriodId w żądaniu CourseWork na pusty ciąg znaków (gradingPeriodId: "").

Co się stanie z identyfikatorem okresu oceniania w przypadku aktualizacji terminu?

Jeśli aktualizujesz pole dueDate CourseWork i chcesz zachować powiązanie okresu oceniania lub nie ma go wcale, musisz uwzględnić dueDate i gradingPeriodId w elemencie updateMask i treści żądania. Dzięki temu Classroom nie zastępuje wartości gradingPeriodId okresem oceniania zgodnym z nowym 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()