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

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

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

目標

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

必要條件

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

設定環境

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

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

設定 OAuth 同意畫面

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

在 Google Cloud 控制台中，依序前往「Menu」(選單) >「」>「Branding」(品牌化)。
前往「品牌」
如果您已設定，可以在「品牌」、「目標對象」和「資料存取」中設定下列 OAuth 同意畫面設定。如果畫面上顯示「尚未設定」，請按一下「開始使用」：

在「應用程式資訊」下方的「應用程式名稱」中，輸入應用程式名稱。
在「使用者支援電子郵件」中，選擇使用者有同意聲明相關問題時可與您聯絡的支援電子郵件地址。
點選 [下一步]。
在「目標對象」下方，選取「內部」。
點選 [下一步]。
在「聯絡資訊」下方，輸入電子郵件地址，以便在專案有任何異動時通知您。
點選 [下一步]。
在「Finish」下方，詳閱「Google API 服務使用者資料政策」，如果同意，請選取「I agree to the Google API Services: User Data Policy」。
按一下 [繼續]。
按一下「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 視窗的工具列中，按一下「Open Editor」，啟動 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

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

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