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

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

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

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

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

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

• Информацию о файлах манифеста Google Apps Script можно найти в статье Структура манифеста.

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

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

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

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

• Название, логотип и описание приложения Chat для интерфейса Chat.
• Триггеры приложений Chat.

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

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

Чтобы настроить Chat для дополнения, ознакомьтесь с разделом Как использовать Google Chat API.

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

Ниже приведены примеры фрагментов манифеста, в которых определено дополнение Google Workspace, в том числе:

• addOns.common определяет название, логотип, цвета и другие общие настройки дополнения.

• Манифест определяет общую главную страницу, а также главные страницы для Google Календаря, Google Диска, Google Документов, Google Таблиц и Google Презентаций. В Gmail используется главная страница по умолчанию.

• Приведенные ниже настройки манифеста позволяют:

  • Триггеры календаря eventOpen и eventUpdated.

  • (Только для Apps Script) Два решения для видеовстреч в Календаре.

  • Два универсальных действия.

  • Диск А onItemsSelectedTrigger.

  • Действие "Создать письмо" в Gmail и контекстный триггер.

  • Объект linkPreviewTriggers в Документах. Подробнее о том, как использовать умные чипы для предварительного просмотра ссылок…

  • Объект createActionTriggers в Документах. Подробнее о том, как создавать сторонние ресурсы с помощью меню "@"…

  • Интерфейсы для работы с файлами Документов, Таблиц и Презентаций.

  • Варианты sidePanelUri и addOnOrigins для Google Meet.

  • (Только HTTP) Два HttpOptions для отправки заголовка авторизации и поддержки детального согласия.

• В поле oauthScopes задаются области авторизации проекта.

• (Только для Apps Script) Тег urlFetchWhitelist гарантирует, что полученные конечные точки соответствуют указанным префиксам URL с протоколом HTTPS. Подробнее о добавлении URL в белый список…

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

Манифесты включают другие компоненты. Поля в разделе addOns напрямую связаны с дополнениями 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, которые не были добавлены в этот список.

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

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

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

Примечание. Термин белый список, используемый в urlFetchWhitelist, устарел. Вместо него используется термин список разрешенных. Подробнее о том, как писать инклюзивную документацию…

Как добавить префиксы в белый список

Если вы указываете белые списки в файле манифеста (добавляя поле addOns.common.openLinkUrlPrefixes или urlFetchWhitelist), то должны включить список префиксов URL. Префиксы, добавленные в манифест, должны соответствовать следующим требованиям:

• Каждый префикс должен быть действительным URL.
• В каждом префиксе должен использоваться символ https://, а не http://.
• У каждого префикса должен быть полный домен.
• У каждого префикса должен быть непустой путь. Например, https://www.google.com/ – допустимое значение, а https://www.google.com – нет.
• Вы можете использовать подстановочные знаки, чтобы сопоставлять префиксы субдоменов URL.
• В поле addOns.common.openLinkUrlPrefixes можно использовать один подстановочный знак *, чтобы сопоставить все ссылки, но это не рекомендуется, так как может подвергнуть риску данные пользователя и продлить процесс проверки дополнения. Используйте подстановочный знак, только если он необходим для работы дополнения.

При определении того, соответствует ли URL префиксу в белом списке, применяются следующие правила:

• При сопоставлении путей учитывается регистр.
• Если префикс идентичен 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 (подстановочные знаки должны использоваться в качестве ведущего префикса)