افزونه‌های Manifests برای Google Workspace، افزونه‌های Manifests برای Google Workspace، افزونه‌های Manifests برای Google Workspace، افزونه‌های Manifests برای Google Workspace

یک افزونه از یک فایل مانیفست برای پیکربندی جزئیات خاصی در مورد برنامه و عملکرد آن استفاده می کند.

این مستند جزئیات پیکربندی مانیفست برای افزونه Google Workspace را پوشش می‌دهد.

ساختار مانیفست برای افزونه های Google Workspace

افزونه‌های Google Workspace از فایل مانیفست برای تعریف چندین جنبه از ظاهر و رفتار افزونه استفاده می‌کنند.

ویژگی‌های مانیفست افزونه‌های Google Workspace در بخش addOns ساختار شی مانیفست سازمان‌دهی شده‌اند.

مانیفست‌ها برای Google Chat

اگر افزونه Google Workspace شما Google Chat را گسترش می‌دهد، باید با فعال کردن و پیکربندی Google Chat API در کنسول Google Cloud، یک برنامه Google Chat را پیکربندی کنید .

تنظیمات رایج پیکربندی مانیفست (از جمله addons.common ) در چت نادیده گرفته می‌شوند. به جای استفاده از مانیفست افزودنی، از Chat API برای پیکربندی تنظیمات Chat زیر استفاده می‌کنید:

  • نام، نشان‌واره و توضیحات برنامه چت که فقط در رابط کاربری چت ظاهر می‌شود.
  • محرک های برنامه چت

اگر افزونه را در Apps Script ساخته اید، باید اشیاء زیر را نیز در مانیفست خود اضافه یا به روز کنید:

  • addons.chat (الزامی)
  • oauthScopes (اگر برنامه چت Google شما از دامنه های OAuth استفاده می کند، ضروری است)

برای مراحل پیکربندی تنظیمات گپ برای یک افزونه، به پیکربندی برنامه گپ Google مراجعه کنید.

نمونه پیکربندی مانیفست افزونه Google Workspace

نمونه مانیفست زیر بخشی از یک فایل مانیفست را نشان می دهد که یک افزونه Google Workspace را تعریف می کند، شامل جنبه های زیر:

  • بخش addOns.common مانیفست نام، نشانی اینترنتی نشان‌واره، رنگ‌ها و سایر تنظیمات کلی و مستقل از میزبان را برای افزونه تعریف می‌کند.
  • مانیفست یک صفحه اصلی مشترک را تعریف می کند، اما همچنین صفحه اصلی تقویم، Drive، Docs، Sheets و Slides را مشخص می کند. جیمیل از صفحه اصلی پیش فرض استفاده می کند.
  • تنظیمات مانیفست نمونه موارد زیر را فعال می کند:
  • فیلد oauthScopes محدوده های مجوز را برای پروژه تنظیم می کند (معمولاً برای افزودنی ها مورد نیاز است).
  • (فقط اسکریپت برنامه ها) فیلد urlFetchWhitelist فیلدی است که تضمین می کند هر نقطه پایانی واکشی شده با فهرست مشخصی از پیشوندهای URL HTTPS مطابقت دارد. برای اطلاعات بیشتر، URL های لیست مجاز را ببینید.

پیوندهای موجود در نمونه به توضیحات آن فیلد در مستندات مرجع مانیفست مربوطه برای افزونه‌های Apps Script و HTTP 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://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 هایی که به لیست مجاز اضافه نشده اند دسترسی پیدا کنند.

این فیلد هنگام نصب یک استقرار آزمایشی اختیاری است، اما زمانی که یک استقرار نسخه‌سازی شده ایجاد می‌کنید لازم است.

هنگامی که اسکریپت یا افزونه شما اقدامات زیر را انجام می دهد از لیست های مجاز استفاده می کنید:

  • با استفاده از سرویس Apps Script UrlFetch اطلاعات را از یک مکان خارجی (مانند نقاط پایانی HTTPS) بازیابی یا واکشی می کند. برای واکشی 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 (کارت های عام باید به عنوان پیشوند اصلی استفاده شوند)
،

یک افزونه از یک فایل مانیفست برای پیکربندی جزئیات خاصی در مورد برنامه و عملکرد آن استفاده می کند.

این مستند جزئیات پیکربندی مانیفست برای افزونه Google Workspace را پوشش می‌دهد.

ساختار مانیفست برای افزونه های Google Workspace

افزونه‌های Google Workspace از فایل مانیفست برای تعریف چندین جنبه از ظاهر و رفتار افزونه استفاده می‌کنند.

ویژگی‌های مانیفست افزونه‌های Google Workspace در بخش addOns ساختار شی مانیفست سازمان‌دهی شده‌اند.

مانیفست‌ها برای Google Chat

اگر افزونه Google Workspace شما Google Chat را گسترش می‌دهد، باید با فعال کردن و پیکربندی Google Chat API در کنسول Google Cloud، یک برنامه Google Chat را پیکربندی کنید .

تنظیمات رایج پیکربندی مانیفست (از جمله addons.common ) در چت نادیده گرفته می‌شوند. به جای استفاده از مانیفست افزودنی، از Chat API برای پیکربندی تنظیمات Chat زیر استفاده می‌کنید:

  • نام، نشان‌واره و توضیحات برنامه چت که فقط در رابط کاربری چت ظاهر می‌شود.
  • محرک های برنامه چت

اگر افزونه را در Apps Script ساخته اید، باید اشیاء زیر را نیز در مانیفست خود اضافه یا به روز کنید:

  • addons.chat (الزامی)
  • oauthScopes (اگر برنامه چت Google شما از دامنه های OAuth استفاده می کند، ضروری است)

برای مراحل پیکربندی تنظیمات گپ برای یک افزونه، به پیکربندی برنامه گپ Google مراجعه کنید.

نمونه پیکربندی مانیفست افزونه Google Workspace

نمونه مانیفست زیر بخشی از یک فایل مانیفست را نشان می دهد که یک افزونه Google Workspace را تعریف می کند، شامل جنبه های زیر:

  • بخش addOns.common مانیفست نام، نشانی اینترنتی نشان‌واره، رنگ‌ها و سایر تنظیمات کلی و مستقل از میزبان را برای افزونه تعریف می‌کند.
  • مانیفست یک صفحه اصلی مشترک را تعریف می کند، اما همچنین صفحه اصلی تقویم، Drive، Docs، Sheets و Slides را تعریف می کند. جیمیل از صفحه اصلی پیش فرض استفاده می کند.
  • تنظیمات مانیفست نمونه موارد زیر را فعال می کند:
  • فیلد oauthScopes محدوده های مجوز را برای پروژه تنظیم می کند (معمولاً برای افزودنی ها مورد نیاز است).
  • (فقط اسکریپت برنامه ها) فیلد urlFetchWhitelist فیلدی است که تضمین می کند هر نقطه پایانی واکشی شده با فهرست مشخصی از پیشوندهای URL HTTPS مطابقت دارد. برای اطلاعات بیشتر، URL های لیست مجاز را ببینید.

پیوندهای موجود در نمونه به توضیحات آن فیلد در مستندات مرجع مانیفست مربوطه برای افزونه‌های Apps Script و HTTP 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://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 هایی که به لیست مجاز اضافه نشده اند دسترسی پیدا کنند.

این فیلد هنگام نصب یک استقرار آزمایشی اختیاری است، اما زمانی که یک استقرار نسخه‌سازی شده ایجاد می‌کنید لازم است.

هنگامی که اسکریپت یا افزونه شما اقدامات زیر را انجام می دهد از لیست های مجاز استفاده می کنید:

  • با استفاده از سرویس Apps Script UrlFetch اطلاعات را از یک مکان خارجی (مانند نقاط پایانی HTTPS) بازیابی یا واکشی می کند. برای واکشی 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 (کارت های عام باید به عنوان پیشوند اصلی استفاده شوند)
،

یک افزونه از یک فایل مانیفست برای پیکربندی جزئیات خاصی در مورد برنامه و عملکرد آن استفاده می کند.

این مستند جزئیات پیکربندی مانیفست برای افزونه Google Workspace را پوشش می‌دهد.

ساختار مانیفست برای افزونه های Google Workspace

افزونه‌های Google Workspace از فایل مانیفست برای تعریف چندین جنبه از ظاهر و رفتار افزونه استفاده می‌کنند.

ویژگی‌های مانیفست افزونه‌های Google Workspace در بخش addOns ساختار شی مانیفست سازمان‌دهی شده‌اند.

مانیفست‌ها برای Google Chat

اگر افزونه Google Workspace شما Google Chat را گسترش می‌دهد، باید با فعال کردن و پیکربندی Google Chat API در کنسول Google Cloud، یک برنامه Google Chat را پیکربندی کنید .

تنظیمات رایج پیکربندی مانیفست (از جمله addons.common ) در چت نادیده گرفته می‌شوند. به جای استفاده از مانیفست افزودنی، از Chat API برای پیکربندی تنظیمات Chat زیر استفاده می‌کنید:

  • نام، نشان‌واره و توضیحات برنامه چت که فقط در رابط کاربری چت ظاهر می‌شود.
  • محرک های برنامه چت

اگر افزونه را در Apps Script ساخته اید، باید اشیاء زیر را نیز در مانیفست خود اضافه یا به روز کنید:

  • addons.chat (الزامی)
  • oauthScopes (اگر برنامه چت Google شما از دامنه های OAuth استفاده می کند، ضروری است)

برای مراحل پیکربندی تنظیمات گپ برای یک افزونه، به پیکربندی برنامه گپ Google مراجعه کنید.

نمونه پیکربندی مانیفست افزونه Google Workspace

نمونه مانیفست زیر بخشی از یک فایل مانیفست را نشان می دهد که یک افزونه Google Workspace را تعریف می کند، شامل جنبه های زیر:

  • بخش addOns.common مانیفست نام، نشانی اینترنتی نشان‌واره، رنگ‌ها و سایر تنظیمات کلی و مستقل از میزبان را برای افزونه تعریف می‌کند.
  • مانیفست یک صفحه اصلی مشترک را تعریف می کند، اما همچنین صفحه اصلی تقویم، Drive، Docs، Sheets و Slides را مشخص می کند. جیمیل از صفحه اصلی پیش فرض استفاده می کند.
  • تنظیمات مانیفست نمونه موارد زیر را فعال می کند:
  • فیلد oauthScopes محدوده های مجوز را برای پروژه تنظیم می کند (معمولاً برای افزودنی ها مورد نیاز است).
  • (فقط اسکریپت برنامه ها) فیلد urlFetchWhitelist فیلدی است که تضمین می کند هر نقطه پایانی واکشی شده با فهرست مشخصی از پیشوندهای URL HTTPS مطابقت دارد. برای اطلاعات بیشتر، URL های لیست مجاز را ببینید.

پیوندهای موجود در نمونه به توضیحات آن فیلد در مستندات مرجع مانیفست مربوطه برای افزونه‌های Apps Script و HTTP 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://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 هایی که به لیست مجاز اضافه نشده اند دسترسی پیدا کنند.

این فیلد هنگام نصب یک استقرار آزمایشی اختیاری است، اما زمانی که یک استقرار نسخه‌سازی شده ایجاد می‌کنید لازم است.

هنگامی که اسکریپت یا افزونه شما اقدامات زیر را انجام می دهد از لیست های مجاز استفاده می کنید:

  • با استفاده از سرویس Apps Script UrlFetch اطلاعات را از یک مکان خارجی (مانند نقاط پایانی HTTPS) بازیابی یا واکشی می کند. برای واکشی 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 (کارت های عام باید به عنوان پیشوند اصلی استفاده شوند)
،

یک افزونه از یک فایل مانیفست برای پیکربندی جزئیات خاصی در مورد برنامه و عملکرد آن استفاده می کند.

این مستند جزئیات پیکربندی مانیفست برای افزونه Google Workspace را پوشش می‌دهد.

ساختار مانیفست برای افزونه های Google Workspace

افزونه‌های Google Workspace از فایل مانیفست برای تعریف چندین جنبه از ظاهر و رفتار افزونه استفاده می‌کنند.

ویژگی‌های مانیفست افزونه‌های Google Workspace در بخش addOns ساختار شی مانیفست سازمان‌دهی شده‌اند.

مانیفست‌ها برای Google Chat

اگر افزونه Google Workspace شما Google Chat را گسترش می‌دهد، باید با فعال کردن و پیکربندی Google Chat API در کنسول Google Cloud، یک برنامه Google Chat را پیکربندی کنید .

تنظیمات رایج پیکربندی مانیفست (از جمله addons.common ) در چت نادیده گرفته می‌شوند. به جای استفاده از مانیفست افزودنی، از Chat API برای پیکربندی تنظیمات Chat زیر استفاده می‌کنید:

  • نام، نشان‌واره و توضیحات برنامه چت که فقط در رابط کاربری چت ظاهر می‌شود.
  • محرک های برنامه چت

اگر افزونه را در Apps Script ساخته اید، باید اشیاء زیر را نیز در مانیفست خود اضافه یا به روز کنید:

  • addons.chat (الزامی)
  • oauthScopes (اگر برنامه چت Google شما از دامنه های OAuth استفاده می کند، ضروری است)

برای مراحل پیکربندی تنظیمات گپ برای یک افزونه، به پیکربندی برنامه گپ Google مراجعه کنید.

نمونه پیکربندی مانیفست افزونه Google Workspace

نمونه مانیفست زیر بخشی از یک فایل مانیفست را نشان می دهد که یک افزونه Google Workspace را تعریف می کند، شامل جنبه های زیر:

  • بخش addOns.common مانیفست نام، نشانی اینترنتی نشان‌واره، رنگ‌ها و سایر تنظیمات کلی و مستقل از میزبان را برای افزونه تعریف می‌کند.
  • مانیفست یک صفحه اصلی مشترک را تعریف می کند، اما همچنین صفحه اصلی تقویم، Drive، Docs، Sheets و Slides را تعریف می کند. جیمیل از صفحه اصلی پیش فرض استفاده می کند.
  • تنظیمات مانیفست نمونه موارد زیر را فعال می کند:
  • فیلد oauthScopes محدوده های مجوز را برای پروژه تنظیم می کند (معمولاً برای افزودنی ها مورد نیاز است).
  • (فقط اسکریپت برنامه ها) فیلد urlFetchWhitelist فیلدی است که تضمین می کند هر نقطه پایانی واکشی شده با فهرست مشخصی از پیشوندهای URL HTTPS مطابقت دارد. برای اطلاعات بیشتر، URL های لیست مجاز را ببینید.

پیوندهای موجود در نمونه به توضیحات آن فیلد در مستندات مرجع مانیفست مربوطه برای افزونه‌های Apps Script و HTTP 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://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 هایی که به لیست مجاز اضافه نشده اند دسترسی پیدا کنند.

این فیلد هنگام نصب یک استقرار آزمایشی اختیاری است، اما زمانی که یک استقرار نسخه‌سازی شده ایجاد می‌کنید لازم است.

هنگامی که اسکریپت یا افزونه شما اقدامات زیر را انجام می دهد از لیست های مجاز استفاده می کنید:

  • با استفاده از سرویس Apps Script UrlFetch اطلاعات را از یک مکان خارجی (مانند نقاط پایانی HTTPS) بازیابی یا واکشی می کند. برای واکشی 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 (کارت های عام باید به عنوان پیشوند اصلی استفاده شوند)