本頁面由 Cloud Translation API 翻譯而成。

使用 Node.js 建構 Google Workspace 外掛程式

在 Cloud Functions 中使用 Node.js 執行階段建立 Google Workspace 外掛程式。

目標

設定環境。
建立及部署 Cloud 函式。
建立及部署外掛程式。
安裝外掛程式。

必要條件

Google Cloud 專案。
請確認您已為 Cloud 專案啟用計費功能。瞭解如何驗證專案的帳單狀態。
Cloud SDK 已設定 Cloud 專案。

設定環境

在 Google Cloud 控制台中開啟 Cloud 專案

前往 Google Cloud 控制台的「選取專案」頁面。
選取 Cloud 專案
選取要使用的 Google Cloud 專案。或者，按一下「建立專案」，然後按照畫面上的指示操作。建立 Google Cloud 專案後，您可能需要為專案啟用計費功能。

設定 OAuth 同意畫面

Google Workspace 外掛程式需要設定同意畫面。設定外掛程式的 OAuth 同意畫面，可決定 Google 向使用者顯示的內容。

在 Google Cloud 控制台中，依序前往「選單」 > Google Auth platform >「品牌」。
前往「品牌宣傳」
如果您已設定 Google Auth platform，可以在「品牌」、「目標對象」和「資料存取權」中，設定下列 OAuth 同意畫面設定。如果看到「尚未設定」Google Auth platform 訊息，請按一下「開始使用」：

在「App Information」(應用程式資訊) 下方的「App name」(應用程式名稱) 欄位中，輸入應用程式名稱。
在「使用者支援電子郵件」中，選擇支援電子郵件地址，方便使用者在同意聲明方面有任何疑問時與您聯絡。
點選 [下一步]。
在「目標對象」下方，選取「內部」。
點選 [下一步]。
在「聯絡資訊」下方，輸入可接收專案異動通知的電子郵件地址。
點選 [下一步]。
在「完成」部分，請詳閱《Google API 服務使用者資料政策》，然後選取「我同意《Google API 服務：使用者資料政策》」。
按一下 [繼續]。
按一下「Create」(建立)。

目前可以略過新增範圍。日後為 Google Workspace 機構以外的使用者建立應用程式時，請務必將「使用者類型」變更為「外部」。然後新增應用程式需要的授權範圍。詳情請參閱完整的「設定 OAuth 同意畫面」指南。

建立及部署 Cloud 函式

在 Google Cloud 控制台中，按一下「啟用 Cloud Shell」圖示。

啟用 Cloud Shell

Cloud Shell 終端機隨即開啟，並在 Google Cloud 控制台的底部窗格啟動工作階段。
點選「授權」，佈建並連線至 Cloud Shell。

在 Cloud Shell 終端機中，開啟 Cloud Functions API、Cloud Build API、Google Workspace 外掛程式 API 和 Compute Engine API：

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

按一下 Cloud Shell 視窗工具列中的「開啟編輯器」，啟動 Cloud Shell 編輯器。

這個內建程式碼編輯器可讓您在建構及部署專案的相同環境中，輕鬆查看及編輯檔案。

在空白目錄中，建立 function.js 檔案，並加入下列範例程式碼：

/**
 * Cloud 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"
  }
}

按一下「Open Terminal」(開啟終端機) ，返回 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 functions deploy loadHomePage --runtime nodejs22 --trigger-http
```
如果出現提示訊息，請指定不允許未經驗證就叫用函式。部署函式可能需要幾分鐘的時間。

建立外掛程式部署作業

找出外掛程式的服務帳戶電子郵件地址：
```
gcloud workspace-add-ons get-authorization
```

將 cloudfunctions.invoker 角色授予服務帳戶。將 SERVICE_ACCOUNT_EMAIL 替換為上一步的 serviceAccountEmail 欄位。

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

取得已部署函式的網址。如要取得網址，請執行下列指令，並在 httpsTrigger 區段下方尋找 url 欄位：
```
gcloud functions describe loadHomePage
```
按一下「Open Editor」(開啟編輯器) ，返回 Cloud Shell 編輯器。

在 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

如要避免系統向您的 Google Cloud 帳戶收取這個快速入門導覽課程所用資源的費用，請刪除 Cloud 專案：
```
gcloud projects delete PROJECT_ID
```
將 PROJECT_ID 替換為您在快速入門中使用的 Cloud 專案 ID。您可以在 Google Cloud 控制台的「資訊主頁」頁面找到 Cloud 專案 ID。

如要為 Google Workspace 外掛程式新增更多功能，請參閱下列內容：