علامات المرفقات ودرجات التراجع عن الظهور

هذا هو العرض التوضيحي السادس في سلسلة العروض التوضيحية الخاصة بإضافات Classroom.

في هذا الشرح، ستعدّل المثال من خطوة الشرح السابقة لإنشاء مرفق من نوع نشاط مقيّم. يمكنك أيضًا إرجاع درجة إلى Google Classroom آليًا، وستظهر في دفتر علامات المعلم كدرجة مسودّة.

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

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

خلال هذا الشرح، ستكمل ما يلي:

• عدِّل طلبات إنشاء المرفقات السابقة إلى واجهة برمجة تطبيقات Classroom لضبط المقام الخاص بدرجة المرفق أيضًا.
• تسجيل درجة الطالب آليًا وتحديد بسط درجة المرفق.
• يمكنك اتّباع طريقتَين لنقل درجة المهمة إلى Classroom باستخدام بيانات اعتماد المعلّم المسجّل الدخول أو بيانات اعتماد المعلّم غير الإلكترونية.

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

لأغراض هذا المثال، أعِد استخدام النشاط من الشرح السابق، والذي يظهر فيه للطالب صورة لمعلم شهير ويُطلب منه إدخال اسمه. امنح الطالب العلامة الكاملة على المرفق إذا أدخل الاسم الصحيح، وإلا امنحه صفرًا.

التعرّف على ميزة التقييم في Classroom Add-ons API

يمكن للإضافة ضبط كلّ من بسط الدرجة ومقام الدرجة للمرفق. يتم ضبط هاتين القيمتين على التوالي باستخدام القيمتَين pointsEarned وmaxPoints في واجهة برمجة التطبيقات. تعرض بطاقة المرفق في واجهة مستخدم Classroom القيمة maxPoints عند ضبطها.

الشكل 1. واجهة مستخدم إنشاء المهام التي تتضمّن ثلاث بطاقات مرفقات إضافات تم ضبط maxPoints فيها.

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

عادةً، يتم وضع التصنيف "مزامنة الدرجات" على المرفق الأول الذي تمت إضافته إلى المهمة والذي يضبط maxPoints. راجِع مثال واجهة مستخدم إنشاء المهام المعروض في الشكل 1 للاطّلاع على مثال على التصنيف "مزامنة الدرجات". لاحظ أنّ بطاقة "المرفق 1" تحمل التصنيف "مزامنة الدرجات" وأنّه تم تعديل درجة المهمة في المربّع الأحمر إلى 50 نقطة. يُرجى العِلم أيضًا أنّه على الرغم من أنّ الشكل 1 يعرض ثلاث بطاقات مرفقات، إلا أنّ بطاقة واحدة فقط تحمل التصنيف "مزامنة الدرجات". وهذا قيد أساسي في عملية التنفيذ الحالية، إذ يمكن لمرفق واحد فقط أن يحمل التصنيف "مزامنة الدرجات".

إذا كانت هناك مرفقات متعددة تم ضبط maxPoints لها، لن يؤدي إزالة المرفق الذي تم تفعيل خيار مزامنة الدرجات له إلى تفعيل هذا الخيار في أي من المرفقات المتبقية. تؤدي إضافة مرفق آخر يضبط maxPoints إلى تفعيل ميزة "مزامنة الدرجات" في المرفق الجديد، ويتم تعديل الحد الأقصى لدرجة المهمة لتتطابق معها. لا تتوفّر آلية لمعرفة المرفق الذي يحمل التصنيف "مزامنة الدرجات" بشكل آلي، ولا لمعرفة عدد المرفقات التي تتضمّنها مهمة معيّنة.

ضبط الحد الأقصى لدرجة مرفق

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

يجب إجراء تعديل بسيط فقط على عملية التنفيذ الحالية لتفعيل ميزات التقييم. عند إنشاء مرفق، أضِف القيمة maxPoints في عنصر AddOnAttachment نفسه الذي يحتوي على studentWorkReviewUri وteacherViewUri وحقول المرفقات الأخرى.

يُرجى العِلم أنّ الحدّ الأقصى التلقائي لدرجة مهمة جديدة هو 100. نقترح ضبط قيمة maxPoints على قيمة أخرى غير 100 حتى تتمكّن من التأكّد من ضبط الدرجات بشكل صحيح. اضبط قيمة maxPoints على 50 كعرض توضيحي:

attachment = {
    # Specifies the route for a teacher user.
    "teacherViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True),
    },
    # Specifies the route for a student user.
    "studentViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True)
    },
    # Specifies the route for a teacher user when the attachment is
    # loaded in the Classroom grading view.
    "studentWorkReviewUri": {
        "uri":
            flask.url_for(
                "view_submission", _scheme='https', _external=True)
    },
    # Sets the maximum points that a student can earn for this activity.
    # This is the denominator in a fractional representation of a grade.
    "maxPoints": 50,
    # The title of the attachment.
    "title": f"Attachment {attachment_count}",
}

لأغراض هذا العرض التوضيحي، يمكنك أيضًا تخزين قيمة maxPoints في قاعدة بيانات المرفقات المحلية، ما يوفّر عليك إجراء طلب إضافي من واجهة برمجة التطبيقات لاحقًا عند تقييم المهام التي يرسلها الطلاب. يُرجى العِلم، مع ذلك، أنّه من المحتمل أن يغيّر المعلّمون إعدادات درجات المهام بشكل مستقل عن الإضافة. أرسِل طلب GET إلى نقطة النهاية courses.courseWork للاطّلاع على قيمة maxPoints على مستوى المهمة. عند إجراء ذلك، مرِّر itemId في الحقل CourseWork.id.

الآن، عدِّل نموذج قاعدة البيانات ليحتوي أيضًا على قيمة maxPoints للمرفق. ننصحك باستخدام القيمة maxPoints من الردّ CREATE:

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    # Store the maxPoints value returned in the response.
    max_points=int(resp.get("maxPoints")))
db.session.add(new_attachment)
db.session.commit()

أصبح للمرفق الآن حدّ أقصى للدرجة. من المفترض أن تتمكّن من اختبار هذا السلوك الآن، وذلك من خلال إضافة مرفق إلى مهمة جديدة وملاحظة أنّ بطاقة المرفق تعرض التصنيف "مزامنة الدرجات" وتتغيّر قيمة "النقاط" الخاصة بالمهمة.

ضبط علامة تسليم الطالب في Classroom

يوضّح هذا القسم كيفية ضبط البسط لدرجة مرفق، أي درجة الطالب الفردية للمرفق. لإجراء ذلك، اضبط قيمة pointsEarned لمرفق أرسله الطالب.

عليك الآن اتّخاذ قرار مهم: كيف يجب أن يرسل الإضافة طلبًا لضبط pointsEarned؟

المشكلة هي أنّ ضبط pointsEarned يتطلّب نطاق OAuth teacher. يجب عدم منح نطاق teacher لمستخدمي الطلاب، لأنّ ذلك قد يؤدي إلى سلوك غير متوقّع عندما يتفاعل الطلاب مع الإضافة، مثل تحميل إطار iframe الخاص بـ "عرض المعلّم" بدلاً من إطار iframe الخاص بـ "عرض الطالب". وبالتالي، لديك خياران لتحديد قيمة pointsEarned:

• استخدام بيانات اعتماد المعلّم الذي سجّل الدخول
• استخدام بيانات اعتماد المعلّم المخزَّنة (بلا إنترنت)

تتناول الأقسام التالية المفاضلة بين كل طريقة قبل عرض كل عملية تنفيذ. يُرجى العِلم أنّ الأمثلة التي نقدّمها توضّح كلا الطريقتَين لنقل الدرجات إلى Classroom. راجِع التعليمات الخاصة بكل لغة أدناه لمعرفة كيفية اختيار طريقة عند تشغيل الأمثلة المقدَّمة:

ضبط الدرجات باستخدام بيانات اعتماد المعلّم الذي سجّل الدخول

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

ومع ذلك، يجب مراعاة أنّ المعلّم يتفاعل فقط مع المهمة التي أرسلها الطالب في إطار iframe الخاص بميزة "مراجعة عمل الطالب". وينطوي ذلك على بعض الآثار المهمة، وهي:

• لن تظهر أي درجات في Classroom إلى أن يتّخذ المعلّم إجراءً في واجهة مستخدم Classroom.
• قد يضطر المعلّم إلى فتح كل عمل أرسله الطالب من أجل إدخال درجات جميع الطلاب.
• هناك تأخير بسيط بين تلقّي Classroom للدرجة وظهورها في واجهة مستخدم Classroom. عادةً ما يتراوح التأخير بين خمس ثوانٍ وعشر ثوانٍ، ولكن يمكن أن يصل إلى 30 ثانية.

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

لتنفيذ هذا الأسلوب، أضِف طلب بيانات آخر من واجهة برمجة التطبيقات إلى مسار "مراجعة أعمال الطلاب" الحالي.

بعد استرداد سجلات مرفقات ومهمة الطالب، قيِّم مهمة الطالب وخزِّن الدرجة الناتجة. اضبط الدرجة في الحقل pointsEarned الخاص بأحد عناصر AddOnAttachmentStudentSubmission. أخيرًا، أرسِل طلب PATCH إلى نقطة النهاية courses.courseWork.addOnAttachments.studentSubmissions مع مثيل AddOnAttachmentStudentSubmission في نص الطلب. يُرجى العِلم أنّه يجب أيضًا تحديد pointsEarned في updateMask في طلب PATCH:

# Look up the student's submission in our database.
student_submission = Submission.query.get(flask.session["submissionId"])

# Look up the attachment in the database.
attachment = Attachment.query.get(student_submission.attachment_id)

grade = 0

# See if the student response matches the stored name.
if student_submission.student_response.lower(
) == attachment.image_caption.lower():
    grade = attachment.max_points

# Create an instance of the Classroom service.
classroom_service = ch._credential_handler.get_classroom_service()

# Build an AddOnAttachmentStudentSubmission instance.
add_on_attachment_student_submission = {
    # Specifies the student's score for this attachment.
    "pointsEarned": grade,
}

# Issue a PATCH request to set the grade numerator for this attachment.
patch_grade_response = classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

ضبط الدرجات باستخدام بيانات اعتماد المعلّم بلا إنترنت

يتطلّب الأسلوب الثاني لتحديد الدرجات استخدام بيانات اعتماد مخزّنة للمعلّم الذي أنشأ المرفق. يتطلّب هذا التنفيذ إنشاء بيانات اعتماد باستخدام رموز مميزة لإعادة التحميل والدخول خاصة بمدرّس تم منح الإذن له سابقًا، ثم استخدام بيانات الاعتماد هذه لضبط pointsEarned.

من المزايا المهمة لهذا الأسلوب أنّه يتم ملء الدرجات بدون أن يضطر المعلم إلى اتخاذ أي إجراء في واجهة مستخدم Classroom، ما يؤدي إلى تجنُّب المشاكل المذكورة أعلاه. والنتيجة هي أنّ المستخدمين النهائيين يرون تجربة التقييم على أنّها سلسة وفعّالة. بالإضافة إلى ذلك، يتيح لك هذا الأسلوب اختيار الوقت الذي تريد فيه إعادة الدرجات، مثلاً عندما يكمل الطلاب النشاط أو بشكل غير متزامن.

أكمِل المهام التالية لتنفيذ هذا الأسلوب:

1. عدِّل سجلّات قاعدة بيانات المستخدم لتخزين رمز دخول.
2. عدِّل سجلّات قاعدة بيانات المرفقات لتخزين معرّف معلّم.
3. استرداد بيانات اعتماد المعلّم وإنشاء مثيل جديد لخدمة Classroom (اختياري)
4. ضبط درجة إرسال

لأغراض هذا العرض التوضيحي، اضبط العلامة عندما يكمل الطالب النشاط، أي عندما يرسل الطالب النموذج في مسار "طريقة عرض الطالب".

تعديل سجلّات قاعدة بيانات المستخدم لتخزين رمز الدخول

يجب توفُّر رمزين مميّزين فريدين لإجراء طلبات إلى واجهة برمجة التطبيقات، وهما رمز إعادة التحميل ورمز الدخول. إذا كنت قد تابعت سلسلة الشرح حتى الآن، من المفترض أنّ مخطط جدول User يخزّن رمزًا مميزًا لإعادة التحميل. يكون تخزين رمز التحديث كافيًا عندما تجري طلبات إلى واجهة برمجة التطبيقات باستخدام المستخدم الذي سجّل الدخول فقط، لأنّك تتلقّى رمز دخول كجزء من عملية المصادقة.

ومع ذلك، عليك الآن إجراء المكالمات بصفتك مستخدمًا آخر غير المستخدم الذي سجّل الدخول، ما يعني أنّ إجراءات المصادقة غير متاحة. لذلك، عليك تخزين رمز الدخول مع رمز إعادة التحميل. عدِّل مخطط جدول User ليشمل رمز دخول:

# Database model to represent a user.
class User(db.Model):
    # The user's identifying information:
    id = db.Column(db.String(120), primary_key=True)
    display_name = db.Column(db.String(80))
    email = db.Column(db.String(120), unique=True)
    portrait_url = db.Column(db.Text())

    # The user's refresh token, which will be used to obtain an access token.
    # Note that refresh tokens will become invalid if:
    # - The refresh token has not been used for six months.
    # - The user revokes your app's access permissions.
    # - The user changes passwords.
    # - The user belongs to a Google Cloud organization
    #   that has session control policies in effect.
    refresh_token = db.Column(db.Text())

    # An access token for this user.
    access_token = db.Column(db.Text())

بعد ذلك، عدِّل أي رمز ينشئ سجلّ User أو يعدّله لتخزين الرمز المميز للوصول أيضًا:

def save_credentials_to_storage(self, credentials):
    # Issue a request for the user's profile details.
    user_info_service = googleapiclient.discovery.build(
        serviceName="oauth2", version="v2", credentials=credentials)
    user_info = user_info_service.userinfo().get().execute()
    flask.session["username"] = user_info.get("name")
    flask.session["login_hint"] = user_info.get("id")

    # See if we have any stored credentials for this user. If they have used
    # the add-on before, we should have received login_hint in the query
    # parameters.
    existing_user = self.get_credentials_from_storage(user_info.get("id"))

    # If we do have stored credentials, update the database.
    if existing_user:
        if user_info:
            existing_user.id = user_info.get("id")
            existing_user.display_name = user_info.get("name")
            existing_user.email = user_info.get("email")
            existing_user.portrait_url = user_info.get("picture")

        if credentials and credentials.refresh_token is not None:
            existing_user.refresh_token = credentials.refresh_token
            # Update the access token.
            existing_user.access_token = credentials.token

    # If not, this must be a new user, so add a new entry to the database.
    else:
        new_user = User(
            id=user_info.get("id"),
            display_name=user_info.get("name"),
            email=user_info.get("email"),
            portrait_url=user_info.get("picture"),
            refresh_token=credentials.refresh_token,
            # Store the access token as well.
            access_token=credentials.token)

        db.session.add(new_user)

    db.session.commit()

تعديل سجلّات قاعدة بيانات المرفقات لتخزين معرّف المعلّم

من أجل تحديد درجة لنشاط، يجب إجراء طلب لضبط pointsEarned كمعلّم في الدورة التدريبية. هناك عدة طرق لتحقيق ذلك:

• تخزين عملية ربط محلية لبيانات اعتماد المعلّم بمعرّفات الدورات التدريبية يُرجى العِلم أنّ المعلّم نفسه قد لا يكون مرتبطًا دائمًا بدورة تدريبية معيّنة.
• أرسِل طلبات GET إلى نقطة نهاية courses في Classroom API للحصول على المعلّمين الحاليين. بعد ذلك، ابحث في سجلات المستخدمين المحليين للعثور على بيانات اعتماد مطابقة خاصة بالمعلّم.
• عند إنشاء مرفق إضافة، خزِّن رقم تعريف المعلّم في قاعدة بيانات المرفقات المحلية. بعد ذلك، استرجِع بيانات اعتماد المعلّم من attachmentId التي تم تمريرها إلى إطار iframe الخاص بـ "طريقة عرض الطالب".

يوضّح هذا المثال الخيار الأخير لأنّك تحدّد الدرجات عندما يكمل الطالب مرفق نشاط.

أضِف حقل معرّف المعلّم إلى جدول Attachment في قاعدة البيانات:

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

    # The ID of the teacher that created the attachment.
    teacher_id = db.Column(db.String(120))

بعد ذلك، عدِّل أي رمز برمجي ينشئ سجلّ Attachment أو يعدّله لتخزين معرّف المنشئ أيضًا:

# Store the attachment by id.
new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    max_points=int(resp.get("maxPoints")),
    teacher_id=flask.session["login_hint"])
db.session.add(new_attachment)
db.session.commit()

استرداد بيانات اعتماد المعلّم

ابحث عن المسار الذي يعرض إطار iframe الخاص بـ "طريقة عرض الطالب". بعد تخزين رد الطالب في قاعدة البيانات المحلية مباشرةً، استردِد بيانات اعتماد المعلّم من وحدة التخزين المحلية. يجب أن تكون هذه الخطوة بسيطة بالنظر إلى التحضير في الخطوتَين السابقتَين. يمكنك أيضًا استخدامها لإنشاء مثيل جديد من خدمة Classroom لمستخدم المعلّم:

# Create an instance of the Classroom service using the tokens for the
# teacher that created the attachment.

# We're assuming that there are already credentials in the session, which
# should be true given that we are adding this within the Student View
# route; we must have had valid credentials for the student to reach this
# point. The student credentials will be valid to construct a Classroom
# service for another user except for the tokens.
if not flask.session.get("credentials"):
    raise ValueError(
        "No credentials found in session for the requested user.")

# Make a copy of the student credentials so we don't modify the original.
teacher_credentials_dict = deepcopy(flask.session.get("credentials"))

# Retrieve the requested user's stored record.
teacher_record = User.query.get(attachment.teacher_id)

# Apply the user's tokens to the copied credentials.
teacher_credentials_dict["refresh_token"] = teacher_record.refresh_token
teacher_credentials_dict["token"] = teacher_record.access_token

# Construct a temporary credentials object.
teacher_credentials = google.oauth2.credentials.Credentials(
    **teacher_credentials_dict)

# Refresh the credentials if necessary; we don't know when this teacher last
# made a call.
if teacher_credentials.expired:
    teacher_credentials.refresh(Request())

# Request the Classroom service for the specified user.
teacher_classroom_service = googleapiclient.discovery.build(
    serviceName=CLASSROOM_API_SERVICE_NAME,
    version=CLASSROOM_API_VERSION,
    credentials=teacher_credentials)

ضبط درجة إرسال

الإجراء من هنا مطابق للإجراء الخاص باستخدام بيانات اعتماد المعلّم الذي سجّل الدخول. يُرجى العِلم أنّه يجب إجراء المكالمة باستخدام بيانات اعتماد المعلّم التي تم استردادها في الخطوة السابقة:

# Issue a PATCH request as the teacher to set the grade numerator for this
# attachment.
patch_grade_response = teacher_classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

اختبار الإضافة

على غرار الجولة الإرشادية السابقة، أنشئ مهمة تتضمّن مرفقًا من نوع نشاط بصفتك معلّمًا، وأرسِل ردًا بصفتك طالبًا، ثم افتح المهمة التي أرسلتها في إطار iframe الخاص بمراجعة عمل الطلاب. من المفترض أن يظهر التقييم في أوقات مختلفة حسب طريقة التنفيذ التي تتّبعها:

• إذا اخترت إرجاع درجة بعد أن أكمل الطالب النشاط، من المفترض أن تظهر لك درجة المسودة في واجهة المستخدم قبل فتح إطار iframe الخاص بـ "مراجعة عمل الطالب". يمكنك أيضًا الاطّلاع عليها في قائمة الطلاب عند فتح الواجب، وفي مربّع "الدرجة" بجانب إطار iframe الخاص بمراجعة "عمل الطالب".
• إذا اخترت إعادة درجة عندما يفتح المعلّم إطار iframe الخاص بمراجعة "عمل الطالب"، من المفترض أن تظهر الدرجة في مربّع "الدرجة" بعد تحميل إطار iframe بوقت قصير. كما ذكرنا أعلاه، يمكن أن يستغرق ذلك مدة تصل إلى 30 ثانية. بعد ذلك، يجب أن تظهر الدرجة للطالب المحدّد أيضًا في طرق العرض الأخرى لدفتر العلامات في Classroom.

تأكَّد من ظهور النتيجة الصحيحة للطالب.

تهانينا! أنت جاهز للانتقال إلى الخطوة التالية: إنشاء مرفقات خارج Google Classroom.