إنشاء مجموعات الطلاب وإدارتها

يمكنك استخدام المجموعات لتنظيم الطلاب وفق أغراض مختلفة، مثل الواجبات المستهدفة أو الأنشطة التعاونية. استخدِم 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

إذا اتّبعت دليل البدء السريع في Python كنقطة بداية، عدِّل خدمة Classroom للوصول إلى طرق المعاينة.

Python

classroom_service = 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')

التحقّق من أهلية المستخدم

توفّر Classroom API نقطة نهاية userProfiles.checkUserCapability لمساعدتك في تحديد ما إذا كان بإمكان المستخدم إنشاء مجموعات طلابية وتعديلها وأعضائها بشكل استباقي.

لا تقيّم نقطة النهاية userProfiles.checkUserCapability سوى ما إذا كان المستخدم مؤهَّلاً لاستخدام إمكانية معيّنة، مثل تعديل مجموعات الطلاب. لا يقدّم أي معلومات عن دور الدورة التدريبية. على سبيل المثال، حتى إذا كان لدى المستخدم إذن الوصول إلى CREATE_STUDENT_GROUP، إذا كان طالبًا في الدورة التدريبية، لن ينجح طلب إلى نقطة النهاية CreateStudentGroup.

Python

def check_student_groups_update_capability(classroom_service, course_id):
    """Checks whether a user is able to create and modify student groups in a course."""
    capability = classroom_service.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 allowed to create and modify student groups.")
    else:
        print("User is not allowed 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,
        previewVersion="V1_20250630_PREVIEW",
    ).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",
        previewVersion="V1_20250630_PREVIEW"
    ).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,
        previewVersion="V1_20250630_PREVIEW",
    ).execute()

    print(response)

يمكنك استرداد مجموعات الطلاب ضمن دورة تدريبية باستخدام نقطة النهاية ListStudentGroups:

Python

def list_student_groups(classroom_service, course_id):
    results = classroom_service.courses().studentGroups().list(
        courseId=course_id,
        previewVersion="V1_20250630_PREVIEW"
    ).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,
        previewVersion="V1_20250630_PREVIEW"
    ).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",
        previewVersion="V1_20250630_PREVIEW"
    ).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,
        previewVersion="V1_20250630_PREVIEW"
    ).execute()

    print(results.get("studentGroupMembers"))

يتضمّن كل مرجع StudentGroupMember courseId وstudentGroupId وuserId الخاصين بالعضو في المجموعة.

السابق
إنشاء أوصياء وإدارتهم