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

בדף הזה מוסבר איך ליצור ולהגדיר פרויקטים ב-Google Cloud לתוספים ל-Classroom. פרויקטים ב-Google Cloud משמשים להטמעה של כניסה יחידה (SSO) של Google באמצעות OAuth 2.0 (כניסה יחידה של Google), לאישור בקשות שמוגשות על ידי התוסף ולניהול של דף התוסף בחנות Google Workspace Marketplace.

מידע כללי נוסף על פרסום תוסף ב-Marketplace זמין במאמר פרסום אפליקציה.

יצירת פרויקט ב-Google Cloud

יש שני סוגים של פרויקטים שאפשר ליצור: פרויקט פרטי שמשמש לפיתוח ופרויקט ציבורי שאפשר להגיע אליו דרך משתמשי קצה. התוויות 'ציבורי' ו'פרטי' מתייחסות לחשיפה של האפליקציה ב-Google Workspace Marketplace. אפליקציה פרטית ב-Marketplace יכולה להיות מותקנת רק על ידי משתמשים בדומיין שבו היא נוצרה, ואילו אפליקציה ציבורית ב-Marketplace זמינה לכל דומיין ב-Google Workspace. צריך לשלוח שתי בקשות נפרדות, כי אי אפשר להגדיר פרויקט כגלוי לכולם וגם כפרטי. אפליקציות ציבוריות צריכות לעבור בדיקה ולקבל אישור לפני שהן זמינות ב-Marketplace.

למידע כללי על יצירת פרויקטים ב-Google Cloud, אפשר לעבור אל יצירת פרויקט ב-Google Cloud.

יצירת פרויקט ציבורי ב-Google Cloud

הפרויקט הזה מייצג את אפליקציית התוסף שאדמינים, מורים ותלמידים יכולים לגשת אליה. צוות Google Workspace Marketplace צריך לבדוק ולאשר פרויקט ציבורי לפני שאפשר להשיק או להתקין אותו.

  1. יוצרים פרויקט חדש ב-Google Cloud בדומיין הייצור.

    יצירת פרויקט ב-Google Cloud

  2. מפעילים את Classroom API בפרויקט ב-Cloud.

    הפעלת Classroom API

  3. מפעילים את Google Workspace Marketplace SDK בפרויקט ב-Cloud.

    הפעלת Google Workspace Marketplace SDK

  4. מגדירים את App Visibility (חשיפת האפליקציה) ל-Public (גלוי לכולם) ב-App Configuration (הגדרת האפליקציה) ב-Marketplace SDK ומסמנים את התיבה Unlisted (לא רשום).

  5. ממלאים את שדות החובה בדף Store Listing (פרטי האפליקציה בחנות) ב-Marketplace SDK ולוחצים על PUBLISH (פרסום).

  6. צוות 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:

  1. מבצעים את השלבים כדי לקבל דומיין בדיקה למפתחים.

  2. כשאתם מחוברים כמשתמשים עם הרשאות אדמין בדומיין ההדגמה, יוצרים פרויקט חדש ב-Google Cloud.

    יצירת פרויקט ב-Google Cloud

    אם אין לכם גישה ל-מסוף Google Cloud או שאתם לא יכולים ליצור פרויקטים ב-Cloud, כדאי לבדוק את הדברים הבאים ב מסוף Admin:

    • נכנסים לדף הגדרות חשבון > הגדרות גישה מבוססת-גיל ובוחרים באפשרות כל המשתמשים בקבוצה או ביחידה הארגונית הזו הם בני 18 ומעלה.
    • בקטע אפליקציות > שירותי Google נוספים:
    • ‫Google Cloud Platform מופעל לכולם.
    • ההגדרה של יצירת פרויקטים היא המשתמשים יכולים ליצור פרויקטים.
    • הגדרות הגישה ל-Cloud Shell הן מותר לגשת אל Cloud Shell.

  3. ממלאים את טופס הבקשה לשדרוג דומיין הדגמה ושולחים אותו. מילוי הטופס הזה הוא בקשה לשדרוג הדומיין של ההדגמה ל-Google Workspace for Education Plus עם עשרה רישיונות, ומתן הרשאה לפרויקט בענן ב-API של התוספים ל-Classroom.

    תקבלו אימייל כשתהליכי השדרוג והוספה לרשימת ההיתרים יסתיימו. מקצים רישיונות ל-Plus לחשבונות המורים לניסיון ב מסוף Admin. בקטע ספרייה > משתמשים, יוצרים או בוחרים את חשבונות המורים לבדיקה. בכרטיסייה Licenses (רישיונות) של כל מורה, מוודאים ש-Google Workspace for Education Plus מוגדר כ-Assigned (מוקצה).

  4. מפעילים את Classroom API בפרויקט ב-Cloud.

    הפעלת Classroom API

  5. מפעילים את Google Workspace Marketplace SDK בפרויקט ב-Cloud.

    הפעלת Google Workspace Marketplace SDK

  6. מגדירים את App Configuration (הגדרת אפליקציה) ב-Marketplace SDK App Visibility (חשיפת האפליקציה) לprivate (פרטית).

  7. ממלאים את שדות החובה בדף 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

אם אתם רוצים לשלב את האפליקציות שלכם ב-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 של Attachment Discovery. מורים משתמשים ב-iframe של 'חיפוש קבצים מצורפים' כדי למצוא תוכן או פעילויות לצירוף למטלה. אפשר להגדיר את זה במסוף של פרויקט בענן של Google.

הגדרת URI של iframe

ההגדרה 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, sally.student@<your demo domain>

כדי ליצור חשבון בדיקה חדש, פועלים לפי השלבים הבאים:

  1. נכנסים למסוף Admin.
  2. עוברים אל משתמשים.
  3. לוחצים על הוספת משתמש חדש (ראו איור 1).
  4. מזינים את פרטי המשתמש ומקצים לו את התפקידים המתאימים.

לוחצים על 'הוספת משתמש חדש'. איור 1. מיקום הקישור הוספת משתמש חדש במסוף Admin.

כדי ליצור קבוצת בדיקה חדשה:

  1. נכנסים למסוף Admin.
  2. עוברים אל קבוצות.
  3. לוחצים על יצירת קבוצה (ראו איור 2).
  4. מזינים את החברים והבעלים של הקבוצה.

לוחצים על 'יצירת קבוצה'. איור 2. המיקום של הקישור יצירת קבוצה במסוף Admin.