В этом руководстве объясняется, как использовать Google Chat API для создания сообщений, содержащих интерактивные карточки от имени пользователей, и как асинхронно обновлять эти карточки.
Создавать и обновлять карточки полезно, если вы хотите:
- Публиковать карточки, представляющие задачи или внешние ресурсы, от имени пользователя.
- Обновлять статус карточки (например, менять "В процессе" на "Завершено") на основе внешних событий, не дожидаясь действий пользователя.
- Обновлять контент карточки в сообщении пользователя, например предварительный просмотр ссылки.
Требования
Node.js
- Аккаунт Google Workspace Business или Enterprise с доступом к Google Chat.
- Настройте среду:
- Создайте проект Google Cloud.
- Настройте окно запроса доступа OAuth.
- Включите и настройте Google Chat API, указав название, значок и описание приложения Chat.
- Установите клиентскую библиотеку API Google для Node.js.
- Создайте учетные данные для доступа в зависимости от того, как вы хотите выполнять аутентификацию в запросе Google Chat API:
- Чтобы выполнить аутентификацию от имени пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде JSON-файла с названием
credentials.jsonв локальном каталоге. - Чтобы выполнить аутентификацию от имени приложения Chat, создайте учетные данные сервисного аккаунта и сохраните их в JSON-файле с названием
credentials.json.
- Чтобы выполнить аутентификацию от имени пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде JSON-файла с названием
- Выберите область действия авторизации в зависимости от того, хотите ли вы выполнить аутентификацию в качестве пользователя или приложения Chat.
Python
- Аккаунт Google Workspace Business или Enterprise с доступом к Google Chat.
- Настройте среду:
- Создайте проект Google Cloud.
- Настройте окно запроса доступа OAuth.
- Включите и настройте Google Chat API, указав название, значок и описание приложения Chat.
- Установите клиентскую библиотеку Google API для Python.
- Создайте учетные данные для доступа в зависимости от того, как вы хотите выполнять аутентификацию в запросе Google Chat API:
- Чтобы выполнить аутентификацию от имени пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде JSON-файла с названием
credentials.jsonв локальном каталоге. - Чтобы выполнить аутентификацию от имени приложения Chat, создайте учетные данные сервисного аккаунта и сохраните их в JSON-файле с названием
credentials.json.
- Чтобы выполнить аутентификацию от имени пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде JSON-файла с названием
- Выберите область действия авторизации в зависимости от того, хотите ли вы выполнить аутентификацию в качестве пользователя или приложения Chat.
Java
- Аккаунт Google Workspace Business или Enterprise с доступом к Google Chat.
- Настройте среду:
- Создайте проект Google Cloud.
- Настройте окно запроса доступа OAuth.
- Включите и настройте Google Chat API, указав название, значок и описание приложения Chat.
- Установите клиентскую библиотеку API Google для Java.
- Создайте учетные данные для доступа в зависимости от того, как вы хотите выполнять аутентификацию в запросе Google Chat API:
- Чтобы выполнить аутентификацию от имени пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде JSON-файла с названием
credentials.jsonв локальном каталоге. - Чтобы выполнить аутентификацию от имени приложения Chat, создайте учетные данные сервисного аккаунта и сохраните их в JSON-файле с названием
credentials.json.
- Чтобы выполнить аутентификацию от имени пользователя Chat, создайте учетные данные идентификатора клиента OAuth и сохраните их в виде JSON-файла с названием
- Выберите область действия авторизации в зависимости от того, хотите ли вы выполнить аутентификацию в качестве пользователя или приложения Chat.
Apps Script
- Аккаунт Google Workspace Business или Enterprise с доступом к Google Chat.
- Настройте среду:
- Создайте проект Google Cloud.
- Настройте окно запроса доступа OAuth.
- Включите и настройте Google Chat API, указав название, значок и описание приложения Chat.
- Создайте отдельный проект Apps Script и включите расширенный сервис Chat.
- В этом руководстве вам нужно использовать аутентификацию пользователя или приложения. Чтобы выполнить аутентификацию от имени приложения Chat, создайте учетные данные сервисного аккаунта. Инструкции приведены в статье Как настроить аутентификацию и авторизацию для приложения Google Chat.
- Выберите область действия авторизации в зависимости от того, хотите ли вы выполнить аутентификацию в качестве пользователя или приложения Chat.
Как создать сообщение-карточку от имени пользователя
Чтобы создать сообщение с карточками от имени пользователя, используйте аутентификацию пользователя.
Чтобы создать сообщение, укажите в запросе следующее:
- Область авторизации
chat.messages.createилиchat.messages. - Поле
cardsV2в ресурсеMessage, содержащее данные карты. 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
const chat = google.chat({version: 'v1'});
// 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.
service = build('chat', 'v1', credentials=credentials)
# 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 Script
/**
* 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
const chat = google.chat({version: 'v1'});
// 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.
service = build('chat', 'v1', credentials=credentials)
# 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 Script
/**
* 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 может заменять только карточки, которые оно прикрепило к сообщению, но не карточки, прикрепленные другими приложениями Chat.
Если пользователь изменит текст сообщения, карточки, принадлежащие приложению Chat, будут удалены и вы больше не сможете их обновлять.