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