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 设置：

Chat 应用在 Chat 界面中的名称、徽标和说明。
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 撰写操作和上下文触发器。
- 一个 Google 文档 linkPreviewTriggers 对象。请参阅包含智能条状标签的预览链接。
- 一个 Google 文档 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 （通配符必须用作前导前缀）