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