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