תוסף משתמש בקובץ מניפסט כדי להגדיר פרטים מסוימים לגבי האפליקציה והפעולה שלה.
במסמך הזה מוסבר איך מגדירים מניפסט לתוסף ל-Google Workspace.
מבנה המניפסט של תוספים ל-Google Workspace
תוספים ל-Google Workspace משתמשים בקובץ המניפסט כדי להגדיר כמה היבטים של המראה וההתנהגות של התוסף.
מאפייני המניפסט של תוספים ל-Google Workspace מאורגנים בקטע addOns
במבנה האובייקט של המניפסט.
- מידע על קובצי מניפסט של Apps Script זמין במאמר מבנה המניפסט.
- מידע על קובצי מניפסט של תוספים שנוצרו באמצעות נקודות קצה מסוג HTTP זמין במאמר משאב REST:
projects.deployments
מניפסטים ל-Google Chat
אם התוסף ל-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.
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
בקובץ המניפסט.
הוספת תחיליות לרשימת ההיתרים
כשמציינים רשימות של כתובות מורשות בקובץ המניפסט (על ידי הכללת השדה 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
(צריך להשתמש בתווים כלליים לחיפוש כקידומת מובילת)