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