以 Google Chat 應用程式的身分進行驗證

本指南說明如何設定及使用服務帳戶，代表 Google Chat 應用程式存取 Google Chat API。首先，本指南會逐步說明如何建立服務帳戶。接著，本文會示範如何編寫指令碼，使用服務帳戶向 Chat API 進行驗證，並在 Chat 聊天室中發布訊息。

使用服務帳戶進行驗證時，如要取得 Chat 聊天室的相關資料或執行動作，Chat 應用程式必須是該聊天室的成員。舉例來說，如要列出聊天室成員或在聊天室中建立訊息，Chat 應用程式本身必須是聊天室成員。但如果 Chat 應用程式透過應用程式驗證建立聊天室，應用程式就會建立聊天室，並自動成為成員。

如果 Google Chat API 方法支援應用程式授權，且授權範圍名稱以 https://www.googleapis.com/auth/chat.app.* 開頭，則需要管理員核准一次。如果 Google Chat API 方法支援使用 https://www.googleapis.com/auth/chat.bot 授權範圍進行應用程式授權，則不需要額外核准。https://www.googleapis.com/auth/chat.app.* 授權範圍適用於開發人員預覽版。

如果 Chat 擴充應用程式需要存取使用者資料或代表使用者執行動作，請以使用者身分進行驗證。如果您是網域管理員，可以授予全網域授權委派權限，授權 Chat 應用程式的服務帳戶存取使用者資料，不必逐一取得使用者的同意。詳情請參閱使用全網域委派設定進行驗證及授權。

如要進一步瞭解 Chat 擴充應用程式何時需要驗證，以及應使用哪種驗證方式，請參閱 Chat API 驗證和授權總覽中的「必要驗證類型」。

必要條件

Java

  • JDK 1.7 以上版本
  • Maven 套件管理工具
  • 已初始化的 Maven 專案。如要初始化新專案，請在指令列介面中執行下列指令：
    mvn archetype:generate -DgroupId=com.google.chat.app.authsample -DartifactId=auth-sample-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false
  • 接收並回應互動事件的 Google Chat 應用程式。如要使用 HTTP 服務建立互動式即時通訊應用程式，請完成這份快速入門導覽課程。
  • 將 Chat 應用程式新增至聊天室。如要新增 Chat 應用程式，請參閱「 測試 Google Chat 應用程式的互動功能」。

Python

Node.js

Apps Script

步驟 1：在 Google Cloud 控制台中建立服務帳戶

建立服務帳戶，供 Chat 應用程式存取 Google API。

建立服務帳戶

如要建立服務帳戶，請按照下列步驟操作：

Google Cloud 控制台

  1. 在 Google Cloud 控制台中，依序前往「選單」圖示 >「IAM 與管理」 >「服務帳戶」。

    前往「Service Accounts」(服務帳戶) 頁面

  2. 按一下「建立服務帳戶」。
  3. 填寫服務帳戶詳細資料，然後按一下「建立並繼續」。
  4. 選用步驟：將角色指派給服務帳戶，授予 Google Cloud 專案資源的存取權。詳情請參閱「授予、變更及撤銷資源的存取權」。
  5. 按一下「繼續」。
  6. 選用：輸入可管理這個服務帳戶及執行動作的使用者或群組。詳情請參閱「管理服務帳戶模擬功能」。
  7. 按一下「完成」，記下服務帳戶的電子郵件地址。

gcloud CLI

  1. 建立服務帳戶： 
    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
  --display-name="SERVICE_ACCOUNT_NAME"
  2. 選用步驟：將角色指派給服務帳戶，授予 Google Cloud 專案資源的存取權。詳情請參閱「授予、變更及撤銷資源的存取權」。

服務帳戶會顯示在服務帳戶頁面。接著，請為服務帳戶建立私密金鑰。

建立私密金鑰

如要建立及下載服務帳戶的私密金鑰，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中，依序前往「選單」圖示 >「IAM 與管理」 >「服務帳戶」。

    前往「Service Accounts」(服務帳戶) 頁面

  2. 選取服務帳戶。
  3. 依序點選「金鑰」>「新增金鑰」>「建立新的金鑰」。
  4. 選取「JSON」，然後按一下「建立」。

    接著，系統就會為您產生一對新的公開/私密金鑰，並以新檔案的形式下載至您的電腦中。將下載的 JSON 檔案儲存為工作目錄中的 credentials.json。這個檔案是這組金鑰的唯一副本，如要瞭解如何安全儲存金鑰，請參閱「管理服務帳戶金鑰」。

  5. 點選「關閉」。

如要進一步瞭解服務帳戶，請參閱 Google Cloud IAM 說明文件中的服務帳戶。

接著，為這個服務帳戶建立與 Google Workspace Marketplace 相容的 OAuth 用戶端。

取得管理員核准

如要使用 https://www.googleapis.com/auth/chat.bot 授權範圍， 不必經過管理員核准。請參閱 步驟 2：安裝 Google 用戶端程式庫和其他依附元件。 本指南中的範例使用 https://www.googleapis.com/auth/chat.bot 授權範圍，因此如果您要按照範例操作，請前往步驟 2。

如要使用以 https://www.googleapis.com/auth/chat.app.* 開頭的授權範圍 (這類範圍屬於開發人員預覽版)，您的 Chat 應用程式必須取得一次性管理員核准。

如要取得管理員核准，請準備 Chat 應用程式的服務帳戶，並提供下列資訊：

  • 與 Google Workspace Marketplace 相容的 OAuth 用戶端。
  • Google Workspace Marketplace SDK 中的應用程式設定。

建立與 Google Workspace Marketplace 相容的 OAuth 用戶端

如要建立與 Google Workspace Marketplace 相容的 OAuth 用戶端，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中，依序前往「選單」 >「IAM 與管理」>「服務帳戶」。

    前往「Service Accounts」(服務帳戶)

  2. 按一下為 Chat 應用程式建立的服務帳戶。

  3. 按一下 [進階設定]。

  4. 按一下「建立與 Google Workspace Marketplace 相容的 OAuth 用戶端」。

  5. 按一下「繼續」。

畫面上會顯示確認訊息，指出已建立與 Google Workspace Marketplace 相容的 OAuth 用戶端。

在 Google Workspace Marketplace SDK 中設定 Chat 應用程式

如要在 Google Workspace Marketplace SDK 中設定 Chat 應用程式，請按照下列步驟操作：

  1. 在 Google Cloud 控制台中啟用 Google Workspace Marketplace SDK。

    啟用 Google Workspace Marketplace SDK

  2. 在 Google Cloud 控制台中，依序前往「選單」「API 和服務」「已啟用的 API 和服務」「Google Workspace Marketplace SDK」「應用程式設定」。

    前往「應用程式設定」

  3. 完成「應用程式設定」頁面。Chat 應用程式的設定方式取決於目標對象和其他因素。如需應用程式設定頁面的填寫說明，請參閱「在 Google Workspace Marketplace SDK 中設定應用程式」。在本指南中，請輸入下列資訊：

    1. 在「應用程式顯示設定」下方，選取「私人」。
    2. 在「安裝設定」下方，選取「個別使用者 + 管理員安裝」。
    3. 在「應用程式整合」下方，選取「Chat 擴充應用程式」。

    4. 在「OAuth 範圍」下方，輸入 Chat 應用程式使用的所有驗證範圍。

    5. 在「開發人員資訊」下方，輸入「開發人員名稱」、「開發人員網站網址」和「開發人員電子郵件地址」。

    6. 按一下「儲存草稿」。

取得管理員核准

服務帳戶已設定為接收管理員核准，請按照「設定 Chat 應用程式的授權」一文中的步驟，向可授予核准的 Google Workspace 管理員取得核准。

步驟 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 專案，請按照下列步驟操作：

  1. 按一下左側的「編輯器」圖示 。
  2. 在左側「圖書館」旁邊，按一下「新增圖書館」 。
  3. 輸入指令碼 ID 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF。
  4. 按一下「查詢」，然後按一下「新增」。

本範例使用進階 Chat 服務呼叫 Google Chat API。如要為您的「應用程式指令碼」專案啟用這項服務，請按照下列步驟操作：

  1. 按一下左側的「編輯器」圖示 。
  2. 在左側「服務」旁，按一下「新增服務」圖示 。
  3. 選取「Google Chat API」。
  4. 在「版本」中選取「v1」。
  5. 按一下 [新增]。

您可以使用用戶端程式庫支援的任何語言。

步驟 3：編寫指令碼，使用服務帳戶向 Chat API 進行驗證

下列程式碼會使用服務帳戶向 Chat API 進行驗證，然後將訊息發布至 Chat 聊天室：

Java

  1. 在專案目錄中，開啟 src/main/java/com/google/chat/app/authsample/App.java 檔案。

  2. 將 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 using 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();
    }
}

  3. 在程式碼中，將 SPACE_NAME 換成可從 Chat API 的 spaces.list 方法或即時通訊空間網址取得的即時通訊空間名稱。

  4. 在專案目錄中建立名為 resources 的新子目錄。

  5. 請確認服務帳戶的私密金鑰檔案名為 credentials.json，並將該檔案複製到 resources 子目錄。

  6. 如要設定 Maven，將私密金鑰檔案納入專案套件，請編輯專案目錄中的 pom.xml 檔案，並在 <build> 區段中加入下列設定：

    <build>
  <!-- ... existing configurations ... -->
  <resources>
    <resource>
      <directory>resources</directory>
    </resource>
  </resources>
</build>

  7. 如要設定 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

  1. 在工作目錄中，建立名為 chat_app_auth.py 的檔案。

  2. 在 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.
creds = 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=creds)

# 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)

  3. 在程式碼中，將 SPACE_NAME 換成可從 Chat API 的 spaces.list 方法或即時通訊空間網址取得的即時通訊空間名稱。請確認服務帳戶的私密金鑰檔案名為 credentials.json。

Node.js

  1. 在專案目錄中，建立名為 chat_app_auth.js 的檔案。

  2. 在 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);

  3. 在程式碼中，將 SPACE_NAME 換成可從 Chat API 的 spaces.list 方法或即時通訊空間網址取得的即時通訊空間名稱。請確認服務帳戶的私密金鑰檔案名為 credentials.json。

Apps Script

  1. 在 Apps Script 編輯器中編輯 appsscript.json 檔案，並新增 OAuth 範圍，以便發出外部要求來取得服務帳戶 OAuth 權杖：

      "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]

  2. 在 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 using 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());
}

  3. 在程式碼中，將 CREDENTIALS 替換為 credentials.json 檔案的內容。

  4. 在程式碼中，將 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 檔案，然後按一下「執行」。

您的指令碼會向 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 聊天室。

管理員必須授予應用程式執行這項動作所需的 OAuth 授權範圍

執行指令碼時，您可能會收到以下錯誤訊息：

<HttpError 403 when requesting https://chat.googleapis.com/v1/spaces/{space}?alt=json returned "The administrator must grant the app the required OAuth authorization scope for this action.". Details: "The administrator must grant the app the required OAuth authorization scope for this action.">

這則錯誤訊息表示 Google Workspace 管理員尚未一次性核准 Chat 應用程式，使用以 https://www.googleapis.com/auth/chat.app.* 開頭的授權範圍。

如要解決這項錯誤，請按照下列步驟操作：

  • 請 Google Workspace 管理員核准您的 Chat 應用程式。在 Chat 應用程式邏輯中處理這項錯誤時，請考慮傳送訊息，告知 Chat 應用程式需要管理員核准才能執行要求動作，例如：To perform this action, I need approval. <https://support.google.com/a?p=chat-app-auth|Learn more>.
  • 如果 Google Chat API 方法支援https://www.googleapis.com/auth/chat.bot授權範圍 (不需要管理員核准)，請考慮改用該方法。如要查看方法支援的授權範圍，請參閱 Google Chat API 參考說明文件。
  • 如要瞭解 Chat API 的其他功能，請參閱 Chat API 參考說明文件。
  • 如果使用以 https://www.googleapis.com/auth/chat.app.* 開頭的 OAuth 授權範圍，請參閱這篇文章，瞭解管理員如何授予一次性核准。