此页面由 Cloud Translation API 翻译。

作为 Google Chat 应用进行身份验证

本指南介绍了如何设置和使用服务账号代表 Chat 应用访问 Google Chat API。首先，它会引导您创建服务账号。然后，该视频演示了如何编写脚本，以使用服务账号通过 Chat API 进行身份验证并在 Chat 聊天室中发布消息。

使用服务账号进行身份验证时，Chat 应用必须是聊天室的成员，才能获取聊天室中的数据或执行操作。例如，如需列出聊天室的成员或在聊天室中创建消息，Chat 应用本身必须是聊天室的成员。唯一的例外情况是 Chat 应用使用应用身份验证创建聊天室，在这种情况下，应用会创建聊天室，然后自动成为成员。

支持使用名称以 https://www.googleapis.com/auth/chat.app.* 开头的授权范围进行应用授权的 Google Chat API 方法需要一次性管理员批准。支持使用 https://www.googleapis.com/auth/chat.bot 授权范围进行应用授权的 Google Chat API 方法无需额外审批。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 应用添加到聊天室。如需添加 Chat 应用，请参阅测试 Google Chat 应用的交互功能。

Python

Python 3.6 或更高版本
pip 软件包管理工具
启用了交互功能的 Google Chat 应用。如需使用 HTTP 服务创建交互式 Chat 应用，请完成此快速入门。
将 Chat 应用添加到聊天室。如需添加 Chat 应用，请参阅测试 Google Chat 应用的交互功能。

Node.js

Node.js 14 或更高版本
npm 软件包管理工具
初始化的 Node.js 项目。如需初始化新项目，请创建并切换到新文件夹，然后在命令行界面中运行以下命令：
```
npm init
```
启用了交互功能的 Google Chat 应用。如需使用 HTTP 服务创建交互式 Chat 应用，请完成此快速入门。
将 Chat 应用添加到聊天室。如需添加 Chat 应用，请参阅测试 Google Chat 应用的交互功能。

Apps 脚本

启用了交互功能的 Google Chat 应用。如需在 Apps 脚本中创建交互式 Chat 应用，请完成此快速入门。
将 Chat 应用添加到聊天室。如需添加 Chat 应用，请参阅测试 Google Chat 应用的交互功能。

第 1 步：在 Google Cloud 控制台中创建服务账号

创建一个服务账号，供 Chat 应用使用来访问 Google API。

创建服务账号

如需创建服务账号，请按照以下步骤操作：

Google Cloud 控制台

在 Google Cloud 控制台中，依次选择“菜单”图标 > IAM 和管理 > 服务账号。
转到“服务账号”
点击创建服务账号。
填写服务账号详细信息，然后点击创建并继续。
注意：默认情况下，Google 会创建一个唯一的服务账号 ID。如果您想更改 ID，请在“服务账号 ID”字段中修改该 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 文档中的服务账号部分。

接下来，为此服务账号创建与 Google Workspace Marketplace 兼容的 OAuth 客户端。

获得管理员批准

如需使用以 https://www.googleapis.com/auth/chat.app.* 开头的授权范围（这些范围在开发者预览版中提供），您的 Chat 应用必须获得一次性管理员批准。

如需使用 https://www.googleapis.com/auth/chat.bot 授权范围，无需获得管理员批准。

如需获得管理员批准，您必须准备 Chat 应用的服务账号，并提供以下信息：

与 Google Workspace Marketplace 兼容的 OAuth 客户端。
Google Workspace Marketplace SDK 中的应用配置。

创建与 Google Workspace Marketplace 兼容的 OAuth 客户端

如需创建与 Google Workspace Marketplace 兼容的 OAuth 客户端，请按以下步骤操作：

在 Google Cloud 控制台中，依次选择“菜单” > IAM 和管理 > 服务账号。

转到“服务账号”
点击您为 Chat 应用创建的服务账号。
点击高级设置。
点击创建与 Google Workspace Marketplace 兼容的 OAuth 客户端。
点击继续。

系统会显示一条确认消息，说明已创建与 Google Workspace Marketplace 兼容的 OAuth 客户端。

在 Google Workspace Marketplace SDK 中配置 Chat 应用

如需在 Google Workspace Marketplace SDK 中配置 Chat 应用，请按以下步骤操作：

在 Google Cloud 控制台中，启用 Google Workspace Marketplace SDK。

启用 Google Workspace Marketplace SDK
在 Google Cloud 控制台中，依次选择菜单 > API 和服务 > 已启用的 API 和服务 > Google Workspace Marketplace SDK > 应用配置。

前往“应用配置”
填写“应用配置”页面。您如何配置 Chat 应用取决于您的目标受众群体和其他因素。如需有关填写应用配置页面的帮助，请参阅在 Google Workspace Marketplace SDK 中配置您的应用。在本指南中，请输入以下信息：
1. 在应用公开范围下，选择不公开。
2. 在安装设置下，选择个人 + 管理员安装。
3. 在应用集成下，选择 Chat 扩展应用。
4. 在 OAuth 范围下，输入 Chat 应用使用的所有身份验证范围。
  
  警告：请勿输入 https://www.googleapis.com/auth/chat.bot 授权范围，此范围不需要在此页面上进行配置。由于本指南中的示例使用了 https://www.googleapis.com/auth/chat.bot 授权范围，因此您无需在此处输入任何内容即可运行该示例。
5. 在开发者信息下，输入您的开发者名称、开发者网站网址和开发者电子邮件地址。
6. 点击 Save draft。

获取管理员批准

现在，您的服务账号已配置为接收管理员批准，请向 Google Workspace 管理员申请批准，管理员可以按照为 Chat 应用设置授权中的步骤授予批准。

第 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 脚本

此示例使用适用于 Apps 脚本的 OAuth2 库生成 JWT 令牌以进行服务账号身份验证。如需将该库添加到您的 Apps 脚本项目中，请执行以下操作：

点击左侧的编辑器图标。
在左侧，点击“库”旁边的添加库图标。
输入脚本 ID 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF。
点击查找，然后点击添加。

此示例使用高级聊天服务调用 Google Chat API。如需为您的 Apps Script 项目开启该服务，请执行以下操作：

点击左侧的编辑器图标。
在左侧的服务旁边，点击添加服务 。
选择 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 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();
    }
}

在代码中，将 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.
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)

在代码中，将 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 脚本

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

在代码中，将 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 脚本

在 Apps Script 编辑器中打开 ChatAppAuth.gs 文件，然后点击运行。

您的脚本会向 Chat 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 授权范围，请了解管理员如何授予一次性批准。

作为 Google Chat 应用进行身份验证

前提条件

Java

Python

Node.js

Apps 脚本

第 1 步：在 Google Cloud 控制台中创建服务账号

创建服务账号

Google Cloud 控制台

gcloud CLI

创建一个私钥

获得管理员批准

创建与 Google Workspace Marketplace 兼容的 OAuth 客户端

在 Google Workspace Marketplace SDK 中配置 Chat 应用

获取管理员批准

第 2 步：安装 Google 客户端库和其他依赖项

Java

Python

Node.js

Apps 脚本

第 3 步：编写一个脚本，使用服务账号向 Chat API 进行身份验证

Java

Python

Node.js

Apps 脚本

第 4 步：运行完整示例

Java

Python

Node.js

Apps 脚本

对示例进行问题排查

您无权使用此应用

管理员必须向应用授予执行此操作所需的 OAuth 授权范围

相关主题