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

Проект Apps Script использует файл манифеста для настройки определенных сведений о сценарии и его работе. Чтобы узнать, как просматривать и редактировать манифест, см. Манифесты .

В этой документации подробно описаны настройки манифеста для надстройки Google Workspace.

Структура манифеста надстроек Google Workspace

Надстройки Google Workspace используют файл манифеста проекта Apps Script для определения некоторых аспектов внешнего вида и поведения надстройки. Свойства манифеста надстроек Google Workspace организованы в разделе addOns структуры объекта манифеста .

Пример конфигурации манифеста надстройки Google Workspace

В следующем образце манифеста показан раздел файла манифеста, определяющий надстройки Google Workspace, включая следующие аспекты:

  • Раздел манифеста addOns.common определяет имя, URL-адрес логотипа, цвета и другие общие, независимые от хоста параметры надстройки.
  • Манифест определяет общую домашнюю страницу, но также определяет домашние страницы Календаря, Диска, Документов, Таблиц и Слайдов. Gmail использует домашнюю страницу по умолчанию.
  • Параметры примера манифеста включают следующее:
  • Поле 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 (в качестве начального префикса необходимо использовать подстановочные знаки)