דף זה תורגם על ידי Cloud Translation API.

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

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

התיעוד הזה עוסק בפרטים של הגדרת מניפסט עבור תוסף ל-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 (צריך להשתמש בתווים כלליים לחיפוש כקידומת מובילת)