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

בפרויקט 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 של רשימת ההיתרים.

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

הערה: מניפסטים כוללים רכיבים אחרים שקשורים למאפיינים של Apps Script. השדות בשדה addOns קשורים ישירות לתוספים של Google Workspace. הדוגמה הזו היא רק חלק מקובץ מניפסט מלא, והיא לא מניפסט עם פונקציונליות מלאה.

{
  "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 בקובץ המניפסט.

הערה: רשימת היתרים, כפי שנעשה בה שימוש ב-urlFetchWhitelist, היא מונח שהוצא משימוש מקביל לרשימת היתרים ומוחלף. למידע נוסף, כדאי לעיין בכתיבת מסמכים מקיפים.

הוספת תחיליות לרשימת ההיתרים

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