یک افزونه از یک فایل مانیفست برای پیکربندی جزئیات خاصی در مورد برنامه و عملکرد آن استفاده میکند.
این مستندات جزئیات پیکربندی مانیفست برای افزونهی Google Workspace را پوشش میدهد.
ساختار مانیفست برای افزونههای Google Workspace
افزونههای Google Workspace از فایل مانیفست برای تعریف چندین جنبه از ظاهر و رفتار افزونه استفاده میکنند.
ویژگیهای مانیفست افزونههای Google Workspace در بخش addOns از ساختار شیء مانیفست سازماندهی شدهاند.
برای اطلاعات بیشتر در مورد فایلهای مانیفست اسکریپت برنامهها، به ساختار مانیفست مراجعه کنید.
برای اطلاعات مربوط به فایلهای مانیفست افزونههای ساخته شده با نقاط پایانی HTTP، به منبع
projects.deploymentsمراجعه کنید.
مانیفست برای گوگل چت
اگر افزونهی Google Workspace شما، Google Chat را توسعه میدهد، باید با فعال کردن و پیکربندی Google Chat API در کنسول Google Cloud، یک برنامهی Google Chat پیکربندی کنید .
تنظیمات پیکربندی رایج مانیفست (از جمله addons.common ) در Chat نادیده گرفته میشوند. به جای استفاده از مانیفست افزونه، از Chat API برای پیکربندی تنظیمات Chat زیر استفاده میکنید:
- نام، لوگو و توضیحات برنامه چت که فقط در رابط کاربری چت نمایش داده میشوند.
- محرکهای برنامه چت .
اگر افزونه را در Apps Script ساختهاید، باید اشیاء زیر را نیز در مانیفست خود اضافه یا بهروزرسانی کنید:
-
addons.chat(الزامی) -
oauthScopes(در صورتی که برنامه Google Chat شما از محدودههای OAuth استفاده میکند، الزامی است)
برای مراحل پیکربندی تنظیمات چت برای یک افزونه، به پیکربندی برنامه چت گوگل مراجعه کنید.
نمونه پیکربندی مانیفست افزونه Google Workspace
نمونههای مانیفست زیر بخشی از یک فایل مانیفست را نشان میدهند که افزونهی Google Workspace را تعریف میکند و شامل جنبههای زیر است:
بخش
addOns.commonدر فایل مانیفست، نام، آدرس اینترنتی لوگو، رنگها و سایر تنظیمات عمومی و مستقل از میزبان را برای افزونه تعریف میکند.مانیفست یک صفحه اصلی مشترک را تعریف میکند، اما صفحات اصلی مخصوص تقویم گوگل، گوگل درایو، گوگل داکز، شیتها و اسلایدها را نیز تعریف میکند. جیمیل از صفحه اصلی پیشفرض استفاده میکند.
تنظیمات مانیفست نمونه موارد زیر را فعال میکند:
محرکهای
eventOpenتقویم وeventUpdated.(فقط اسکریپت برنامهها) دو راهکار کنفرانس تقویم.
دو اقدام جهانی.
یک محرک
onItemsSelectedTrigger.یک اقدام نوشتن در جیمیل و یک محرک متنی.
یک شیء
linkPreviewTriggersدر Docs. برای کسب اطلاعات بیشتر در مورد این trigger، به Preview links with smart chips مراجعه کنید.یک شیء
createActionTriggersدر Docs. برای کسب اطلاعات بیشتر در مورد این trigger، به بخش Create third-party resources از منوی @ مراجعه کنید.رابطهای مختص فایل برای اسناد، برگهها و اسلایدها.
یک گزینه Meet
sidePanelUriوaddOnOrigins.(فقط HTTP) دو
HttpOptionsبرای ارسال هدر مجوز و پشتیبانی از رضایت جزئی.
فیلد
oauthScopesمحدودههای مجوز برای پروژه را تعیین میکند (معمولاً برای افزونهها لازم است).(فقط اسکریپت برنامهها) فیلد
urlFetchWhitelistفیلدی است که تضمین میکند هر نقطه پایانی واکشی شده با لیست مشخصی از پیشوندهای URL HTTPS مطابقت داشته باشد. برای اطلاعات بیشتر، به Allowlist URLs مراجعه کنید.
پیوندهای موجود در نمونههای مانیفست، به توضیحات آن فیلد در مستندات مرجع مانیفست مربوطه برای افزونههای 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"
}
},
"meet": {
"homepageTrigger",
"Web": [
{
"sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl",
"supportsScreenSharing": true,
"addOnOrigins": [
"https://www.myownpersonaldomain.com",
"https://www.myownpersonaldomain.com:443"
],
"logoUrl": "https://myownpersonaldomain.com/logoUrl",
"darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl"
}
},
},
"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/"
]
}اچتیپی
{ "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" } }, "meet": { "homepageTrigger", "Web": [ { "sidePanelUrl": "https://myownpersonaldomain.com/sidePanelUrl", "supportsScreenSharing": true, "addOnOrigins": [ "https://www.myownpersonaldomain.com", "https://www.myownpersonaldomain.com:443" ], "logoUrl": "https://myownpersonaldomain.com/meetWebLogoUrl", "darkModeLogoUrl": "https://myownpersonaldomain.com/darkModeLogoUrl" } ] }, "httpOptions": { "authorizationHeader": "SYSTEM_ID_TOKEN", "granularOauthPermissionSupport": "OPT_IN" } }, "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هایی که به لیست مجاز اضافه نشدهاند، دسترسی پیدا کنند.
این فیلد هنگام نصب یک استقرار آزمایشی اختیاری است، اما هنگام ایجاد یک استقرار نسخهبندیشده الزامی است.
شما زمانی از لیستهای مجاز استفاده میکنید که اسکریپت یا افزونه شما اقدامات زیر را انجام دهد:
- اطلاعات را از یک مکان خارجی (مانند نقاط انتهایی 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معتبر نیست. - شما میتوانید از کاراکترهای wildcard برای تطبیق پیشوندهای زیر دامنه 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
استفاده از کاراکترهای عمومی
شما میتوانید از یک کاراکتر wildcard ( * ) برای تطبیق یک زیردامنه برای هر دو فیلد urlFetchWhitelist و addOns.common.openLinkUrlPrefixes استفاده کنید. شما نمیتوانید بیش از یک wildcard برای تطبیق چندین زیردامنه استفاده کنید و wildcard باید نشاندهنده پیشوند ابتدای 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(باید از کاراکترهای wildcards به عنوان پیشوند آغازین استفاده شود)