بدء استخدام قواعد التقييم

rubric هو نموذج يمكن للمعلّمين استخدامه عند وضع درجات للطلاب. عمليات الإرسال. تتيح لك Classroom API التصرف نيابةً عن مدرسًا لإدارة قواعد التقييم هذه.

الشكل 1. عرض نموذج لقواعد التقييم في مهمة في Classroom

يشرح هذا الدليل المفاهيم الأساسية ووظائف واجهة برمجة التطبيقات Rubrics API. عرض مقالات مركز المساعدة هذه للتعرف على بنية نموذج التقييم وكيفية تقييمه وضع الدرجات على واجهة مستخدم Classroom.

المتطلبات الأساسية

يفترض هذا الدليل حصولك على ما يلي:

• Python 3.8.6 أو أحدث
• أداة إدارة حزم pip
• مشروع على Google Cloud
• حساب Google Workspace for Education باستخدام Google Classroom مفعَّلة.
• صف تجريبي يتضمّن حساب طالب اختباريًا واحدًا على الأقل إذا لم يكن لديك Classroom الذي يمكنك استخدامه للاختبار، إنشاء حساب في واجهة المستخدم إضافة طالب اختبار

مصادقة بيانات الاعتماد لتطبيق سطح المكتب

للمصادقة كمستخدم نهائي والوصول إلى بيانات المستخدمين في تطبيقك، عليك: إنشاء معرِّف عميل OAuth 2.0 واحد أو أكثر. يُستخدم معرف العميل لتحديد تطبيقًا واحدًا بخوادم OAuth في Google. إذا كان تطبيقك يعمل على أنظمة أساسية متعدّدة عليك إنشاء معرِّف عميل منفصل لكل منصّة.

1. انتقِل إلى صفحة بيانات الاعتماد في Google Cloud في وحدة تحكُّم Google Cloud.
2. انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
3. انقر على نوع التطبيق > تطبيق متوافق مع أجهزة الكمبيوتر المكتبي:
4. في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. هذا الاسم هو فقط كما هو موضح في وحدة تحكم Google Cloud. على سبيل المثال، "عميل معاينة قواعد التقييم".
5. انقر على إنشاء. تظهر الشاشة التي تم إنشاؤها من خلال عميل OAuth تعرض معرِّف العميل وسر العميل.
6. انقر على تنزيل ملف JSON، ثم انقر على حسنًا. بيانات الاعتماد التي تم إنشاؤها حديثًا تظهر ضمن معرِّفات عملاء OAuth 2.0.
7. احفظ ملف JSON الذي تم تنزيله باسم credentials.json، وانقل الملف إلى دليل العمل الخاص بك.
8. انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات ولاحظ مفتاح واجهة برمجة التطبيقات.

يُرجى الاطِّلاع على إنشاء بيانات اعتماد الوصول لمعرفة مزيد من المعلومات.

إعداد نطاقات OAuth

بناءً على نطاقات OAuth الحالية لمشروعك، قد تحتاج إلى ضبط. ونطاقات الإضافة.

1. انتقِل إلى شاشة موافقة OAuth.
2. انقر على تعديل التطبيق >. انقر على حفظ ومتابعة للوصول إلى شاشة "النطاقات".
3. انقر على إضافة نطاقات أو إزالتها.
4. أضِف النطاقات التالية إذا لم تكن متوفرة لديك من قبل:
   • https://www.googleapis.com/auth/classroom.coursework.students
   • https://www.googleapis.com/auth/classroom.courses
5. بعد ذلك انقر على "تعديل" > حفظ ومتابعة > حفظ ومتابعة > الرجوع إلى لوحة البيانات

راجع ضبط شاشة موافقة OAuth لمعرفة أخرى.

يتيح نطاق classroom.coursework.students إمكانية الوصول للقراءة والكتابة إلى قواعد التقييم (وإمكانية الوصول إلى CourseWork) ونطاق classroom.courses تتيح دورات في القراءة والكتابة.

يتم سرد النطاقات المطلوبة لطريقة معيّنة في المستندات المرجعية لمعرفة الطريقة. الاطّلاع على courses.courseWork.rubrics.create نطاقات التفويض كمثال. يمكنك الاطّلاع على جميع نطاقات Classroom في نطاقات OAuth 2.0 لخدمة Google. API. لم يتم ذكر قواعد التقييم هنا لأنّ واجهة برمجة التطبيقات لا تزال في مرحلة المعاينة.

ضبط النموذج

في دليل العمل، ثبِّت مكتبة برامج Google للغة Python:

pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

أنشئ ملفًا باسم main.py لإنشاء مكتبة العملاء والسماح بـ يستخدم مفتاح واجهة برمجة التطبيقات بدلاً من YOUR_API_KEY:

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)

شغِّل النص البرمجي باستخدام python main.py. من المفترض أن يُطلب منك تسجيل الدخول الموافقة على نطاقات OAuth.

إنشاء مهمة دراسية

ترتبط قواعد التقييم بمهمة ما أو CourseWork، وهي متاحة فقط. ذات مغزى في سياق CourseWork. لا يمكن إنشاء قواعد التقييم إلا من خلال مشروع Google Cloud الذي أنشأ عنصر CourseWork الرئيسي. الأغراض في هذا الدليل، أنشئ مهمة CourseWork جديدة باستخدام نص برمجي.

أضِف ما يلي إلى "main.py":

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

عليك الآن تعديل "main.py" لاسترداد course_id من الصف الذي اخترته. وإنشاء عينة جديدة من التكليف ثم استرداد المهمة coursework_id:

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 وcoursework_id. هذه السمة مطلوبة لجميع عناصر CRUD الخاصة بقواعد التقييم. العمليات التجارية.

من المفترض أن يكون لديك الآن نموذج "CourseWork" في Classroom.

الشكل 2. عرض نموذج لمهمة في Classroom

إنشاء قاعدة تقييم

أصبحت الآن جاهزًا لبدء إدارة قواعد التقييم.

يمكن إنشاء قواعد تقييم في CourseWork من خلال استدعاء Create يحتوي على كائن نموذج التقييم الكامل، حيث يتم حذف خصائص رقم التعريف للمعايير والمستويات (يتم إنشاؤها عند إنشاء المحتوى)

أضِف الدالة التالية إلى main.py:

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

بعد ذلك، عدِّل main.py وشغِّلها لإنشاء نموذج قواعد التقييم باستخدام Course. وCourseWork معرّفات من السابق:

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))

إليك بعض النقاط حول تمثيل قواعد التقييم:

• يظهر ترتيب المعيار والمستوى في واجهة مستخدم Classroom.
• يجب ترتيب المستويات المُقيّمة (التي تتضمّن السمة points) حسب النقاط. بترتيب تصاعدي أو تنازلي (لا يمكن ترتيبها عشوائيًا).
• يستطيع المعلمون إعادة ترتيب المعايير والمستويات التي تم تقييمها (ولكن ليس بدون درجات المستويات) في واجهة المستخدم، ويغير ترتيبها في البيانات.

راجِع القيود للاطّلاع على مزيد من التنبيهات بشأن بنية قواعد التقييم.

من المفترض أن يظهر نموذج التقييم الخاص بالمهمة في واجهة المستخدم.

الشكل 3. عرض نموذج لقواعد التقييم في مهمة في Classroom

قراءة قواعد التقييم

يمكن قراءة قواعد التقييم باستخدام الطريقتَين العاديتَين List وGet.

لا يمكن تضمين أكثر من نموذج تقييم واحد في المهمة الدراسية، لذلك قد يبدو الأمر List. غير واضح، ولكنه مفيد إذا لم يكن لديك معرّف نموذج التقييم حاليًا. إذا كان هناك ليس هناك قواعد تقييم مرتبطة بـ CourseWork، فالاستجابة List فارغة.

أضِف الدالة التالية إلى main.py:

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

عليك تعديل main.py وتشغيله لجلب قواعد التقييم التي أضفتها:

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.

سجِّل السمة id في نموذج التقييم للاطّلاع على الخطوات اللاحقة.

يحقّق Get أداءً جيدًا عند توفُّر رقم تعريف قاعدة التقييم. استخدام Get في الدالة بدلاً من ذلك:

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

يعرض هذا التنفيذ الخطأ 404 في حال عدم توفر نموذج تقييم.

تعديل قواعد التقييم

يتم إجراء التعديلات على قواعد التقييم من خلال استدعاءات Patch. بسبب الهيكل المعقد في أي نموذج من قواعد التقييم، يجب إجراء التحديثات بنمط القراءة والتعديل والكتابة، حيث سيتم استبدال السمة criteria بالكامل.

في ما يلي قواعد التعديل:

1. تؤخذ المعايير أو المستويات المضافة بدون معرّف في الاعتبار. الإضافات.
2. يتم أخذ المعايير أو المستويات المفقودة في السابق عمليات الحذف:
3. تؤخذ المعايير أو المستويات التي لها رقم تعريف حالي ولكن مع بيانات معدَّلة في الاعتبار. التعديلات. وتُترك السمات غير المعدَّلة كما هي.
4. تؤخذ المعايير أو المستويات المقدّمة مع معرّفات جديدة أو غير معروفة في الاعتبار. .
5. يُعد ترتيب المعايير والمستويات الجديدة هو ترتيب واجهة المستخدم الجديد (مع القيود المذكورة أعلاه).

إضافة دالة لتحديث قواعد التقييم:

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

في هذا المثال، تم تحديد الحقل criteria لتعديله باستخدام updateMask

بعد ذلك، عدِّل main.py لإجراء تغيير على كل تعديل من التعديلات المذكورة أعلاه. القواعد:

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))

يجب أن تظهر التغييرات الآن للمعلّم في Classroom.

الشكل 4. عرض قواعد التقييم المعدّلة

عرض عمليات الإرسال المصنّفة وفقًا لقواعد التقييم

لا يمكن في الوقت الحالي وضع الدرجات على عمليات إرسال الطلاب باستخدام قواعد تقييم بواسطة واجهة برمجة التطبيقات، ولكن يمكنك يمكنهم قراءة درجات نموذج التقييم للإرسالات التي تم تقييمها باستخدام نموذج تقييم في واجهة مستخدم Classroom.

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

الشكل 5. عرض المعلّم لقواعد التقييم أثناء وضع الدرجات

إنّ عمليات الإرسال للطلاب التي تم وضع درجات لها باستخدام قواعد تقييم تتضمّن مهمتَين جديدتَين. الخاصيتين: draftRubricGrades وassignedRubricGrades، وتمثلان النقاط والمستويات التي اختارها المعلّم أثناء المسودة ووضع الدرجات على التوالي.

بالإضافة إلى ذلك، إنّ عمليات إرسال الطلاب التي تتضمّن قواعد تقييم مرتبطة تتضمّن علامة rubricId. المجال، حتى قبل وضع الدرجات. وهي تمثل أحدث قواعد تقييم مرتبطة CourseWork، وقد تتغير هذه القيمة إذا قام المعلمون بحذف وإعادة إنشاء المهمة.

يمكنك استخدام studentSubmissions.Get الحالية studentSubmissions.List طريقة لعرض المهام التي تم تقييمها.

أضِف الدالة التالية إلى main.py لإدراج تسليمات الطالب:

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

بعد ذلك، يمكنك تعديل main.py وتشغيله لعرض درجات الإرسال.

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 وassignedRubricGrades ما يلي:

• تمثّل هذه السمة criterionId لمعايير قواعد التقييم المقابلة.
• تمثّل هذه السمة points الذي خصّصه المعلّم لكل معيار. يمكن أن يكون هذا من المستوى المحدد، ولكن كان بإمكان المدرس أيضًا استبدال هذا.
• تمثّل هذه السمة levelId للمستوى الذي تم اختياره لكل معيار. وإذا لم يكُن المعلم اختر مستوى، ولكن لا يزال يتم تعيين نقاط للمعيار، فإن هذا الحقل غير موجود.

تحتوي هذه القوائم فقط على إدخالات للمعايير التي يستخدمها المدرس إما أحد المستويات أو حدد نقاطًا. على سبيل المثال، إذا اختار المدرس أن بمعيار واحد أثناء وضع الدرجات، وهو السمة draftRubricGrades لن يكون لدى assignedRubricGrades سوى عنصر واحد، حتى إذا كانت قاعدة التقييم تحتوي على العديد من العناصر المعايير.

حذف قواعد تقييم

يمكن حذف قواعد التقييم من خلال طلب Delete عادي. يُنشئ الكود التالي مثالاً لدالة الاكتمال، ولكن نظرًا لأن التقييم قد بدأت، لا يمكنك حذف قواعد التقييم الحالية:

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

تصدير قواعد التقييم واستيرادها

يمكن تصدير قواعد التقييم يدويًا إلى Google. جداول بيانات يمكن للمعلّمين إعادة استخدامها.

بالإضافة إلى تحديد معايير نموذج التقييم في التعليمات البرمجية، من الممكن إنشاء تعديل قواعد التقييم من أوراق البيانات التي يتم تصديرها من خلال تحديد sourceSpreadsheetId في نص نموذج تقييم بدلاً من criteria:

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

ملاحظات

إذا واجهت أي مشاكل أو كان لديك ملاحظات، يُرجى مشاركة ملاحظاتك.