rubric, öğretmenlerin öğrenci gönderimlerine not verirken kullanabileceği bir şablondur. Classroom API, bu değerlendirme ölçütlerini yönetmek için öğretmen adına işlem yapmanıza ve öğrenci gönderimlerindeki değerlendirme ölçütlerine göre verilen notları okumanıza olanak tanır.
Şekil 1. Classroom ödevindeki örnek puan anahtarı görünümü.
Bu kılavuzda, Rubrics API'nin temel kavramları ve işlevleri açıklanmaktadır. Bir değerlendirme ölçeğinin genel yapısı ve Classroom kullanıcı arayüzünde değerlendirme ölçeğiyle notlandırma hakkında bilgi edinmek için bu Yardım Merkezi makalelerine göz atın.
Ön koşullar
Bu rehberde, aşağıdakileri kullanabileceğiniz varsayılmaktadır:
- Python 3.8.6 veya üzeri
- pip paket yönetim aracı
- Google Cloud projesi.
- Google Classroom'un etkinleştirildiği ve Google Workspace for Education Plus lisansının atandığı bir Google Workspace for Education hesabı. Demo hesabınız yoksa yeni sürüme geçirilmiş bir geliştirici demo hesabı isteyebilirsiniz.
- En az bir test öğrenci hesabı içeren bir test sınıfı. Test için kullanabileceğiniz bir Classroom sınıfınız yoksa kullanıcı arayüzünde bir sınıf oluşturun ve test öğrencisi ekleyin.
Masaüstü uygulaması için kimlik bilgilerini yetkilendirme
Son kullanıcı olarak kimlik doğrulamak ve uygulamanızdaki kullanıcı verilerine erişmek için bir veya daha fazla OAuth 2.0 istemci kimliği oluşturmanız gerekir. İstemci kimliği, tek bir uygulamanın Google OAuth sunucularına tanıtılması için kullanılır. Uygulamanız birden fazla platformda çalışıyorsa her platform için ayrı bir istemci kimliği oluşturmanız gerekir.
- Google Cloud Console'da Google Cloud Kimlik bilgileri sayfasına gidin.
- Kimlik Bilgileri Oluştur > OAuth istemci kimliği'ni tıklayın.
- Uygulama türü > Masaüstü uygulaması'nı tıklayın.
- Ad alanına, kimliğin adını yazın. Bu ad yalnızca Google Cloud Console'da gösterilir. Örneğin, "Rubrics müşterisi".
- Oluştur'u tıklayın. Yeni istemci kimliğinizi ve istemci gizli anahtarınızı gösteren OAuth istemcisi oluşturuldu ekranı gösterilir.
- JSON'u indir'i ve ardından Tamam'ı tıklayın. Yeni oluşturulan kimlik bilgileri OAuth 2.0 istemci kimlikleri altında görünür.
- İndirilen JSON dosyasını
credentials.jsonolarak kaydedin ve dosyayı çalışma dizininize taşıyın. - Kimlik bilgileri oluştur > API anahtarı'nı tıklayın ve API anahtarını not edin.
Daha fazla bilgi için Erişim kimlik bilgileri oluşturma başlıklı makaleye bakın.
OAuth kapsamlarını yapılandırma
Projenizin mevcut OAuth kapsamlarına bağlı olarak ek kapsamlar yapılandırmanız gerekebilir.
- OAuth kullanıcı rızası ekranına gidin.
- Kapsamlar ekranına gitmek için Uygulamayı Düzenle > Kaydet ve Devam Et'i tıklayın.
- Kapsam Ekle veya Kaldır'ı tıklayın.
- Henüz yoksa aşağıdaki kapsamları ekleyin:
https://www.googleapis.com/auth/classroom.coursework.studentshttps://www.googleapis.com/auth/classroom.courses
- Ardından Güncelle > Kaydet ve Devam Et > Kaydet ve Devam Et > Kontrol Paneline Dön'ü tıklayın.
Daha fazla bilgi için OAuth kullanıcı rızası ekranını yapılandırma başlıklı makaleyi inceleyin.
classroom.coursework.students kapsamı, notlandırmalara okuma ve yazma erişimi (CourseWork erişiminin yanı sıra) sağlar. classroom.courses kapsamı ise kursları okumaya ve yazmaya olanak tanır.
Belirli bir yöntem için gereken kapsamlar, yöntemin referans dokümanında listelenir. Örnek olarak courses.courseWork.rubrics.create yetkilendirme kapsamlarına bakın. Tüm Classroom kapsamlarını Google API'leri için OAuth 2.0 Kapsamları bölümünde görebilirsiniz.
Örneği yapılandırma
Çalışma dizininizde Python için Google istemci kitaplığını yükleyin:
pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
YOUR_API_KEY yerine API anahtarınızı kullanarak istemci kitaplığını oluşturan ve kullanıcıyı yetkilendiren main.py adlı bir dosya oluşturun:
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)
Komut dosyasını python main.py kullanarak çalıştırın. Oturum açmanız ve OAuth kapsamlarını kabul etmeniz istenir.
Ödev oluşturma
Notlandırma sistemi, bir ödev veya CourseWork ile ilişkilendirilir ve yalnızca ilgili CourseWork bağlamında anlamlı olur. Başlıklar yalnızca üst CourseWork öğesini oluşturan Google Cloud projesi tarafından oluşturulabilir. Bu kılavuzun amaçları doğrultusunda, komut dosyası içeren yeni bir CourseWork ödevi oluşturun.
main.py alanına aşağıdakileri ekleyin:
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
Şimdi, yeni oluşturduğunuz test sınıfının course_id değerini almak için main.py değerini güncelleyin, yeni bir örnek ödev oluşturun ve ödevin coursework_id değerini alın:
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.
course_id ve coursework_id dosyalarını kaydedin. Bunlar, tüm puanlama ölçütleri CRUD işlemleri için gereklidir.
Artık Classroom'da bir CourseWork örneğiniz var.
Şekil 2. Classroom'daki örnek bir ödevin görünümü.
Kullanıcı uygunluğunu kontrol etme
Ölçüt oluşturmak ve güncellemek için hem istekte bulunan kullanıcının hem de ilgili kurs sahibinin Google Workspace for Education Plus lisansına sahip olması gerekir. Classroom, geliştiricilerin kullanıcıların erişebildiği özellikleri belirlemesine olanak tanımak için kullanıcı uygunluk uç noktası özelliğini destekler.
Test hesabınızın notlandırma özelliğine erişimi olduğunu onaylamak için main.py'ü güncelleyin ve çalıştırın:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
capability = service.userProfiles().checkUserCapability(
userId='me',
# Specify the preview version. checkUserCapability is
# supported in V1_20240930_PREVIEW and later.
previewVersion="V1_20240930_PREVIEW",
capability="CREATE_RUBRIC").execute()
if not capability.get('allowed'):
print('User ineligible for rubrics creation.')
# TODO(developer): in a production app, this signal could be used to
# proactively hide any rubrics related features from users or encourage
# them to upgrade to the appropriate license.
else:
print('User eligible for rubrics creation.')
Puan anahtarı oluşturma
Artık notlandırma ölçütlerini yönetmeye hazırsınız.
Puan anahtarı, ölçüt ve düzeylerin kimlik özelliklerinin atlandığı (bunlar oluşturulurken oluşturulur) tam puan anahtarı nesnesini içeren bir create() çağrısıyla CourseWork üzerinde oluşturulabilir.
main.py dosyasına aşağıdaki işlevi ekleyin:
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
).execute()
print(f"Rubric created with ID {rubric.get('id')}")
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
Ardından, daha önce oluşturduğunuz Course ve CourseWork kimliklerini kullanarak örnek notlandırmayı oluşturmak için main.py'ü güncelleyip çalıştırın:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
capability = service.userProfiles().checkUserCapability(
userId='me',
# Specify the preview version. checkUserCapability is
# supported in V1_20240930_PREVIEW and later.
previewVersion="V1_20240930_PREVIEW",
capability="CREATE_RUBRIC").execute()
if not capability.get('allowed'):
print('User ineligible for rubrics creation.')
# TODO(developer): in a production app, this signal could be used to
# proactively hide any rubrics related features from users or encourage
# them to upgrade to the appropriate license.
else:
rubric = create_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
print(json.dumps(rubric, indent=4))
Puan anahtarı gösterimi hakkında bazı noktalar:
- Ölçüt ve düzey sırası, Classroom kullanıcı arayüzüne yansıtılır.
- Puan verilen seviyeler (
pointsmülküne sahip olanlar), puana göre artan veya azalan düzende sıralanır (rastgele sıralanamaz). - Öğretmenler, kullanıcı arayüzünde ölçütleri ve puanlanan seviyeleri (puanlanmamış seviyeler hariç) yeniden sıralayabilir. Bu işlem, verilerin sırasını değiştirir.
Puan anahtarı yapısıyla ilgili diğer uyarılar için kısıtlamalar bölümüne bakın.
Kullanıcı arayüzüne döndüğünüzde ödevdeki puanlandırmayı göreceksiniz.
Şekil 3. Classroom ödevindeki örnek puan anahtarı görünümü.
Puan anahtarını okuma
Puan anahtarları, standart list() ve get() yöntemleriyle okunabilir.
Bir ödevde en fazla bir puan anahtarı bulunabilir. Bu nedenle list() seçeneğinin kullanımı sezgisel görünmeyebilir ancak puan anahtarı kimliğiniz yoksa bu seçenek yararlı olabilir. Bir CourseWork ile ilişkili notlandırma yoksa list() yanıtı boş olur.
main.py dosyasına aşağıdaki işlevi ekleyin:
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
).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
Eklediğiniz puan anahtarını almak için main.py dosyasını güncelleyin ve çalıştırın:
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.
Sonraki adımlar için not bölümündeki id mülkünü not edin.
Get(), notlandırma kimliğiniz olduğunda iyi çalışır. İşlevde bunun yerine get() kullanıldığında aşağıdaki gibi görünebilir:
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
).execute()
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
Bu uygulama, notlandırma yoksa 404 hatası döndürür.
Puan anahtarını güncelleme
Puan anahtarlarında yapılan güncellemeler patch() çağrılarıyla yapılır. Ölçeğin karmaşık yapısı nedeniyle güncellemeler, criteria mülkünün tamamının değiştirildiği bir okuma-değiştirme-yazma kalıbıyla yapılmalıdır.
Güncelleme kuralları aşağıdaki gibidir:
- Kimlik olmadan eklenen ölçütler veya seviyeler ekleme olarak kabul edilir.
- Önceki sürümde bulunmayan ölçütler veya seviyeler silinmiş olarak kabul edilir.
- Mevcut kimliği olan ancak değiştirilmiş verileri içeren ölçütler veya seviyeler düzenleme olarak kabul edilir. Değiştirilmemiş özellikler olduğu gibi bırakılır.
- Yeni veya bilinmeyen kimliklerle sağlanan ölçütler ya da seviyeler hata olarak kabul edilir.
- Yeni ölçütlerin ve seviyelerin sırası, yeni kullanıcı arayüzü sırası olarak kabul edilir (yukarıda belirtilen kısıtlamalar geçerlidir).
Puan anahtarını güncellemek için bir işlev ekleyin:
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'
).execute()
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
Bu örnekte, criteria alanı updateMask ile değiştirilmek üzere belirtilmiştir.
Ardından, yukarıda belirtilen güncelleme kurallarının her biri için değişiklik yapmak üzere main.py öğesini değiştirin:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
capability = service.userProfiles().checkUserCapability(
userId='me',
# Specify the preview version. checkUserCapability is
# supported in V1_20240930_PREVIEW and later.
previewVersion="V1_20240930_PREVIEW",
capability="CREATE_RUBRIC").execute()
if not capability.get('allowed'):
print('User ineligible for rubrics creation.')
# TODO(developer): in a production app, this signal could be used to
# proactively hide any rubrics related features from users or encourage
# them to upgrade to the appropriate license.
else:
# 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))
Değişiklikler artık Classroom'da öğretmene yansıtılmıştır.
Şekil 4. Güncellenen puan anahtarının görünümü.
Puan anahtarıyla notlandırılmış gönderimleri görüntüleme
Şu anda öğrenci gönderimleri API tarafından puan anahtarıyla notlandırılamıyor ancak puan anahtarıyla notlandırılmış gönderimlerin puan anahtarı notlarını Classroom kullanıcı arayüzünde görebilirsiniz.
Classroom kullanıcı arayüzünde öğrenci olarak örnek ödevinizi tamamlayın ve teslim edin. Ardından öğretmen olarak puan anahtarını kullanarak ödevi manuel olarak notlandırın.
Şekil 5. Notlandırma sırasında puan anahtarının öğretmen görünümü.
Puan çizelgesi ile notlandırılan StudentSubmissions'ların iki yeni özelliği vardır: draftRubricGrades ve assignedRubricGrades. Bu özellikler, taslak aşamasında öğretmen tarafından seçilen puanları ve seviyeleri ve atanmış notlandırma durumlarını temsil eder.
Notlandırılmış gönderimleri görüntülemek için mevcut studentSubmissions.get() ve studentSubmissions.list() yöntemlerini kullanabilirsiniz.
Öğrenci gönderimlerini listelemek için main.py işlevine aşağıdaki işlevi ekleyin:
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
).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
Ardından, gönderim notlarını görüntülemek için main.py dosyasını güncelleyip çalıştırın.
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 ve assignedRubricGrades şunları içerir:
- İlgili puan anahtarı ölçütlerinin
criterionIddeğeri. - Öğretmenin her ölçüt için atadığı
points. Bu, seçilen seviyeden kaynaklanabilir ancak öğretmen bu değerin üzerine yazmış da olabilir. - Her ölçüt için seçilen düzeyin
levelIddeğeri. Öğretmen bir seviye seçmediyse ancak ölçüt için puan verdiyse bu alan gösterilmez.
Bu listeler yalnızca bir öğretmenin seviye seçtiği veya puan belirlediği ölçütlere ait girişleri içerir. Örneğin, bir öğretmen notlandırma sırasında yalnızca bir ölçütle etkileşim kurmayı seçerse draftRubricGrades ve assignedRubricGrades'te, notlandırma ölçeğinde birçok ölçüt olsa bile yalnızca bir öğe olur.
Puan anahtarını silme
Bir notlandırma, standart bir delete() isteğiyle silinebilir. Aşağıdaki kodda, eksiksiz olması için örnek bir işlev gösterilmektedir. Ancak notlandırma işlemi zaten başladığından mevcut puan anahtarını silemezsiniz:
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
).execute()
except HttpError as error:
print(f"An error occurred: {error}")
return error
Puan anahtarlarını dışa ve içe aktarma
Puan anahtarları, öğretmenler tarafından yeniden kullanılmak üzere Google E-Tablolar'a manuel olarak dışa aktarılabilir.
Puan anahtarı ölçütlerini kodda belirtmenin yanı sıra, puan anahtarı gövdesinde criteria yerine sourceSpreadsheetId belirterek bu dışa aktarılan sayfalardan puan anahtarı oluşturabilir ve güncelleyebilirsiniz:
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
).execute()
print(f"Rubric created with ID {rubric.get('id')}")
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error