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

בדף הזה מוסבר איך ליצור ולהגדיר פרויקטים ב-Google Cloud לתוספים ל-Classroom. פרויקטים ב-Google Cloud משמשים להטמעה של כניסה יחידה (SSO) של Google באמצעות OAuth 2.0 (כניסת SSO של 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 Visibility (הרשאות גישה לאפליקציה) במקטע App Configuration (הגדרת אפליקציה) ב-Marketplace SDK למצב 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.

App Integration

חובה לציין כתובת URL של iframe להפעלה בשדה מזהה URI של הגדרת קובץ מצורף. כתובת ה-URL הזו משמשת כערך src של ה-iframe של גילוי קבצים מצורפים ב-iframe. מורים משתמשים ב-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@<your demo domain>

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

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

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

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

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

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