Проект Apps Script использует файл манифеста для настройки определенных сведений о сценарии и его работе. Чтобы узнать, как просматривать и редактировать манифест, см. Манифесты .
В этой документации подробно описаны настройки манифеста для надстройки Google Workspace.
Структура манифеста надстроек Google Workspace
Надстройки Google Workspace используют файл манифеста проекта Apps Script для определения некоторых аспектов внешнего вида и поведения надстройки. Свойства манифеста надстроек Google Workspace организованы в разделе addOns структуры объекта манифеста .
Пример конфигурации манифеста надстройки Google Workspace
В следующем образце манифеста показан раздел файла манифеста, определяющий надстройки Google Workspace, включая следующие аспекты:
- Раздел манифеста
addOns.commonопределяет имя, URL-адрес логотипа, цвета и другие общие, независимые от хоста параметры надстройки. - Манифест определяет общую домашнюю страницу, но также определяет домашние страницы Календаря, Диска, Документов, Таблиц и Слайдов. Gmail использует домашнюю страницу по умолчанию.
- Параметры примера манифеста включают следующее:
- Триггеры Calendar
eventOpenиeventUpdated, а также два решения для конференций Calendar. - Два универсальных действия.
- Диск
onItemsSelectedTrigger. - Действие создания Gmail и контекстный триггер.
-
linkPreviewTriggerДокументов. Чтобы узнать об этом триггере, см. раздел Предварительный просмотр ссылок с помощью смарт-чипов . - Файловые интерфейсы для документов, таблиц и слайдов.
- Триггеры Calendar
- Поле
oauthScopesустанавливает области авторизации для проекта (обычно требуется для надстроек). - Поле
urlFetchWhitelist— это поле, которое гарантирует, что любые полученные конечные точки соответствуют указанному списку префиксов URL-адресов HTTPS. Это поле является необязательным для тестовых развертываний, но обязательно для развертываний. Дополнительные сведения см. в разделе URL-адреса белого списка .
Ссылки в образце ведут к описаниям этого поля в справочной документации по манифесту .
// Sample configuration of the addOns section in a manifest file:
{
"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в файл манифеста.
Добавление префиксов в белый список
При указании списков разрешенных в файле манифеста (включая поле 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(в качестве начального префикса необходимо использовать подстановочные знаки)