Google Workspace 插件的清单

插件使用清单文件来配置有关应用及其运行的某些详细信息。

本文档详细介绍了如何为 Google Workspace 加载项配置清单。

Google Workspace 插件的清单结构

Google Workspace 加载项使用清单文件来定义外观和行为的多个方面。

Google Workspace 加购项的清单属性位于 addOns 部分下。

如需了解 Google Apps 脚本清单文件，请参阅清单结构。
如需了解使用 HTTP 端点构建的插件的清单文件，请参阅 projects.deployments。

Google Chat 的清单

如果您的 Google Workspace 插件扩展了 Google Chat，请在 Google Cloud 控制台中启用并配置 Google Chat API，以配置 Google Chat 应用。

在 Chat 中，常见的清单配置设置（包括 addons.common）会被忽略。使用 Chat API 配置以下 Chat 设置：

聊天界面中聊天应用的名称、徽标和说明。
聊天应用触发器。

如果您是在 Apps 脚本中构建的插件，请在清单中添加或更新以下对象：

addons.chat（必需）
oauthScopes（如果您的 Google Chat 应用使用 OAuth，则为必需）

如需为加购项配置 Chat 设置，请参阅配置 Google Chat 应用。

Google Workspace 插件清单配置示例

以下示例展示了清单中用于定义 Google Workspace 插件的部分，包括以下方面：

addOns.common 用于定义插件的名称、徽标、颜色和其他常规设置。
清单定义了一个通用首页，但同时也定义了 Google 日历、Google 云端硬盘、Google 文档、Google 表格和 Google 幻灯片专用的首页。Gmail 使用默认首页。
示例清单设置可实现以下功能：
- 日历 eventOpen 和 eventUpdated 触发器。
- （仅限 Apps 脚本）两种日历会议解决方案。
- 两项通用操作。
- 云端硬盘 onItemsSelectedTrigger。
- Gmail 撰写操作和情境触发器。
- 一个 Docs linkPreviewTriggers 对象。请参阅包含智能条状标签的预览链接。
- 一个 Docs createActionTriggers 对象。请参阅通过 @ 菜单创建第三方资源。
- Google 文档、表格和幻灯片的文件专用界面。
- Google Meet sidePanelUri 和 addOnOrigins 选项。
- （仅限 HTTP）两个 HttpOptions，用于发送授权标头和支持精细化意见征求。
oauthScopes 字段用于设置项目的授权范围。
（仅限 Apps 脚本）urlFetchWhitelist 可确保所提取的端点与指定的 HTTPS 网址前缀相匹配。请参阅将网址列入许可名单。

示例中的链接会重定向到 Apps 脚本和 HTTP Google Workspace 插件的清单参考中的字段说明。

清单包含其他组件。addOns 下的字段直接与 Google Workspace 加载项相关。此示例仅显示了完整清单文件的一部分，无法单独运行。

Apps 脚本

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

将网址列入许可名单

您可以使用许可名单来指定已预先批准可供脚本或插件访问的特定网址。许可名单有助于保护用户数据；定义许可名单后，脚本项目便无法访问未添加到许可名单中的网址。

安装测试部署时，此字段为可选字段；但创建版本化部署时，此字段为必填字段。

当脚本或插件执行以下操作时，您需要使用许可名单：

使用 Apps 脚本 UrlFetch 服务从外部位置（例如 HTTPS 端点）检索或提取信息。如需将网址列入允许名单以进行提取，请在清单文件中添加 urlFetchWhitelist 字段。
打开或显示网址以响应用户操作（对于打开或显示 Google 外部网址的 Google Workspace 加载项，此属性为必需属性）。如需将网址列入允许打开的网址名单，请在清单文件中添加 addOns.common.openLinkUrlPrefixes 字段。

向许可名单添加前缀

在清单文件中指定许可名单时（通过添加 addOns.common.openLinkUrlPrefixes 或 urlFetchWhitelist 字段），您必须添加网址前缀列表。您添加到清单中的前缀必须满足以下要求：

每个前缀都必须是有效的网址。
每个前缀都必须使用 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

使用通配符

您可以使用单个通配符 (*) 来匹配 urlFetchWhitelist 和 addOns.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 （通配符必须用作前导前缀）

Google Workspace 插件的清单 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。