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

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

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

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

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

למידע כללי על יצירת פרויקטים ב-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. מגדירים את הגדרת האפליקציה הרשאות הגישה לאפליקציה ב-Marketplace SDK ל-גלוי לכולם ומסמנים את התיבה לא רשום.

  5. ממלאים את שדות החובה בדף Store Listing ב-Marketplace SDK ולוחצים על PUBLISH.

  6. הצוות של Google Workspace Marketplace יבדוק את האפליקציה שלכם. הם יפנו אליכם דרך כתובת האימייל של המפתח שצוינה ב-SDK של Marketplace. אחרי שהאפליקציה תאושר, צריך לבטל את הסימון בתיבה לא רשומה כדי שמורים ואדמינים יוכלו למצוא אותה ב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 הן Allow access to Cloud Shell.

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

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

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

    הפעלת Classroom API

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

    הפעלת Google Workspace Marketplace SDK

  6. מגדירים את הגדרת האפליקציה ניראות האפליקציה ב-SDK של Marketplace ל-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.
  • https://www.googleapis.com/auth/classroom.addons.student, שמאפשרת להפעיל פעולות אימות וקריאה של קבצים מצורפים.

גם אם יש אסימון גישה תקף ל-OAuth שמציין את פרטי הכניסה של המשתמש, קריאות ל-API כפופות לדרישות נוספות:

  • בכל השיטות, המשתמש צריך להיות מורה או תלמיד בקורס שצוין ב-courseId בבקשה.
  • כדי ליצור, לעדכן, למחוק ולשלוח ציונים דרך קבצים מצורפים, המשתמש צריך להיות מורה.
  • הקריאות לפוסט ספציפי ב-Google Classroom נתונות לבדיקות הבאות.
    • כשלתוסף כבר יש לפחות קובץ מצורף אחד בפוסט, הוא יכול לשלוח בקשות ל:
      • אימות השקת iframe
      • פעולות קריאה, עדכון ומחיקה של קבצים מצורפים
      • עדכוני ציונים בפוסט הזה
    • בפעם הראשונה שפותחים את ה-iframe של Attachment Discovery, יכול להיות שלתוסף עדיין לא יהיה קובץ מצורף בפוסט. הפרמטר addOnToken של השאילתה מאפשר לשלוח בקשות לקבלת הפרטים הבאים:
      • יצירת קובץ מצורף מתחת לפוסט (addOnToken נדרש)
      • אימות ההשקה (addOnToken מאומת אם הוא מסופק, והוא נדרש אם אין לקובץ התוסף קובץ מצורף קיים בפוסט)

אימות OAuth

תוסף ל-Classroom משתמש ב-Google APIs כדי לגשת לנתונים של משתמשי Google.

למידע נוסף על תהליך האימות, אפשר לעיין בשאלות נפוצות בנושא אימות OAuth API.

דף המוצר ב-Google Workspace Marketplace

למידע כללי על הגדרת ערכת SDK של Google Workspace Marketplace, אפשר לעיין במאמרים הפעלה והגדרה של ערכת ה-SDK של Google Workspace Marketplace ויצירת דף מוצר בחנות Google Workspace Marketplace.

שיקולים לגבי דף האפליקציה

הרשומה של חנות ה-SDK ב-Marketplace של הפרויקט הציבורי ב-Google Cloud מציינת את השם והתיאורים של האפליקציה למשתמשים הקצה. אפשר לספק את הפרטים האלה בכמה שפות בקטע פרטי האפליקציה.

חשוב לפעול לפי ההנחיות הבאות בנכסי המלון:

  • בקטע פרטי האפליקציה:

    • אין להשתמש בסימני פיסוק בשם האפליקציה. לדוגמה, עדיף להשתמש בשם 'התוסף שלי של חברת My Company' במקום 'חברת My Company: התוסף שלי' או 'התוסף שלי, של חברת My Company'.

    • התיאור הקצר והתיאור המפורט לא צריכים להכיל את אותו הטקסט.

    + מוודאים שבחרתם ערך בשדה Pricing. השדה הזה כולל את האפשרויות בחינם, בתשלום עם תקופת ניסיון בחינם, בתשלום עם תכונות בחינם ובתשלום. אין צורך לציין את סכום העלות במודעה ב-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 להפעלה בשדה Attachment Setup URI. כתובת ה-URL הזו משמשת כערך src של ה-iframe בiframe של מודעות Discovery עם קבצים מצורפים. המורים משתמשים ב-iframe של Discovery כדי למצוא תוכן או פעילויות שאפשר לצרף למטלה.

בנוסף, צריך לציין את כל קידומות ה-URI שמהן מותר לצרף קבצים מהתוסף. התכונה הזו מגבירה את האבטחה על ידי מניעת צירוף קבצים ממקורות לא מורשים.

פרטים נוספים על השדות האלה זמינים בדף המדריך בנושא iframes.

חשבונות בדיקה

יוצרים חשבונות בדיקה בדומיין הניסיוני כדי לוודא שהתוסף הפרטי פועל כמו שצריך. כדי לבדוק את המעבר בין תלמידים ב-iframe של 'בדיקת עבודות של תלמידים', נדרשים שני חשבונות של תלמידים.

הצעות לחשבונות בדיקה:

  • Tammy Teacher, ‏ tammy.teacher@<your demo domain>
  • Sam Student, ‏ sam.student@<your demo domain>
  • נעמה סטודנטית, sally.student@<your demo domain>

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

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

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

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

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

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