ציונים של קבצים מצורפים וחזרת ציונים

זהו המדריך השישי בסדרת המדריכים שלנו על תוספים ל-Classroom.

במדריך הזה, תשנו את הדוגמה מהשלב הקודם במדריך כדי ליצור קובץ מצורף מסוג פעילות שניתן לתת עליו ציונים. אתם יכולים גם להעביר חזרה ל-Google Classroom ציון באופן פרוגרמטי, והוא יופיע ביומן הציונים של המורה כטיוטה.

המדריך הזה שונה במקצת מהמדריכים האחרים בסדרה, כי יש בו שתי גישות אפשריות להעברת הציונים בחזרה ל-Classroom. לשני הגורמים האלה יש השפעה שונה על חוויית המשתמש וחוויית הפיתוח, ולכן חשוב להביא בחשבון את שניהם בתכנון התוסף ל-Classroom. אפשר לקרוא את המדריך בנושא אינטראקציה עם קבצים מצורפים כדי לקבל מידע נוסף על אפשרויות ההטמעה.

לתשומת ליבכם: תכונות הדירוג ב-API הן אופציונליות. אפשר להשתמש בהם עם כל קובץ מצורף מסוג פעילות.

במהלך המדריך הזה, תבצעו את הפעולות הבאות:

• משנים את הבקשות הקודמות ליצירת קבצים מצורפים ל-Classroom API כך שיגדירו גם את המכנה של הציון של הקובץ המצורף.
• מתן ציון באופן פרוגרמטי למטלה שהתלמיד או התלמידה הגישו והגדרת המונה של הציון של הקובץ המצורף.
• איך מטמיעים שתי גישות להעברת הציון של המטלה ל-Classroom באמצעות פרטי הכניסה של המורה או פרטי הכניסה שלו אופליין.

בסיום, הציונים יופיעו ביומן הציונים של Classroom אחרי שההתנהגות של ההעברה החוזרת מופעלת. הרגע המדויק שבו זה קורה תלוי בשיטת ההטמעה.

לצורך הדוגמה הזו, נשתמש שוב בפעילות מההדרכה הקודמת, שבה מוצגת לתלמידים תמונה של אתר היסטורי מפורסם והם מתבקשים להזין את השם שלו. נותנים ציונים מלאים על הקובץ המצורף אם התלמיד/ה מזינים את השם הנכון, ואפס אחרת.

הסבר על התכונה 'מתן ציונים' ב-API של התוספים ל-Classroom

התוסף יכול להגדיר גם את המונה וגם את המכנה של הציון של הקובץ המצורף. הערכים האלה מוגדרים באמצעות הערכים pointsEarned ו-maxPoints ב-API. כרטיס הקובץ המצורף בממשק המשתמש של Classroom מציג את הערך של maxPoints אחרי שהוא מוגדר.

איור 1. ממשק המשתמש ליצירת מטלה עם שלוש כרטיסיות של קבצים מצורפים של תוספי Classroom שמוגדרת בהם הערך maxPoints.

באמצעות ה-API של התוספים ל-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 במסד הנתונים המקומי של הקבצים המצורפים. כך לא תצטרכו לבצע קריאה נוספת ל-API מאוחר יותר כשתנתנו ציונים למטלות של התלמידים. עם זאת, חשוב לזכור שיכול להיות שהמורים ישנו את ההגדרות של ציונים במטלות ללא קשר לתוסף. שולחים בקשת 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?

הבעיה היא שנדרש היקף הרשאות OAuth‏ teacher כדי להגדיר את pointsEarned. לא מומלץ להקצות את ההיקף teacher למשתמשים שהם תלמידים. הדבר עלול לגרום להתנהגות בלתי צפויה כשהתלמידים ייצרו אינטראקציה עם התוסף, למשל טעינה של iframe בתצוגת המורה במקום iframe בתצוגת התלמיד/ה. לכן יש שתי אפשרויות להגדרת pointsEarned:

• באמצעות פרטי הכניסה של המורה שמחובר לחשבון.
• באמצעות פרטי הכניסה של המורה ששמורים (באופליין).

בקטעים הבאים נסביר על היתרונות והחסרונות של כל גישה, ואז נציג הדגמה של כל הטמעה. חשוב לדעת שבדוגמאות שצירפנו מופיעות שתי הגישות להעברת ציון ל-Classroom. בהוראות הספציפיות לשפות השונות שמפורטות בהמשך מוסבר איך לבחור גישה כשמריצים את הדוגמאות:

הגדרת ציונים באמצעות פרטי הכניסה של המורה שנכנס לחשבון

משתמשים בפרטי הכניסה של המשתמש שמחובר כדי לשלוח את הבקשה להגדרת pointsEarned. הפעולה הזו אמורה להיות אינטואיטיבית למדי, כי היא משקפת את שאר תהליך ההטמעה עד כה, והיא לא מצריכה הרבה מאמץ.

עם זאת, חשוב לזכור שהמורה רק יכול לבצע פעולות בעבודה של התלמיד/ה בתוך ה-iframe של בדיקת העבודות של התלמידים. יש לכך כמה השלכות חשובות:

• הציונים לא יאוכלסו ב-Classroom עד שהמורה יבצע פעולה בממשק המשתמש של Classroom.
• יכול להיות שהמורה יצטרך לפתוח כל עבודה שהתלמידים הגישו כדי לאכלס את כל הציונים של התלמידים.
• יש עיכוב קצר בין הזמן שבו Classroom מקבל את הציון לבין הזמן שבו הוא מופיע בממשק המשתמש של Classroom. בדרך כלל, ההשהיה נמשכת חמש עד עשר שניות, אבל היא יכולה להימשך עד 30 שניות.

השילוב של הגורמים האלה עשוי לחייב את המורים לבצע עבודה ידנית משמעותית וממושכת כדי לאכלס את הציונים של הכיתה באופן מלא.

כדי להטמיע את הגישה הזו, מוסיפים קריאה אחת נוספת ל-API למסלול הקיים של בדיקת המטלות של התלמידים.

אחרי אחזור הרשומות של ההגשה והקבצים המצורפים של התלמיד, צריך להעריך את ההגשה של התלמיד ולאחסן את הציון שהתקבל. מגדירים את הציון בשדה pointsEarned של אובייקט AddOnAttachmentStudentSubmission. לבסוף, שולחים בקשת PATCH אל נקודת הקצה (endpoint) 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. להגדיר ציון למטלה.

לצורך ההדגמה הזו, נגדיר את הציון כשהתלמיד או התלמידה משלימים את הפעילות, כלומר כשהם שולחים את הטופס במסלול 'תצוגת התלמיד/ה'.

שינוי הרשומות במסד הנתונים של המשתמשים כדי לאחסן את טוקן הגישה

כדי לבצע קריאות ל-API נדרשים שני אסימונים ייחודיים: אסימון הרענון ואסימון הגישה. אם פעלתם לפי ההוראות עד עכשיו, סכימת הטבלה User אמורה כבר לאחסן אסימון רענון. אחסון אסימון הרענון מספיק כשאתם מבצעים קריאות API רק עם המשתמש שמחובר לחשבון, כי אתם מקבלים אסימון גישה כחלק מתהליך האימות.

עם זאת, עכשיו תצטרכו לבצע שיחות בשם משתמש אחר ולא בשם המשתמש שנכנס לחשבון, כלומר תהליך האימות לא יהיה זמין. לכן, צריך לאחסן את אסימון הגישה לצד אסימון הרענון. מעדכנים את הסכימה של טבלת 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.