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.
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:
- Python w wersji 3.8.6 lub nowszej
- narzędzie do zarządzania pakietami pip;
- Projekt Google Cloud.
- konto Google Workspace for Education z Google Classroom włączono.
- Zajęcia testowe z co najmniej 1 testowym kontem ucznia. Jeśli nie masz zajęcia w Classroom, których możesz użyć do testowania; utwórz ją w interfejsie, dodaj ucznia egzaminacyjnego.
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.
- Otwórz stronę Dane logowania do Google Cloud w konsoli Google Cloud.
- Kliknij Utwórz dane logowania > Identyfikator klienta OAuth.
- Kliknij Typ aplikacji > Aplikacja komputerowa.
- 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”.
- Kliknij Utwórz. Pojawi się ekran z utworzonym klientem OAuth i nowym Identyfikator klienta i tajny klucz klienta.
- Kliknij Pobierz JSON, a następnie OK. Nowo utworzone dane logowania pojawi się w sekcji Identyfikatory klientów OAuth 2.0.
- Zapisz pobrany plik JSON jako
credentials.jsoni przenieś go do w katalogu roboczym. - 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.
- Otwórz Ekran zgody OAuth.
- Kliknij Edytuj aplikację > Zapisz i kontynuuj, aby przejść do ekranu Zakresy.
- Kliknij Dodaj lub usuń zakresy.
- Dodaj te zakresy, jeśli jeszcze ich nie masz:
https://www.googleapis.com/auth/classroom.coursework.studentshttps://www.googleapis.com/auth/classroom.courses
- 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.
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.
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:
- Kryteria lub poziomy dodane bez identyfikatora są brane pod uwagę dodatków.
- Uwzględniane są kryteria lub poziomy, których nie ma wcześniej usunięć.
- Uwzględniane są kryteria lub poziomy z istniejącym identyfikatorem, ale zmodyfikowanymi danymi. zmiany. Niezmodyfikowane właściwości pozostają bez zmian.
- Kryteria lub poziomy podane za pomocą nowego lub nieznanego identyfikatora są brane pod uwagę. .
- 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.
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.
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ść
criterionIdodpowiednich kryteriów oceny cząstkowej. - Pole
pointsprzypisane przez nauczyciela do każdego kryterium. Może to być ze strony ale nauczyciel mógł go też zastąpić. levelIdpoziomu 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ę.