rubric, öğretmenlerin öğrenci gönderimlerine not verirken kullanabileceği bir şablondur. Classroom API, bu puan anahtarlarını yönetmek için öğretmenin adına işlem yapmanıza olanak tanır.
Şekil 1. Classroom ödevindeki örnek puan anahtarının görünümü.
Bu kılavuzda, Rubrics API'siyle ilgili temel kavramlar ve işlevler açıklanmaktadır. Bir puan anahtarının genel yapısı ve puan anahtarı notlandırmasının Classroom kullanıcı arayüzünde nasıl yapıldığı hakkında bilgi edinmek için bu Yardım Merkezi makalelerine bakın.
Ön koşullar
Bu kılavuzda, aşağıdakilere sahip olduğunuz varsayılmaktadır:
- Python 3.8.6 veya üzeri
- pip paket yönetim aracı
- Bir Google Cloud projesi.
- Google Classroom'un etkin olduğu bir Google Workspace for Education hesabı.
- En az bir test öğrencisi 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.
Bir masaüstü uygulaması için kimlik bilgilerini yetkilendirme
Son kullanıcı olarak kimlik doğrulaması yapmak ve uygulamanızda kullanıcı verilerine erişmek için bir veya daha fazla OAuth 2.0 İstemci Kimliği oluşturmanız gerekir. İstemci kimliği, tek bir uygulamayı Google'ın OAuth sunucularına tanımlamak 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 GCP 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 kimlik bilgisi için bir ad yazın. Bu ad yalnızca Google Cloud Console'da gösterilir. Örneğin, "Puan Anahtarları Önizleme istemcisi".
- Create'i (Oluştur) tıklayın. Yeni İstemci Kimliğinizi ve İstemci gizli anahtarınızı gösteren OAuth istemcisi oluşturma ekranı görünür.
- Download JSON (JSON'ı indir) ve ardından OK (Tamam) seçeneğini tıklayın. Yeni oluşturulan kimlik bilgisi, OAuth 2.0 İstemci Kimlikleri altında görünür.
- İndirilen JSON dosyasını
credentials.jsonolarak kaydedin ve ç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 edinmek 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 ekleme kapsamlarını yapılandırmanız gerekebilir.
- OAuth izin 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 yapmadıysanız 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 edinmek için OAuth izin ekranını yapılandırma başlıklı makaleye bakın.
classroom.coursework.students kapsamı, puan anahtarlarına okuma ve yazma erişimi (CourseWork erişimiyle birlikte) ve classroom.courses kapsamı, okuma ve yazma kurslarına izin verir.
Belirli bir yöntem için gerekli kapsamlar, yöntemin referans belgelerinde listelenmiştir. Örnek olarak courses.courseWork.rubrics.create yetkilendirme kapsamları bölümüne bakın. Tüm Classroom kapsamlarını Google API'leri için OAuth 2.0 Kapsamları bölümünde görebilirsiniz. API hâlâ önizleme aşamasında olduğu için burada puan anahtarlarından bahsedilmiyor.
Örneği yapılandırın
Çalışma dizininize 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 adında 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ına izin vermeniz istenir.
Ödev oluşturma
Puan anahtarı bir ödev veya CourseWork ile ilişkilendirilir ve yalnızca CourseWork bağlamında anlamlıdır. Puan anahtarları 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 için 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, oluşturduğunuz test sınıfının course_id değerini almak, yeni bir örnek ödev oluşturmak ve ödevin coursework_id ödevini almak için main.py uygulamasını güncelleyin:
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 kaydedin. Bunlar, puan anahtarı CRUD işlemleri için tüm gereklidir.
Artık Classroom'da örnek bir CourseWork öğeniz olmalı.
Şekil 2. Classroom'daki örnek bir ödevin görünümü.
Puan anahtarı oluşturma
Artık puan anahtarlarını yönetmeye hazırsınız.
CourseWork üzerinde tam puan anahtarı nesnesini içeren bir Create çağrısıyla bir puan anahtarı oluşturulabilir. Burada ölçütler ve düzeylere ilişkin kimlik özellikleri atlanır (bunlar oluşturma sırasında oluşturulur).
main.py hücresine 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,
# 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
Ardından, önceki Course ve CourseWork kimliklerinizi kullanarak örnek puan anahtarını oluşturmak için main.py aracını güncelleyip çalıştırın:
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))
Puan anahtarı temsiliyle ilgili bazı noktalar:
- Ölçüt ve düzey sırası, Classroom kullanıcı arayüzüne yansıtılır.
- Puanlanmış düzeyler (
pointsözelliğine sahip olanlar) artan veya azalan düzende puana göre sıralanmalıdır (rastgele sıralanamaz). - Öğretmenler, kullanıcı arayüzünde ölçütleri ve puanlanmış seviyeleri (ancak puanlanmamış seviyeleri değil) yeniden sıralayabilir. Bu, verilerin verilerdeki sıralarını değiştirir.
Puan anahtarı yapısıyla ilgili daha fazla uyarı için sınırlamalara bakın.
Kullanıcı arayüzüne döndüğünüzde, ödevde puan anahtarını görürsünüz.
Şekil 3. Classroom ödevindeki örnek puan anahtarının görünümü.
Puan anahtarı okuma
Puan anahtarları, standart List ve Get yöntemleriyle okunabilir.
Bir ödevde en fazla bir puan anahtarı olabilir, bu nedenle List kullanışlı olmayabilir, ancak puan anahtarı kimliğiniz yoksa faydalı olabilir. CourseWork ile ilişkilendirilmiş bir puan anahtarı yoksa List yanıtı boş olur.
main.py hücresine 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,
# 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
Eklediğiniz puan anahtarını getirmek için main.py uygulamasını güncelleyip ç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 puan anahtarındaki id özelliğini not edin.
Get, puan anahtarı kimliğiniz olduğunda iyi bir şekilde çalışır. Bunun yerine işlevde Get kullanmak 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,
# 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
Puan anahtarı yoksa bu uygulama, 404 hatası döndürür.
Puan anahtarını güncelleme
Puan anahtarı güncellemeleri Patch çağrılarında yapılır. Puan anahtarının karmaşık yapısı nedeniyle, güncellemeler bir okuma-değiştirme-yazma kalıbıyla yapılmalıdır. Bu kalıpta criteria özelliğinin tamamı değiştirilir.
Güncelleme kuralları aşağıdaki gibidir:
- Kimlik olmadan eklenen ölçütler veya seviyeler ekleme olarak kabul edilir.
- Daha önce eksik olan ölçütler veya seviyeler silme olarak kabul edilir.
- Mevcut bir kimliğe sahip olan ancak verileri değiştirilmiş ölçüt veya seviyeler düzenleme olarak kabul edilir. Değiştirilmemiş özellikler olduğu gibi kalır.
- Yeni veya bilinmeyen kimliklerle sağlanan ölçütler veya 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 sınırlamalarla birlikte).
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',
# 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
Bu örnekte criteria alanı, bir 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 üzerinde değişiklik yapın:
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))
Değişikliklerin Classroom'daki öğretmen için artık geçerli olması gerekir.
Şekil 4. Güncellenen puan anahtarının görünümü.
Puan anahtarıyla not verilen gönderimleri görüntüleme
Şimdilik öğrenci gönderimlerine API tarafından bir puan anahtarı ile not verilemez, ancak Classroom kullanıcı arayüzünde bir puan anahtarı ile not verilen gönderimlere ilişkin puan anahtarı notlarını okuyabilirsiniz.
Classroom kullanıcı arayüzünde öğrenci olarak örnek ödevinizi tamamlayın ve teslim edin. Ardından, öğretmen olarak puan anahtarını kullanarak ödeve manuel olarak not verin.
Şekil 5. Not verme sırasında puan anahtarının öğretmen görünümü.
Puan anahtarı ile not verilen öğrenci gönderimlerinin iki yeni özelliği vardır: draftRubricGrades ve assignedRubricGrades. Bunlar, sırasıyla taslak sırasında ve atanan notlandırma durumları sırasında öğretmen tarafından seçilen puanları ve seviyeleri temsil eder.
Ayrıca, ilişkili bir puan anahtarı bulunan öğrenci gönderimleri not vermeden önce bile bir rubricId alanı içerir. Bu, CourseWork ile ilişkilendirilmiş en son puan anahtarını temsil eder ve öğretmenler bir puan anahtarını silip yeniden oluşturursa bu değer değişebilir.
Not verilen 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 öğesine şu 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,
# 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
Ardından, gönderim notlarını görüntülemek için main.py uygulamasını güncelleyin ve ç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 düzeyden olabilir ancak öğretmen de bunun üzerine yazmış olabilir. - Her ölçüt için seçilen seviyenin
levelIddeğeri. Öğretmen bir düzey seçmemesine rağmen ölçüt için yine de puan atadıysa bu alan bulunmaz.
Bu listeler yalnızca öğretmenin bir seviye veya ayarlanan puan seçtiği ölçütlerle ilgili girişleri içerir. Örneğin, not verme sırasında yalnızca tek bir ölçütle etkileşimde bulunmayı seçen bir öğretmen, puan anahtarında çok sayıda ölçüt olsa bile draftRubricGrades ve assignedRubricGrades yalnızca bir öğeye sahip olur.
Puan anahtarını silme
Puan anahtarları, standart Delete isteğiyle silinebilir. Aşağıdaki kodda, eksiksiz olması için örnek bir işlev gösterilmektedir, ancak notlandırma başlamış olduğu için 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,
# 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
Puan anahtarlarını dışa ve içe aktarma
Puan anahtarları, öğretmenlerin yeniden kullanımı için Google E-Tablolar'a manuel olarak dışa aktarılabilir.
Kodda puan anahtarı ölçütlerini belirtmeye ek olarak, dışa aktarılan bu sayfalardan puan anahtarları oluşturup güncellemek için criteria yerine bir puan anahtarı gövdesinde sourceSpreadsheetId öğesini belirtebilirsiniz:
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
Geri bildirim
Herhangi bir sorun tespit ederseniz veya görüşleriniz olursa geri bildiriminizi paylaşın.