Эта страница переведена с помощью Cloud Translation API.

Манифесты дополнений Google Workspace

Проект 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 ДокументыPreviewTrigger. Подробнее об этом триггере см. в разделе Предварительный просмотр ссылок со смарт-чипами .
- Интерфейсы для файлов для документов, таблиц и слайдов.
Поле 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) с помощью службы 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 (в качестве ведущего префикса необходимо использовать подстановочные знаки)