此页面由 Cloud Translation API 翻译。

Google Workspace 插件的清单

插件使用清单文件配置与应用及其操作有关的某些详细信息。

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

Google Workspace 插件的清单结构

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

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

如需了解 Apps Script 清单文件，请参阅清单结构。
如需了解使用 HTTP 端点构建的插件对应的清单文件，请参阅 REST 资源：projects.deployments

Google Chat 的清单

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

Chat 会忽略常见的清单配置设置（包括 addons.common）。您可以使用 Chat API 配置以下 Chat 设置，而不是使用插件清单：

Chat 应用的名称、徽标和说明，仅显示在 Chat 界面中。
Chat 应用触发器。

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

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

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

Google Workspace 插件清单配置示例

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

清单的 addOns.common 部分用于定义插件的名称、徽标网址、颜色以及其他与主机无关的常规设置。
该清单定义了通用首页，但也定义了 Google 日历、云端硬盘、文档、表格和幻灯片专用首页。Gmail 使用默认首页。
示例清单设置可启用以下功能：
- 日历 eventOpen 和 eventUpdated 触发器。
- （仅限 Apps 脚本）两个 Google 日历会议解决方案。
- 两个通用操作。
- 云端硬盘 onItemsSelectedTrigger。
- Gmail 撰写操作和上下文触发器。
- Google 文档 linkPreviewTriggers 对象。如需了解此触发器，请参阅包含智能条状标签的预览链接。
- Google 文档 createActionTriggers 对象。如需了解此触发器，请参阅通过“@”菜单创建第三方资源。
- 适用于文档、表格和幻灯片的文件专用界面。
oauthScopes 字段用于为项目设置授权范围（通常对插件而言是必需的）。
（仅限 Apps Script）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"
      }
    }
  },
  "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"
      }
    }
  },
  "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 Script 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（通配符必须用作前置前缀）