לכל אפליקציה ל-Google Chat שאתם יוצרים צריך להיות פרויקט משלה ב-Google Cloud, שבו Chat API מופעל ומוגדר.
כדי לבצע קריאות ל-API לקריאה בלבד עם אימות משתמש, כמו קבלת מרחבים משותפים והצגת הודעות, צריך רק להפעיל את ה-API וליצור לקוח OAuth.
כדי לבצע קריאות ל-API ליצירה, לעדכון ולמחיקה, או כדי לפרוס ולבדוק אפליקציה אינטראקטיבית ל-Chat (שנוצרה כתוסף ל-Google Workspace שמרחיב את Chat), צריך גם להגדיר את Chat API. בהגדרות של Chat API אתם מציינים את כל הפרטים על האפליקציה ל-Chat, כולל השם המוצג, הדמות, נקודות הקצה לפריסה והתכונות האינטראקטיביות.
דרישות מוקדמות
- חשבון Business או Enterprise ב-Google Workspace עם גישה ל-Google Chat.
- יוצרים פרויקט ב-Google Cloud.
- מגדירים את מסך ההסכמה ל-OAuth.
- מפעילים את Google Chat API.
בוחרים שם לתצוגה, דמות ותיאור לאפליקציית הצ'אט
כשמפעילים את Chat API, מגדירים את הפרטים של האפליקציה ל-Chat שמוצגים למשתמשים ב-Chat, כולל שם לתצוגה, דמות ותיאור. הפרטים האלה מופיעים רק ב-Chat. כדי לפרסם את האפליקציה ל-Chat ב-Marketplace, צריך גם לציין את הפרטים שמופיעים בדף האפליקציה ל-Chat ב-Marketplace.
לפני שמגדירים אפליקציה ל-Chat, צריך להכין את הפרטים הבאים:
| שדה | תיאור | פורמט |
|---|---|---|
| שם האפליקציה | השם המוצג של האפליקציה ל-Chat. | עד 25 תווים אלפאנומריים |
| כתובת ה-URL של הדמות | התמונה שמוצגת בתור הדמות של האפליקציה ל-Chat. | כתובת URL מסוג HTTPS שמפנה לתמונה גרפית ריבועית (PNG או JPEG). הגודל המומלץ הוא 256 על 256 פיקסלים או יותר. |
| תיאור | תיאור קצר של האפליקציה ל-Chat, שמוצג כשמשתמשים מחפשים אפליקציות ב-Chat. | עד 40 תווים אלפאנומריים |
| תיאור ארוך | אופציונלי. תיאור של מה שהאפליקציה ל-Chat יכולה לעשות, שמוצג כשמשתמשים מתחילים שיחה עם האפליקציה ל-Chat או פותחים את דף הבית של הסשנים של נציג. זמין כחלק מתוכנית תצוגה מקדימה למפתחים. כרגע אפשר להשתמש באפשרות הזו רק כשמעדכנים את הגדרות האפליקציה באמצעות מסוף Google Cloud, ואי אפשר להשתמש בה באמצעות Google Workspace add-ons API. | עד 250 תווים |
השם, הדמות והתיאור של האפליקציה ל-Chat מוצגים למשתמשים בממשק המשתמש של Chat. בבקשות כתיבה מסוימות של Chat API, Chat משתמש במידע הזה כדי לשייך את הפעולות שאפליקציית Chat מבצעת ב-Chat.
לדוגמה, אם קוראים ל-method spaces.create(), השם של האפליקציה ל-Chat מופיע בתיאור של מי שיצר את המרחב, כמו שמוצג בתמונה הבאה:
spaces.create() כדי ליצור מרחב בשם המשתמש.
כדי לקיים אינטראקציה עם אפליקציות ל-Chat, המשתמשים גם רואים את המידע הזה או משתמשים בו בדרכים הבאות:
- כדי לצרף את אפליקציית Chat למרחב או לשלוח לה הודעה, אתם יכולים לתייג אותה באמצעות @.
- מוצאים את האפליקציה ל-Chat ומתחילים איתה צ'אט אישי. בתפריט אפליקציות, הצ'אטים האישיים מציגים את השם והדמות של האפליקציה ל-Chat.
- בשורת הכתיבה, המשתמשים יכולים לחפש אפליקציות ל-Chat ולראות את השם, הדמות והתיאור שלהן.
הגדרת אפליקציית הצ'אט במסוף Google Cloud
אחרי שאתם יודעים מהם פרטי האפליקציה ל-Chat, אתם יכולים לפתוח את הפרויקט בענן ולהגדיר את Chat API:
במסוף Google Cloud, נכנסים לדף Chat API ולוחצים על הדף Configuration:
בקטע Application info, ממלאים את השדות App name, Avatar URL ו-Description.
אופציונלי: ממלאים את השדה תיאור ארוך (זמין כחלק מתוכנית המפתחים של Google Workspace לתצוגה מקדימה).
אופציונלי: בתפריט תחביר תגי העיצוב, בוחרים את תחביר תגי העיצוב שיוגדר כברירת מחדל (Markdown או Chat) להודעות של האפליקציה ל-Chat. במאמר עיצוב הודעות מוסבר איך מעצבים טקסט ואיך Chat קובע את תחביר תגי העיצוב לבקשות API.
בקטע Interactive features (תכונות אינטראקטיביות), מגדירים אם האפליקציה ל-Chat תגיב לאינטראקציות של משתמשים:
כדי ליצור אפליקציית צ'אט אינטראקטיבית, מפעילים את האפשרות Enable interactive features ומבצעים את הפעולות הבאות:
- בקטע פונקציונליות:
- אופציונלי: בוחרים באפשרות תמיכה בדף הבית של האפליקציה כדי להציג כרטיס בדף הבית בכרטיסייה דף הבית של הצ'אטים האישיים עם האפליקציה ל-Chat.
- כדי שהאפליקציה ל-Chat תהיה זמינה להתקנה ולשימוש, בוחרים באפשרות הצטרפות למרחבים ולשיחות קבוצתיות. כברירת מחדל, המשתמשים יכולים להתקין את האפליקציה ל-Chat ולהתכתב איתה במרחב ייעודי בין המשתמש לאפליקציה. המשתמשים יכולים גם להוסיף את האפליקציה ל-Chat למרחבים עם כמה אנשים ולהתכתב איתה שם.
בקטע Connection settings, בוחרים את הארכיטקטורה שבה רוצים להשתמש כדי לקבל אובייקטים מסוג אירוע מ-Chat:
- כדי להשתמש בשירות HTTP, בוחרים באפשרות HTTP endpoint URL ומזינים כתובת URL.
- כדי להשתמש בפרויקט של Google Apps Script, בוחרים באפשרות Apps Script ומזינים את מזהה הפריסה של הפרויקט.
- כדי להשתמש בנציג Dialogflow, בוחרים באפשרות Dialogflow, בוחרים באפשרות Dialogflow CX או Dialogflow ES ומציינים את שם המשאב של הנציג.
- כדי להשתמש ב-Pub/Sub, בוחרים באפשרות Cloud Pub/Sub ומזינים את שם הנושא.
אופציונלי: כדי לנתב אובייקטים מסוג אירוע לנקודות קצה או לפונקציות ספציפיות, נכנסים להגדרות החיבור > טריגרים ומזינים או מעדכנים את נקודות הקצה או הפונקציות של הקריאה החוזרת (callback) לטריגרים הבאים של Chat:
- דף הבית של האפליקציה (אם האפשרות תמיכה בדף הבית של האפליקציה מופעלת): המשתמש פותח את הכרטיסייה דף הבית בצ'אט אישי עם האפליקציה ל-Chat.
- הוספה למרחב משותף: משתמש מוסיף את האפליקציה ל-Chat לשיחה קבוצתית או למרחב משותף, או מתקין את האפליקציה ל-Chat לצ'אטים אישיים.
- הודעה: המשתמש שולח הודעה לאפליקציה ל-Chat. לדוגמה, המשתמש שולח הודעה ישירה לאפליקציה ל-Chat או מתייג אותה באמצעות @במרחב עם כמה אנשים.
- הוסרה מהמרחב: משתמש מסיר את האפליקציה ל-Chat מהמרחב.
- פקודה לאפליקציה: המשתמש מפעיל פקודה מהירה, פקודה דרך שורת הפקודות או פעולה בהודעה באפליקציה ל-Chat.
אופציונלי: מוסיפים תכונות אינטראקטיביות אחרות כמו סשנים, הצעה לפרומפט, פקודות (פקודות מהירות, פקודות דרך שורת הפקודות ופעולות בהודעות) או תצוגות מקדימות של קישורים.
בקטע הרשאות גישה, בוחרים באפשרות אפליקציית הצ'אט הזו תהיה זמינה לאנשים ולקבוצות ספציפיים ומזינים את כתובות האימייל של אנשים או קבוצות ב-Google בארגון שלכם ב-Google Workspace:
- כדי להתקין ולבדוק את האפליקציה בעצמך, צריך להזין את כתובת האימייל שלך.
- כדי לשתף אפליקציית Chat פנימית עם צוות או עם כל הארגון בלי לפרסם אותה ב-Marketplace, צריך להזין קבוצה אחת או יותר ב-Google. אין הגבלה על מספר החברים בקבוצות. אם האפליקציה מבקשת היקפי הרשאות של
chat.app.*, עדיין צריך לפרסם את האפליקציה כדי לקבל אישור מהאדמין. - אם האדמין שלכם מגביל את ההתקנות מ-Marketplace לאפליקציות שברשימת ההיתרים, מסוף Google Cloud מגביל את השדה הזה לחמש כתובות אימייל של משתמשים נפרדים לצורכי פיתוח. הגדרת החשיפה לקבוצה חלה רק אחרי שאדמין מוסיף את האפליקציה לרשימת ההיתרים.
- בקטע פונקציונליות:
אופציונלי: בקטע Logs, מסמנים את התיבה Log errors to Logging כדי להשתמש ב-Google Cloud Logging. מידע נוסף מופיע במאמר שאילתות ביומני השגיאות של אפליקציות ל-Chat.
לוחצים על שמירה.
אחרי ששומרים את ההגדרות, כל מי שציינתם בהגדרה הרשאות גישה ב-Chat API יכול להתקין את האפליקציה ל-Chat, לבדוק אותה או להשתמש בה. כדי להתחיל לבדוק את האפליקציה ל-Chat ולנפות בה באגים, קראו את המאמר בדיקת תכונות אינטראקטיביות באפליקציות ל-Google Chat.
איך מגדירים את האפליקציה ל-Chat באמצעות Google Workspace add-ons API
במקום להגדיר את אפליקציית הצ'אט באופן ידני במסוף Google Cloud, אתם יכולים להשתמש בפרויקט בענן של Google שרשום לתוכנית של Google Workspace לתצוגה מקדימה למפתחים כדי לקרוא ולעדכן באופן פרוגרמטי את ההגדרות של אפליקציית הצ'אט שנוצרה כתוסף ל-Google Workspace באמצעות המשאב chatAppConfig ב-Google Workspace add-ons API.
chatAppConfig הוא משאב יחיד (singleton) שתמיד קיים בכל פרויקט בענן. לפני ששומרים הגדרה בפעם הראשונה, המשאב מכיל הגדרה ריקה (שגם מוחזרת על ידי GetChatAppConfig אם קוראים את המשאב לפני השמירה הראשונה). מכיוון שהמשאב כבר קיים, אין צורך ליצור אותו בנפרד – משתמשים ב-UpdateChatAppConfig גם כדי לשמור את ההגדרה הראשונית וגם כדי לעדכן הגדרה קיימת.
דרישות מוקדמות ואימות
לפני שקוראים ל-GetChatAppConfig או ל-UpdateChatAppConfig, צריך להשלים את הדרישות המוקדמות הבאות:
- רושמים את פרויקט הענן ב-Google Cloud לתוכנית 'תצוגה מקדימה למפתחים' של Google Workspace.
- מפעילים את Google Workspace Add-ons API (
gsuiteaddons.googleapis.com) בפרויקט ב-Cloud. אם רוצים לראות או לעדכן את ההגדרות של האפליקציה ל-Chat במסוף Google Cloud, או לשלוח קריאה ל-Chat API, אפשר להפעיל את Google Chat API (chat.googleapis.com). - אימות כמשתמש אנושי באמצעות פרטי כניסה של OAuth 2.0 שכוללים את ההיקף
https://www.googleapis.com/auth/cloud-platform. אי אפשר לאמת חשבון שירות בשיטות שלchatAppConfig. - מוודאים שלמשתמש המאומת יש את ההרשאות הנדרשות לניהול זהויות והרשאות גישה (IAM) בפרויקט היעד ב-Cloud:
-
gsuiteaddons.chatAppConfigs.getו-chat.bots.getכדי לקרוא את ההגדרות (GetChatAppConfig). -
gsuiteaddons.chatAppConfigs.updateו-chat.bots.updateכדי לעדכן את ההגדרות (UpdateChatAppConfig).
-
- אם אתם משתמשים בספריית לקוח, הורידו את ספריית הלקוח של תצוגה מקדימה למפתחים באמצעות החשבון הרשום שלכם בתצוגה מקדימה למפתחים.
עדכון ההגדרות של אפליקציית Chat
כדי להגדיר אפליקציה ל-Chat בפעם הראשונה או לעדכן הגדרה קיימת, שולחים בקשת PATCH (UpdateChatAppConfig) למשאב היחיד (singleton) chatAppConfig בפרויקט הענן שלכם:
- כששומרים בפעם הראשונה פרויקט בענן עם
chatAppConfigריק, צריך להזין אתdisplayName(3 עד 25 תווים) ואתdescription(תו אחד עד 40 תווים). אם לא תכללו אתinteractiveFeatureConfigבשמירה הראשונית, האפליקציה ל-Chat תוגדר כלא אינטראקטיבית. - בעדכונים הבאים, משתמשים בפרמטר השאילתה האופציונלי
updateMaskכדי לציין את השדות שרוצים לעדכן, מופרדים בפסיקים (או משמיטים אתupdateMaskכדי לעדכן את כל השדות שצוינו). עדכון של שדה חוזר (appCommands,urlPatternsאוallowlistedTestingPrincipals) מחליף את כל הרשימה.
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"name": "projects/PROJECT_NUMBER/chatAppConfig",
"displayName": "Cymbal Assistant",
"description": "Helps manage tasks and schedules",
"avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
"state": "ACTIVE",
"errorLoggingEnabled": true,
"markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
"interactiveFeatureConfig": {
"supportsMultiuserSpaces": false,
"connectionConfig": {
"httpEndpointConfig": {
"commonUrl": "https://example.com/chat"
}
},
"appCommands": [
{
"commandType": "SLASH_COMMAND",
"commandId": 1,
"command": "/help",
"description": "Show available commands",
"dialogEnabled": false
}
],
"urlPatterns": [
{
"hostPattern": "example.com",
"pathPrefix": "tasks/"
}
],
"allowlistedTestingPrincipals": [
"USER_EMAIL"
]
}
}
מחליפים את הערכים הבאים בכתובת ה-URL, בכותרת ובגוף של הבקשה:
-
PROJECT_NUMBER: מספר הפרויקט ב-Cloud שמארח את האפליקציה ל-Chat. -
ACCESS_TOKEN: טוקן גישה מסוג OAuth 2.0 של משתמש, שאושר עם היקף ההרשאותhttps://www.googleapis.com/auth/cloud-platform. -
USER_EMAIL: כתובת אימייל או קבוצה ב-Google מהארגון שלכם ב-Google Workspace, שרוצים להוסיף לרשימת ההיתרים כדי לבדוק את האפליקציה ל-Chat (לדוגמה, כתובת האימייל שלכם). - שדות התצורה לדוגמה בגוף הבקשה (כמו
displayName,description,avatarUriו-interactiveFeatureConfig, כולל תצורת נקודת הקצה, הפקודות, תבניות ה-URL של התצוגה המקדימה של הקישורים והחשבונות הראשיים לבדיקה) עם הערכים של אפליקציית הצ'אט. לפרטים על כל השדות הנתמכים והאפשרויות של נקודות הקצה, עיינו בחומר העזר בנושא REST שלprojects.chatAppConfigוב-projects.chatAppConfig.patch.
איך מקבלים את ההגדרות של אפליקציית Chat
כדי לקרוא את ההגדרות הנוכחיות של אפליקציית הצ'אט בפרויקט בענן, צריך להפעיל את GetChatAppConfig.
אפשר להעביר את הפרמטר האופציונלי של השאילתה view (ChatAppConfigView):
-
BASIC(ברירת המחדל): החזרת מטא-נתונים בסיסיים בליinteractiveFeatureConfig. -
FULL: מחזירה את כל שדות התצורה, כוללinteractiveFeatureConfig.
אם ההגדרות של אפליקציית הצ'אט עדיין לא נשמרו בפרויקט בענן, השיטה מחזירה אובייקט ChatAppConfig ריק.
HTTP
GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN
Node.js
const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;
const client = new GSuiteAddOnsClient();
async function getChatAppConfig() {
const [response] = await client.getChatAppConfig({
name: 'projects/PROJECT_NUMBER/chatAppConfig',
view: 'FULL',
});
console.log(JSON.stringify(response, null, 2));
}
getChatAppConfig();
Python
from google.cloud import gsuiteaddons_v1
client = gsuiteaddons_v1.GSuiteAddOnsClient()
request = gsuiteaddons_v1.GetChatAppConfigRequest(
name="projects/PROJECT_NUMBER/chatAppConfig",
view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)
שיקולים לגבי תוספים קיימים ל-Google Workspace
ההגדרה של אפליקציות צ'אט שונה מההגדרה של תוספים ל-Google Workspace שמרחיבים אפליקציות אחרות של Google Workspace. אם התוסף שלכם מרחיב אפליקציות אחרות של Google Workspace, כדאי להביא בחשבון את הדרישות הבאות להגדרת אפליקציית הצ'אט:
- גם משתמשים פרטיים וגם אדמינים ב-Google Workspace צריכים להיות מסוגלים להתקין את התוסף מ-Marketplace. אתם קובעים את הגדרות ההתקנה האלה ב-Marketplace SDK.
- אפליקציות צ'אט לא משתמשות בשם ובלוגו שאתם מגדירים לאפליקציות אחרות של Google Workspace באובייקט
addons.commonשל המניפסט. - בתוספים שפורסמו ב-Google Workspace Marketplace, אי אפשר לשמור טיוטה של שינויים בהגדרות האישיות של Google Chat API. אחרי שמעדכנים ושומרים את הגדרות התצורה של Chat API, אפליקציית Chat המעודכנת זמינה באופן מיידי לכל המשתמשים הקיימים. כדי לעדכן את דף האפליקציה ב-Marketplace, אתם יכולים ליצור טיוטה לפני שאתם שולחים את השינויים.
- אם פיתחתם את התוסף באמצעות Apps Script:
- אתם צריכים להשתמש באותו מזהה פריסה של Apps Script שבו אתם משתמשים בשאר ההגדרות של התוסף.
- אי אפשר להשתמש בעורך של Apps Script כדי להתקין פריסות לבדיקה ב-Chat. במקום זאת, צריך להתקין אותן ישירות מממשק המשתמש של Chat.
- אם פיתחתם את התוסף באמצעות שירות HTTP, אל תכללו את פרטי ההגדרות של אפליקציית הצ'אט במניפסט של
projects.deploymentsשאתם יוצרים באמצעות Google Workspace add-ons API. פריסות ה-HTTP שאתם מציינים ב-Google Workspace Marketplace SDK משמשות רק לאפליקציות אחרות של Google Workspace. במקום זאת, צריך להגדיר את האפליקציה ל-Chat במסוף Google Cloud או באמצעות המשאבchatAppConfigב-Google Workspace add-ons API.
איך נותנים לאנשים אחרים הרשאה להגדיר את Chat API
אתם יכולים לתת למשתמשים ספציפיים גישה לדף ההגדרות של אפליקציית הצ'אט, על ידי הקצאת התפקיד בניהול זהויות והרשאות גישה (IAM) ב-Google Cloud בעלים של אפליקציות צ'אט או צפייה באפליקציות צ'אט. משתמשים עם התפקידים האלה לא יכולים לעבור לדף ההגדרות של אפליקציות ל-Chat דרך מרכז הבקרה APIs & Services, אבל הם יכולים לגשת לדף ההגדרות דרך מסוף Google Cloud של הפרויקט המארח של האפליקציה ל-Chat ב-Cloud, באופן הבא:
https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID
PROJECT_ID הוא מזהה הפרויקט ב-Google Cloud שמארח את אפליקציית הצ'אט.
נושאים קשורים
- בחירת ארכיטקטורה לאפליקציה ל-Chat
- קבלת אינטראקציות של משתמשים ושליחת תגובות אליהן
- בדיקת תכונות אינטראקטיביות באפליקציות ל-Google Chat
אפליקציות ל-Chat שהן לא תוספים: הגדרת Google Chat API
אם אתם מתחזקים אפליקציה ל-Chat שהיא לא תוסף ל-Google Workspace, ההגדרה שלכם משתמשת בנקודת קצה אחת לכל אירועי האינטראקציה, ולא בטריגרים לכל אירוע:
במסוף Google Cloud, נכנסים לדף Configuration של Chat API:
בקטע תכונות אינטראקטיביות, מפעילים את האפשרות הפעלת תכונות אינטראקטיביות.
מבטלים את הסימון של האפשרות פיתוח אפליקציית Chat כתוסף ל-Google Workspace. תיפתח תיבת דו-שיח שבה תתבקשו לאשר את הפעולה. בתיבת הדו-שיח, לוחצים על השבתה.
בקטע פונקציונליות, בוחרים באפשרות תמיכה בדף הבית של האפליקציה או באפשרות הצטרפות למרחבים משותפים ולשיחות קבוצתיות, לפי הצורך.
בקטע Connection settings, מציינים נקודת קצה אחת לאפליקציה ל-Chat (HTTP endpoint URL, מזהה פריסה של Apps Script, Cloud Pub/Sub topic name או Dialogflow).
מגדירים את האפשרויות Commands, Link previews, Visibility ו-Logs, ואז לוחצים על Save.
כדי לשדרג אפליקציה ל-Chat שהיא לא תוסף לתוסף ל-Google Workspace שמרחיב את Google Chat, קראו את המאמר המרת אפליקציה ל-Google Chat לתוסף ל-Google Workspace.