תוסף משתמש בקובץ מניפסט כדי להגדיר פרטים מסוימים על האפליקציה ועל הפעולה שלה.
במסמכי התיעוד האלה מוסבר איך מגדירים מניפסט לתוסף של Google Workspace.
מבנה המניפסט לתוספים ל-Google Workspace
התוספים ל-Google Workspace משתמשים בקובץ המניפסט כדי להגדיר כמה היבטים במראה ובהתנהגות של התוסף.
מאפייני המניפסט של התוספים ל-Google Workspace מאורגנים בקטע addOns
של מבנה אובייקט המניפסט.
- למידע נוסף על קובצי מניפסט של Apps Script, ראו מבנה המניפסט.
- למידע על קובצי מניפסט לתוספים שנוצרו עם נקודות קצה ב-HTTP, קראו את המאמר משאב REST:
projects.deployments
דוגמה להגדרה של מניפסט לתוסף ל-Google Workspace
בדוגמת המניפסט הבאה אפשר לראות את הקטע בקובץ מניפסט שמגדיר תוספים ל-Google Workspace, כולל ההיבטים הבאים:
- בקטע
addOns.common
במניפסט מוגדרים השם, כתובת ה-URL של הלוגו, הצבעים והגדרות כלליות נוספות של התוסף שלא תלויות במארח. - המניפסט מגדיר דף בית משותף, אבל מגדיר גם דפי בית ספציפיים ליומן Google, ל-Drive, ל-Docs, ל-Sheets ול-Slides. Gmail משתמש בדף הבית שמוגדר כברירת מחדל.
- הגדרות המניפסט לדוגמה מאפשרות את התכונות הבאות:
- טריגרים של יומן
eventOpen
ו-eventUpdated
. - (ב-Apps Script בלבד) שני פתרונות לשיחות ועידה ביומן.
- שתי פעולות אוניברסליות.
onItemsSelectedTrigger
של Drive.- פעולת כתיבה ב-Gmail וטריגר לפי הקשר.
- אובייקט
linkPreviewTriggers
ב-Docs. למידע נוסף על הטריגר הזה, ראו תצוגה מקדימה של קישורים באמצעות צ'יפים חכמים. - אובייקט
createActionTriggers
ב-Docs. למידע נוסף על הטריגר הזה, ראו יצירת משאבים של צד שלישי מתפריט ה-@. - ממשקים ספציפיים לקבצים ב-Docs, ב-Sheets וב-Slides.
- טריגרים של יומן
- השדה
oauthScopes
מגדיר את היקפי ההרשאות של הפרויקט (בדרך כלל נדרש לתוספים). - (ב-Apps Script בלבד) השדה
urlFetchWhitelist
הוא שדה שמבטיח שכל נקודות הקצה שמאוחזרות תואמות לרשימה מסוימת של קידומות URL מסוג HTTPS. מידע נוסף מופיע במאמר כתובות URL ברשימת ההיתרים.
הקישורים שבדוגמה מפנים לתיאורים של השדה הזה במסמכי העזר התואמים של המניפסט של Apps Script ושל תוספי Google Workspace HTTP.
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) באמצעות שירות Apps Script
UrlFetch
. כדי להוסיף כתובות URL לרשימת ההיתרים לאחזור, צריך לכלול את השדהurlFetchWhitelist
בקובץ המניפסט. - פתיחה או הצגה של כתובת URL בתגובה לפעולת משתמש (חובה לתוספים ל-Google Workspace שפותחים כתובות URL שהן חיצוניות ל-Google או מציגות אותן). כדי להוסיף כתובות URL לרשימת ההיתרים לפתיחה, צריך לכלול את השדה
addOns.common.openLinkUrlPrefixes
בקובץ המניפסט.
הוספת קידומות לרשימת ההיתרים
כשמציינים רשימות היתרים בקובץ המניפסט (על ידי הוספת השדה 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
(חובה להשתמש בתווים כלליים לחיפוש כקידומת מובילה)