יצירת תוסף ל-Classroom

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

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

ההדרכה המפורטת כוללת את הדברים הבאים:

  • יוצרים פרויקט חדש ב-Google Cloud לתוסף.
  • צור אפליקציית אינטרנט בסיסית עם לחצני כניסה באמצעות placeholder.
  • מפרסמים דף אפליקציה בחנות Google Workspace Marketplace בשביל התוסף.

בסיום אפשר להתקין את התוסף ולטעון אותו iframe של תוספים ל-Classroom.

דרישות מוקדמות

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

Python

בדוגמה שלנו ב-Python נעשה שימוש ב-Flask framework. אפשר להוריד את כל קוד מקור לכל ההדרכות המפורטות מהדף 'סקירה כללית'. הקוד עבור הדרכה מפורטת מסוימת נמצאת בספרייה /flask/01-basic-app/.

אם יש צורך, מתקינים את Python 3.7 ואילך ומוודאים ש-pip זמין.

python -m ensurepip --upgrade

מומלץ גם להגדיר ולהפעיל גרסה וירטואלית חדשה של Python הסביבה.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

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

cd flask/01-basic-app
pip install -r requirements.txt

Node.js

בדוגמה שלנו ל-Node.js נעשה שימוש ב-framework של Express. אפשר להוריד את להשלים את קוד המקור לכל ההדרכה המפורטת מהדף 'סקירה כללית'.

אם יש צורך, מתקינים את NodeJS v16.13+.

התקנת המודולים הנדרשים של צמתים באמצעות npm.

npm install

Java

בדוגמה שלנו ל-Java נעשה שימוש ב-Spring Boot framework. אפשר להוריד קוד המקור המלא לכל ההדרכות המפורטות בדף הסקירה הכללית.

מתקינים את Java 11+ אם הוא עדיין לא מותקן במחשב שלכם.

אפליקציות Springboo יכולות להשתמש ב-Gradle או ב-Maven כדי לנהל גרסאות build ולנהל אותן של יחסי התלות. הדוגמה הזו כוללת את ה-wrapper של Maven שמבטיח בלי שתצטרכו להתקין את Maven עצמה.

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

java --version
./mvnw --version

או ב-Windows:

java -version
mvnw.cmd --version

הגדרת פרויקט ב-Google Cloud

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

יצירת הפרויקט

כדי ליצור פרויקט חדש ב-Google Cloud, נכנסים לדף יצירת הפרויקט. אפשר מזינים שם לפרויקט החדש. לוחצים על Create.

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

בחירת הפרויקט ב-Google Cloud
מסוף

צירוף של Google Workspace Marketplace SDK לפרויקט ב-Google Cloud

עוברים לדפדפן של API Library. חיפוש של Google Workspace Marketplace SDK ה-SDK אמור להופיע ברשימה של תוצאות.

Google Workspace Marketplace SDK
קלפים

בוחרים את הכרטיס של Google Workspace Marketplace SDK ולוחצים על הפעלה.

הגדרת ה-SDK של Google Workspace Marketplace

Google Workspace Marketplace מספק את דף האפליקציה שדרכו המשתמשים אדמינים מתקינים את התוסף. מגדירים את הגדרת האפליקציה ושל Marketplace SDK רשימה ומסך ההסכמה של OAuth כדי להמשיך.

הגדרת האפליקציה

עוברים לדף הגדרת אפליקציה של Marketplace SDK. מספקים את הפרטים הבאים:

  • מגדירים את הרשאות גישה לאפליקציה לערך Public או Private.

    • ההגדרה הציבורית מיועדת לאפליקציות שבסופו של דבר יושקו. למשתמשי הקצה. אפליקציה ציבורית צריכה לעבור תהליך אישור לפני שהיא שמיועדות למשתמשי קצה, אבל אפשר לציין משתמשים שיכולים להתקין לבדוק אותו כטיוטה. זוהי מדינה טרום-פרסום שמאפשרת כדי לבדוק ולפתח את התוסף לפני ששולחים אותו לאישור.
    • ההגדרה הפרטית מתאימה לבדיקות ולפיתוח פנימיים. א' רק משתמשים באותו דומיין יכולים להתקין את האפליקציה הפרטית הפרויקט נוצר. לכן עליך להגדיר את החשיפה ל'פרטי' רק אם הפרויקט נוצר בדומיין עם חשבון Google Workspace for Education המינוי, אחרת משתמשי הבדיקה לא יוכלו להפעיל תוספים ל-Classroom.
  • אם רוצים, משנים את הגדרות ההתקנה ל-Admin Only install. להגביל את ההתקנה למנהלי דומיין בלבד.

  • בקטע שילוב האפליקציה, בוחרים באפשרות תוסף ל-Classroom. היתרה שלך תוצג בקשה ל-URI מאובטח להגדרת קבצים מצורפים; זו כתובת ה-URL ייטענו כשמשתמש פותח את התוסף. למטרות ההדרכה המפורטת, היא צריכה להיות https://<your domain>/addon-discovery.

  • הקידומות המותרות של URI של קבצים מצורפים משמשות לאימות של מזהי ה-URI שהוגדרו AddOnAttachment באמצעות courses.*.addOnAttachments.create courses.*.addOnAttachments.patch שיטות. האימות מילולי התאמה לתחילית של מחרוזת ולא מאפשרת להשתמש בתווים כלליים לחיפוש בשלב הזה בזמן האימון. מוסיפים לפחות את הדומיין הבסיסי (root) של שרת התוכן, כמו https://localhost:5000/ או https://cdn.myedtech.com/.

  • מוסיפים את אותם היקפי הרשאות OAuth שמופיעים במסך ההסכמה של OAuth השלב הקודם.

  • ממלאים את השדות בהתאם לארגון בקטע מפתח קישורים.

רישום חנות

עוברים אל דף דף האפליקציה בחנות של Marketplace SDK. מספקים את הפרטים הבאים:

  • בקטע פרטי האפליקציה, מוסיפים שפה או מרחיבים את התפריט הנפתח שלצד שפה שכבר רשומה. לספק שם אפליקציה ותיאורים; האלה יופיעו בדף האפליקציה בחנות Google Workspace Marketplace של התוסף. לוחצים על סיום כדי לשמור.
  • בוחרים קטגוריה לתוסף.
  • בקטע נכסים גרפיים, מספקים תמונות של שדות החובה. האתרים האלה יכולים יכולים להשתנות מאוחר יותר, והם יכולים להיות placeholders כרגע.
  • בקטע קישורים לתמיכה, מציינים את כתובות ה-URL הנדרשות. האפשרויות האלה יכולות להיות placeholders אם הגדרתם את חשיפת האפליקציה כפרטית בכל פעימה.

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

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

עוברים לדף ליצירת מסך ההסכמה של OAuth. צריך לספק את הפרטים הבאים מידע:

  • מגדירים את User Type כ-External (חיצוני). לוחצים על Create.
  • בדף הבא, ממלאים את הפרטים הנדרשים של האפליקציה ואת הפרטים ליצירת קשר. צריך לספק את כל הדומיינים שמארחים את האפליקציה בקטע דומיינים מורשים. לוחצים על שמירה והמשך.
  • מוסיפים היקפי OAuth שנדרשים לאפליקציית האינטרנט. לעיון ב-OAuth מדריך הגדרהלהסבר מעמיק על היקפים והמטרה שלהם.

    עליך לבקש לפחות אחד מההיקפים הבאים כדי ש-Google תוכל שולחים את פרמטר השאילתה login_hint. הסבר מפורט יותר בנושא ההתנהגות זמינה במדריך להגדרת OAuth:

    • https://www.googleapis.com/auth/userinfo.email (כבר כלול)
    • https://www.googleapis.com/auth/userinfo.profile (כבר כלול)

    ההיקפים הבאים ספציפיים לתוספים ל-Classroom:

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

    לכלול גם את כל היקפי ההרשאות של Google API שהאפליקציה שלכם דורשת מקצה. משתמשים.

    לוחצים על שמור והמשך.

  • צריך לציין את כתובות האימייל של כל חשבונות הבדיקה בדף משתמשים לבדיקה. לוחצים על שמירה והמשך.

מוודאים שההגדרות נכונות ואז חוזרים אל מרכז הבקרה.

התקנת התוסף

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

פיתוח של אפליקציית אינטרנט בסיסית

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

אפליקציית אינטרנט לדוגמה ב-iframe

מטמיעים את שתי נקודות הקצה הבאות:

  • /: מציג הודעת פתיחה ולחצן לסגירה של הכרטיסייה הנוכחית ו-iframe של התוסף.
  • /addon-discovery: הצגת הודעת פתיחה ושני לחצנים: אחד לסגירה רכיב ה-iframe של התוסף ותוסף אחד לפתיחת אתר בכרטיסייה חדשה.

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

יצירת סקריפט של כלי עזר

יוצרים ספריית static/scripts. יצירת קובץ חדש addon-utils.js. מוסיפים את לאחר שתי פונקציות.

/**
 *   Opens a given destination route in a new window. This function uses
 *   window.open() so as to force window.opener to retain a reference to the
 *   iframe from which it was called.
 *   @param {string} destinationURL The endpoint to open, or "/" if none is
 *   provided.
 */
function openWebsiteInNewTab(destinationURL = '/') {
  window.open(destinationURL, '_blank');
}

/**
 *   Close the iframe by calling postMessage() in the host Classroom page. This
 *   function can be called directly when in a Classroom add-on iframe.
 *
 *   Alternatively, it can be used to close an add-on iframe in another window.
 *   For example, if an add-on iframe in Window 1 opens a link in a new Window 2
 *   using the openWebsiteInNewTab function, you can call
 *   window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
 *   1.
 */
function closeAddonIframe() {
  window.parent.postMessage({
    type: 'Classroom',
    action: 'closeIframe',
  }, '*');
};

יצירת מסלולים

הטמעת נקודות הקצה /addon-discovery ו-/.

Python

הגדרה של ספריית האפליקציות

לצורך הדוגמה הזו, צריך לבנות את הלוגיקה של האפליקציה ב-Python. זוהי הספרייה webapp בדוגמה שסופקה.

לדוגמה, יוצרים ספרייה למודול השרת, webapp. מזיזים את static בספרייה של המודול. יצירת ספריית template גם בספריית המודולים; קובצי ה-HTML שלך מועברים לכאן.

פיתוח מודול השרת*

יוצרים את הקובץ __init__.py בספריית המודולים ומוסיפים את הפרטים הבאים ייבוא והצהרות.

from flask import Flask
import config

app = Flask(__name__)
app.config.from_object(config.Config)

# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes

לאחר מכן יוצרים קובץ לטיפול במסלולים של אפליקציית האינטרנט. הדבר webapp/routes.py בדוגמה שסופקה. להטמיע את שני המסלולים חדש.

from webapp import app
import flask

@app.route("/")
def index():
    return flask.render_template("index.html",
                                message="You've reached the index page.")

@app.route("/classroom-addon")
def classroom_addon():
    return flask.render_template(
        "addon-discovery.html",
        message="You've reached the addon discovery page.")

חשוב לשים לב ששני המסלולים שלנו מעבירים משתנה message למשתנה שלהם תבניות Jinja. המידע הזה שימושי כדי לזהות לאיזה דף המשתמש הגיע.

יצירת הגדרות אישיות והפעלה של קבצים

בתיקיית השורש של האפליקציה, יוצרים את main.py ואת config.py . צריך להגדיר את המפתח הסודי ב-config.py.

import os

class Config(object):
    # Note: A secret key is included in the sample so that it works.
    # If you use this code in your application, replace this with a truly secret
    # key. See https://flask.palletsprojects.com/quickstart/#sessions.
    SECRET_KEY = os.environ.get(
        'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."

בקובץ main.py, מייבאים את המודול ומפעילים את שרת Flask.

from webapp import app

if __name__ == "__main__":
    # Run the application over HTTPs with a locally stored certificate and key.
    # Defaults to https://localhost:5000.
    app.run(
        host="localhost",
        ssl_context=("localhost.pem", "localhost-key.pem"),
        debug=True)

Node.js

הנתיבים רשומים בקובץ app.js עם השורות הבאות.

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/addon-discovery', addonRouter);

צריך לפתוח את /01-basic-app/routes/index.js ולבדוק את הקוד. מסלול זה הוא שמגיעים אליו כשמשתמש הקצה נכנס לאתר של החברה. המסלול יוצר את התשובה באמצעות תבנית הכידון של index ומעבירה לתבנית אובייקט נתונים שמכיל את המשתנים title ו-message.

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

פותחים את המסלול השני /01-basic-app/routes/classroom-addon.js ובודקים בקוד. הנתיב מתקבל כשמשתמש הקצה נכנס לתוסף. הודעה שהמסלול הזה משתמש בתבנית הכידון של discovery וגם הפריסה addon.hbs כדי לעבד את הדף באופן שונה מהפריסה של החברה האתר.

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
  });
});

Java

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

צריך ליצור מחלקה של בקר, Controller.java בפרויקט לדוגמה הזה, כדי מגדירים את נקודות הקצה. בקובץ הזה, מייבאים את ההערה @GetMapping את התלות spring-boot-starter-web.

import org.springframework.web.bind.annotation.GetMapping;

מוסיפים את ההערה של Spring framework control מעל הכיתה כדי לציין את מטרת הכיתה.

@org.springframework.stereotype.Controller
public class Controller {

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

/** Returns the index page that will be displayed when the add-on opens in a
*   new tab.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the index page template if successful, or the onError method to
*   handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
  try {
    return "index";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Returns the add-on discovery page that will be displayed when the iframe
*   is first opened in Classroom.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
  try {
    return "addon-discovery";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Handles application errors.
*   @param errorMessage message to be displayed on the error page.
*   @param model the Model interface to pass error information to display on
*   the error page.
*   @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
  model.addAttribute("error", errorMessage);
  return "error";
}

בדיקת התוסף

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

מעולה! עכשיו אפשר להמשיך לשלב הבא: כניסת משתמשים באמצעות SSO של Google.