本指南說明如何設定服務帳戶,並代表 Chat 應用程式使用 Google Chat API。首先,本指南會逐步引導您建立服務帳戶。接著示範如何編寫使用服務帳戶向 Chat API 進行驗證的指令碼,並在 Chat 聊天室中張貼訊息。
即時通訊應用程式可在非同步呼叫 Google Chat API 時,使用服務帳戶進行驗證,以便:
- 透過
spaces.messages.create
傳送訊息至 Google Chat,以便:- 長時間執行背景工作完成時,通知使用者。
- 提醒使用者伺服器離線。
- 詢問客服人員通常對於新的客戶案件。
- 使用
spaces.messages.update
將先前傳送的訊息更新為:- 變更執行中作業的狀態。
- 更新工作的指派對像或到期日。
- 使用
spaces.members.list
列出聊天室中的使用者,即可執行以下操作:- 查看聊天室成員。
- 驗證聊天室成員包含所有團隊成員。
使用服務帳戶進行驗證時,如要取得 Chat 聊天室中相關資料或執行動作的資料,即時通訊應用程式必須具備聊天室成員資格。舉例來說,如要列出聊天室成員,或在聊天室中建立訊息,Chat 應用程式必須是聊天室的成員。
如果您的 Chat 應用程式需要存取使用者資料或對使用者執行動作,請改為以使用者的身分進行驗證。
如果您是網域管理員,可以授予全網域授權委派,授權應用程式服務帳戶存取使用者資料,而不需要每位使用者取得同意。設定全網域委派功能後,您可以使用服務帳戶進行 API 呼叫,以模擬使用者帳戶。雖然服務帳戶是用於驗證,但全網域委派會冒用使用者,因此會視為使用者驗證。任何需要使用者驗證的功能都可以使用全網域委派。
如要進一步瞭解 Chat 擴充應用程式何時需要進行驗證,以及使用何種驗證機制,請參閱 Chat API 驗證與授權總覽中的「必要驗證類型」。
先備知識
如要執行本指南中的範例,您必須具備下列先決條件:
- 可存取 Google Chat 的 Google Workspace 帳戶。
- 已啟用 Chat API 的 Google Cloud 專案。如要建立專案並啟用 API,請參閱「建立專案並啟用 API」一文。
- 具備成員資格的已發布 Chat 應用程式:
- 如要建立並發布即時通訊應用程式,請參閱使用 Cloud Functions 建構 Google Chat 應用程式。
- 如要將 Chat 應用程式新增至 Chat 聊天室,請參閱「將應用程式加入 Google Chat 聊天室或對話」一文。
此外,您還需要下列特定語言的必備條件:
Java
Python
- Python 3.6 以上版本
- pip 套件管理工具
Node.js
Apps Script
- 連結至您 Google Cloud 專案的 Apps Script 專案。如要初始化 Apps Script 專案,請參閱 Google Apps Script Chat 應用程式快速入門導覽課程。
步驟 1:在 Google Cloud 控制台中建立服務帳戶
建立服務帳戶,讓 Chat 應用程式可用來存取 Google API。
建立服務帳戶
如要建立服務帳戶,請按照下列步驟操作:
Google Cloud 控制台
- 在 Google Cloud 控制台中,依序點選「選單」圖示 >「IAM 與管理」>>「服務帳戶」。
- 點選「建立服務帳戶」。
- 填寫服務帳戶詳細資料,然後按一下「建立並繼續」。 注意:根據預設,Google 會建立不重複的服務帳戶 ID。
- 選用:為服務帳戶指派角色,授予 Google Cloud 專案資源的存取權。詳情請參閱「授予、變更及撤銷資源的存取權」。
- 點選「繼續」。
- 選用:輸入可以透過這個服務帳戶管理及執行動作的使用者或群組。詳情請參閱「管理服務帳戶模擬功能」。
- 按一下 [完成]。記下服務帳戶的電子郵件地址。
gcloud CLI
- 建立服務帳戶:
gcloud iam service-accounts create
SERVICE_ACCOUNT_NAME
\ --display-name="SERVICE_ACCOUNT_NAME
" - 選用:為服務帳戶指派角色,授予 Google Cloud 專案資源的存取權。詳情請參閱「授予、變更及撤銷資源的存取權」。
服務帳戶會顯示在「服務帳戶」頁面中。接下來,為服務帳戶建立私密金鑰
建立私密金鑰
如要建立並下載服務帳戶的私密金鑰,請按照下列步驟操作:
- 在 Google Cloud 控制台中,依序點選「選單」圖示 >「IAM 與管理」>>「服務帳戶」。
- 選取服務帳戶。
- 依序按一下「金鑰」>「新增金鑰」>「建立新的金鑰」。
- 選取「JSON」,然後按一下「建立」。
系統會產生新的公開/私密金鑰組,並以新檔案的形式下載到您的電腦。將下載的 JSON 檔案儲存為
credentials.json
在您的工作目錄中。這個檔案是這組金鑰的唯一副本。如要瞭解如何安全儲存金鑰,請參閱管理服務帳戶金鑰。 - 點選「關閉」。
如要進一步瞭解服務帳戶,請參閱 Google Cloud IAM 說明文件中的服務帳戶。
步驟 2:安裝 Google 用戶端程式庫和其他依附元件
安裝 Google 用戶端程式庫和專案需要的其他依附元件。
Java
如要將 Google 用戶端程式庫和其他必要的依附元件新增至 Maven 專案,請編輯專案目錄中的 pom.xml
檔案,並新增下列依附元件:
<dependencies>
<!-- ... existing dependencies ... -->
<dependency>
<groupId>com.google.apis</groupId>
<artifactId>google-api-services-chat</artifactId>
<version>v1-rev20230905-2.0.0</version>
</dependency>
<dependency>
<groupId>com.google.auth</groupId>
<artifactId>google-auth-library-oauth2-http</artifactId>
<version>1.19.0</version>
</dependency>
<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.10.1</version>
</dependency>
</dependencies>
Python
如果您尚未安裝 Python 適用的 Google 用戶端程式庫,請在指令列介面中執行下列指令:
pip3 install --upgrade google-api-python-client google-auth
Node.js
如要將 Google 用戶端程式庫新增到 Node.js 專案,請切換至專案目錄,然後在指令列介面中執行下列指令:
npm install "@googleapis/chat"
Apps Script
這個範例使用 Apps Script 的 OAuth2 程式庫產生服務帳戶驗證所需的 JWT 憑證。如要將程式庫加入 Apps Script 專案,請按照下列指示操作:
- 按一下左側的「編輯器」圖示 。
- 在左側的「程式庫」旁邊,按一下「新增程式庫」 。
- 輸入指令碼 ID
1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF
。 - 依序按一下「查詢」和「新增」。
這個範例使用進階 Chat 服務來呼叫 Google Chat API。如要為 Apps Script 專案開啟服務,請按照下列步驟操作:
- 按一下左側的「編輯器」圖示 。
- 在左側的「Service」(服務) 旁邊,按一下「Add a service」(新增服務) 。
- 選取「Google Chat API」。
- 在「版本」中選取「v1」。
- 按一下「新增」。
您可以使用用戶端程式庫支援的任何語言。
步驟 3:編寫使用服務帳戶驗證 Chat API 的指令碼
下列程式碼會使用服務帳戶使用 Chat API 進行驗證,然後將訊息張貼至 Chat 聊天室:
Java
- 在專案的目錄中開啟
src/main/java/com/google/chat/app/authsample/App.java
檔案。 將
App.java
中的內容替換為下列程式碼:package com.google.chat.app.authsample; import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport; import com.google.api.client.http.HttpRequestInitializer; import com.google.api.client.json.gson.GsonFactory; import com.google.api.services.chat.v1.HangoutsChat; import com.google.api.services.chat.v1.model.Message; import com.google.auth.http.HttpCredentialsAdapter; import com.google.auth.oauth2.GoogleCredentials; /** * Authenticates with Chat API via service account credentials, * then creates a Chat message. */ public class App { // Specify required scopes. private static final String CHAT_SCOPE = "https://www.googleapis.com/auth/chat.bot"; // Specify service account details. private static final String PRIVATE_KEY_RESOURCE_URI = "/credentials.json"; public static void main( String[] args ) { try { // Run app. Message response = App.createChatMessage(); // Print details about the created message. System.out.println(response); } catch (Exception e) { e.printStackTrace(); } } private static Message createChatMessage() throws Exception { // Build the Chat API client and authenticate with the service account. GoogleCredentials credentials = GoogleCredentials.fromStream( App.class.getResourceAsStream(PRIVATE_KEY_RESOURCE_URI)) .createScoped(CHAT_SCOPE); HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials); HangoutsChat chatService = new HangoutsChat.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), requestInitializer) .setApplicationName("auth-sample-app") .build(); // The space to create the message in. // // Replace SPACE_NAME with a space name. // Obtain the space name from the spaces resource of Chat API, // or from a space's URL. String spaceName = "spaces/SPACE_NAME"; // Create a Chat message. Message message = new Message().setText("Hello, world!"); return chatService.spaces().messages().create(spaceName, message).execute(); } }
在程式碼中,將
SPACE_NAME
替換為聊天室名稱,您可以從 Chat API 的spaces.list
方法或聊天室網址取得。在專案的目錄中建立名為
resources
的新子目錄。確認服務帳戶的私密金鑰檔案名為
credentials.json
,並將其複製到resources
子目錄。若要設定 Maven 以在專案套件中加入私密金鑰檔案,請編輯專案目錄中的
pom.xml
檔案,並將下列設定新增至<build>
區段:<build> <!-- ... existing configurations ... --> <resources> <resource> <directory>resources</directory> </resource> </resources> </build>
如要設定 Maven 以在專案套件中加入依附元件,並執行應用程式的主要類別,請編輯專案目錄中的
pom.xml
檔案,並將下列設定新增至<plugins>
區段:<plugins> <!-- ... existing configurations ... --> <plugin> <artifactId>maven-assembly-plugin</artifactId> <configuration> <archive> <manifest> <mainClass>com.google.chat.app.authsample.App</mainClass> </manifest> </archive> <descriptorRefs> <descriptorRef>jar-with-dependencies</descriptorRef> </descriptorRefs> </configuration> </plugin> </plugins>
Python
- 在工作目錄中,建立名為
chat_app_auth.py
的檔案。 在
chat_app_auth.py
中加入下列程式碼:from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE_NAME with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE_NAME', # The message to create. body={'text': 'Hello, world!'} ).execute() # Prints details about the created message. print(result)
在程式碼中,將
SPACE_NAME
替換為聊天室名稱,您可以從 Chat API 的spaces.list
方法或聊天室網址取得。確認服務帳戶的私密金鑰檔案名為credentials.json
。
Node.js
- 在專案的目錄中,建立名為
chat_app_auth.js
的檔案。 在
chat_app_auth.js
中加入下列程式碼:const chat = require('@googleapis/chat'); async function createMessage() { const auth = new chat.auth.GoogleAuth({ // Specify service account details. keyFilename: 'credentials.json', // Specify required scopes. scopes: ['https://www.googleapis.com/auth/chat.bot'] }); const authClient = await auth.getClient(); // Create the Chat API client and authenticate with the service account. const chatClient = await chat.chat({ version: 'v1', auth: authClient }); // Create a Chat message. const result = await chatClient.spaces.messages.create({ // The space to create the message in. // // Replace SPACE_NAME with a space name. // Obtain the space name from the spaces resource of Chat API, // or from a space's URL. parent: 'spaces/SPACE_NAME', // The message to create. requestBody: { 'text': 'Hello, world!' } }); return result; } // Execute function then print details about the created message. createMessage().then(console.log);
在程式碼中,將
SPACE_NAME
替換為聊天室名稱,您可以從 Chat API 的spaces.list
方法或聊天室網址取得。確認服務帳戶的私密金鑰檔案名為credentials.json
。
Apps Script
在 Apps Script 編輯器中,編輯
appsscript.json
檔案並新增發出外部要求所需的 OAuth 範圍,以取得服務帳戶 OAuth 權杖:"oauthScopes": [ "https://www.googleapis.com/auth/script.external_request" ]
將下列程式碼儲存在 Apps Script 專案中名為
ChatAppAuth.gs
的檔案:// Specify the contents of the file credentials.json. const CREDENTIALS = CREDENTIALS; const SCOPE = 'https://www.googleapis.com/auth/chat.bot'; // The space to create the message in. // // Replace SPACE_NAME with a space name. // Obtain the space name from the spaces resource of Chat API, // or from a space's URL. const PARENT = 'spaces/SPACE_NAME' /** * Authenticates with Chat API via app credentials, then posts a message. */ function createMessageWithAppCredentials() { try { const service = getService_(); if (!service.hasAccess()) { console.error(service.getLastError()); return; } // Specify the message to create. const message = {'text': 'Hello world!'}; // Call Chat API with a service account to create a message. const result = Chat.Spaces.Messages.create( message, PARENT, {}, // Authenticate with the service account token. {'Authorization': 'Bearer ' + service.getAccessToken()}); // Log details about the created message. console.log(result); } catch (err) { // TODO (developer) - Handle exception. console.log('Failed to create message with error %s', err.message); } } /** * Configures the OAuth library to authenticate with the service account. */ function getService_() { return OAuth2.createService(CREDENTIALS.client_email) .setTokenUrl('https://oauth2.googleapis.com/token') .setPrivateKey(CREDENTIALS.private_key) .setIssuer(CREDENTIALS.client_email) .setSubject(CREDENTIALS.client_email) .setScope(SCOPE) .setPropertyStore(PropertiesService.getScriptProperties()); }
在程式碼中,將
CREDENTIALS
替換為credentials.json
檔案的內容。在程式碼中,將
SPACE_NAME
替換為聊天室名稱,您可以從 Chat API 的spaces.list
方法或聊天室網址取得。
步驟 4:執行完整範例
在工作目錄中建構並執行範例:
Java
mvn compile assembly:single
java -jar target/auth-sample-app-1.0-SNAPSHOT-jar-with-dependencies.jar
Python
python3 chat_app_auth.py
Node.js
node chat_app_auth.js
Apps Script
在 Apps Script 編輯器中開啟 ChatAppAuth.gs
檔案,然後按一下「Run」。
指令碼會向 Chat API 發出已驗證的要求,這個 API 會以 Chat 應用程式的形式在 Chat 聊天室中發布訊息做為回應。
排解範例問題
本節說明嘗試執行這個範例時可能會遇到的常見問題。
您無法使用這個應用程式
執行指令碼時,您可能會收到以下錯誤訊息:
<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}/messages?alt=json returned "You are not permitted to use this app". Details: "You are not permitted to use this app">
這則錯誤訊息表示 Chat 應用程式的權限不足,無法在指定 Chat 聊天室中建立 Chat 訊息。
如要解決這個錯誤,請將 Chat 應用程式新增至指令碼中指定的 Chat 聊天室。
相關主題
如要瞭解 Chat API 還可以執行哪些操作,請參閱 Chat API 的參考說明文件。