מניפסטים של תוספים ל-Google Workspace

תוסף משתמש בקובץ manifest כדי להגדיר פרטים מסוימים לגבי האפליקציה והפעולה שלה.

במסמך הזה מוסבר איך מגדירים מניפסט לתוסף ל-Google Workspace.

מבנה המניפסט של תוספים ל-Google Workspace

תוספים ל-Google Workspace משתמשים בקובץ המניפסט כדי להגדיר כמה היבטים של המראה וההתנהגות של התוסף.

מאפייני המניפסט של תוספים ל-Google Workspace מאורגנים בקטע addOns במבנה האובייקט של המניפסט.

• מידע על קובצי מניפסט של Apps Script זמין במאמר מבנה המניפסט.
• מידע על קובצי מניפסט של תוספים שנוצרו באמצעות נקודות קצה מסוג HTTP זמין במאמר משאב REST: projects.deployments

מניפסטים ל-Google Chat

גרסת Developer Preview: זמינה כחלק מתוכנית Developer Preview של Google Workspace, שמעניקה גישה מוקדמת לתכונות מסוימות.

אם התוסף ל-Google Workspace מרחיב את Google Chat, צריך להגדיר אפליקציית Google Chat על ידי הפעלה והגדרה של Google Chat API במסוף Google Cloud.

הגדרות קובץ מניפסט נפוצות (כולל addons.common) מתעלמות ב-Chat. במקום להשתמש במניפסט של התוסף, משתמשים ב-Chat API כדי להגדיר את ההגדרות הבאות של Chat:

• השם, הלוגו והתיאור של אפליקציית Chat, שמופיעים רק בממשק המשתמש של Chat.
• טריגרים של אפליקציית Chat.

אם יצרתם את התוסף ב-Apps Script, תצטרכו גם להוסיף או לעדכן את האובייקטים הבאים במניפסט:

• addons.chat (חובה)
• oauthScopes (חובה אם באפליקציית Google Chat נעשה שימוש בהיקפי הרשאות של OAuth)

במאמר הגדרת אפליקציית Google Chat מוסבר איך מגדירים את ההגדרות של Chat עבור תוסף.

דוגמה להגדרת מניפסט של תוסף ל-Google Workspace

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

• הקטע addOns.common במניפסט מגדיר את השם, כתובת ה-URL של הלוגו, הצבעים והגדרות כלליות אחרות של התוסף, שאינן תלויות במארח.
• המניפסט מגדיר דף בית משותף, אבל גם דפי בית ספציפיים ל-Calendar,‏ Drive,‏ Docs,‏ Sheets ו-Slides. ב-Gmail נעשה שימוש בדף הבית שמוגדר כברירת מחדל.
• הגדרות המניפסט לדוגמה מאפשרות את הפעולות הבאות:
  • טריגרים eventOpen ו-eventUpdated ביומן.
  • (ב-Apps Script בלבד) שני פתרונות לשיחות ועידה ביומן Google.
  • שתי פעולות אוניברסליות.
  • onItemsSelectedTrigger ב-Drive.
  • פעולת כתיבת ב-Gmail וטריגר לפי הקשר.
  • אובייקט linkPreviewTriggers ב-Docs. מידע נוסף על הטריגר הזה זמין במאמר תצוגה מקדימה של קישורים באמצעות צ'יפים חכמים.
  • אובייקט createActionTriggers ב-Docs. מידע נוסף על הטריגר הזה זמין במאמר יצירת משאבים של צד שלישי מהתפריט @.
  • ממשקים ספציפיים לקובצי Docs,‏ Sheets ו-Slides.
• השדה oauthScopes מגדיר את היקפי ההרשאות בפרויקט (בדרך כלל נדרש לתוספים).
• (ב-Apps Script בלבד) השדה urlFetchWhitelist הוא שדה שמבטיח שכל נקודות הקצה שאוחזרו תואמות לרשימה מסוימת של קידומות של כתובות URL מסוג HTTPS. מידע נוסף זמין במאמר רשימת היתרים של כתובות URL.

הקישורים בדוגמה מפנים לתיאורים של השדה הזה במסמכי העזרה המתאימים של המניפסט לתוספים של Apps Script ושל HTTP ל-Google Workspace.

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

Apps Script

{
  "addOns": {
    "calendar": {
      "createSettingsUrlFunction": "getConferenceSettingsPageUrl",
      "conferenceSolution": [{
        "id": "my-video-conf",
        "logoUrl": "https://lh3.googleusercontent.com/...",
        "name": "My Video Conference",
        "onCreateFunction": "onCreateMyVideoConference"
      }, {
        "id": "my-streamed-conf",
        "logoUrl": "https://lh3.googleusercontent.com/...",
        "name": "My Streamed Conference",
        "onCreateFunction": "onCreateMyStreamedConference"
      }],
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "onDefaultHomePageOpen",
        "enabled": true
      },
      "layoutProperties": {
        "primaryColor": "#ff392b",
        "secondaryColor": "#d68617"
      },
      "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png",
      "name": "Demo Google Workspace Add-on",
      "openLinkUrlPrefixes": [
        "https://mail.google.com/",
        "https://script.google.com/a/google.com/d/",
        "https://drive.google.com/a/google.com/file/d/",
        "https://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },
    "drive": {
      "homepageTrigger": {
        "runFunction": "onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "onDriveItemsSelected"
      }
    },
    "gmail": {
      "composeTrigger": {
        "selectActions": [
          {
            "text": "Add images to email",
            "runFunction": "getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onGmailMessageOpen"
        }
      ]
    },
    "docs": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      },
      "linkPreviewTriggers": [
        {
        "runFunction": "onLinkPreview",
        "patterns": [
            {
              "hostPattern": "example.com",
              "pathPrefix": "example-path"
            }
        ],
        "labelText": "Link preview",
        "localizedLabelText": {
          "es": "Link preview localized in Spanish"
        },
        "logoUrl": "https://www.example.com/images/smart-chip-icon.png"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "exampleFunction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedEditors"
      }
    }
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.addons.current.event.read",
    "https://www.googleapis.com/auth/calendar.addons.current.event.write",
    "https://www.googleapis.com/auth/drive.addons.metadata.readonly",
    "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/script.locale",
    "https://www.googleapis.com/auth/script.scriptapp",
    "https://www.googleapis.com/auth/drive.file",
    "https://www.googleapis.com/auth/documents.currentonly",
    "https://www.googleapis.com/auth/spreadsheets.currentonly",
    "https://www.googleapis.com/auth/presentations.currentonly",
    "https://www.googleapis.com/auth/workspace.linkpreview"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ]
}

HTTP

{
  "addOns": {
    "calendar": {
      "currentEventAccess": "READ_WRITE",
      "eventOpenTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventOpen"
      },
      "eventUpdateTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventUpdate"
      },
      "eventAttachmentTrigger": {
        "label": "My Event Attachment",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarEventAddAttachment"
      },
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCalendarHomePageOpen",
        "enabled": true
      }
    },
    "common": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDefaultHomePageOpen",
        "enabled": true
      },
      "layoutProperties": {
        "primaryColor": "#ff392b",
        "secondaryColor": "#d68617"
      },
      "logoUrl": "https://ssl.gstatic.com/docs/script/images/logo/script-64.png",
      "name": "Demo Google Workspace Add-on",
      "openLinkUrlPrefixes": [
        "https://mail.google.com/",
        "https://script.google.com/a/google.com/d/",
        "https://drive.google.com/a/google.com/file/d/",
        "https://www.example.com/"
      ],
      "universalActions": [{
        "label": "Open settings",
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getSettingsCard"
      }, {
        "label": "Open Help URL",
        "openLink": "https://www.example.com/help"
      }],
      "useLocaleFromApp": true
    },
    "drive": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveHomePageOpen",
        "enabled": true
      },
      "onItemsSelectedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onDriveItemsSelected"
      }
    },
    "gmail": {
      "composeTrigger": {
        "actions": [
          {
            "label": "Add images to email",
            "runFunction": "https://myownpersonaldomain.com/mypage?trigger=getInsertImageComposeCards"
          }
        ],
        "draftAccess": "METADATA"
      },
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "https://myownpersonaldomain.com/mypage?trigger=onGmailMessageOpen"
        }
      ]
    },
    "docs": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      },
      "linkPreviewTriggers": [
        {
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onLinkPreview",
          "patterns": [
              {
                "hostPattern": "example.com",
                "pathPrefix": "example-path"
              }
          ],
          "labelText": "Link preview",
          "localizedLabelText": {
            "es": "Link preview localized in Spanish"
          },
          "logoUrl": "https://www.example.com/images/smart-chip-icon.png"
        }
      ],
      "createActionTriggers": [
        {
          "id": "exampleId",
          "labelText": "Example label text",
          "localizedLabelText": {
            "es": "Label text localized in Spanish"
          },
          "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onCreateAction",
          "logoUrl": "https://www.example.com/images/case.png"
        }
      ]
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    },
    "slides": {
      "homepageTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "https://myownpersonaldomain.com/mypage?trigger=onFileScopeGrantedEditors"
      }
    }
  },
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.addons.current.event.read",
    "https://www.googleapis.com/auth/calendar.addons.current.event.write",
    "https://www.googleapis.com/auth/drive.addons.metadata.readonly",
    "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/script.locale",
    "https://www.googleapis.com/auth/script.scriptapp",
    "https://www.googleapis.com/auth/drive.file",
    "https://www.googleapis.com/auth/documents.currentonly",
    "https://www.googleapis.com/auth/spreadsheets.currentonly",
    "https://www.googleapis.com/auth/presentations.currentonly",
    "https://www.googleapis.com/auth/workspace.linkpreview"
  ]
}

כתובות URL ברשימת ההיתרים

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

השדה הזה הוא אופציונלי כשמתקינים פריסה לבדיקה, אבל נדרש כשיוצרים פריסה עם גרסאות.

כדאי להשתמש ברשימות ההיתרים כשהסקריפט או התוסף מבצעים את הפעולות הבאות:

• אחזור או אחזור מידע ממיקום חיצוני (כמו נקודות קצה מסוג HTTPS) באמצעות השירות UrlFetch של Apps Script. כדי להוסיף כתובות URL לרשימת ההיתרים לאחזור, צריך לכלול את השדה urlFetchWhitelist בקובץ המניפסט.
• פתיחה או הצגה של כתובת URL בתגובה לפעולה של משתמש (נדרש לתוספים של Google Workspace שפותחים או מציגים כתובות URL שאינן ב-Google). כדי להוסיף כתובות URL לרשימת ההיתרים לפתיחה, צריך לכלול את השדה addOns.common.openLinkUrlPrefixes בקובץ המניפסט.

הערה: המונח רשימת ההיתרים, כפי שהוא מופיע ב-urlFetchWhitelist, הוא מונח שהוצא משימוש ומשמעותו זהה למשמעות של רשימת ההיתרים, שמונח זה מחליף. מידע נוסף זמין במאמר כתיבת מסמכי עזרה שכוללים את כולם.

הוספת תחיליות לרשימת ההיתרים

כשמציינים רשימות של כתובות מותרות בקובץ המניפסט (על ידי הכללת השדה addOns.common.openLinkUrlPrefixes או urlFetchWhitelist), צריך לכלול רשימה של תחיליות של כתובות URL. התחיליות שמוסיפים למניפסט צריכות לעמוד בדרישות הבאות:

• כל קידומת חייבת להיות כתובת URL חוקית.
• בכל תחילית צריך להשתמש ב-https:// ולא ב-http://.
• לכל קידומת צריך להיות דומיין מלא.
• לכל קידומת צריך להיות נתיב לא ריק. לדוגמה, הערך https://www.google.com/ תקין אבל הערך https://www.google.com לא תקין.
• אפשר להשתמש בתווים כלליים לחיפוש כדי להתאים לתחיליות של תת-דומיינים בכתובות URL.
• אפשר להשתמש בתו כללי לחיפוש אחד מסוג * בשדה addOns.common.openLinkUrlPrefixes כדי להתאים לכל הקישורים, אבל לא מומלץ לעשות זאת כי זה עלול לחשוף את נתוני המשתמש לסיכון ולהאריך את תהליך בדיקת התוסף. כדאי להשתמש בתו אסימון חלופי רק אם הפונקציונליות של התוסף דורשת זאת.

כדי לקבוע אם כתובת URL תואמת לקידומת ברשימת ההיתרים, חלים הכללים הבאים:

• ההתאמה של הנתיב היא תלוית אותיות רישיות.
• אם התחילית זהה לכתובת ה-URL, יש התאמה.
• אם כתובת ה-URL זהה לתחילית או שהיא צאצא שלה, היא תואמת.

לדוגמה, הקידומת https://example.com/foo תואמת לכתובות ה-URL הבאות:

• https://example.com/foo
• https://example.com/foo/
• https://example.com/foo/bar
• https://example.com/foo?bar
• https://example.com/foo#bar

שימוש בתווים כלליים לחיפוש

אפשר להשתמש בתו כללי לחיפוש אחד (*) כדי להתאים תת-דומיין בשני השדות urlFetchWhitelist ו-addOns.common.openLinkUrlPrefixes. אי אפשר להשתמש ביותר מתווים כלליים לחיפוש אחד כדי להתאים לכמה תת-דומיינים, והתו הכללי חייב לייצג את הקידומת הפותחת של כתובת ה-URL.

לדוגמה, הקידומת https://*.example.com/foo תואמת לכתובות ה-URL הבאות:

• https://subdomain.example.com/foo
• https://any.number.of.subdomains.example.com/foo

הקידומת https://*.example.com/foo לא תואמת לכתובות ה-URL הבאות:

• https://subdomain.example.com/bar (חוסר התאמה בסיומת)
• https://example.com/foo (צריך להופיע תת-דומיין אחד לפחות)

חלק מכללי הקידומת נאכפים כשמנסים לשמור את המניפסט. לדוגמה, התחיליות הבאות יגרמו לשגיאה אם הן נמצאות במניפסט כשמנסים לשמור אותו:

• https://*.*.example.com/foo (אסור להשתמש בכמה תווים כלליים לחיפוש)
• https://subdomain.*.example.com/foo (צריך להשתמש בתווים כלליים לחיפוש כקידומת מובילת)