Wprowadzenie do ocen cząstkowych

rubric to szablon, którego nauczyciele mogą używać do oceniania uczniów. przesłanych treści. Interfejs API Classroom pozwala działać w imieniu: aby nauczyciel zarządzał ocenami cząstkowymi.

Wyświetlanie oceny cząstkowej w interfejsie Classroom Rysunek 1. Widok przykładowej oceny cząstkowej w projekcie w Classroom.

W tym przewodniku opisano podstawowe pojęcia i funkcje interfejsu Rubrics API. Zobacz tych artykułach w Centrum pomocy, ogólnych struktura oceny cząstkowej i jej ocena cząstkowa jest oceniana w interfejsie Classroom.

Wymagania wstępne

W tym przewodniku przyjęto założenie, że masz:

Autoryzacja danych logowania w aplikacji komputerowej

Aby uwierzytelnić się jako użytkownik i uzyskać dostęp do jego danych w aplikacji, musisz: utwórz co najmniej jeden identyfikator klienta OAuth 2.0. Identyfikator klienta służy do identyfikowania z jedną aplikacją na serwery OAuth Google. Jeśli Twoja aplikacja działa na wielu platformach, musisz utworzyć oddzielny identyfikator klienta dla każdej platformy.

  1. Otwórz stronę Dane logowania do Google Cloud w konsoli Google Cloud.
  2. Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
  3. Kliknij Typ aplikacji > Aplikacja komputerowa.
  4. W polu Nazwa wpisz nazwę danych logowania. Ta nazwa jest tylko widoczne w konsoli Google Cloud. Na przykład „Klient podglądu ocen cząstkowych”.
  5. Kliknij Utwórz. Pojawi się ekran z utworzonym klientem OAuth i nowym Identyfikator klienta i tajny klucz klienta.
  6. Kliknij Pobierz JSON, a następnie OK. Nowo utworzone dane logowania pojawi się w sekcji Identyfikatory klientów OAuth 2.0.
  7. Zapisz pobrany plik JSON jako credentials.json i przenieś go do w katalogu roboczym.
  8. Kliknij Utwórz dane logowania > Klucz interfejsu API i zanotuj klucz interfejsu API.

Więcej informacji znajdziesz w artykule Tworzenie danych logowania.

Skonfiguruj zakresy protokołu OAuth

W zależności od istniejących zakresów protokołu OAuth w projekcie może być konieczne skonfigurowanie dodatkowe zakresy.

  1. Otwórz Ekran zgody OAuth.
  2. Kliknij Edytuj aplikację > Zapisz i kontynuuj, aby przejść do ekranu Zakresy.
  3. Kliknij Dodaj lub usuń zakresy.
  4. Dodaj te zakresy, jeśli jeszcze ich nie masz:
    • https://www.googleapis.com/auth/classroom.coursework.students
    • https://www.googleapis.com/auth/classroom.courses
  5. Następnie kliknij Aktualizuj > Zapisz i kontynuuj > Zapisz i kontynuuj > Powrót do panelu.

Więcej informacji znajdziesz w artykule Konfigurowanie ekranu zgody OAuth. i innych.

Zakres classroom.coursework.students zapewnia uprawnienia do odczytu i zapisu w oceny cząstkowe (wraz z dostępem do CourseWork) oraz zakres classroom.courses umożliwia kursy czytania i pisania.

Zakresy wymagane dla danej metody są wymienione w dokumentacji referencyjnej dla danej metody. Zobacz zakresy autoryzacji (courses.courseWork.rubrics.create) . Wszystkie zakresy Classroom możesz wyświetlić w zakresach protokołu OAuth 2.0 dla Google interfejsów API. Nie wspomniano tutaj o ocenach cząstkowych, ponieważ interfejs API jest nadal w wersji przedpremierowej.

Konfigurowanie przykładu

W katalogu roboczym zainstaluj bibliotekę klienta Google dla Pythona:

pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

Utwórz plik o nazwie main.py, który utworzy bibliotekę klienta i autoryzuje użytkownika za pomocą klucza interfejsu API zamiast klucza YOUR_API_KEY:

import json
import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# If modifying these scopes, delete the file token.json.
SCOPES = ['https://www.googleapis.com/auth/classroom.courses',
          'https://www.googleapis.com/auth/classroom.coursework.students']

def build_authenticated_service(api_key):
    """Builds the Classroom service."""
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'credentials.json', SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run.
        with open('token.json', 'w') as token:
            token.write(creds.to_json())

    try:
        # Build the Classroom service.
        service = build(
            serviceName="classroom",
            version="v1",
            credentials=creds,
            discoveryServiceUrl=f"https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key={api_key}")

        return service

    except HttpError as error:
        print('An error occurred: %s' % error)

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

Uruchom skrypt za pomocą polecenia python main.py. Powinien pojawić się komunikat z prośbą o zalogowanie się i zgody na zakresy protokołu OAuth.

Utwórz zadanie

Ocena cząstkowa jest powiązana z projektem (inaczej CourseWork) i ma wartość tylko istotne w kontekście tego elementu (CourseWork). Oceny cząstkowe mogą tworzyć tylko projekt Google Cloud, który utworzył nadrzędny element CourseWork. Cele: w tym przewodniku utwórz nowy projekt CourseWork ze skryptem.

Dodaj do main.py:

def get_latest_course(service):
    """Retrieves the last created course."""
    try:
        response = service.courses().list(pageSize=1).execute()
        courses = response.get("courses", [])
        if not courses:
            print("No courses found. Did you remember to create one in the UI?")
            return
        course = courses[0]
        return course

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

def create_coursework(service, course_id):
    """Creates and returns a sample coursework."""
    try:
        coursework = {
            "title": "Romeo and Juliet analysis.",
            "description": """Write a paper arguing that Romeo and Juliet were
                                time travelers from the future.""",
            "workType": "ASSIGNMENT",
            "state": "PUBLISHED",
        }
        coursework = service.courses().courseWork().create(
            courseId=course_id, body=coursework).execute()
        return coursework

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Teraz zaktualizuj main.py, aby pobrać course_id klasy testowej, którą właśnie wysłałeś utwórz nowy przykładowy projekt i pobierz jego coursework_id:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    course = get_latest_course(service)
    course_id = course.get("id")
    course_name = course.get("name")
    print(f"'{course_name}' course ID: {course_id}")

    coursework = create_coursework(service, course_id)
    coursework_id = coursework.get("id")
    print(f"Assignment created with ID {coursework_id}")

    #TODO(developer): Save the printed course and coursework IDs.

Zapisz course_id i coursework_id. Są one wymagane w przypadku wszystkich ocen cząstkowych CRUD operacji.

Masz teraz w Classroom przykładowy CourseWork.

Wyświetlanie projektu w interfejsie Classroom Rysunek 2. Widok przykładowego projektu w Classroom.

Tworzenie oceny cząstkowej

Teraz możesz zacząć zarządzać ocenami cząstkowymi.

Ocena cząstkowa można utworzyć w dokumencie CourseWork za pomocą wywołania Create zawierającego pełną ocenę cząstkową z pominiętymi właściwościami identyfikatorów kryteriów i poziomów. (są one generowane podczas tworzenia).

Dodaj do main.py tę funkcję:

def create_rubric(service, course_id, coursework_id):
    """Creates an example rubric on a coursework."""
    try:
        body = {
            "criteria": [
                {
                    "title": "Argument",
                    "description": "How well structured your argument is.",
                    "levels": [
                        {"title": "Convincing",
                         "description": "A compelling case is made.", "points": 30},
                        {"title": "Passable",
                         "description": "Missing some evidence.", "points": 20},
                        {"title": "Needs Work",
                         "description": "Not enough strong evidence..", "points": 0},
                    ]
                },
                {
                    "title": "Spelling",
                    "description": "How well you spelled all the words.",
                    "levels": [
                        {"title": "Perfect",
                         "description": "No mistakes.", "points": 20},
                        {"title": "Great",
                         "description": "A mistake or two.", "points": 15},
                        {"title": "Needs Work",
                         "description": "Many mistakes.", "points": 5},
                    ]
                },
                {
                    "title": "Grammar",
                    "description": "How grammatically correct your sentences are.",
                    "levels": [
                        {"title": "Perfect",
                         "description": "No mistakes.", "points": 20},
                        {"title": "Great",
                         "description": "A mistake or two.", "points": 15},
                        {"title": "Needs Work",
                         "description": "Many mistakes.", "points": 5},
                    ]
                },
            ]
        }

        rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id, courseWorkId=coursework_id, body=body,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()
        print(f"Rubric created with ID {rubric.get('id')}")
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Następnie zaktualizuj i uruchom polecenie main.py, aby utworzyć przykładową ocenę cząstkową za pomocą: Course i CourseWork z wcześniejszych identyfikatorów:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    rubric = create_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(rubric, indent=4))

Oto kilka punktów na temat reprezentacji ocen cząstkowych:

  • Kolejność kryteriów i poziomów jest odzwierciedlana w interfejsie Classroom.
  • Ocenione poziomy (mające właściwość points) muszą być sortowane według punktów w kolejności rosnącej lub malejącej (nie mogą być uporządkowane losowo).
  • Nauczyciele mogą ponownie sortować kryteria i poziomy z oceną (ale nie mają oceny poziomów) w interfejsie, co wpływa na ich kolejność w danych.

Zapoznaj się z ograniczeniami, aby poznać więcej zastrzeżeń dotyczących struktury ocen cząstkowych.

W interfejsie powinna być widoczna ocena cząstkowa projektu.

Wyświetlanie oceny cząstkowej w interfejsie Classroom Rysunek 3. Widok przykładowej oceny cząstkowej w projekcie w Classroom.

Czytanie oceny cząstkowej

Oceny cząstkowe można odczytywać za pomocą standardowych metod List i Get.

Projekt może mieć maksymalnie 1 ocenę cząstkową, więc List może wydawać się, nie jest intuicyjne, ale jest przydatne, jeśli nie masz jeszcze identyfikatora oceny cząstkowej. Jeśli nie ma oceny cząstkowej powiązanej z elementem CourseWork, odpowiedź List jest pusta.

Dodaj do main.py tę funkcję:

def get_rubric(service, course_id, coursework_id):
    """
    Get the rubric on a coursework. There can only be at most one.
    Returns null if there is no rubric.
    """
    try:
        response = service.courses().courseWork().rubrics().list(
            courseId=course_id, courseWorkId=coursework_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()

        rubrics = response.get("rubrics", [])
        if not rubrics:
            print("No rubric found for this assignment.")
            return
        rubric = rubrics[0]
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Zaktualizuj i uruchom polecenie main.py, aby pobrać dodaną ocenę cząstkową:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(rubric, indent=4))

    #TODO(developer): Save the printed rubric ID.

Zanotuj właściwość id w ocenach cząstkowych, aby przejść do kolejnych kroków.

Get działa dobrze, gdy masz identyfikator oceny cząstkowej. Używanie w funkcji elementu Get może wyglądać tak:

def get_rubric(service, course_id, coursework_id, rubric_id):
    """
    Get the rubric on a coursework. There can only be at most one.
    Returns a 404 if there is no rubric.
    """
    try:
        rubric = service.courses().courseWork().rubrics().get(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Jeśli nie ma wartości cząstkowej, ta implementacja zwraca błąd 404.

Aktualizowanie oceny cząstkowej

Aktualizowanie oceny cząstkowej odbywa się za pomocą wywołań Patch. Ze względu na złożoną strukturę oceny cząstkowej, aktualizacje muszą być przeprowadzane za pomocą wzorca odczytu, modyfikacji i zapisu, przy czym zastąpiono całą właściwość criteria.

Oto reguły aktualizacji:

  1. Kryteria lub poziomy dodane bez identyfikatora są brane pod uwagę dodatków.
  2. Uwzględniane są kryteria lub poziomy, których nie ma wcześniej usunięć.
  3. Uwzględniane są kryteria lub poziomy z istniejącym identyfikatorem, ale zmodyfikowanymi danymi. zmiany. Niezmodyfikowane właściwości pozostają bez zmian.
  4. Kryteria lub poziomy podane za pomocą nowego lub nieznanego identyfikatora są brane pod uwagę. .
  5. Kolejność nowych kryteriów i poziomów jest uznawana za nową kolejność w interfejsie (z wspomnianymi ograniczeniami).

Dodaj funkcję aktualizowania oceny cząstkowej:

def update_rubric(service, course_id, coursework_id, rubric_id, body):
    """
    Updates the rubric on a coursework.
    """
    try:
        rubric = service.courses().courseWork().rubrics().patch(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            body=body,
            updateMask='criteria',
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

W tym przykładzie pole criteria jest określone na potrzeby modyfikacji za pomocą atrybutu updateMask

Następnie zmodyfikuj main.py, aby wprowadzić zmianę w każdej z wymienionych wcześniej aktualizacji. reguły:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    # Get the latest rubric.
    rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    criteria = rubric.get("criteria")
    """
    The "criteria" property should look like this:
    [
        {
            "id": "NkEyMdMyMzM2Nxkw",
            "title": "Argument",
            "description": "How well structured your argument is.",
            "levels": [
                {
                    "id": "NkEyMdMyMzM2Nxkx",
                    "title": "Convincing",
                    "description": "A compelling case is made.",
                    "points": 30
                },
                {
                    "id": "NkEyMdMyMzM2Nxky",
                    "title": "Passable",
                    "description": "Missing some evidence.",
                    "points": 20
                },
                {
                    "id": "NkEyMdMyMzM2Nxkz",
                    "title": "Needs Work",
                    "description": "Not enough strong evidence..",
                    "points": 0
                }
            ]
        },
        {
            "id": "NkEyMdMyMzM2Nxk0",
            "title": "Spelling",
            "description": "How well you spelled all the words.",
            "levels": [...]
        },
        {
            "id": "NkEyMdMyMzM2Nxk4",
            "title": "Grammar",
            "description": "How grammatically correct your sentences are.",
            "levels": [...]
        }
    ]
    """

    # Make edits. This example will make one of each type of change.

    # Add a new level to the first criteria. Levels must remain sorted by
    # points.
    new_level = {
        "title": "Profound",
        "description": "Truly unique insight.",
        "points": 50
    }
    criteria[0]["levels"].insert(0, new_level)

    # Remove the last criteria.
    del criteria[-1]

    # Update the criteria titles with numeric prefixes.
    for index, criterion in enumerate(criteria):
        criterion["title"] = f"{index}: {criterion['title']}"

    # Resort the levels from descending to ascending points.
    for criterion in criteria:
        criterion["levels"].sort(key=lambda level: level["points"])

    # Update the rubric with a patch call.
    new_rubric = update_rubric(
        service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID, YOUR_RUBRIC_ID, rubric)

    print(json.dumps(new_rubric, indent=4))

Zmiany powinny być już widoczne u nauczyciela w Classroom.

Widok zaktualizowanej oceny cząstkowej w interfejsie Classroom Rysunek 4. Widok zaktualizowanej oceny cząstkowej.

Wyświetlanie przesłanych treści z oceną cząstkową

Obecnie prace przesłane przez uczniów nie mogą być oceniane za pomocą oceny cząstkowej przez interfejs API, ale może odczytywać oceny cząstkowe za zadanie, które zostało ocenione za pomocą oceny cząstkowej w interfejsu Classroom.

Jako uczeń w interfejsie Classroom ukończ i oddaj przykładowy projekt. Następnie jako nauczyciel możesz ręcznie ocenić projekt za pomocą oceny cząstkowej.

Wyświetlanie oceny cząstkowej w interfejsie Classroom Rysunek 5. Widok cząstkowy nauczyciela podczas oceniania.

Zadania uczniów, które zostały ocenione za pomocą oceny cząstkowej, zawierają 2 nowe właściwości: draftRubricGrades i assignedRubricGrades, reprezentujące punkty i poziomy wybrane przez nauczyciela w wersji roboczej i przypisanej ocenie; stanów.

Dodatkowo zadania przesłane przez uczniów z powiązaną oceną cząstkową zawierają też rubricId nawet przed wystawieniem oceny. To jest ostatnia ocena cząstkowa powiązana z CourseWork. Ta wartość może się zmienić, jeśli nauczyciele usuną i ponownie utworzysz ocena cząstkowa.

Istniejących studentSubmissions.Get oraz studentSubmissions.List metod, aby wyświetlić ocenione zadania.

Dodaj do main.py tę funkcję, aby wyświetlić listę zadań przesłanych przez uczniów:

def get_latest_submission(service, course_id, coursework_id):
    """Retrieves the last submission for an assignment."""
    try:
        response = service.courses().courseWork().studentSubmissions().list(
            courseId = course_id,
            courseWorkId = coursework_id,
            pageSize=1,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()
        submissions = response.get("studentSubmissions", [])
        if not submissions:
            print(
                """No submissions found. Did you remember to turn in and grade
                   the assignment in the UI?""")
            return
        submission = submissions[0]
        return submission

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Następnie zaktualizuj i uruchom polecenie main.py, aby wyświetlić oceny przesłane.

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    submission = get_latest_submission(
        service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(submission, indent=4))

draftRubricGrades i assignedRubricGrades zawierają:

  • Wartość criterionId odpowiednich kryteriów oceny cząstkowej.
  • Pole points przypisane przez nauczyciela do każdego kryterium. Może to być ze strony ale nauczyciel mógł go też zastąpić.
  • levelId poziomu wybranego dla każdego kryterium. Jeśli nauczyciel nie wyraził zgody, wybrać poziom, ale nadal przypisuje mu punkty, nie ma adresu.

Te listy zawierają tylko pozycje spełniające kryteria kryteriów, których nauczyciel wybrany poziom lub punkty. Jeśli na przykład nauczyciel określi, że wchodzą w interakcję z jednym kryterium podczas oceniania, elementy draftRubricGrades oraz assignedRubricGrades zawiera tylko 1 element, nawet jeśli ocena cząstkowa ma wiele kryteria.

Usuwanie oceny cząstkowej

Ocenę cząstkową można usunąć przy użyciu standardowego żądania Delete. Następujący kod: pokazuje przykładową funkcję dla kompletności, ale ponieważ ocenianie już zostało nie możesz usunąć bieżącej oceny cząstkowej:

def delete_rubric(service, course_id, coursework_id, rubric_id):
    """Deletes the rubric on a coursework."""
    try:
        service.courses().courseWork().rubrics().delete(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Eksportowanie i importowanie ocen cząstkowych

Oceny cząstkowe można ręcznie wyeksportować do Google. arkuszy kalkulacyjnych do ponownego wykorzystania przez nauczycieli;

Oprócz określania kryteriów oceny cząstkowej w kodzie możesz tworzyć zaktualizować oceny cząstkowe z tych wyeksportowanych arkuszy, określając sourceSpreadsheetId w treści oceny cząstkowej zamiast criteria:

def create_rubric_from_sheet(service, course_id, coursework_id, sheet_id):
    """Creates an example rubric on a coursework."""
    try:
        body = {
            "sourceSpreadsheetId": sheet_id
        }

        rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id, courseWorkId=coursework_id, body=body,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()

        print(f"Rubric created with ID {rubric.get('id')}")
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

Prześlij opinię

Jeśli zauważysz problemy lub chcesz przekazać swoje uwagi, prześlij opinię.