使用 Node.js 构建 Google Workspace 插件

使用 Node.js 运行时在 Cloud Run 函数中创建 Google Workspace 插件。

目标

设置环境。
创建和部署 Cloud Run 函数。
创建和部署插件。
安装插件。

前提条件

Google Cloud 项目。
为您的云项目启用结算功能。了解如何验证项目的结算状态。
Cloud SDK 已配置云项目。

设置环境

在 Google Cloud 控制台中打开您的云项目

在 Google Cloud 控制台中，前往选择项目 页面。
选择 Cloud 项目
选择您要使用的 Google Cloud 项目。或者，点击创建项目 ，然后按照屏幕上的说明操作。如果您创建了 Google Cloud 项目，可能需要为该项目启用结算功能。

配置 OAuth 权限请求页面

Google Workspace 插件需要配置权限请求页面。配置插件的 OAuth 权限请求页面可定义 Google 向用户显示的内容。

在 Google API 控制台中，依次前往“菜单”图标 > Google Auth 平台 > 品牌宣传。
前往“品牌宣传”
如果您已配置 Google Auth 平台，则可以在“品牌宣传”、“受众群体”和“数据访问权限”中配置以下 OAuth 权限请求页面设置。如果您看到一条消息，指出尚未配置 Google Auth 平台，请点击开始使用：

在应用信息 下的应用名称 中，输入应用的名称。
在用户支持邮箱中，选择一个支持邮箱地址，以便用户在对自己的同意情况有疑问时与您联系。
点击下一步 。
在受众群体 下，选择内部。
点击下一步 。
在联系信息 下，输入一个电子邮件地址 ，以便您接收有关项目变更的通知。
点击下一步 。
在完成部分，查看《Google API 服务用户数据政策》，如果您同意该政策，请选择我同意 Google API 服务：用户数据政策。
点击继续。
点击创建。

目前，您可以跳过添加权限范围的步骤。将来，当您创建的应用要在 Google Workspace 组织外部使用时，必须将 用户类型 更改为外部。然后，添加应用所需的授权权限范围。如需了解详情，请参阅完整的配置 OAuth 权限请求页面指南。

创建和部署 Cloud Run 函数

点击授权以预配并连接到 Cloud Shell。

在 Cloud Shell 终端中，启用 Cloud Run functions API、Cloud Build API、Google Workspace 插件 API、Compute Engine API 和 Cloud Run API：

gcloud services enable cloudfunctions.googleapis.com  \
                    cloudbuild.googleapis.com  \
                    gsuiteaddons.googleapis.com  \
                    compute.googleapis.com  \
                    run.googleapis.com

通过点击 Cloud Shell 窗口工具栏上的 打开编辑器 ，启动 Cloud Shell Editor。

此内置代码编辑器提供了在构建和部署项目的相同环境中查看和修改文件的便利。

在空目录中，使用以下示例代码创建文件 function.js：

/**
 * Cloud Run function that loads the homepage for a
 * Google Workspace add-on.
 *
 * @param {Object} req Request sent from Google
 * @param {Object} res Response to send back
 */
exports.loadHomePage = function addonsHomePage (req, res) {
  res.send(createAction());
};

/** Creates a card with two widgets. */
function createAction() {
  return {
    "action": {
      "navigations": [
        {
          "pushCard": {
            "header": {
              "title": "Cats!"
            },
            "sections": [
              {
                "widgets": [
                  {
                    "textParagraph": {
                      "text": "Your random cat:"
                    }
                  },
                  {
                    "image": {
                      "imageUrl": "https://cataas.com/cat"
                     }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  };
}

在同一目录中，使用以下示例代码创建文件 package.json：

{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

点击 打开终端，返回 Cloud Shell 终端。

将 Cloud Build Service Account 角色 (roles/cloudbuild.builds.builder) 添加到 Compute Engine 默认服务账号。

首先，设置服务账号权限：

export PROJECT_ID=$(gcloud config get project)
export SERVICE_ACCOUNT_NAME=$(gcloud compute project-info describe \
  --format="value(defaultServiceAccount)")

接下来，授予缺少的服务账号权限：

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/cloudbuild.builds.builder"

运行以下命令以部署函数：
```
gcloud run deploy loadHomePage --runtime nodejs22 --trigger-http
```
如果出现提示，请指定您不允许在未经身份验证的情况下调用该函数。函数可能需要几分钟才能部署完毕。

创建插件部署

查找插件的服务账号电子邮件地址：
```
gcloud workspace-add-ons get-authorization
```

向服务账号授予 cloudfunctions.invoker 角色。将 SERVICE_ACCOUNT_EMAIL 替换为上一步中的 serviceAccountEmail 字段。

gcloud run services add-iam-policy-binding loadHomePage \
    --role roles/roles/run.invoker \
    --member serviceAccount:SERVICE_ACCOUNT_EMAIL

获取已部署函数的网址。如需获取该网址，请运行以下命令，然后在 httpsTrigger 部分下查找 url 字段：
```
gcloud run services describe loadHomePage
```
点击 打开编辑器 ，返回 Cloud Shell Editor。

在与 package.json 相同的目录中，使用以下示例代码创建文件 deployment.json。将 URL 替换为上一步中已部署函数的 url 。

{
  "oauthScopes": ["https://www.googleapis.com/auth/gmail.addons.execute"],
  "addOns": {
    "common": {
      "name": "My HTTP Add-on",
      "logoUrl": "https://raw.githubusercontent.com/webdog/octicons-png/main/black/beaker.png",
      "homepageTrigger": {
        "runFunction": "URL"
      }
    },
    "gmail": {},
    "drive": {},
    "calendar": {},
    "docs": {},
    "sheets": {},
    "slides": {},
    "httpOptions": {
      "granularOauthPermissionSupport": "OPT_IN"
    }
  }
}

返回 Cloud Shell 终端以创建部署：

gcloud workspace-add-ons deployments create quickstart \
    --deployment-file=deployment.json

安装插件

在开发模式下安装部署：

gcloud workspace-add-ons deployments install quickstart

打开或重新加载 Gmail 以查看插件。在右侧的工具栏中，查找烧杯图标。
点击该图标以打开插件。如果出现提示，请为插件授权。

可选：清理

为避免产生费用，请删除您创建的资源：

从您的 Google 账号中卸载插件：

gcloud workspace-add-ons deployments uninstall quickstart

为避免因本快速入门中使用的资源而产生费用，请删除云项目：
```
gcloud projects delete PROJECT_ID
```
将 PROJECT_ID 替换为您用于快速入门的 Cloud 项目的 ID。您可以在 Google API 控制台的信息中心页面上找到云项目 ID。

如需为您的 Google Workspace 插件添加更多功能，请参阅以下内容：

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

目标