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

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

Дополнение использует файл манифеста для настройки определенных сведений о приложении и его работе.

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

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

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

Свойства манифеста для надстроек Google Workspace организованы в разделе « addOns » структуры объекта манифеста.

Информацию о файлах манифеста Apps Script см. в разделе Структура манифеста .
Информацию о файлах манифеста для дополнений, созданных с использованием конечных точек HTTP, можно найти в ресурсе projects.deployments .

Манифесты для Google Chat

Если ваше дополнение Google Workspace расширяет возможности Google Chat, вам необходимо настроить приложение Google Chat , включив и настроив API Google Chat в консоли Google Cloud.

Общие параметры конфигурации манифеста (включая addons.common ) игнорируются в Chat. Вместо использования манифеста дополнения вы используете API Chat для настройки следующих параметров Chat:

Название, логотип и описание приложения чата, которые отображаются только в пользовательском интерфейсе чата.
Триггеры чат-приложения .

Если вы создали надстройку в Apps Script, вам также необходимо добавить или обновить следующие объекты в манифесте:

addons.chat (обязательно)
oauthScopes (требуется, если ваше приложение Google Chat использует области OAuth)

Инструкции по настройке параметров чата для надстройки см. в разделе Настройка приложения Google Chat .

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

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

Раздел addOns.common манифеста определяет название, URL-адрес логотипа, цвета и другие общие, независимые от хоста параметры для дополнения.
Манифест определяет общую домашнюю страницу, а также отдельные домашние страницы для Календаря, Диска, Документов, Таблиц и Презентаций. Gmail использует домашнюю страницу по умолчанию.
Пример настроек манифеста позволяет:
- Триггеры событий календаря eventOpen и eventUpdated .
- (Только Apps Script) Два решения для конференций «Календарь».
- Два универсальных действия.
- Диск onItemsSelectedTrigger .
- Действие создания письма в Gmail и контекстный триггер.
- Объект Docs linkPreviewTriggers . Подробнее об этом триггере см. в статье Предварительный просмотр ссылок с помощью смарт-чипов .
- Объект Docs createActionTriggers . Подробнее об этом триггере см. в разделе Создание сторонних ресурсов из меню @ .
- Специфические интерфейсы для документов, таблиц и слайдов.
- (Только HTTP) Два HttpOptions для отправки заголовка авторизации и поддержки детального согласия.
Поле oauthScopes устанавливает области авторизации для проекта (обычно требуется для дополнений).
(Только для Apps Script) Поле 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"
      }
    }
    "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-адресов используются для указания определенных 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 (в качестве начального префикса необходимо использовать подстановочные знаки)