פיתוח ממשקים ב-Google Drive

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

גישה לממשק המשתמש של התוסף

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

• אם משתמש לוחץ על סמל התוסף ב-Google Drive, התוסף מריץ את הפונקציה drive.homepageTrigger התואמת (אם היא קיימת). הפונקציה יוצרת כרטיס דף בית ומחזירה אותו ל-Google Drive להצגה. אם לא מוגדרת פונקציה של drive.homepageTrigger, יוצג במקום זאת כרטיס גנרי של דף הבית.
• אם המשתמש בוחר פריט אחד או יותר ב-Google Drive ואז לוחץ על סמל התוסף, או בוחר פריטים בזמן שהתוסף פתוח, התוסף מריץ את הפונקציה לפי הקשר drive.onItemsSelectedTrigger (אם היא קיימת). הפונקציה הזו יוצרת את ממשק 'פריטים שנבחרו' לפי הקשר של התוסף ב-Google Drive ומחזירה אותו ל-Google Drive להצגה.

פיתוח הממשק של התוסף ב-Drive

כדי ליצור ממשקים שמרחיבים את Google Drive, צריך לבצע את השלבים הכלליים הבאים:

1. מחליטים אם לתוסף יהיה דף בית ספציפי ל-Drive. בנוסף, צריך להחליט אם רוצים לספק ממשק לפי הקשר כשהמשתמש בוחר פריטים ב-Drive.
2. מוסיפים את השדות המתאימים addOns.common ו-addOns.drive למאניפסט של פרויקט הסקריפט של התוסף, כולל כל היקפי הגישה ל-Drive הנדרשים.
3. אם אתם מספקים דף בית ספציפי ל-Drive, צריך להטמיע את הפונקציה drive.homepageTrigger כדי ליצור את הממשק הזה. אפשר גם להשתמש בממשק common.homepageTrigger למספר מארחים של Google Workspace.
4. אם אתם מספקים ממשק לבחירת פריטים לפי הקשר ב-Drive, עליכם להטמיע פונקציית טריגר לפי הקשר מסוג drive.onItemsSelectedTrigger כדי ליצור את הממשק הזה. פרטים נוספים זמינים במאמר ממשק לפי הקשר ב-Drive לפריטים שנבחרו.
5. מטמיעים את פונקציות הקריאה החוזרת המשויכות שנדרשות כדי להגיב לאינטראקציות של המשתמש בממשק המשתמש, כמו קליקים על לחצנים.

דפי הבית של Drive

ב-Google Drive אפשר להציג דפי בית של תוספים ל-Google Workspace. כדי להציג את דף הבית המשותף של התוסף ב-Google Drive, פשוט מוודאים שיש שדה addOns.drive במניפסט של התוסף.

לחלופין, אפשר להוסיף את הקוד drive.homepageTrigger למניפסט של התוסף כדי לספק דף בית ספציפי ל-Drive.

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

ממשק לפי הקשר ב-Drive לפריטים שנבחרו

Google Drive מסתמך על טריגר לפי הקשר כדי לקבוע איזה ממשק (אם בכלל) יוצג כשהמשתמש בוחר פריט אחד או יותר ב-Google Drive. כשהטריגר מופעל, הוא מפעיל את פונקציית הטריגר לפי הקשר שצוינה בשדה drive.onItemsSelectedTrigger.runFunction במניפסט של התוסף.

כדי ליצור ממשק לבחירת פריטים לפי הקשר ב-Drive, צריך לבצע את הפעולות הבאות:

1. מוודאים שקובץ המניפסט של התוסף כולל את https://www.googleapis.com/auth/drive.addons.metadata.readonly היקף

2. מוודאים שהמניפסט כולל את הקטע drive.onItemsSelectedTrigger.

3. מטמיעים את הפונקציה ששמורה בשדה drive.onItemsSelectedTrigger. הפונקציה מקבלת אובייקט אירוע כארגומנטים, וצריך להחזיר אובייקט Card יחיד או מערך של אובייקטים מסוג Card.

4. כמו בכל כרטיס, צריך להטמיע את כל פונקציות הקריאה החוזרת שמשמשות לספק אינטראקטיביות של ווידג'ט לממשק. לדוגמה, אם אתם כוללים לחצן בממשק, צריך לצרף לו פעולה ופונקציית קריאה חוזרת (callback) שמופעל כשמקישים על הלחצן.

אובייקטים של אירועים

אובייקט אירוע נוצר ומועבר לפונקציית הטריגר drive.homepageTrigger או drive.onItemsSelectedTrigger כשפונים לפונקציות האלה. פונקציית הטריגר יכולה להשתמש במידע באובייקט האירוע הזה כדי לקבוע איך ליצור כרטיסי תוספים או לשלוט בהתנהגות של התוסף בדרכים אחרות.

המבנה המלא של אובייקטי האירועים מתואר בקטע אובייקטי אירועים. כש-Drive היא אפליקציית המארח בפועל של התוסף, אובייקטים של אירועים לפי הקשר כוללים את השדה Drive event object שמכיל את פרטי הלקוח הספציפיים ל-Drive.

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

בדוגמה הבאה מוצג אובייקט אירוע ב-Drive שמוענק לפונקציה drive.onItemsSelectedTrigger:

    {
      "commonEventObject": { ... },
      "drive": {
        "activeCursorItem":{
          "addonHasFileScopePermission": true,
          "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
          "iconUrl": "https://drive-thirdparty.googleusercontent.com...",
          "mimeType":"application/pdf",
          "title":"How to get started with Drive"
        },
        "selectedItems": [
          {
            "addonHasFileScopePermission": true,
            "id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
            "iconUrl":"https://drive-thirdparty.googleusercontent.com...",
            "mimeType":"application/pdf",
            "title":"How to get started with Drive"
          },
          ...
        ]
      },
      ...
    }