此页面由 Cloud Translation API 翻译。

Google Workspace 插件的清单

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

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

Google Workspace 插件的清单结构

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

Google Workspace 插件的清单属性位于清单对象结构的 addOns 部分下。

如需了解 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 界面中。
聊天应用触发器。

如果您已在 Apps 脚本中构建了插件，还必须在清单中添加或更新以下对象：

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

如需了解如何为插件配置 Chat 设置，请参阅配置 Google Chat 应用。

Google Workspace 插件清单配置示例

以下清单示例展示了清单文件中定义 Google Workspace 加载项的部分，包括以下方面：

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

清单示例中的链接会重定向到 Apps 脚本和 HTTP 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 （通配符必须用作前导前缀）