Bu kılavuzda, Google Classroom API'deki notlandırma dönemleri uç noktalarının nasıl kullanılacağı açıklanmaktadır.
Genel Bakış
Notlandırma dönemleri, ödevleri, testleri ve projeleri belirli tarih aralıklarında düzenlemek için oluşturulur. Classroom API, geliştiricilerin yöneticiler ve öğretmenler adına Classroom'da notlandırma dönemleri oluşturmasına, değiştirmesine ve okumasına olanak tanır. CourseWork'te notlandırma dönemlerini ayarlamak için Classroom API'yi de kullanabilirsiniz.
Classroom API, bir derste notlandırma dönemi bilgilerini okumak ve yazmak için iki uç nokta sunar:
GetGradingPeriodSettings
: Bir kurstaki notlandırma dönemi ayarlarını okumanızı sağlar.UpdateGradingPeriodSettings
: Notlandırma dönemi ekleme, değiştirme ve silme ve yapılandırılmış notlandırma dönemlerini mevcut tüm ders çalışmalarına uygulama yoluyla bir kurstaki notlandırma dönemi ayarlarını yönetmenize olanak tanır.
Lisanslama koşulları
Bir kurstaki notlandırma dönemi ayarlarını değiştirme
UpdateGradingPeriodSettings
uç noktasını kullanarak bir derste notlandırma dönemleri oluşturmak, değiştirmek veya silmek için aşağıdaki koşulların karşılanması gerekir:
- İstekte bulunan kullanıcıya Google Workspace for Education Plus lisansı atanmış olmalıdır.
- Dersin sahibine Google Workspace for Education Plus lisansı atanmıştır.
Bir kurstaki notlandırma dönemi ayarlarını okuma
Alan yöneticileri ve bir dersin öğretmenleri, atanmış oldukları lisanstan bağımsız olarak notlandırma dönemi ayarlarını okuyabilir. Bu, GetGradingPeriodSettings
uç noktasına yapılan isteklerin herhangi bir alan yöneticisi veya öğretmen adına izin verildiği anlamına gelir.
CourseWork'te notlandırma dönemi kimliği ayarlama
Bir dersin öğretmenleri, atanmış oldukları lisanstan bağımsız olarak API'yi kullanarak CourseWork'u oluştururken veya güncellerken gradingPeriodId
değerini ekleyebilir.
Kullanıcıların notlandırma dönemleri ayarlama uygunluğunu kontrol etme
Herhangi bir yönetici veya öğretmen adına checkGradingPeriodsSetupEligibility
uç noktasına yönelik isteklere izin verilir. Kullanıcının bir dersteki notlandırma dönemlerini değiştirip değiştiremeyeceğini belirlemek için bunu kullanın.
Ön koşullar
Bu kılavuzda, Python'da kod örnekleri sağlanmakta ve aşağıdakilere sahip olduğunuz varsayılmaktadır:
- Bir Google Cloud projesi. Python hızlı başlangıç kılavuzundaki talimatları uygulayarak tek bir kod oluşturabilirsiniz.
- Projenizin OAuth izin ekranına aşağıdaki kapsamları ekleyin:
https://www.googleapis.com/auth/classroom.courses
https://www.googleapis.com/auth/classroom.coursework.students
- Notlandırma dönemlerinin değiştirilmesi gereken bir dersin kimliği. Kurs sahibinin Google Workspace for Education Plus lisansı olmalıdır.
- Google Workspace for Education Plus lisansına sahip bir öğretmenin veya yöneticinin kimlik bilgilerine erişim. CourseWork’ü oluşturmak ya da değiştirmek için bir öğretmenin kimlik bilgileri gerekiyor. Yöneticiler, derste öğretmen değilse CourseWork'ü oluşturamaz veya değiştiremez.
GradingPeriodSettings
kaynağını yönetme
GradingPeriodSettings
kaynağı, bağımsız GradingPeriods
öğelerinin listesini ve applyToExistingCoursework
adlı bir boole alanını içerir.
GradingPeriods
listesi, bir kurstaki tüm notlandırma dönemlerini temsil eder. Listedeki her notlandırma dönemi için bir başlık, başlangıç tarihi ve bitiş tarihi belirtmeniz gerekir. Bir kurstaki her notlandırma döneminin benzersiz bir başlığı olmalıdır ve farklı notlandırma dönemlerinin başlangıç ve bitiş tarihleri çakışamaz. Her notlandırma döneminin, Classroom API tarafından atanan kendi tanımlayıcıları vardır.
applyToExistingCoursework
doğru/yanlış değeri, daha önce oluşturulmuş ders çalışmalarını her ders çalışması için gradingPeriodId
değerini değiştirmek üzere ayrı bir API çağrısı yapmak zorunda kalmadan notlandırma dönemlerine ayırmanıza olanak tanıyan kalıcı bir ayardır. Bu değer True
olarak ayarlanırsa Classroom, courseWork.dueDate
mevcut bir notlandırma döneminin başlangıç ve bitiş tarihlerine denk gelirse mevcut tüm CourseWork'larda gradingPeriodId
değerini otomatik olarak ayarlar. Ödev için teslim tarihi ayarlanmamışsa Classroom, courseWork.scheduledTime
değerini kullanır. Bu iki alan da mevcut değilse veya mevcut bir notlandırma döneminin başlangıç ve bitiş tarihleriyle eşleşme yoksa ders çalışması herhangi bir notlandırma dönemiyle ilişkilendirilmez.
Kullanıcıların bir kurstaki notlandırma dönemi ayarlarını değiştirip değiştiremeyeceğini belirleme
Classroom'da notlandırma dönemleri oluşturma ve değiştirme özelliği yalnızca belirli bir lisansa sahip kullanıcılar tarafından kullanılabildiğinden, Classroom API, kullanıcının UpdateGradingPeriodSettings
uç noktasına istek gönderip gönderemeyeceğini proaktif olarak belirlemenize yardımcı olmak için checkGradingPeriodsSetupEligibility
uç noktasını sağlar.
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
Notlandırma dönemi ekleme
Kullanıcının, bir kurstaki notlandırma dönemi ayarlarını değiştirmek için gerekli lisansa sahip olduğundan emin olduğunuza göre UpdateGradingPeriodSettings
uç noktasına istek göndermeye başlayabilirsiniz. Ayrı notlandırma dönemleri ekleme, mevcut notlandırma dönemlerini değiştirme veya notlandırma dönemi silme gibi işlemlerde GradingPeriodSettings
kaynağında yapılan tüm değişiklikler UpdateGradingPeriodSettings
uç noktası kullanılarak gerçekleştirilir.
Python
Aşağıdaki örnekte, gradingPeriodSettings
kaynağı iki notlandırma dönemi içerecek şekilde değiştirilmiştir. applyToExistingCoursework
boole değeri True
olarak ayarlanır. Bu durumda, bir notlandırma döneminin başlangıç ve bitiş tarihi arasına denk gelen mevcut CourseWork öğelerindeki gradingPeriodId
değiştirilir. updateMask
'ün her iki alanı da içerdiğini unutmayın. Yanıtta döndürüldükten sonra ayrı notlandırma dönemlerine ait kimlikleri kaydedin. Gerekirse notlandırma dönemlerini güncellemek için bu kimlikleri kullanmanız gerekir.
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
Notlandırma dönemi ayarlarını okuma
GradingPeriodSettings
, GetGradingPeriodSettings
uç noktası kullanılarak okunur.
Lisanstan bağımsız olarak tüm kullanıcılar, bir kurstaki notlandırma dönemleri ayarlarını okuyabilir.
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
Listeye ayrı bir notlandırma dönemi ekleme
Belirli bir notlandırma dönemindeki güncellemeler, okuma-değiştirme-yazma kalıbına göre yapılmalıdır. Bu nedenle:
GetGradingPeriodSettings
uç noktasını kullanarakGradingPeriodSettings
kaynağındaki notlandırma dönemleri listesini okuyun.- Notlandırma dönemleri listesinde istediğiniz değişiklikleri yapın.
- Yeni notlandırma dönemleri listesini
UpdateGradingPeriodSettings
isteğinde bulunun.
Bu kalıp, bir kurstaki notlandırma dönemi başlıklarının farklı olmasını ve notlandırma dönemlerinin başlangıç ile bitiş tarihleri arasında çakışma olmamasına yardımcı olur.
Notlandırma dönemleri listesini güncellemeyle ilgili aşağıdaki kuralları göz önünde bulundurun:
- Listeye kimlik olmadan eklenen notlandırma dönemleri, ekleme olarak kabul edilir.
- Listede eksik olan notlandırma dönemleri silinmiş olarak kabul edilir.
- Mevcut bir kimlikle ancak değiştirilmiş veriler içeren notlandırma dönemleri düzenleme olarak kabul edilir. Değiştirilmemiş özellikler olduğu gibi bırakılır.
- Yeni veya bilinmeyen kimliklere sahip notlandırma dönemleri hata olarak kabul edilir.
Python
Aşağıdaki kod, bu kılavuzdaki örnekten yararlanır. "Yaz" başlıklı yeni bir notlandırma dönemi oluşturulur. applyToExistingCoursework
boole değeri, istek gövdesinde False
olarak ayarlanmıştır.
Bunu yapmak için mevcut GradingPeriodSettings
okunur, listeye yeni bir notlandırma dönemi eklenir ve applyToExistingCoursework
doğru/yanlış değeri False
olarak ayarlanır. Mevcut Ödevler'e uygulanmış notlandırma dönemlerinin kaldırılmayacağını unutmayın. Önceki örnekte, "1. Dönem" ve "2. Dönem" notlandırma dönemleri mevcut CourseWork'a zaten uygulanmıştır ve sonraki isteklerde applyToExistingCoursework
False olarak ayarlanırsa CourseWork'tan kaldırılmaz.
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
applyToExistingCoursework
Boole alanıyla ilgili faydalı ipuçları
applyToExistingCoursework
boole değerinin kalıcı olduğunu unutmayın. Bu durumda, boole değeri önceki bir API çağrısında True
olarak ayarlanmışsa ve değiştirilmemişse notlandırma dönemlerinde yapılan sonraki güncellemeler mevcut CourseWork'e uygulanacaktır.
UpdateGradingPeriodSettings
isteğinde bu boole değerini True
yerine False
olarak değiştirirseniz yalnızca GradingPeriodSettings
'da yaptığınız yeni değişiklikler mevcut CourseWork'a uygulanmaz. Doğru/yanlış değeri True
olarak ayarlandığında önceki API çağrılarında CourseWork'a uygulanan tüm notlandırma dönemi bilgileri kaldırılmaz. Bu boole ayarını, mevcut ders çalışmalarını yapılandırılmış notlandırma dönemlerinizle ilişkilendirmeyi desteklediği ancak ders çalışmaları ile yapılandırılmış notlandırma dönemleri arasındaki mevcut ilişkilendirmeleri kaldırmayı desteklemediği şeklinde düşünebilirsiniz.
Bir notlandırma döneminin başlığını siler veya değiştirirseniz bu değişiklikler, applyToExistingCoursework
doğru/yanlış değerinin ayarından bağımsız olarak mevcut tüm CourseWork'lara dağıtılır.
Listede tek bir notlandırma dönemini güncelleme
Mevcut bir notlandırma dönemiyle ilişkili bazı verileri değiştirmek için mevcut notlandırma döneminin kimliğini, değiştirilen verilerle birlikte listeye ekleyin.
Python
Bu örnekte, "Yaz" notlandırma dönemi bitiş tarihi değiştirilecektir. applyToExistingCoursework
alanı True
olarak ayarlanır. Bu boole değerini True
olarak ayarladığınızda, yapılandırılmış tüm notlandırma dönemleri mevcut CourseWork'a uygulanır. Önceki API isteğinde, "Yaz" notlandırma döneminin mevcut CourseWork'a uygulanmaması için boole değeri False
olarak ayarlandı. Bu boole alanı True
olarak ayarlandığı için "Yaz" notlandırma dönemi, eşleşen mevcut tüm CourseWork'lere uygulanır.
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
Notlandırma dönemlerini tek tek silme
Notlandırma dönemini silmek için notlandırma dönemini listeden çıkarın. Bir notlandırma dönemi silinirse applyToExistingCoursework
ayarından bağımsız olarak CourseWork'ta notlandırma dönemine yapılan tüm referansların da silineceğini unutmayın.
Python
Bu kılavuzdaki örneği kullanmaya devam etmek için notlandırma dönemini ("Yaz") atlayın.
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
CourseWork'ta gradingPeriodId
alanını yönetme
CourseWork kaynağı bir gradingPeriodId
alanı içerir. CourseWork uç noktalarını kullanarak CourseWork ile ilişkili notlandırma dönemini okuyabilir ve yazabilirsiniz. Bu ilişkilendirmeyi yönetmenin üç yolu vardır:
- tarihe dayalı otomatik notlandırma dönemi ilişkilendirme
- özel ilişkilendirilmiş notlandırma dönemi
- notlandırma dönemi ilişkilendirmesi yok
1. Tarihe dayalı notlandırma dönemi ilişkilendirmesi
Ödev oluştururken Classroom'un notlandırma dönemi ilişkilendirmesini sizin adınıza yapmasını sağlayabilirsiniz. Bunu yapmak için CourseWork isteğinden gradingPeriodId
alanını çıkarın. Ardından CourseWork isteğinde dueDate
veya scheduledTime
alanlarını belirtin. dueDate
, mevcut bir notlandırma dönemi tarih aralığına denk geliyorsa Classroom, notlandırma dönemi kimliğini CourseWork'te ayarlar. dueDate
alanı belirtilmezse Classroom, gradingPeriodId
öğesini scheduledTime
alanına göre belirler. Hiçbir alan belirtilmezse veya notlandırma dönemi tarih aralığı eşleşmesi yoksa CourseWork'ta gradingPeriodId
ayarlanmaz.
2. Özel ilişkili notlandırma dönemi
Ödevi, dueDate
veya scheduledTime
ile uyumlu olandan farklı bir notlandırma dönemiyle ilişkilendirmek istiyorsanız Ödev'i oluştururken veya güncellerken gradingPeriodId
alanını manuel olarak ayarlayabilirsiniz. gradingPeriodId
ayarını manuel olarak yaparsanız Classroom, tarihe dayalı otomatik notlandırma dönemi ilişkilendirmesini gerçekleştirmez.
3. Notlandırma dönemi ilişkilendirmesi yok
CourseWork'ün herhangi bir notlandırma dönemiyle ilişkilendirilmesini istemiyorsanız CourseWork isteğindeki gradingPeriodId
alanını boş bir dizeye (gradingPeriodId
: ""
) ayarlayın.
Son tarih güncellenirse notlandırma dönemi kimliğine ne olur?
CourseWork dueDate
alanını güncelliyorsanız ve özel bir notlandırma dönemi ilişkilendirmesini veya notlandırma dönemi ilişkilendirmesini korumak istiyorsanız updateMask ve istek gövdesine dueDate
ve gradingPeriodId
öğelerini eklemeniz gerekir. Bu işlem, Classroom'a gradingPeriodId
değerini yeni dueDate
ile eşleşen notlandırma dönemiyle geçersiz kılmaması gerektiğini söyler.
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()