Google Workspace 插件清单

Apps 脚本项目使用清单文件来配置脚本及其操作的特定详细信息。如需了解如何查看和修改清单,请参阅清单

本文档详细介绍了为 Google Workspace 插件配置清单。

Google Workspace 插件的清单结构

Google Workspace 插件使用 Apps 脚本项目清单文件定义插件的外观和行为的多个方面。Google Workspace 插件的清单属性在清单对象结构的 addOns 部分下整理。

Google Workspace 插件清单配置示例

以下清单示例显示了定义 Google Workspace 插件的清单文件部分,包括以下方面:

  • 清单的 addOns.common 部分定义了插件的名称、徽标网址、颜色以及其他与主机无关的常规设置。
  • 该清单定义了一个通用首页,还定义了特定于 Google 日历、云端硬盘、文档、表格和幻灯片的首页。Gmail 使用默认首页。
  • 示例清单设置可启用以下功能:
    • 日历 eventOpeneventUpdated 触发器以及两个日历会议解决方案
    • 两个通用操作。
    • 云端硬盘 onItemsSelectedTrigger
    • Gmail 撰写操作和上下文触发器。
    • Google 文档、表格和幻灯片的文件专属界面。
  • oauthScopes 字段可为项目设置授权范围(插件通常需要这样做)。
  • urlFetchWhitelist 字段会设置 HTTPS 网址前缀,以确保任何提取的端点都与前缀匹配(通常对于插件是必需的)。如需了解详情,请参阅将网址列入许可名单

示例中的链接指向清单参考文档中该字段的说明。

// 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"
      }
    },

    "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"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ],
}

许可名单网址

有时,您可能希望脚本或插件打开网址来响应用户操作。有时,您可能希望脚本或插件使用 Apps 脚本 UrlFetch 服务从外部位置检索信息。在这两种情况下,您都必须您在项目清单中打开或提取的网址列入许可名单。

列入许可名单是指定脚本或插件预先批准访问特定网址的过程。此要求有助于保护用户数据;如果您定义了许可名单,脚本项目无法访问尚未列入许可名单的网址。 Google Workspace 插件要求先将网址列入许可名单,然后才能提取或打开这些网址。

您可以将网址列入提取许可名单,方法是将相应网址或匹配的前缀添加到 urlFetchWhitelist 清单字段。对于 Google Workspace插件项目,您可以将要打开的网址或匹配的前缀添加到 addOns.common.openLinkUrlPrefixes 清单字段,从而列入许可名单。

您添加到清单中的前缀必须符合以下要求:

  • 每个前缀都必须是有效网址。
  • 每个前缀都必须使用 https://,而不是 http://
  • 每个前缀都必须有完整的域名。
  • 每个前缀必须具有非空路径。例如,https://www.google.com/ 有效,但 https://www.google.com 无效。
  • 您可以使用通配符来匹配网址子网域前缀。
  • 可以在 addOns.common.openLinkUrlPrefixes 字段中使用单个 * 通配符来匹配所有链接,但不建议这样做,因为它可能会让用户的数据面临风险,并可能延长插件审核流程。只有当插件功能需要时,才使用通配符。

在确定网址是否与列入许可名单的前缀匹配时,请遵循以下规则:

  • 路径匹配区分大小写。
  • 如果前缀与网址相同,就是匹配项。
  • 如果网址是同一个前缀或子前缀,就表示匹配。

例如,前缀 https://example.com/foo 与以下网址匹配:

  • https://example.com/foo
  • https://example.com/foo/
  • https://example.com/foo/bar
  • https://example.com/foo?bar
  • https://example.com/foo#bar

使用通配符

您可以使用单个通配符 (*) 为 urlFetchWhitelistaddOns.common.openLinkUrlPrefixes 字段匹配子网域。您不能使用多个通配符来匹配多个子网域,并且通配符必须表示网址的开头前缀。

例如,前缀 https://*.example.com/foo 与以下网址匹配:

  • https://subdomain.example.com/foo
  • https://any.number.of.subdomains.example.com/foo

前缀 https://*.example.com/foo 不会与以下网址匹配:

  • https://subdomain.example.com/bar(后缀不匹配)
  • https://example.com/foo(必须至少提供一个子网域)

当您尝试保存清单时,系统会强制执行部分前缀规则。例如,如果尝试保存时清单中存在以下前缀,则会引发错误:

  • https://*.*.example.com/foo(禁止使用多个通配符)
  • https://subdomain.*.example.com/foo(通配符必须用作前置前缀)