בדף הזה מוסבר איך ליצור ולהגדיר פרויקטים ב-Google Cloud לתוספים של Classroom. פרויקטים ב-Google Cloud משמשים להטמעה של כניסה יחידה (SSO) של Google באמצעות OAuth 2.0 (Google SSO), לאישור בקשות שמוגשות על ידי התוסף ולניהול של דף התוסף בחנות Google Workspace Marketplace.
מידע כללי נוסף על פרסום תוסף ב-Marketplace זמין במאמר פרסום אפליקציה.
יצירת פרויקט ב-Google Cloud
יש שני סוגים של פרויקטים שאפשר ליצור: פרויקט פרטי שמשמש לפיתוח ופרויקט ציבורי שאפשר להגיע אליו דרך משתמשי הקצה. התוויות 'ציבורי' ו'פרטי' מתייחסות לחשיפה של האפליקציה ב-Google Workspace Marketplace. אפליקציה פרטית ב-Marketplace יכולה להיות מותקנת רק על ידי משתמשים בדומיין שבו היא נוצרה, ואילו אפליקציה ציבורית ב-Marketplace זמינה לכל דומיין ב-Google Workspace. צריך ליצור שתי אפליקציות נפרדות, כי פרויקט לא יכול להיות גם ציבורי וגם פרטי. אפליקציות ציבוריות צריכות לעבור בדיקה ולקבל אישור לפני שהן זמינות ב-Marketplace.
למידע כללי על יצירת פרויקטים ב-Google Cloud, אפשר לעבור אל יצירת פרויקט ב-Google Cloud.
יצירת פרויקט ציבורי ב-Google Cloud
הפרויקט הזה מייצג את אפליקציית התוסף שאדמינים, מורים ותלמידים יכולים לגשת אליה. צוות Google Workspace Marketplace צריך לבדוק ולאשר פרויקט ציבורי לפני שאפשר להשיק או להתקין אותו.
יוצרים פרויקט חדש ב-Google Cloud בדומיין הייצור.
מפעילים את Classroom API בפרויקט ב-Cloud.
מפעילים את Google Workspace Marketplace SDK בפרויקט ב-Cloud.
מגדירים את App Configuration (הגדרת האפליקציה) ב-Marketplace SDK > App Visibility (חשיפת האפליקציה) לPublic (גלוי לכולם) ומסמנים את התיבה Unlisted (לא רשום).
ממלאים את שדות החובה בדף Store Listing (פרטי האפליקציה בחנות) ב-Marketplace SDK ולוחצים על PUBLISH (פרסום).
צוות Google Workspace Marketplace יבדוק את האפליקציה. הם יתקשרו איתך באמצעות כתובת האימייל של המפתח שצוינה ב-Marketplace SDK. אחרי שהאפליקציה אושרה, צריך לבטל את הסימון בתיבה לא רשום כדי שמורים ואדמינים יוכלו למצוא אותה ב- Marketplace.
יצירת פרויקט פרטי ב-Google Cloud
הפרויקט הפרטי הזה מייצג את אפליקציית התוסף שמשמשת לפיתוח. הוא לא נגיש למשתמשים מחוץ לדומיין שבו הוא נוצר, אבל לא צריך לאשר אותו לפני ההתקנה. לכן, Google ממליצה להשתמש בפרויקט הזה כדי לפתח ולבדוק את התוסף בסביבה מבוקרת.
כדי ליצור פרויקט פרטי, צריך גישה לדומיין Google Workspace for Education עם רישיון Teaching & Learning או Plus. אם עדיין אין לכם גישה לדומיין כזה, אתם יכולים לפעול לפי השלבים הבאים כדי להגדיר דומיין הדגמה של Google Workspace for Education, לשדרג אותו לרישיון Plus ולאפשר לו גישה ל-Classroom add-ons API:
- מבצעים את השלבים לקבלת דומיין בדיקה למפתחים.
כשאתם מחוברים כמשתמש עם הרשאות אדמין בדומיין ההדגמה, יוצרים פרויקט חדש ב-Google Cloud.
אם אתם לא מצליחים לגשת אל Google Cloud Console או ליצור פרויקטים ב-Cloud, כדאי לבדוק את הדברים הבאים ב מסוף Admin:
- עוברים לדף הגדרות חשבון > הגדרות גישה לפי גיל ובוחרים באפשרות כל המשתמשים בקבוצה או ביחידה הארגונית הזו הם בני 18 ומעלה.
- בקטע אפליקציות > שירותי Google נוספים:
- Google Cloud Platform מופעל לכולם.
- ההגדרה של יצירת פרויקטים היא המשתמשים יכולים ליצור פרויקטים.
- הגדרות הגישה ל-Cloud Shell הן מותר לגשת אל Cloud Shell.
ממלאים את טופס הבקשה לשדרוג דומיין הדמו ושולחים אותו. מילוי הטופס הזה ושליחתו מהווים בקשה לשדרוג הדומיין של ההדגמה ל-Google Workspace for Education Plus עם עשרה רישיונות, ומאפשרים לפרויקט Cloud שלכם לגשת ל-Classroom add-ons API.
תקבלו אימייל כשתהליכי השדרוג והוספה לרשימת ההיתרים יסתיימו. מקצים רישיונות ל-Plus לחשבונות המורים לבדיקה ב מסוף Admin. בקטע ספרייה > משתמשים, יוצרים או בוחרים את חשבונות המורים לבדיקה. בכרטיסייה Licenses (רישיונות) של כל מורה, מוודאים ש-Google Workspace for Education Plus מופיע כ-Assigned (מוקצה).
מפעילים את Classroom API בפרויקט ב-Cloud.
מפעילים את Google Workspace Marketplace SDK בפרויקט ב-Cloud.
מגדירים את App Configuration (הגדרת האפליקציה) של Marketplace SDK App Visibility (הרשאות גישה לאפליקציה) למצב private (פרטי).
ממלאים את שדות החובה בדף Store Listing (פרטי האפליקציה בחנות) ב-Marketplace SDK ולוחצים על PUBLISH (פרסום). אחרי שדף האפליקציה בחנות מתפרסם, משתמשים בדומיין יכולים למצוא ולהתקין את האפליקציה ב-Google Workspace Marketplace או על ידי מעבר אל כתובת ה-URL של האפליקציה שמוצגת בדף האפליקציה בחנות.
OAuth 2.0
כדי לגשת ל-Classroom API, צריך לקבל הסכמה לגישה לנתוני המשתמשים. האסימונים האלה מתקבלים על ידי בקשת גישה של Google להיקפי הרשאות OAuth עבור המשתמש המחובר, וקבלת אסימון שאפשר להשתמש בו בהמשך כדי לבצע קריאות API ל-Google Classroom. צריך להגדיר את ההיקפים בדף של התוסף ב-Google Workspace Marketplace כדי שאדמין הדומיין יוכל לתת הסכמה בשם המשתמשים בדומיין אם הם יתקינו את התוסף.
ההיקפים של Classroom הם רגישים, ולכן צריך לבקש אימות OAuth לפני שמפעילים את התוסף. אחרת, המשתמשים יראו הודעת אזהרה שהאפליקציה לא אומתה, ורק מספר קטן של משתמשים יוכלו לגשת למוצר שלכם. מידע נוסף על אימות זמין בסקירה הכללית על רצף הבדיקה.
במאמר היקפי OAuth ל-Google APIs מופיעה רשימה מפורטת של כל ההיקפים הזמינים והשימושים שלהם. למידע כללי על הגדרת OAuth, אפשר לעיין במאמר הגדרת דף OAuth במסמכי Workspace.
הרשאות של משתמשים
אפליקציית האינטרנט צריכה לבקש לפחות אחת מההרשאות הבאות:
-
https://www.googleapis.com/auth/userinfo.email, שמאפשרת לאפליקציה לצפות בכתובת האימייל של המשתמש. -
https://www.googleapis.com/auth/userinfo.profile, שמאפשרת לאפליקציה לראות מידע אישי כמו תמונה, שם פרטי ושם משפחה ומידע אישי אחר שהמשתמש הפך לזמין לציבור.
אחרי שמשתמש מאשר אחת מההרשאות האלה בתוסף, הוא מזוהה באמצעות פרמטר השאילתה login_hint. הפרמטר הזה מועבר לכל כתובות ה-URL של אפליקציית האינטרנט כשפותחים iframe. אם משתמש לא אישר אחד מההיקפים האלה, login_hint לא יישלח.
login_hint הוא פרמטר סטנדרטי של OpenID Connect שאפשר להעביר ל-Google כשמשתמשים בכניסה באמצעות חשבון Google או כשמבקשים אסימון OAuth. המטרה היא לשפר את חוויית ההרשאה של משתמש הקצה.
היקפי הגישה של תוספים ל-Classroom
ההיקפים הבאים ספציפיים לתוספים ל-Classroom:
-
https://www.googleapis.com/auth/classroom.addons.teacher, שמאפשר גישה לכל ה-API methods. -
https://www.googleapis.com/auth/classroom.addons.student, שמאפשרת גישה להפעלת אימות ולפעולות קריאה של קבצים מצורפים.
גם אם יש אסימון גישה תקף ל-OAuth שמציין את פרטי הכניסה של המשתמש, קריאות ל-API מוגבלות בדרישות נוספות:
- כל השיטות מחייבות שהמשתמש יהיה מורה או תלמיד בקורס שצוין על ידי
courseIdבבקשה. - כדי ליצור, לעדכן או למחוק קבצים מצורפים ולהעביר ציונים, המשתמש צריך להיות מורה.
- הגישה לשיחות בפוסט ספציפי ב-Google Classroom מוגבלת על ידי הבדיקות הבאות.
- אם לתוסף כבר יש לפחות קובץ מצורף אחד בפוסט, הוא יכול לשלוח בקשות ל:
- אימות ההשקה של iframe
- פעולות קריאה, עדכון ומחיקה של קבצים מצורפים
- עדכוני ציונים בפוסט הזה
- כשפותחים את ה-iframe של התוסף בפעם הראשונה, יכול להיות שעדיין לא צורף קובץ לפוסט. יש פרמטר של שאילתה
addOnTokenשאפשר להשתמש בו כדי לשלוח בקשות לפרטים הבאים:- יצירת קובץ מצורף מתחת לפוסט (נדרש
addOnToken) - הפעלת אימות (
addOnTokenמאומת אם הוא מסופק, והוא נדרש אם לתוסף אין קובץ מצורף קיים בפוסט)
- יצירת קובץ מצורף מתחת לפוסט (נדרש
- אם לתוסף כבר יש לפחות קובץ מצורף אחד בפוסט, הוא יכול לשלוח בקשות ל:
אימות OAuth
תוסף ל-Classroom משתמש ב-Google APIs כדי לגשת לנתונים של משתמשי Google.
מידע נוסף על תהליך האימות מופיע בשאלות נפוצות בנושא אימות אפליקציות באמצעות OAuth API.
הרישום ב-Google Workspace Marketplace
למידע כללי על הגדרת Google Workspace Marketplace SDK, אפשר לעבור אל הפעלה והגדרה של Google Workspace Marketplace SDK ויצירת דף מוצר ב-Google Workspace Marketplace.
שיקולים לגבי דף האפליקציה
בMarketplace SDK Store Listing של פרויקט Google Cloud הציבורי שלכם מפורטים השם והתיאורים של האפליקציה שמוצגים למשתמשי הקצה. אפשר לספק את הפרטים האלה בכמה שפות בקטע פרטי האפליקציה.
חשוב להקפיד על ההנחיות הבאות כשיוצרים כרטיסי מוצר:
- בקטע פרטי האפליקציה:
- לא כדאי להשתמש בסימני פיסוק בשם האפליקציה. לדוגמה, עדיף להשתמש ב-My Add-on by My Company (התוסף שלי מאת החברה שלי) במקום ב-My Company: My Add-on (החברה שלי: התוסף שלי) או ב-My Add-on, by My Company (התוסף שלי, מאת החברה שלי).
- הטקסט בתיאור הקצר ובתיאור המפורט לא יכול להיות זהה.
- מוודאים שבחרתם ערך בשדה תמחור. השדה הזה כולל אפשרויות לתמחור בחינם, בתשלום עם תקופת ניסיון בחינם, בתשלום עם תכונות בחינם ובתשלום. אין צורך לציין את סכום העלות בכרטיס המוצר ב-Marketplace.
- מוודאים שבחרתם ערך בשדה קטגוריה. משאבים אקדמיים או כלים למורים ולאדמינים יכולים להיות בחירה טובה לתוסף ל-Classroom.
- מידע נוסף מופיע בתיאור של פרטי האפליקציה ב-Marketplace.
- בקטע נכסי גרפיקה:
- נכסי הגרפיקה שסופקו לא מטושטשים ועומדים בדרישות הגודל שצוינו בתקנים של Google Workspace Marketplace
- צילומי המסך שסיפקתם הם ייצוגים מדויקים של חוויית השימוש בתוסף.
- בקטע Support Links (קישורי תמיכה):
- חשוב לוודא שסיפקת קישור לתנאים ולהגבלות של האפליקציה.
- חשוב לוודא שאתם עומדים בהנחיות המיתוג של Google API, שכוללות את השמות והתיאורים המותרים.
- אם אתם מתייחסים למוצרים של Google בפרטי המוצר, אתם צריכים להשתמש בשם שלהם בפורמט שמופיע ברשימת הסימנים המסחריים. אם מצוין, צריך להשתמש בסמל של סימן מסחרי (™), למשל Google Docs™ ולא Google Docs.
שילוב עם שירותי הרישוי והחיוב של Google
אם אתם רוצים לשלב את האפליקציות שלכם ב-Google Workspace Marketplace עם שירותי הרישוי והחיוב של Google, אתם יכולים להיעזר ב- Marketplace API.
הגדרות ההתקנה
תוספים יכולים לאפשר התקנה אישית בנוסף להתקנה על ידי אדמין. בדף הזה מודגשים כמה הבדלים בין שני סוגי ההתקנות. המטרה היא לא לקדם אף אחד מסוגי ההתקנות. אתם יכולים לבחור אם לאפשר התקנה אישית בדף הגדרת האפליקציה ב-Google Workspace Marketplace SDK.
התקנה על ידי אדמין
התקנות על ידי אדמין מאפשרות לאדמין להוסיף תוסף לכל החשבונות בדומיין או לקבוצות גישה או ליחידות ארגוניות ספציפיות. רק אדמין של הדומיין יכול לבצע התקנה של אדמין. האדמין יכול גם להסכים לכל היקפי הגישה בשם כל המשתמשים בדומיין. אם האדמין בוחר לעשות זאת, המשתמשים לא מתבקשים להסכים להיקפי גישה כלשהם.
ריכזנו כאן כמה נקודות שכדאי לזכור לגבי התקנה על ידי אדמין.
- אמצעי בקרה מחמירים יותר. אדמינים יכולים להגביל את הגישה לתוסף למשתמשים מסוימים.
- תאימות לרישוי. אם האפליקציה שלכם דורשת רישיון, ניהול ההתקנות דרך אדמין יכול לעזור לוודא שהרישיונות מופצים ומשמשים בצורה מתאימה במוסד הרלוונטי.
- הפחתת העומס על משתמשי הקצה. התקנה על ידי אדמין מפחיתה את עומס ההגדרה על המורים והתלמידים. התוצאה יכולה להיות חוויית משתמש חלקה יותר עם פחות קליקים ופחות הזדמנויות לבלבול.
במאמר התקנה של אפליקציות מ-Marketplace בדומיין מוסבר איך לבצע התקנות כאדמינים, ובמאמר איך המבנה הארגוני פועל מוסבר על יחידות ארגוניות ועל קבוצות גישה.
התקנה רק אצלי
התקנות פרטיות מוסיפות תוסף לחשבון של המשתמש. במהלך ההתקנה, המשתמש מתבקש להסכים להיקפי הגישה של התוסף.
ריכזנו כאן כמה נקודות שכדאי לזכור לגבי התקנה אישית.
- לסייע באימוץ. יותר משתמשים יוכלו לראות ולהתקין את התוסף שלכם מ-Google Workspace Marketplace. אם תאפשרו התקנה פרטנית, יכול להיות שיותר מורים יאמצו את המוצר שלכם או ימליצו עליו.
- בדיקות של אדמינים. אדמינים יכולים להתקין תוסף באופן פרטני כדי לבדוק או להעריך אותו לפני שהם מאשרים או מתקינים אותו לקבוצה רחבה יותר.
בנוסף להתקנת תוספים בשם המשתמשים, אדמינים יכולים גם לנהל רשימת היתרים כדי לאפשר למשתמשים להתקין תוספים שמאפשרים התקנה פרטנית. אם תוסף לא נמצא ברשימת ההיתרים, המשתמשים עדיין יכולים לראות את דף התוסף ב-Google Workspace Marketplace, אבל הם לא יכולים להתקין אותו. במקום זאת, הם רואים הודעה שמסבירה שאדמין הדומיין לא אישר את התקנת התוסף. מידע נוסף על ההתנהגות הזו זמין במאמר בנושא ניהול אפליקציות מ-Google Workspace Marketplace ברשימת ההיתרים.
למידע נוסף, אפשר לעיין בתיעוד של הגדרות ההתקנה ב-Google Workspace Marketplace.
שילוב אפליקציות
חובה לציין כתובת URL של iframe להפעלה בשדה URI של הגדרת קובץ מצורף. כתובת ה-URL הזו משמשת כערך src של ה-iframe של גילוי קבצים מצורפים. מורים משתמשים ב-iframe של חיפוש קבצים מצורפים כדי למצוא תוכן או פעילויות שאפשר לצרף למטלה. אפשר להגדיר את זה במסוף של פרויקט Google Cloud.
ההגדרות של Allowed Attachment URI Prefixes משמשות לאימות של ה-URI שמוגדר ב-AddOnAttachment באמצעות השיטות *.addOnAttachments.create ו-*.addOnAttachments.patch. האימות הוא התאמה של מחרוזת מילולית עם קידומת, ואי אפשר להשתמש בתווים כלליים לחיפוש.
צריך גם לציין את כל הקידומות של מזהי ה-URI שמהן התוסף יכול לצרף קבצים. התכונה הזו משפרת את האבטחה על ידי מניעת קבצים מצורפים ממקורות לא מורשים.
מגדירים את שני הערכים האלה בדף App Configuration של Marketplace SDK בפרויקט Google Cloud.
חשבונות בדיקה
צריך ליצור חשבונות בדיקה בדומיין ההדגמה כדי לוודא שהתוסף הפרטי מתנהג בצורה נכונה. צריך שני חשבונות של תלמידים כדי לבדוק את המעבר בין תלמידים ב-iframe של כלי לבדיקת עבודות של תלמידים.
הצעות לחשבונות בדיקה:
- תמי המורה, tammy.teacher@<your demo domain>
- סם סטודנט, sam.student@<your demo domain>
- תלמיד/ה סאלי, sally.student@<your demo domain>
כדי ליצור חשבון בדיקה חדש, פועלים לפי השלבים הבאים:
- נכנסים למסוף Admin.
- עוברים אל משתמשים.
- לוחצים על הוספת משתמש חדש (ראו איור 1).
- מזינים את פרטי המשתמש ומקצים לו את התפקידים המתאימים.
איור 1. מיקום הקישור הוספת משתמש חדש במסוף Admin.
כדי ליצור קבוצת בדיקה חדשה:
- נכנסים למסוף Admin.
- עוברים אל קבוצות.
- לוחצים על יצירת קבוצה (ראו איור 2).
- מזינים את החברים והבעלים של הקבוצה.
איור 2. מיקום הקישור יצירת קבוצה במסוף Admin.