يمكنك استخدام المجموعات لتنظيم الطلاب وفق أغراض مختلفة، مثل الواجبات المستهدفة والأنشطة التعاونية. استخدِم Classroom API لإنشاء مجموعات الطلاب وتعديلها وقراءتها ضمن دورة تدريبية نيابةً عن المشرفين والمعلّمين.
يمكنك إنشاء مجموعات الطلاب وتعديلها وحذفها وقراءتها باستخدام الطرق التالية:
يمكنك أيضًا إضافة أعضاء وإزالتهم وقراءة معلوماتهم ضمن مجموعة طلاب باستخدام الطرق التالية:
متطلبات الترخيص والأهلية
لإنشاء مجموعات طلاب أو تعديلها أو حذفها في إحدى الدورات التدريبية وإضافة أعضاء إلى مجموعات الطلاب أو إزالتهم منها، يجب استيفاء الشروط التالية:
- يجب أن يكون المستخدم الذي يقدّم الطلب معلّمًا في الدورة التدريبية أو مشرفًا على النطاق.
- يجب أن يكون لدى المستخدم الذي يقدّم الطلب ترخيص Google Workspace for Education Plus.
- يجب أن يكون لدى مالك الدورة التدريبية ترخيص Google Workspace for Education Plus.
قراءة مجموعات الطلاب وأعضائها
يمكن للمشرفين والمعلّمين في دورة تدريبية قراءة بيانات مجموعات الطلاب
بغض النظر عن نوع الترخيص المخصّص لهم. وهذا يعني أنّه يُسمح بإرسال الطلبات إلى نقاط النهاية ListStudentGroups وListStudentGroupMembers نيابةً عن أي مشرف أو معلّم في إحدى الدورات التدريبية.
المتطلبات الأساسية لمثال الرمز
يقدّم هذا الدليل أمثلة على الرموز البرمجية بلغة Python، ويفترض أنّك تستوفي الشروط التالية:
- مشروع Google Cloud يمكنك إعدادها باتّباع التعليمات الواردة في دليل البدء السريع في Python.
- تمت إضافة النطاقات التالية إلى شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth في مشروعك:
https://www.googleapis.com/auth/classroom.rosters-
https://www.googleapis.com/auth/classroom.rosters.readonlyلنقاط النهاية للقراءة فقط.
- معرّف الدورة التدريبية التي يجب إدارة مجموعات الطلاب فيها. يجب أن يكون لدى مالك الدورة التدريبية ترخيص Google Workspace for Education Plus.
- الوصول إلى بيانات اعتماد المعلّم أو المشرف باستخدام ترخيص Google Workspace for Education Plus
التحقّق من أهلية المستخدم
توفّر Classroom API نقطة النهاية userProfiles.checkUserCapability
لمساعدتك في تحديد ما إذا كان بإمكان المستخدم إنشاء مجموعات طلابية وتعديلها
وأعضائها بشكل استباقي. تتوفّر الطريقة من خلال
برنامج معاينة المطوّر. إذا اتّبعت دليل البدء السريع في Python كنقطة بداية، عليك إعداد خدمة Classroom جديدة يمكنها الوصول إلى طرق المعاينة:
Python
classroom_service_with_capability_endpoint = googleapiclient.discovery.build(
serviceName='classroom',
version='v1',
credentials=creds,
static_discovery=False,
discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY')
لا تقيّم نقطة النهاية userProfiles.checkUserCapability سوى ما إذا كان المستخدم مؤهلاً لاستخدام إمكانية معيّنة، مثل تعديل مجموعات الطلاب. لا يقدّم أي معلومات عن دور الدورة التدريبية. على سبيل المثال،
حتى إذا كان لدى المستخدم إذن CREATE_STUDENT_GROUP،
لن ينجح طلب إلى نقطة النهاية CreateStudentGroup
إذا كان المستخدم طالبًا في الدورة التدريبية.
Python
def check_student_groups_update_capability():
"""Checks whether a user is eligible to create and modify student groups."""
capability = classroom_service_with_capability_endpoint.userProfiles().checkUserCapability(
userId="me", # Can also be set to a different user's email address or ID
capability="CREATE_STUDENT_GROUP",
previewVersion="V1_20240930_PREVIEW" # Required while the method is in the DPP.
).execute()
if capability.get("allowed"): # Retrieve the `allowed` boolean from the response.
print("User is eligible to create and modify student groups.")
else:
print("User is not eligible to create and modify student groups.")
إدارة مجموعات الطلاب
يمكن إنشاء مجموعات الطلاب باستخدام نقطة النهاية CreateStudentGroup.
Python
def create_student_group(classroom_service, course_id):
body = {
"title": "Team Blue"
}
response = classroom_service.courses().studentGroups().create(
courseId=course_id,
body=body
).execute()
print(response)
يتضمّن الرد id لمجموعة الطلاب التي تم إنشاؤها حديثًا، وcourseId، وtitle لمجموعة الطلاب.
يمكن استخدام مجموعة الطلاب id لتعديل مجموعة الطلاب الفردية أو حذفها.
Python
def update_student_group(classroom_service, course_id, student_group_id):
body = {
"title": "Team Green"
}
response = classroom_service.courses().studentGroups().patch(
courseId=course_id,
id=student_group_id,
body=body,
updateMask="title"
).execute()
print(response)
def delete_student_group(classroom_service, course_id, student_group_id):
response = classroom_service.courses().studentGroups().delete(
courseId=course_id,
id=student_group_id
).execute()
print(response)
يمكنك استرداد مجموعات الطلاب ضمن دورة تدريبية باستخدام نقطة النهاية
ListStudentGroups:
Python
def list_student_groups(classroom_service, course_id):
results = classroom_service.courses().studentGroups().list(
courseId=course_id
).execute()
studentGroups = results.get("studentGroups")
إدارة أعضاء مجموعة الطلاب
بعد إنشاء مجموعة الطلاب بنجاح، يمكنك إضافة أعضاء إليها.
Python
def add_student_group_member(classroom_service, course_id, student_group_id):
body = {
"userId": "student@schooldomain.com"
}
response = classroom_service.courses().studentGroups().studentGroupMembers().create(
courseId=course_id,
studentGroupId=student_group_id,
body=body
).execute()
print(response)
إذا أردت إزالة عضو من مجموعة طلاب، يمكنك تقديم طلب على النحو التالي:
Python
def delete_student_group_member(classroom_service, course_id, student_group_id):
response = classroom_service.courses().studentGroups().studentGroupMembers().delete(
courseId=course_id,
studentGroupId=student_group_id,
userId="student@schooldomain.com"
).execute()
print(response)
يمكنك قراءة الأعضاء داخل مجموعة من خلال تقديم الطلب التالي:
Python
def list_student_group_members(classroom_service, course_id, student_group_id):
results = classroom_service.courses().studentGroups().studentGroupMembers().list(
courseId=course_id,
studentGroupId=student_group_id
).execute()
print(results.get("studentGroupMembers"))
يتضمّن كل مرجع StudentGroupMember courseId وstudentGroupId وuserId الخاصين بأحد أعضاء المجموعة.