במדריך הזה מוסבר איך משתמשים ב-Google Chat API כדי ליצור הודעות עם כרטיסים אינטראקטיביים בשם המשתמשים, ואיך לעדכן את הכרטיסים האלה באופן אסינכרוני.
יצירה ועדכון של כרטיסים שימושיים כשרוצים לבצע את הפעולות הבאות:
- לפרסם בשם המשתמש כרטיס שמייצג משימה או משאב חיצוני.
- לעדכן את הסטטוס של הכרטיס (לדוגמה, מ"בטיפול" ל "הושלם") על סמך אירועים חיצוניים, בלי לחכות לאינטראקציה של המשתמש.
- לרענן את התוכן של כרטיס בהודעה של משתמש, כמו תצוגה מקדימה של קישור.
דרישות מוקדמות
Node.js
- חשבון Business או Enterprise ב-Google Workspace עם גישה ל-Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- מגדירים את מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, סמל ותיאור לאפליקציה ל-Chat.
- מתקינים את ספריית הלקוח של Google API ל-Node.js.
- יוצרים פרטי כניסה בהתאם לאופן שבו רוצים לבצע אימות בבקשה ל-Google Chat API:
- כדי לאמת כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים את פרטי הכניסה כקובץ JSON בשם
credentials.jsonבספרייה המקומית. - כדי לאמת את אפליקציית Chat, יוצרים פרטי כניסה לחשבון שירות ושומרים אותם כקובץ JSON בשם
credentials.json.
- כדי לאמת כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים את פרטי הכניסה כקובץ JSON בשם
- בוחרים היקף הרשאה בהתאם לאופן שבו רוצים לאמת את הזהות – כמשתמש או כאפליקציה ל-Chat.
Python
- חשבון Business או Enterprise ב-Google Workspace עם גישה ל-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
- חשבון Business או Enterprise ב-Google Workspace עם גישה ל-Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- מגדירים את מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, סמל ותיאור לאפליקציה ל-Chat.
- מתקינים את ספריית הלקוח של Google API ל-Java.
- יוצרים פרטי כניסה בהתאם לאופן שבו רוצים לבצע אימות בבקשה ל-Google Chat API:
- כדי לאמת כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים את פרטי הכניסה כקובץ JSON בשם
credentials.jsonבספרייה המקומית. - כדי לאמת את אפליקציית Chat, יוצרים פרטי כניסה לחשבון שירות ושומרים אותם כקובץ JSON בשם
credentials.json.
- כדי לאמת כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים את פרטי הכניסה כקובץ JSON בשם
- בוחרים היקף הרשאה בהתאם לאופן שבו רוצים לאמת את הזהות – כמשתמש או כאפליקציה ל-Chat.
Apps Script
- חשבון Business או Enterprise ב-Google Workspace עם גישה ל-Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- מגדירים את מסך ההסכמה של OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, סמל ותיאור לאפליקציה ל-Chat.
- יוצרים פרויקט Apps Script עצמאי ומפעילים את שירות הצ'אט המתקדם.
- במדריך הזה, אתם צריכים להשתמש באימות משתמש או אפליקציה. כדי לאמת את אפליקציית 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);
}
}
עדכון כרטיסים באופן אסינכרוני
אחרי שיוצרים הודעה עם כרטיסים, אפשר לעדכן את הכרטיסים באופן אסינכרוני באמצעות אימות של האפליקציה. כך האפליקציה יכולה לרענן את תוכן הכרטיס בלי שהמשתמש יצטרך לעשות משהו. רק אפליקציית הצ'אט שהוסיפה את הכרטיס להודעה של המשתמש יכולה להחליף אותו. אם משתמש עורך את הטקסט של ההודעה, הכרטיסים שבבעלות האפליקציה מוסרים, והאפליקציה לא יכולה יותר לעדכן אותם.
כדי לעדכן את הכרטיסים, צריך להפעיל את השיטה 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);
}
}
מגבלות
כשיוצרים הודעות עם כרטיסים בשם משתמש או מעדכנים כרטיסים, אפליקציית הצ'אט חייבת להיות חברה במרחב המשותף. הדרישה הזו חלה במקרים הבאים:
- יצירת הודעה עם כרטיסים בשם המשתמש.
- החלפה או עדכון של הכרטיסים בהודעה.
הדרישה הזו שונה מממשקי API אחרים שמשתמשים באימות משתמשים, שבדרך כלל לא דורשים שהאפליקציה תהיה חברה במרחב המשותף.
השיטה
replaceCardsתומכת בהחלפה ובהסרה של כרטיסים, ואפשר להוסיף כרטיסים נוספים תוך כדי החלפה שלהם, אבל אי אפשר להוסיף כרטיסים להודעה שאין בה כבר כרטיסים.האפליקציה ל-Chat יכולה להחליף רק כרטיסים שהיא צירפה להודעה, ולא כרטיסים שאפליקציות אחרות ל-Chat צירפו.
אם משתמש עורך את הטקסט של ההודעה, הכרטיסים שבבעלות האפליקציה ל-Chat מוסרים, ואי אפשר יותר לעדכן אותם.