创建和更新交互式卡片

本指南介绍了如何使用 Google Chat API 代表用户创建包含互动式卡片的消息，以及如何异步更新这些卡片。

如果您想执行以下操作，创建和更新卡片会很有用：

代表用户发布表示任务或外部资源的卡片。
根据外部事件更新卡片的状态（例如，从“进行中”更新为“已完成”），而无需等待用户互动。
刷新用户消息中的卡片内容，例如链接预览。

在开发者预览计划之外，通过用户身份验证创建的消息只能包含文本。

前提条件

Node.js

拥有可访问 Google Chat 的 Google Workspace 商务版或企业版账号。

设置环境：
- 创建 Google Cloud 项目。
- 配置 OAuth 权限请求页面。
- 启用并配置 Google Chat API，为您的聊天应用指定名称、图标和说明。
- 安装 Node.js Google API 客户端库。
- 根据您希望在 Google Chat API 请求中进行身份验证的方式，创建访问凭据：
  - 如需以 Chat 用户身份进行身份验证，请创建 OAuth 客户端 ID 凭据，并将该凭据保存为名为 credentials.json 的 JSON 文件，保存到您的本地目录。
  - 如需以 Chat 应用的身份进行身份验证，请创建服务账号凭据，并将凭据保存为名为 credentials.json 的 JSON 文件。
选择授权范围，具体取决于您是想以用户身份还是以 Chat 应用身份进行身份验证。

Python

拥有可访问 Google Chat 的 Google Workspace 商务版或企业版账号。

设置环境：
- 创建 Google Cloud 项目。
- 配置 OAuth 权限请求页面。
- 启用并配置 Google Chat API，为您的聊天应用指定名称、图标和说明。
- 安装 Python Google API 客户端库。
- 根据您希望在 Google Chat API 请求中进行身份验证的方式，创建访问凭据：
  - 如需以 Chat 用户身份进行身份验证，请创建 OAuth 客户端 ID 凭据，并将该凭据保存为名为 credentials.json 的 JSON 文件，保存到您的本地目录。
  - 如需以 Chat 应用的身份进行身份验证，请创建服务账号凭据，并将凭据保存为名为 credentials.json 的 JSON 文件。
选择授权范围，具体取决于您是想以用户身份还是以 Chat 应用身份进行身份验证。

Java

拥有可访问 Google Chat 的 Google Workspace 商务版或企业版账号。

设置环境：
- 创建 Google Cloud 项目。
- 配置 OAuth 权限请求页面。
- 启用并配置 Google Chat API，为您的聊天应用指定名称、图标和说明。
- 安装 Java Google API 客户端库。
- 根据您希望在 Google Chat API 请求中进行身份验证的方式，创建访问凭据：
  - 如需以 Chat 用户身份进行身份验证，请创建 OAuth 客户端 ID 凭据，并将该凭据保存为名为 credentials.json 的 JSON 文件，保存到您的本地目录。
  - 如需以 Chat 应用的身份进行身份验证，请创建服务账号凭据，并将凭据保存为名为 credentials.json 的 JSON 文件。
选择授权范围，具体取决于您是想以用户身份还是以 Chat 应用身份进行身份验证。

Apps 脚本

拥有可访问 Google Chat 的 Google Workspace 商务版或企业版账号。

设置环境：
- 创建 Google Cloud 项目。
- 配置 OAuth 权限请求页面。
- 启用并配置 Google Chat API，为您的聊天应用指定名称、图标和说明。
- 创建独立的 Apps 脚本项目，然后启用高级聊天服务。
- 在本指南中，您必须使用用户或应用身份验证。如需以 Chat 应用身份进行身份验证，请创建服务账号凭据。如需了解具体步骤，请参阅以 Google Chat 聊天应用的身份进行身份验证和授权。
选择授权范围，具体取决于您是想以用户身份还是以 Chat 应用身份进行身份验证。

创建 API 密钥以访问开发者预览版功能

如需调用开发者预览版 API 方法，您必须使用非公开的开发者预览版 API 发现文档。如需对请求进行身份验证，您必须传递 API 密钥。

如需创建 API 密钥，请打开应用的 Google Cloud 项目并执行以下操作：

在 Google Cloud 控制台中，依次前往菜单 > API 和服务 > 凭据。
进入“凭据”页面
依次点击创建凭据 > API 密钥。
系统会显示您的新 API 密钥。
- 点击“复制”图标即可复制 API 密钥，以便在应用的代码中使用。您还可以在项目的凭据的“API 密钥”部分中找到 API 密钥。
- 为防止未经授权的使用，我们建议您限制 API 密钥可用于哪些位置和 API。如需了解详情，请参阅添加 API 限制。

代表用户创建卡片消息

如需代表用户创建包含卡片的邮件，请使用用户身份验证。

如需创建消息，请在请求中指定以下内容：

chat.messages.create 或 chat.messages 授权范围。
Message 资源中的 cardsV2 字段，包含卡片数据。
每张卡的 cardId，这是异步更新所必需的。

以下示例展示了如何代表用户创建包含卡片的讯息：

Node.js

/**
 * This sample shows how to create a message with a card on behalf of a user.
 */
const {google} = require('googleapis');
const {auth} = require('google-auth-library');

async function main() {
  // Create a client
  const authClient = await auth.getClient({
    scopes: ['https://www.googleapis.com/auth/chat.messages.create']
  });
  google.options({auth: authClient});

  // Initialize the Chat API with Developer Preview labels
  const chat = await google.discoverAPI(
    'https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY'
  );

  // The space to create the message in.
  const parent = 'spaces/SPACE_NAME';

  // Create the request
  const request = {
    parent: parent,
    requestBody: {
      text: 'Here is a card created on my behalf:',
      cardsV2: [{
        cardId: 'unique-card-id',
        card: {
          header: {
            title: 'Card Title',
            subtitle: 'Card Subtitle'
          },
          sections: [{
            widgets: [{
              textParagraph: {
                text: 'This card is attached to a user message.'
              }
            }]
          }]
        }
      }]
    }
  };

  // Call the API
  const response = await chat.spaces.messages.create(request);

  // Handle the response
  console.log(response.data);
}

main().catch(console.error);

Python

"""
This sample shows how to create a message with a card on behalf of a user.
"""
from google.oauth2 import service_account
from googleapiclient.discovery import build
import google.auth

def create_message_with_card():
    # Create a client
    scopes = ["https://www.googleapis.com/auth/chat.messages.create"]
    credentials, _ = google.auth.default(scopes=scopes)

    # Build the service endpoint for Chat API with Developer Preview labels.
    service = build(
        'chat',
        'v1',
        credentials=credentials,
        discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY'
    )

    # The space to create the message in.
    parent = "spaces/SPACE_NAME"

    # Create the request
    result = service.spaces().messages().create(
        parent=parent,
        body={
            'text': 'Here is a card created on my behalf:',
            'cardsV2': [{
                'cardId': 'unique-card-id',
                'card': {
                    'header': {
                        'title': 'Card Title',
                        'subtitle': 'Card Subtitle'
                    },
                    'sections': [{
                        'widgets': [{
                            'textParagraph': {
                                'text': 'This card is attached to a user message.'
                            }
                        }]
                    }]
                }
            }]
        }
    ).execute()

    print(result)

if __name__ == "__main__":
    create_message_with_card()

Java

/**
 * This sample shows how to create a message with a card on behalf of a user.
 */
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.gson.GsonFactory;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

public class CreateMessageWithCard {
  public static void main(String[] args) throws Exception {
    HttpTransport transport = GoogleNetHttpTransport.newTrustedTransport();
    GsonFactory jsonFactory = GsonFactory.getDefaultInstance();

    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/chat.messages.create"));
    HttpRequestFactory requestFactory = transport.createRequestFactory(new HttpCredentialsAdapter(credentials));

    String parent = "spaces/SPACE_NAME";
    GenericUrl url = new GenericUrl("https://chat.googleapis.com/v1/" + parent + "/messages");

    // Construct the message body
    Map<String, Object> message = new HashMap<>();
    message.put("text", "Here is a card created on my behalf:");

    Map<String, Object> header = new HashMap<>();
    header.put("title", "Card Title");
    header.put("subtitle", "Card Subtitle");

    Map<String, Object> textParagraph = new HashMap<>();
    textParagraph.put("text", "This card is attached to a user message.");

    Map<String, Object> widget = new HashMap<>();
    widget.put("textParagraph", textParagraph);

    Map<String, Object> section = new HashMap<>();
    section.put("widgets", Collections.singletonList(widget));

    Map<String, Object> card = new HashMap<>();
    card.put("header", header);
    card.put("sections", Collections.singletonList(section));

    Map<String, Object> cardWithId = new HashMap<>();
    cardWithId.put("cardId", "unique-card-id");
    cardWithId.put("card", card);

    message.put("cardsV2", Collections.singletonList(cardWithId));

    HttpRequest request = requestFactory.buildPostRequest(url, new JsonHttpContent(jsonFactory, message));
    System.out.println(request.execute().parseAsString());
  }
}

Apps 脚本

/**
 * This sample shows how to create a message with a card on behalf of a user.
 */
function createMessageWithCard() {
  const parent = 'spaces/SPACE_NAME';
  const url = `https://chat.googleapis.com/v1/${parent}/messages`;

  const message = {
    text: 'Here is a card created on my behalf:',
    cardsV2: [{
      cardId: 'unique-card-id',
      card: {
        header: {
          title: 'Card Title',
          subtitle: 'Card Subtitle'
        },
        sections: [{
          widgets: [{
            textParagraph: {
              text: 'This card is attached to a user message.'
            }
          }]
        }]
      }
    }]
  };

  const options = {
    method: 'post',
    headers: {
      Authorization: 'Bearer ' + ScriptApp.getOAuthToken()
    },
    contentType: 'application/json',
    payload: JSON.stringify(message),
    muteHttpExceptions: true
  };

  try {
    const response = UrlFetchApp.fetch(url, options);
    console.log(response.getContentText());
  } catch (err) {
    console.log('Failed to create message: ' + err.message);
  }
}

异步更新卡片

使用卡片创建消息后，您可以使用应用身份验证异步更新卡片。这样，您的应用就可以刷新卡片内容，而无需用户互动。只有将卡片添加到用户消息中的 Chat 应用才能替换该卡片。如果用户修改消息文本，应用拥有的卡片会被移除，并且您的应用无法再更新这些卡片。

如需更新卡片，请使用以下内容调用 replaceCards 方法：

chat.bot 授权范围。
要更新的消息的 name。
新的 cardsV2 列表。这会替换消息中的所有现有卡片。如果您提供空列表，系统会移除相应卡。

以下示例展示了如何更新消息的卡片：

Node.js

/**
 * This sample shows how to update cards on a message.
 */
const {google} = require('googleapis');
const {auth} = require('google-auth-library');

async function main() {
  // Create a client with app credentials
  const authClient = await auth.getClient({
    scopes: ['https://www.googleapis.com/auth/chat.bot']
  });
  google.options({auth: authClient});

  // Initialize the Chat API with Developer Preview labels
  const chat = await google.discoverAPI(
    'https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY'
  );

  // The message to update.
  const messageName = 'spaces/SPACE_NAME/messages/MESSAGE_ID';

  // Create the request
  const request = {
    name: messageName,
    requestBody: {
      cardsV2: [{
        cardId: 'unique-card-id',
        card: {
          header: {
            title: 'Updated Card Title',
            subtitle: 'Updated Card Subtitle'
          },
          sections: [{
            widgets: [{
              textParagraph: {
                text: 'The card content has been updated asynchronously.'
              }
            }]
          }]
        }
      }]
    }
  };

  // Call the API
  await chat.spaces.messages.replaceCards(request);
  console.log('Cards updated.');
}

main().catch(console.error);

Python

"""
This sample shows how to update cards on a message.
"""
from google.oauth2 import service_account
from googleapiclient.discovery import build
import google.auth

def replace_message_cards():
    # Create a client with app credentials
    scopes = ["https://www.googleapis.com/auth/chat.bot"]
    credentials, _ = google.auth.default(scopes=scopes)

    # Build the service endpoint for Chat API with Developer Preview labels.
    service = build(
        'chat',
        'v1',
        credentials=credentials,
        discoveryServiceUrl='https://chat.googleapis.com/$discovery/rest?version=v1&labels=DEVELOPER_PREVIEW&key=API_KEY'
    )

    # The message to update.
    message_name = "spaces/SPACE_NAME/messages/MESSAGE_ID"

    # Create the request
    result = service.spaces().messages().replaceCards(
        name=message_name,
        body={
            'cardsV2': [{
                'cardId': 'unique-card-id',
                'card': {
                    'header': {
                        'title': 'Updated Card Title',
                        'subtitle': 'Updated Card Subtitle'
                    },
                    'sections': [{
                        'widgets': [{
                            'textParagraph': {
                                'text': 'The card content has been updated asynchronously.'
                            }
                        }]
                    }]
                }
            }]
        }
    ).execute()

    print("Cards updated.")

if __name__ == "__main__":
    replace_message_cards()

Java

/**
 * This sample shows how to update cards on a message.
 */
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.gson.GsonFactory;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;

public class ReplaceMessageCards {
  public static void main(String[] args) throws Exception {
    HttpTransport transport = GoogleNetHttpTransport.newTrustedTransport();
    GsonFactory jsonFactory = GsonFactory.getDefaultInstance();

    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/chat.bot"));
    HttpRequestFactory requestFactory = transport.createRequestFactory(new HttpCredentialsAdapter(credentials));

    String messageName = "spaces/SPACE_NAME/messages/MESSAGE_ID";
    GenericUrl url = new GenericUrl("https://chat.googleapis.com/v1/" + messageName + ":replaceCards");

    // Construct the body
    Map<String, Object> header = new HashMap<>();
    header.put("title", "Updated Card Title");
    header.put("subtitle", "Updated Card Subtitle");

    Map<String, Object> textParagraph = new HashMap<>();
    textParagraph.put("text", "The card content has been updated asynchronously.");

    Map<String, Object> widget = new HashMap<>();
    widget.put("textParagraph", textParagraph);

    Map<String, Object> section = new HashMap<>();
    section.put("widgets", Collections.singletonList(widget));

    Map<String, Object> card = new HashMap<>();
    card.put("header", header);
    card.put("sections", Collections.singletonList(section));

    Map<String, Object> cardWithId = new HashMap<>();
    cardWithId.put("cardId", "unique-card-id");
    cardWithId.put("card", card);

    Map<String, Object> body = new HashMap<>();
    body.put("cardsV2", Collections.singletonList(cardWithId));

    HttpRequest request = requestFactory.buildPostRequest(url, new JsonHttpContent(jsonFactory, body));
    request.execute();
    System.out.println("Cards updated.");
  }
}

Apps 脚本

/**
 * This sample shows how to update cards on a message.
 */
function replaceMessageCards() {
  const messageName = 'spaces/SPACE_NAME/messages/MESSAGE_ID';
  const url = `https://chat.googleapis.com/v1/${messageName}:replaceCards`;

  const request = {
    cardsV2: [{
      cardId: 'unique-card-id',
      card: {
        header: {
          title: 'Updated Card Title',
          subtitle: 'Updated Card Subtitle'
        },
        sections: [{
          widgets: [{
            textParagraph: {
              text: 'The card content has been updated asynchronously.'
            }
          }]
        }]
      }
    }]
  };

  const options = {
    method: 'post',
    headers: {
      Authorization: 'Bearer ' + ScriptApp.getOAuthToken()
    },
    contentType: 'application/json',
    payload: JSON.stringify(request),
    muteHttpExceptions: true
  };

  try {
    const response = UrlFetchApp.fetch(url, options);
    console.log('Cards updated.');
  } catch (err) {
    console.log('Failed to update cards: ' + err.message);
  }
}

限制

当代表用户创建包含卡片的消息或更新卡片时，Chat 应用必须是相应聊天室的成员。此要求适用于以下情况：
- 代表用户创建包含卡片的消息。
- 替换或更新消息的卡片。
此要求不同于使用用户身份验证的其他 API，后者通常不要求应用成为相应空间的成员。
replaceCards 方法支持卡片替换和移除，您可以在替换卡片的同时添加其他卡片，但无法向尚无卡片的消息添加卡片。
聊天应用只能替换其附加到消息的卡片，而不能替换其他聊天应用附加的卡片。
如果用户修改了消息文本，则 Chat 应用拥有的卡片会被移除，您将无法再更新这些卡片。

创建和更新交互式卡片 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

前提条件

Node.js

Python

Java

Apps 脚本

创建 API 密钥以访问开发者预览版功能

代表用户创建卡片消息

Node.js

Python

Java

Apps 脚本

异步更新卡片

Node.js

Python

Java

Apps 脚本

限制

相关主题

创建和更新交互式卡片