בפרויקט Apps Script נעשה שימוש בקובץ מניפסט כדי להגדיר פרטים מסוימים לגבי הסקריפט והפעולה שלו. במאמר מניפסטים מוסבר איך להציג ולערוך מניפסט.
במאמר הזה מוסבר איך מגדירים מניפסט לתוסף Google Workspace.
מבנה המניפסט לתוספים ל-Google Workspace
תוספים ל-Google Workspace משתמשים בקובץ המניפסט של פרויקט Apps Script כדי להגדיר מספר היבטים במראה ובהתנהגות של התוסף. מאפייני המניפסט של תוספים ל-Google Workspace מאורגנים בקטע addOns
במבנה אובייקט המניפסט.
דוגמה להגדרה של מניפסט תוסף ל-Google Workspace
בדוגמת המניפסט הבאה, מוצג הקטע בקובץ מניפסט שמגדיר תוספים של Google Workspace, כולל ההיבטים הבאים:
- הקטע
addOns.common
במניפסט מגדיר את השם, כתובת ה-URL של הלוגו, הצבעים והגדרות כלליות אחרות שאינן תלויות במארח של התוסף. - המניפסט מגדיר דף בית משותף, אבל מגדיר גם דפי בית ספציפיים ליומן, ל-Docs, ל-Sheets ול-Slides. Gmail משתמש בברירת המחדל לדף הבית.
- הגדרות המניפסט לדוגמה מאפשרות את הפעולות הבאות:
- טריגרים של היומן
eventOpen
ו-eventUpdated
, ושני פתרונות לשיחות ועידה ביומן. - שתי פעולות אוניברסליות.
onItemsSelectedTrigger
של Drive.- פעולה לכתיבה של Gmail וטריגר לפי הקשר.
- קובץ של Docs
linkPreviewTrigger
. אפשר לקרוא מידע נוסף על הטריגר הזה במאמר תצוגה מקדימה של קישורים עם צ'יפים חכמים. - ממשקים ספציפיים לקבצים ב-Docs, ב-Sheets וב-Slides.
- טריגרים של היומן
- השדה
oauthScopes
מגדיר היקפי הרשאות לפרויקט (בדרך כלל לתוספים). - השדה
urlFetchWhitelist
הוא שדה שמבטיח שכל נקודות הקצה שאוחזרו יתאימו לרשימה שצוינה של קידומות של כתובות URL מסוג HTTPS. מידע נוסף זמין במאמר כתובות URL של רשימת ההיתרים.
הקישורים בדוגמה מפנים לתיאורים של השדה הזה במסמכי העזר למניפסט.
{ "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://en.wikipedia.org/wiki/", "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" } ] }, "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/" ] }
כתובות 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
(חובה להשתמש בתווים כלליים לחיפוש כקידומת מובילה)