בדף הזה מוצג כל המידע שצריך לדעת על יצירה והגדרה של פרויקטים ב-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. אלה צריכים להיות שתי אפליקציות נפרדות, כי פרויקט לא יכול להיות גם ציבורי וגם פרטי. אפליקציות ציבוריות צריכות לעבור בדיקה ולקבל אישור לפני שהן זמינות בזירת המסחר.
במאמר יצירת פרויקט ב-Google Cloud תוכלו לקרוא מידע כללי על יצירת פרויקטים ב-Google Cloud.
יצירת פרויקט פרטי ב-Google Cloud
הפרויקט הפרטי הזה מייצג את אפליקציית התוסף שמשמשת לפיתוח. היא לא נגישה למשתמשים מחוץ לדומיין שבו היא נוצרה, אבל לא צריך לקבל אישור לפני ההתקנה. לכן, Google ממליצה להשתמש בפרויקט הזה כדי לפתח ולבדוק את התוסף בסביבה מבוקרת.
כדי ליצור פרויקט פרטי, צריך גישה לדומיין ב-Google Workspace for Education עם רישיונות Teaching & Learning או Plus. אם עדיין אין לכם גישה לדומיין הזה, תוכלו לבצע את הפעולות הבאות כדי להגדיר דומיין הדגמה של Google Workspace for Education, לשדרג אותו לרישיון Plus ולתת לו גישה ל-API של התוספים ל-Classroom:
- מבצעים את השלבים לקבלת דומיין לבדיקה למפתחים.
כשאתם מחוברים כאדמינים בדומיין לדוגמה, אתם יכולים ליצור פרויקט חדש ב-Google Cloud.
הפעל את Classroom API.
מפעילים את Google Workspace Marketplace SDK.
מגדירים את החשיפה של האפליקציה ל-Marketplace SDK App Configuration (חשיפה של האפליקציה) כ-Private.
ממלאים ושולחים את טופס הבקשה לשדרוג דומיין להדגמה. שליחת הטופס הזה תאפשר ל-Google לשדרג את הדומיין לדוגמה שלך ל-Google Workspace for Education Plus עם עשרה רישיונות, ולאפשר לפרויקט ב-Cloud להוסיף את הפרויקט שלך ב-Cloud לממשק ה-API של התוספים ל-Classroom.
יצירת פרויקט ציבורי ב-Google Cloud
הפרויקט הזה מייצג את האפליקציה של התוסף שאדמינים, מורים ותלמידים יכולים לגשת אליה.
- יוצרים פרויקט חדש ב-Google Cloud ומפעילים את Google Workspace Marketplace SDK. הגדר את Marketplace SDK App Configuration App Visibility (חשיפה של אפליקציות) כציבורי ולא רשום. אי אפשר לשתף או להמיר את הפרויקט הפרטי שנעשה בו שימוש במהלך בדיקות פנימיות. עליו להיות מספר פרויקט חדש.
- כדי להוסיף את הפרויקט לרשימת ההיתרים של התוספים, משתפים את מזהה הפרויקט ב-Google Cloud עם השותף שלכם ב-Google. כך, הפרויקט מקבל גישה לתכונות התוסף החדשות של ממשק ה-API של Classroom.
- לאחר אישור התוסף, צוות Google Workspace Marketplace משנה את התוסף מ'לא רשום' ל'רשום', כדי שמורים יוכלו למצוא אותו בחנות.
OAuth 2.0
כדי להשתמש ב-Classroom API, צריך לקבל הסכמה להרשאת גישה לנתוני משתמשים. כדי להשיג את ההרשאות האלה, צריך לבקש מ-Google לגשת להיקפי OAuth עבור המשתמש המחובר, ולקבל אסימון שיכול לשמש בהמשך לביצוע קריאות ל-API ב-Google Classroom. את היקפי ההרשאות צריך להגדיר בדף האפליקציה בחנות ב-Google Workspace Marketplace, כדי שמנהל הדומיין יוכל להביע הסכמה בשמם של משתמשי הדומיין אם הם יתקינו את התוסף.
בדף OAuth Scopes for Google APIs אפשר למצוא רשימה מפורטת של כל ההיקפים הזמינים והשימושים שלהם. למידע כללי על הגדרות OAuth, קראו את המאמר הגדרת הדף OAuth במסמכי התיעוד של Workspace.
הרשאות של משתמשים
אפליקציית האינטרנט שלך צריכה לבקש לפחות אחד מההיקפים הבאים:
https://www.googleapis.com/auth/userinfo.email, שמאפשרת לאפליקציה לראות את כתובת האימייל של המשתמש.https://www.googleapis.com/auth/userinfo.profile, שמאפשרת לאפליקציה לראות מידע אישי כמו דיוקן, שם פרטי ושם משפחה ומידע אישי אחר שהמשתמש הגדיר כגלוי לכולם.
אחרי שמשתמש אישר אחד מההיקפים האלה בתוסף, הוא מזוהה באמצעות פרמטר השאילתה login_hint. הפרמטר הזה מועבר לכל אחת מכתובות ה-URL של אפליקציית האינטרנט שלכם כשפותחים iframe. אם משתמש לא אישר אחד מההיקפים, הפרמטר hd ('דומיין מתארח') מועבר במקום זאת לכתובות ה-URL של אפליקציית האינטרנט שלכם.
login_hint ו-hd הם פרמטרים רגילים של OpenID Connect שאפשר להעביר ל-Google אם רוצים להשתמש בכניסה באמצעות חשבון Google או לבקש אסימון OAuth. המטרה היא לשפר את חווית השימוש של משתמשי הקצה.
היקפי תוספים ל-Classroom
ההיקפים הבאים ספציפיים לתוספים ל-Classroom:
https://www.googleapis.com/auth/classroom.addons.teacher, שמאפשר גישה לכל שיטות ה-API.https://www.googleapis.com/auth/classroom.addons.student, שמאפשר גישה להפעלת פעולות של אימות וקריאה של קבצים מצורפים.
גם אם יש אסימון גישה תקין ל-OAuth שמציין את פרטי הכניסה של המשתמשים, הקריאות ל-API מוגבלות על ידי דרישות נוספות:
- בכל השיטות, המשתמש חייב להיות מורה או תלמיד בקורס שצוין על ידי
courseIdבבקשה. - כדי ליצור קבצים מצורפים, לעדכן אותם, למחוק אותם ולהעביר ציונים, המשתמש צריך להיות מורה.
- קריאות לפוסט ספציפי ב-Google Classroom מוגדרות באמצעות הבדיקות הבאות.
- כשתוסף כבר כולל לפחות קובץ מצורף אחד בפוסט, הוא יכול לשלוח בקשות לגבי:
- אימות הפעלת iframe
- פעולות של קריאה, עדכון ומחיקה של קבצים מצורפים
- עדכונים ציונים על פוסט זה
- כשפותחים בפעם הראשונה קובץ iframe מסוג Discovery של קבצים מצורפים, יכול להיות שהתוסף עדיין לא יכלול קובץ מצורף. ניתן להשתמש בפרמטר של השאילתה
addOnToken, שאפשר להשתמש בו כדי לשלוח בקשות לפריטים הבאים:- יצירת קובץ מצורף מתחת לפוסט (חובה
addOnToken) - אימות ההפעלה (
addOnTokenמאומת אם הוא סופק, והוא נדרש כאשר לתוסף אין קובץ מצורף קיים בפוסט)
- יצירת קובץ מצורף מתחת לפוסט (חובה
- כשתוסף כבר כולל לפחות קובץ מצורף אחד בפוסט, הוא יכול לשלוח בקשות לגבי:
אימות OAuth
תוסף Classroom משתמש ב-Google APIs כדי לגשת לנתונים של משתמשי Google.
למידע נוסף על תהליך האימות, קראו את המאמר שאלות נפוצות בנושא אימות OAuth API.
דף האפליקציה ב-Google Workspace Marketplace
יש כמה דברים שכדאי לשים לב אליהם כשיוצרים דף אפליקציה ב-Marketplace עבור תוספים ל-Classroom במהלך תוכנית הגישה המוקדמת.
למידע כללי על הגדרות ה-SDK של Google Workspace Marketplace, אפשר לקרוא את המאמרים הפעלה והגדרה של Google Workspace Marketplace SDK ויצירת דף אפליקציה בחנות ב-Google Workspace Marketplace.
שיקולים בנוגע לרישום
בדף של חנות האפליקציות ב-Marketplace SDK של הפרויקט הציבורי שלך ב-Google Cloud מצוינים השם והתיאורים של האפליקציה שמיועדים למשתמשי הקצה. אפשר לספק את הפרטים האלה בכמה שפות בקטע פרטי האפליקציה.
יש לפעול לפי ההנחיות הבאות ברישומים שלכם:
בקטע פרטי האפליקציה:
הימנע מסימני פיסוק בשם האפליקציה. לדוגמה, השתמשו ב-"My Add-on by My Company" במקום ב-"My Company: My Add-on" או "My Add-on, by My Company".
השדה Short Description ו-Detailed Description לא יכול להכיל את אותו הטקסט.
חשוב לוודא שבחרתם ערך בשדה תמחור. השדה הזה כולל אפשרויות לאפשרויות הבאות: Free, paid with a free trial, תשלום באמצעות תכונות בחינם ובתשלום. אין צורך לציין את סכום העלות בדף האפליקציה ב-Marketplace.
מוודאים שבחרתם ערך בשדה קטגוריה. משאבים אקדמיים או כלים למורים ולניהול יכולים להיות אפשרויות טובות לתוסף ל-Classroom.
למידע נוסף, תוכלו לקרוא את הפריטים שמופיעים בתיאור פרטי האפליקציה ב-Marketplace.
בקטע נכסים גרפיים:
הנכסים הגרפיים שסופקו לא יהיו מעורפלים ומתאימים לגדלים שצוינו בסטנדרטים של Google Workspace Marketplace.
צילומי המסך שסופקו הם ייצוגים מדויקים של חוויית השימוש בתוסף.
בקטע קישורים לתמיכה:
- ודאו שסיפקתם קישור לתנאים ולהגבלות של האפליקציה.
הקפידו לפעול בהתאם להנחיות המיתוג של Google API, שכוללות את השמות והתיאורים המותרים.
אם אתם מפנים למוצר כלשהו של Google בכרטיס המוצר, צריך להשתמש בשם שלו בפורמט שמופיע ברשימת הסימנים המסחריים. הקפידו לכלול את סמל הסימן המסחרי (TM) אם צוין, אבל השתמשו ב-"Google DocsTM" ולא ב-"Google Docs".
שילוב עם שירותי הרישוי והחיוב של Google
אם אתם רוצים לאפשר לאפליקציות שלכם מ-Google Workspace Marketplace לשלב את שירותי הרישוי והחיוב של Google, יש להיכנס אל Marketplace API.
הגדרות התקנה
תוספים יכולים לאפשר התקנה נפרדת, נוסף על התקנה של אדמין. בדף הזה מודגשים כמה הבדלים בין שני סוגי ההתקנות, והוא לא מיועד לקדם אף אחד מסוגי ההתקנה. אפשר לבחור אם לאפשר התקנה בנפרד בדף הגדרת האפליקציה של Google Workspace Marketplace.
התקנה על ידי מנהל המערכת
התקנות שאדמינים יכולים להגדיר מאפשרות לאדמין להוסיף תוסף לכל החשבונות בדומיין או לקבוצות גישה או ליחידות ארגוניות ספציפיות. רק אדמין של דומיין יכול להתקין התקנה של אדמין. האדמין יכול להביע הסכמה לכל היקפי הגישה בשם כל המשתמשים בדומיין. המשתמשים לא מתבקשים להביע הסכמה להיקפי גישה כלשהם אם האדמין בוחר לעשות זאת.
בהמשך מפורטים כמה שיקולים לגבי התקנה של מנהל מערכת.
- פקדים הדוקים יותר. אדמינים יכולים להגביל את הגישה של המשתמשים לתוסף.
- תאימות לרישוי. אם אתם צריכים רישיון לאפליקציה שלכם, תוכלו להיעזר באדמין של התקנות כדי לוודא שהרישיונות יופצו וישמשו אותם באופן הולם במוסד הרלוונטי.
- הורדת הנטל על משתמשי הקצה. התקנה של אדמין מפחיתה את עומס ההגדרה עבור מורים ותלמידים. כתוצאה מכך, חוויית המשתמש עשויה להיות חלקה יותר, עם פחות קליקים ופחות הזדמנויות לבלבול.
למידע נוסף על התקנות של אדמינים ואיך פועל המבנה הארגוני, ראו התקנת אפליקציות Marketplace בדומיין שלכם. למידע נוסף על יחידות ארגוניות וקבוצות גישה.
התקנה אישית
התקנות בודדות מוסיפות תוסף לחשבון של המשתמש. במהלך ההתקנה המשתמשים יתבקשו להביע הסכמה להיקפי הגישה של התוסף.
בהמשך מפורטים כמה שיקולים לגבי התקנה בודדת.
- מסייעים במעבר אל. יותר משתמשים יכולים לראות את התוסף שלכם מ-Google Workspace Marketplace ולהתקין אותו. אם תאשרו את ההתקנה של משתמשים מסוימים, תוכלו לעודד מורים נוספים לאמץ את המוצר שלכם או להמליץ עליו.
- בדיקה של אדמין. אדמין יכול להתקין בנפרד תוסף כדי לבדוק או לבדוק אותו לפני האישור או ההתקנה שלו בקבוצה רחבה יותר.
בנוסף להתקנת תוספים בשם המשתמשים, אדמינים יכולים גם ליצור רשימת היתרים כדי לאפשר למשתמשים להתקין תוספים שמאפשרים התקנה בנפרד. גם אם תוסף לא מופיע ברשימת ההיתרים, המשתמשים עדיין יכולים לראות את הדף של התוסף ב-Google Workspace Marketplace, אבל לא להתקין אותו. במקום זאת, הם מקבלים הודעה שבה מוסבר שמנהל הדומיין לא אישר להתקין את התוסף. בקטע ניהול אפליקציות מ-Marketplace של Google Workspace ברשימת ההיתרים אפשר לקרוא מידע נוסף על ההתנהגות הזו.
למידע נוסף, עיינו במסמכי התיעוד בנושא הגדרות ההתקנה של Google Workspace Marketplace.
שילוב אפליקציה
עליך לספק כתובת אתר של iframe להפעלה בשדה URI של הגדרת קבצים מצורפים. כתובת ה-URL הזו משמשת כערך src של iframe עבור קובץ מצורף מסוג iframe. מורים משתמשים ב-iframe מסוג Discovery כדי למצוא תוכן או פעילויות שמצרפים למטלה שלהם.
עליכם גם לציין את כל קידומות ה-URI שמהן מותר לצרף קבצים מהתוסף. התכונה הזו מגבירה את האבטחה בכך שהיא מונעת קבצים מצורפים ממקורות לא מורשים.
לפרטים נוספים על השדות האלה, ניתן לעיין בדף המדריך בנושא iframes.
חשבונות בדיקה
כדי לאמת את ההתנהגות הנכונה של התוסף הפרטי, צריך ליצור חשבונות בדיקה בדומיין ההדגמה. כדי לבדוק את המעבר בין התלמידים ב-iframe של הביקורת על עבודות התלמידים, נדרשים שני חשבונות.
הצעות לחשבונות בדיקה:
- תמי מורה, tammy.teacher@<your Demo domain>
- Sam סטודנט, sam.student@<שם הדומיין לדוגמה>
- סאלי סטודנט, sally.student@<שם הדומיין לדוגמה>
כך יוצרים חשבון בדיקה חדש:
- מתחברים למסוף Admin.
- עוברים אל משתמשים.
- לוחצים על הוספת משתמש חדש (איור 1).
- צריך להזין את פרטי המשתמש ולהקצות לו תפקידים מתאימים.
איור 1. מיקום הקישור הוספת משתמש חדש במסוף Admin.
כך יוצרים קבוצת בדיקה חדשה:
- מתחברים למסוף Admin.
- עוברים אל קבוצות.
- לוחצים על יצירת קבוצה (לפי איור 2).
- מזינים את שמות החברים והבעלים של הקבוצה.
איור 2. מיקום הקישור Create group (יצירת קבוצה) במסוף Admin.