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

זוהי ההדרכה המפורטת השביעית בנושא תוספים ל-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. הוספת ההיקף הזה לרשימות של היקפים בפרויקט ב-Cloud Google Workspace Marketplace SDK, מסך ההסכמה של OAuth קוד השרת.

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 וגם על ידי מורה באמצעות ממשק המשתמש של 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()
)

בדיקת התוסף

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

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

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

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

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

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

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