קבצים מצורפים חיצוניים והגשה

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

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

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

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

הוספת היקף ה-OAuth לניהול ההקצאות

חשוב לוודא שהאפליקציה מבקשת את ההיקפים הבאים:

  • https://www.googleapis.com/auth/classroom.addons.teacher
  • https://www.googleapis.com/auth/classroom.addons.student
  • https://www.googleapis.com/auth/classroom.coursework.students

לא היה צורך בהיקף classroom.coursework.students בעבר, והוא משמש ליצירה או לשינוי של הקצאות CourseWork. מוסיפים את ההיקף הזה לרשימות של היקפי ההרשאות ב- Google Workspace Marketplace SDK, במסך ההסכמה של OAuth ובקוד השרת של הפרויקט שלכם ב-Cloud.

Python

  SCOPES = [
    "https://www.googleapis.com/auth/classroom.addons.teacher",
    "https://www.googleapis.com/auth/classroom.addons.student",
    "https://www.googleapis.com/auth/classroom.coursework.students",
  ]

יצירת מטלה ב-Classroom

הוספת לחצנים לדף אינטרנט שאינו iframe

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

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

Python

דוגמת ה-Python שסופקה משנה את הנתיב /index שהוצגה בשלב הראשון של ההדרכה המפורטת.

<!-- /webapp/templates/index.html -->
<a href="clear-credentials.html">Logout</a>
<a href="start-auth-flow.html">Login</a>

<br>

<a href="create-coursework-assignment.html">Create a CourseWork Assignment</a>

יש להוסיף תבנית HTML לייצוג יעד באתר שלך. הדף הזה מייצג את התוכן שיצורף למטלה CourseWork.

<!-- /webapp/templates/example-coursework-assignment.html -->
<h1>CourseWork assignment loaded!</h1>
<p>You've loaded a CourseWork assignment! It was created from an external web page.</p>

יוצרים קובץ מודול Python חדש לטיפול בנתיבים שקשורים ל-CourseWork. הערך הוא coursework_routes.py בדוגמה שסופקה שלנו. מוסיפים את שלושת המסלולים הבאים, ושימו לב שחלק מהתוכן צריך לעבור בהמשך.

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """

  # Check that the user is signed in. If not, perform the OAuth 2.0
  # authorization flow.
  credentials = get_credentials()

  if not credentials:
    return start_auth_flow("coursework_assignment_callback")

  # Construct the Google Classroom service.
  classroom_service = get_classroom_service()

  pass  # To be completed later.

@app.route("/example-coursework-assignment/<assignment_type>")
def example_coursework_assignment(assignment_type):
  """
  Renders the "example-coursework-assignment.html" template.
  """
  return flask.render_template(
      "example-coursework-assignment.html", assignment_type=assignment_type
  )

@app.route("/coursework-assignment-callback")
def coursework_assignment_callback():
  """
  Completes the OAuth 2.0 handshake and stores credentials in the session.
  This is identical to the callback introduced in the sign-in walkthrough,
  but redirects the user to the index page instead of the attachment
  discovery page.
  """
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE,
      scopes=SCOPES,
      state=flask.session["state"],
      redirect_uri=flask.url_for("coursework_assignment_callback", _external=True),
  )

  flow.fetch_token(authorization_response=flask.request.url)

  credentials = flow.credentials
  flask.session["credentials"] = session_credentials_to_dict(
      credentials
  )

  # Close the current window and redirect the user to the index page.
  return flask.render_template("close-me.html", redirect_destination="index")

איך בודקים אם משתמש עומד בדרישות ליצירת תוסף

כדי ליצור קבצים מצורפים של תוספים בשם המשתמש, יש כמה דרישות מוקדמות שצריך לעמוד בהן. לנוחיותכם, Google מספקת את השיטה courses.checkAddOnCreationEligibility כדי לקבוע אם המשתמש עומד בדרישות המוקדמות האלה. משתמש שעומד בדרישות המוקדמות נקרא כשיר.

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

Python

# /webapp/coursework_routes.py
@app.route("/create-coursework-assignment")
def create_coursework_assignment():
  """
  Completes the assignment creation flow.
  """
  # ... Check that the user is signed in and get the Classroom service ...

  # The ID of the course to which the assignment will be added.
  course_id = 1234567890  # TODO(developer) Replace with an actual course ID.

  # Check whether the user can create add-on attachments.
  eligibility_response = (
      classroom_service.courses()
      .checkAddOnCreationEligibility(courseId=course_id)
      .execute()
  )
  is_create_attachment_eligible = eligibility_response.get("isCreateAttachmentEligible")

  if is_create_attachment_eligible:
    # See the "Create an assignment with add-on attachment for eligible users" section for implementation.
  if not is_create_attachment_eligible:
    # See the "Create a Link Material" section for implementation.

יצירת מטלה עם קובץ מצורף של תוסף למשתמשים שעומדים בדרישות

אם המשתמש עומד בקריטריונים ליצירת קבצים מצורפים של תוספים, יש לבצע את הפעולות הבאות:

  1. שליחה של בקשת API ליצירת מטלה courseWork ב-Google Classroom ללא קבצים מצורפים.
  2. מחלצים את id של המטלה החדשה שנוצרה.
  3. יוצרים CourseWork AddOnAttachment חדש.
  4. אפשר לשלוח בקשה ליצירת קובץ מצורף של תוסף במטלה החדשה שנוצרה ב-Google Classroom.

Python

# /webapp/coursework_routes.py
if is_create_attachment_eligible:
  # Create an assignment.
  coursework = {
      "title": "My CourseWork Assignment with Add-on Attachment",
      "description": "Created using the Classroom CourseWork API.",
      "workType": "ASSIGNMENT",
      "state": "DRAFT",  # Set to 'PUBLISHED' to assign to students.
  }

  # Issue a request to create the assignment.
  create_assignment_response = (
      classroom_service.courses()
      .courseWork()
      .create(courseId=course_id, body=coursework)
      .execute()
  )

  # Create an add-on attachment that links to the selected content and
  # associate it with the new assignment.
  content_url = flask.url_for(
      "example_coursework_assignment",
      assignment_type="add-on-attachment",
      _scheme="https",
      _external=True,
  )

  # Construct an AddOnAttachment instance.
  attachment = {
      "teacherViewUri": {"uri": content_url},
      "studentViewUri": {"uri": content_url},
      "title": f'Test Attachment for Assignment {create_assignment_response.get("id")}',
  }

  # Issue a request to create the attachment.
  add_on_attachment_response = (
      classroom_service.courses()
      .courseWork()
      .addOnAttachments()
      .create(
          courseId=course_id,
          itemId=create_assignment_response.get("id"),  # ID of the new assignment.
          body=attachment,
      )
      .execute()
  )

אם המשתמש לא עומד בדרישות ליצור קבצים מצורפים של תוספים, צריך במקום זאת ליצור 'חומר קישור' על ידי ביצוע הפעולות הבאות:

Python

if not is_create_attachment_eligible:
    coursework = {
        "title": "My CourseWork Assignment with Link Material",
        "description": "Created using the Classroom CourseWork API.",
        "workType": "ASSIGNMENT",
        "state": "DRAFT",  # Set to 'PUBLISHED' to assign to students.
        # Specify the URL for your content as a Link Material.
        "materials": [
            {
                "link": {
                    "url": flask.url_for(
                        "example_coursework_assignment",
                        assignment_type="link-material",
                        _scheme="https",
                        _external=True,
                    )
                }
            }
        ],
    }

    # Issue a request to create the assignment.
    assignment_response = (
        classroom_service.courses()
        .courseWork()
        .create(courseId=course_id, body=coursework)
        .execute()
    )

שינוי מטלה שכבר נוצרה

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

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

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

Python

דוגמת ה-Python שסופקה משנה את הנתיב /index שהשתנה מוקדם יותר בהדרכה המפורטת הזו.

<!-- /webapp/templates/index.html -->
<a href="modify-coursework-assignment.html">Create a CourseWork Assignment</a>

כדי לטפל במסלולים שקשורים ל-CourseWork, צריך ליצור מסלול חדש. זהו הקובץ coursework_routes.py בדוגמה שסופקה.

# Check that the user is signed in.
credentials = get_credentials()

if not credentials:
  return start_auth_flow("coursework_assignment_callback")

# Get the Google Classroom service.
classroom_service = get_classroom_service()

# The ID of the course to which the assignment will be added.
# Ordinarily, you'll prompt the user to specify which course to use. For
# simplicity, we use a hard-coded value in this example.
course_id = 1234567890  # TODO(developer) Replace with an actual course ID.
assignment_id = 1234567890  # TODO(developer) Replace with an actual assignment ID.

# Retrieve details about the CourseWork assignment.
get_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .get(courseId=course_id, id=assignment_id)
    .execute()
)

# Alter the current title.
assignment_title = f"{get_coursework_response.get('title')} (Modified by API request)"

# Issue a request to modify the assignment.
modify_coursework_response = (
    classroom_service.courses()
    .courseWork()
    .patch(
        courseId=course_id,
        id=assignment_id,
        updateMask="title",
        body={"title": assignment_title},
    )
    .execute()
)

בדיקת התוסף

כדי לפשט את הדברים, בדוגמאות שניתנו נעשה שימוש במזהי קורס ומטלות כתובים בתוך הקוד. כדי להשיג את המזהים האלה, שולחים בקשות באמצעות פרטי הכניסה של המורים לשיטות get ו-list של המשאבים courses ו-courseWork. הם גם מוחזרים בתגובה כשיוצרים courseWork מטלות.

מריצים את השרת, עוברים לדף האינדקס ומתחברים לחשבון כמורה, ללא רישיון ל-Google Workspace for Education Teaching & Learning או Plus. אפשר לשנות את סטטוס הרישיון של המשתמש ממסוף Admin בדומיין של הבחינה. לוחצים על הלחצן Create a CourseWork Assignment (יצירת מטלה ב-CourseWork). לאחר מכן, פותחים את ממשק המשתמש של Google Classroom ומוודאים שנוצרה מטלה עם קובץ מצורף של Link Material. הקובץ המצורף אמור לכלול את הכותרת של דף האינטרנט המקושר וכתובת URL.

בדיקה של יצירת קובץ מצורף של תוסף

חוזרים לדף האינדקס ומתחברים כמורה כמשתמש/ת עם רישיון Google Workspace for Education Teaching& Learning או Plus. לוחצים על יצירת מטלה ב-CourseWork, פותחים את ממשק המשתמש של Google Classroom ומוודאים שנוצרה מטלה עם קובץ מצורף. בקובץ המצורף אמורים להופיע השם של אפליקציית התוסף והכותרת שמופיעה בקוד.

בדיקת שינוי של מטלות

חוזרים לדף האינדקס ומוודאים שנכנסתם כמשתמש מורה עם רישיון Teaching & Learning או Plus. לוחצים על הלחצן שינוי מטלה בקורסים, חוזרים לממשק המשתמש של Google Classroom ומוודאים שכותרת המטלה שונתה.

כל הכבוד! השלמת את סדרת ההדרכה המפורטת.