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

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

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

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

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

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

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

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

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

Если ваше дополнение 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-адрес логотипа, цвета и другие общие, независимые от хоста настройки для дополнения.
В манифесте определяется общая домашняя страница, а также домашние страницы для Google Календаря, Google Диска, Google Документов, Таблиц и Презентаций. Gmail использует домашнюю страницу по умолчанию.
Пример настроек манифеста включает следующие параметры:
- Триггеры событий Calendar eventOpen и eventUpdated .
- (Только для Apps Script) Два решения для конференц-связи через календарь.
- Два универсальных действия.
- A Drive onItemsSelectedTrigger .
- Действие при создании письма в Gmail и контекстный триггер.
- Объект Docs linkPreviewTriggers . Подробнее об этом триггере см. в разделе «Предварительный просмотр ссылок с помощью смарт-чипов» .
- Объект createActionTriggers из документации. Подробнее об этом триггере см. в разделе «Создание сторонних ресурсов из меню @» .
- Интерфейсы, специфичные для каждого файла: Документы, Таблицы и Презентации.
- Опции Meet sidePanelUri и addOnOrigins .
- (Только HTTP) Два HttpOptions для отправки заголовка авторизации и поддержки детального согласия.
Поле oauthScopes задает области авторизации для проекта (обычно требуется для дополнений).
(Только для Apps Script) Поле urlFetchWhitelist гарантирует, что все получаемые конечные точки соответствуют указанному списку префиксов HTTPS-адресов. Для получения дополнительной информации см. раздел «URL-адреса в списке разрешенных» .

Ссылки в примерах манифеста перенаправляют на описания этого поля в соответствующей справочной документации по манифестам для дополнений Apps Script и HTTP Google Workspace.

Apps Script

{
  "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/"
  ]
}

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"
      }
    },
    "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-адресов используются для обозначения конкретных URL-адресов, предварительно одобренных для доступа вашим скриптом или дополнением. Списки разрешенных URL-адресов помогают защитить данные пользователей; при определении списка разрешенных URL-адресов проекты скриптов не могут получить доступ к URL-адресам, которые не были добавлены в этот список.

Это поле является необязательным при установке тестового развертывания, но обязательным при создании версионированного развертывания.

Списки разрешенных действий используются, когда ваш скрипт или дополнение выполняет следующие действия:

Получает информацию из внешнего источника (например, с HTTPS-серверов) с помощью сервиса Apps Script UrlFetch . Чтобы добавить URL-адреса в список разрешенных для получения данных, укажите поле urlFetchWhitelist в файле манифеста.
Открывает или отображает URL-адрес в ответ на действие пользователя (требуется для дополнений Google Workspace, которые открывают или отображают URL-адреса, находящиеся вне Google). Чтобы добавить URL-адреса в список разрешенных для открытия, добавьте поле addOns.common.openLinkUrlPrefixes в файл манифеста.

Добавление префиксов в список разрешенных.

При указании списков разрешенных URL-адресов в файле манифеста (путем включения поля 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 (в качестве начального префикса необходимо использовать символы подстановки)