設定 Google Chat API

您建立的每個 Google Chat 應用程式，都需要有專屬的 Google Cloud 專案，並啟用及設定 Chat API。

如要透過使用者驗證執行唯讀 API 呼叫 (例如取得聊天室和列出訊息)，只需啟用 API 並建立 OAuth 用戶端。

如要執行建立、更新和刪除 API 呼叫，或部署及測試互動式 Chat 擴充應用程式 (建構為擴充 Chat 的 Google Workspace 外掛程式)，也必須設定 Chat API。您可以在 Chat API 設定中，指定 Chat 擴充應用程式的所有詳細資料，包括顯示名稱、顯示圖片、部署端點和互動功能。

必要條件

• Business 或 Enterprise Google Workspace 帳戶，且可存取 Google Chat。
• 建立 Google Cloud 專案。
• 設定 OAuth 同意畫面。
• 啟用 Google Chat API。

為 Chat 擴充應用程式選擇顯示名稱、顯示圖片和說明

啟用 Chat API 時，您需要設定 Chat 應用程式的詳細資料，這些資料會顯示在 Chat 中，包括顯示名稱、顯示圖片和說明。這些詳細資料只會顯示在 Chat 中。如要將 Chat 擴充應用程式發布至 Marketplace，您也必須指定 Chat 擴充應用程式在 Marketplace 商店資訊中顯示的詳細資料。

設定 Chat 擴充應用程式前，請先準備下列資訊：

Chat 擴充應用程式的名稱、顯示圖片和說明會顯示在 Chat 使用者介面中。對於某些 Chat API 寫入要求，Chat 會使用這項資訊，將 Chat 擴充應用程式在 Chat 中執行的動作歸因於該應用程式。

舉例來說，如果您呼叫 spaces.create() 方法，Chat 會在聊天室建立者的說明中，加入 Chat 擴充應用程式的名稱，如下圖所示：

使用者也會透過下列方式查看或使用這項資訊，與 Chat 擴充應用程式互動：

• 使用 @ 號提及 Chat 擴充應用程式，即可將其加入聊天室或傳送訊息。
• 在「應用程式」選單中，找到 Chat 擴充應用程式並發起即時訊息，即時訊息會顯示 Chat 擴充應用程式的名稱和顯示圖片。
• 使用者可以透過撰寫列瀏覽 Chat 擴充應用程式，並查看其名稱、顯示圖片和說明。

在 Google Cloud 控制台中設定 Chat 應用程式

取得 Chat 應用程式詳細資料後，請開啟雲端專案並設定 Chat API：

1. 在 Google Cloud 控制台中，前往 Chat API 頁面，然後按一下「Configuration」(設定) 頁面：

   前往 Chat API 設定頁面

2. 在「Application info」(應用程式資訊) 下方，填寫「App name」(應用程式名稱)、「Avatar URL」(顯示圖片網址) 和「Description」(說明) 欄位。

3. 選用：從「Markup syntax」(標記語法) 選單中，選取 Chat 應用程式訊息的預設標記語法 (「Markdown」或「Chat」)。如要進一步瞭解文字格式，以及 Chat 如何判斷 API 要求的標記語法，請參閱「設定訊息格式」。

4. 在「互動功能」下方，設定 Chat 應用程式是否要回應使用者互動：

   如要建構互動式 Chat 應用程式，請開啟「Enable interactive features」(啟用互動功能)，並完成下列步驟：

   1. 在「Functionality」下方：
      • 選用：選取「支援應用程式首頁」，在與 Chat 應用程式的個人即時訊息中，於「首頁」分頁顯示首頁資訊卡。
      • 選取「加入聊天室和群組對話」，即可安裝及使用 Chat 擴充應用程式。根據預設，使用者可以在與 Chat 擴充應用程式的專屬聊天室中，安裝 Chat 擴充應用程式並傳送訊息。使用者也可以在多人聊天室中，新增 Chat 擴充應用程式並與其互動。

   2. 在「Connection settings」(連線設定) 下方，選取要用於接收 Chat 事件物件的架構：

      • 如要使用 HTTP 服務，請選取「HTTP endpoint URL」(HTTP 端點網址)，並提供網址。
      • 如要使用 Google Apps Script 專案，請選取「Apps Script」，並提供專案的部署作業 ID。
      • 如要使用 Dialogflow 代理，請依序選取「Dialogflow」和「Dialogflow CX」或「Dialogflow ES」，然後提供代理的資源名稱。
      • 如要使用 Pub/Sub，請選取「Cloud Pub/Sub」並輸入主題名稱。

   3. 選用：如要將事件物件轉送至特定端點或函式，請前往「Connection settings」>「Triggers」，然後提供或更新下列 Chat 觸發條件的回呼端點或函式：

      • 應用程式首頁 (如果已啟用「支援應用程式首頁」)：使用者在與 Chat 應用程式的個人即時訊息中，開啟「首頁」分頁。
      • 已新增至聊天室：使用者將 Chat 擴充應用程式新增至群組對話或聊天室，或安裝 Chat 擴充應用程式來傳送 1:1 訊息。
      • Message：使用者傳送訊息給 Chat 應用程式。例如，使用者傳送即時訊息給 Chat 應用程式，或在有多位成員的聊天室中 @提及 Chat 應用程式。
      • Removed from space：使用者從聊天室解除安裝或移除 Chat 應用程式。
      • 應用程式指令：使用者從 Chat 應用程式叫用快速指令、斜線指令或訊息動作。

   4. 選用：新增其他互動功能，例如啟動提示詞、指令 (快速指令、斜線指令和訊息動作) 或連結預覽。

   5. 在「Visibility」(顯示設定) 下方指定電子郵件地址，以便在發布至 Google Workspace Marketplace 前，安裝及測試 Chat 擴充應用程式。您最多可以指定五位使用者，或一或多個 Google Workspace 機構中的 Google 群組。

5. 選用：在「Logs」(記錄) 下方，勾選「Log errors to Logging」(將錯誤記錄到 Logging) 核取方塊，即可使用 Google Cloud Logging。詳情請參閱「查詢 Chat 擴充應用程式的錯誤記錄」。

6. 按一下 [儲存]。

儲存設定後，您在 Chat API 的「Visibility」(顯示設定) 中指定的任何人，都可以安裝、測試或使用 Chat 應用程式。如要開始測試及偵錯 Chat 應用程式，請參閱「測試 Google Chat 應用程式的互動功能」。

使用 Google Workspace Add-ons API 設定 Chat 擴充應用程式

您不必在 Google Cloud 控制台中手動設定 Chat 應用程式，而是可以使用已註冊 Google Workspace 開發人員預覽版計畫的 Google Cloud 雲端專案，透過 Google Workspace add-ons API 中的 chatAppConfig 資源，以程式輔助方式讀取及更新 Google Workspace 外掛程式建構的 Chat 應用程式設定。

chatAppConfig 是單例資源，一律存在於每個雲端專案中。首次儲存設定前，資源會包含空白設定 (如果您在首次儲存前讀取資源，GetChatAppConfig 也會傳回空白設定)。由於資源已存在，您不需要另外建立，只要使用 UpdateChatAppConfig 即可儲存初始設定及更新現有設定。

先決條件和驗證

呼叫 GetChatAppConfig 或 UpdateChatAppConfig 前，請先完成下列必要條件：

1. 將 Google Cloud 雲端專案註冊加入 Google Workspace 開發人員預覽版計畫。
2. 在雲端專案中啟用 Google Workspace 外掛程式 API (gsuiteaddons.googleapis.com)。如要在 Google Cloud 控制台中查看或更新 Chat 擴充應用程式設定，或呼叫 Chat API，可以選擇啟用 Google Chat API (chat.googleapis.com)。
3. 以真人使用者身分進行驗證，並使用包含 https://www.googleapis.com/auth/cloud-platform 範圍的 OAuth 2.0 憑證。chatAppConfig 方法不支援服務帳戶驗證。
4. 確認已驗證的使用者具備目標雲端專案的必要 Identity and Access Management (IAM) 權限：
   • gsuiteaddons.chatAppConfigs.get 和 chat.bots.get 讀取設定 (GetChatAppConfig)。
   • gsuiteaddons.chatAppConfigs.update 和 chat.bots.update，更新設定 (UpdateChatAppConfig)。
5. 如果您使用用戶端程式庫，請以註冊的開發人員預覽版帳戶下載開發人員預覽版用戶端程式庫。

更新 Chat 擴充應用程式設定

如要首次設定 Chat 擴充應用程式，或更新現有設定，請將 PATCH 要求 (UpdateChatAppConfig) 傳送至雲端專案的單例 chatAppConfig 資源：

• 首次儲存 chatAppConfig 為空的雲端專案時，必須提供 displayName (3 到 25 個字元) 和 description (1 到 40 個字元)。如果在初次儲存時省略 interactiveFeatureConfig，Chat 應用程式會設為非互動式。
• 後續更新時，請使用選用的 updateMask 查詢參數，指定要更新的欄位 (以半形逗號分隔)，或省略 updateMask 來更新所有提供的欄位。更新重複欄位 (appCommands、urlPatterns 或 allowlistedTestingPrincipals) 會取代整個清單。

PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

在要求網址、標頭和主體中，替換下列內容：

• PROJECT_NUMBER：託管 Chat 應用程式的 Cloud 專案數字編號。
• ACCESS_TOKEN：以 https://www.googleapis.com/auth/cloud-platform 範圍授權的使用者 OAuth 2.0 存取權杖。
• USER_EMAIL：Google Workspace 組織中的電子郵件地址或 Google 群組，用於加入許可清單，以便測試 Chat 應用程式 (例如您自己的電子郵件地址)。
• 要求主體中的範例設定欄位 (例如 displayName、description、avatarUri 和 interactiveFeatureConfig，包括端點設定、指令、連結預覽網址模式和測試主體)，以及 Chat 應用程式的值。如要進一步瞭解所有支援的欄位和端點選項，請參閱 projects.chatAppConfig REST 參考資料和 projects.chatAppConfig.patch。

取得 Chat 擴充應用程式設定

如要讀取 Cloud 專案目前的 Chat 擴充應用程式設定，請呼叫 GetChatAppConfig。您可以傳遞選用的 view 查詢參數 (ChatAppConfigView)：

• BASIC (預設)：傳回基本中繼資料，不含 interactiveFeatureConfig。
• FULL：傳回所有設定欄位，包括 interactiveFeatureConfig。

如果雲端專案尚未儲存 Chat 擴充應用程式設定，這個方法會傳回空白的 ChatAppConfig 物件。

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

現有 Google Workspace 外掛程式的注意事項

Chat 擴充應用程式的設定，與擴充其他 Google Workspace 應用程式的 Google Workspace 外掛程式不同。如果外掛程式會擴充其他 Google Workspace 應用程式，請考量下列 Chat 應用程式設定規定：

• 個人和 Google Workspace 管理員都必須能從 Marketplace 安裝您的外掛程式。您可以在 Marketplace SDK 中設定這些安裝設定。
• Chat 擴充應用程式不會使用您在資訊清單的 addons.common 物件中，為其他 Google Workspace 應用程式設定的名稱和標誌。
• 如果外掛程式已發布至 Google Workspace Marketplace，您無法儲存 Google Chat API 設定變更的草稿。更新並儲存 Chat API 設定後，所有現有使用者都能立即使用更新後的 Chat 擴充應用程式。如要更新 Marketplace 產品資訊，您可以先建立草稿，再提交任何變更。
• 如果您使用 Apps Script 建構外掛程式：
  • 您必須使用與其他外掛程式設定相同的 Apps Script 部署 ID。
  • 您無法使用 Apps Script 編輯器在 Chat 中安裝測試部署項目。請改為直接從 Chat UI 安裝。
• 如果您使用 HTTP 服務建構外掛程式，請在透過 Google Workspace Add-ons API 建立的 projects.deployments 資訊清單中，省略任何 Chat 擴充應用程式設定詳細資料。您在 Google Workspace Marketplace SDK 中指定的 HTTP 部署項目，僅適用於其他 Google Workspace 應用程式。請改為在 Google Cloud 控制台中設定 Chat 擴充應用程式，或使用 Google Workspace Add-ons API 中的 chatAppConfig 資源。

授予其他使用者設定 Chat API 的權限

您可以授予Chat 應用程式擁有者或 Chat 應用程式檢視者 Google Cloud Identity Access Management (IAM) 角色，將 Chat 應用程式設定頁面的存取權授予特定使用者。具備這些角色的使用者無法透過「APIs & Services」(API 和服務) 資訊主頁前往 Chat 擴充應用程式設定頁面，但可以前往 Chat 擴充應用程式主機雲端專案的 Google Cloud 控制台，存取設定頁面，步驟如下：

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

其中 PROJECT_ID 是託管 Chat 應用程式的 Google Cloud 專案 ID。

相關主題

• 選擇 Chat 擴充應用程式架構
• 接收及回應使用者互動
• 測試 Google Chat 應用程式的互動功能