Google Workspace 插件的清单

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

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

Google Workspace 插件的清单结构

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

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

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

Google Workspace 插件清单配置示例

以下清单文件示例展示了清单文件中定义 一个 Google Workspace 插件，包括以下几个方面：

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

注意 ：urlFetchWhitelist 中使用的白名单是一个已弃用的术语，与许可名单同义并替换为许可名单。如需了解详情，请参阅编写包容性文档。

将前缀添加到许可名单

在清单文件中指定许可名单（通过添加 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 （通配符必须用作前导前缀）