לכל אפליקציה ל-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.
אופציונלי: ממלאים את השדה תיאור ארוך.
אופציונלי: בתפריט תחביר תגי העיצוב, בוחרים את תחביר תגי העיצוב שיוגדר כברירת מחדל (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.
איך מגדירים את אפליקציית הצ'אט באמצעות Google Cloud CLI
במקום להשתמש במסוף Google Cloud, אתם יכולים להציג ולעדכן את ההגדרות של אפליקציית הצ'אט משורת הפקודה באמצעות ה-CLI של gcloud. לדוגמה, אתם יכולים להגדיר אפליקציה ל-Chat באמצעות סקריפט, או לשמור את ההגדרות שלה בקובץ שאתם מאחסנים עם הקוד.
קבוצת הפקודות gcloud beta workspace-add-ons chat-app-config כוללת את הפקודות הבאות:
הפקודות משתמשות במשאב chatAppConfig ב-Google Workspace add-ons API.
לפני שמתחילים
- מתקינים את ה-CLI של gcloud. אם התקנתם את ה-CLI של gcloud, השתמשו בפקודה
gcloud components updateכדי לבדוק אם הגרסה העדכנית מותקנת. נכנסים ל-CLI של gcloud באמצעות חשבון המשתמש. הפקודות לא תומכות בחשבונות שירות.
gcloud auth loginמגדירים את פרויקט הענן של אפליקציית הצ'אט כפרויקט ברירת המחדל של ה-CLI של gcloud. צריך להשתמש במזהה הפרויקט, כי הפקודות לא מקבלות מספר פרויקט.
gcloud config set project PROJECT_IDלחלופין, אפשר להוסיף את הדגל
--projectלכל פקודה.מפעילים את Google Workspace add-ons API בפרויקט ב-Cloud:
gcloud services enable gsuiteaddons.googleapis.comמוודאים שיש לכם את התפקידים הבאים בניהול הזהויות והרשאות הגישה (IAM) בפרויקט בענן:
- מפתח תוספים ל-Google Workspace (
roles/gsuiteaddons.developer) כדי לראות ולעדכן את ההגדרות, או קורא תוספים ל-Google Workspace (roles/gsuiteaddons.reader) כדי לראות אותן בלבד. התפקידים האלה כוללים את ההרשאות שמפורטות בקטע דרישות מוקדמות ואימות. - Service Usage Consumer
(
roles/serviceusage.serviceUsageConsumer). ה-CLI של gcloud משתמש בפרויקט ב-Cloud כפרויקט לצורך מכסות לבקשות שלו, ולכן נדרשת ההרשאהserviceusage.services.use.
התפקידים בעלים ועריכה כוללים את כל ההרשאות האלה. התפקידים בעלים של אפליקציות צ'אט וצפייה באפליקציות צ'אט, שנותנים גישה לדף ההגדרות במסוף Google Cloud, לא מספיקים.
- מפתח תוספים ל-Google Workspace (
צפייה בהגדרה
כדי לראות את ההגדרות של אפליקציית הצ'אט, מריצים את הפקודה describe:
gcloud beta workspace-add-ons chat-app-config describeהפלט אמור להיראות כך:
avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
allowlistedTestingPrincipals:
- user@example.com
appCommands:
- command: /help
commandId: 1
commandType: SLASH_COMMAND
description: Show available commands
connectionConfig:
httpEndpointConfig:
commonUrl: https://example.com/chat
supportsMultiuserSpaces: true
urlPatterns:
- hostPattern: example.com
pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE
אם לפרויקט בענן עדיין אין אפליקציית צ'אט, הפקודה תצליח ותדפיס רק את השדה name של ההגדרה:
name: projects/123456789012/chatAppConfig
כדי לשנות את הפלט, מוסיפים את אחד מהדגלים הבאים:
-
--format=json: מדפיס את ההגדרות בפורמט JSON. -
--view=basic: לא כולל את הגדרות התכונות האינטראקטיביות (interactiveFeatureConfig). -
--format="value(displayName)": מדפיס רק את השם המוצג, או שורה ריקה אם לפרויקט בענן עדיין אין אפליקציית צ'אט. לאפליקציה ל-Chat שהוגדרה תמיד יש שם לתצוגה, כך שאפשר להשתמש בדגל הזה בסקריפט כדי לבדוק אם האפליקציה ל-Chat קיימת.
עדכון ההגדרות
כדי להגדיר אפליקציה ל-Chat בפעם הראשונה, או כדי לשנות את ההגדרות שלה, מריצים את הפקודה update. מציינים את ההגדרות באמצעות דגלים או בקובץ תצורה. אי אפשר לשלב את שתי הפעולות בפקודה אחת.
בפעם הראשונה שמריצים את הפקודה בפרויקט בענן, צריך לציין לפחות שם לתצוגה ותיאור. אם לא משביתים את אפליקציית Chat, היא תהיה פעילה ברגע שהפקודה תסתיים. האנשים שרשמתם כבודקים יוכלו למצוא את האפליקציה ולהשתמש בה.
שימוש בדגלים
בדוגמה הבאה מוגדרת אפליקציה ל-Chat שמקבלת אירועים בנקודת קצה (endpoint) של HTTP:
gcloud beta workspace-add-ons chat-app-config update \
--display-name="Quickstart App" \
--description="Quickstart app" \
--avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
--http-endpoint-url=HTTP_ENDPOINT_URL \
--supports-multiuser-spaces \
--add-allowlisted-testing-principals=USER_EMAIL \
--error-logging-enabledמחליפים את מה שכתוב בשדות הבאים:
HTTP_ENDPOINT_URL: כתובת ה-URL מסוג HTTPS שמקבלת אובייקטים מסוג אירוע מ-Chat.-
USER_EMAIL: כתובת האימייל של אדם או קבוצה בארגון שלכם ב-Google Workspace שיכולים להתקין ולבדוק את האפליקציה ל-Chat, כמו כתובת האימייל שלכם.
הפקודה מדפיסה את ההגדרות המעודכנות.
בטבלה הבאה מפורטים הדגלים של ההגדרות בדף Configuration של Chat API במסוף Google Cloud. לפרטים על כל דגל, עיינו בחומרי העזר של הפקודה update.
| הגדרה במסוף Google Cloud | דגלים |
|---|---|
| שם האפליקציה | --display-name |
| כתובת ה-URL של הדמות | --avatar-uri עם כתובת ה-URL מסוג HTTPS של תמונה שעומדת בדרישות לגבי דמות ה-Avatar, או
--clear-avatar-uri כדי להשתמש בדמות ה-Avatar שמוגדרת כברירת מחדל |
| תיאור | --description |
| סטטוס האפליקציה | --state=active או --state=disabled |
| תחביר תגי העיצוב | --markup-syntax=markdown או
--markup-syntax=chat |
| להצטרף למרחבים משותפים ולשיחות קבוצתיות. | --supports-multiuser-spaces או
--no-supports-multiuser-spaces |
| הגדרות החיבור | אחד מהפרטים הבאים:
|
| חשיפה | --add-allowlisted-testing-principals,
--remove-allowlisted-testing-principals וגם
--clear-allowlisted-testing-principals |
| רישום שגיאות ב-Logging | --error-logging-enabled או
--no-error-logging-enabled |
לפקודות, לתצוגות מקדימות של קישורים ולנקודות קצה נפרדות לכל טריגר אין דגלים. כדי להגדיר אותם, משתמשים בקובץ תצורה.
לדוגמה, כדי להשבית את אפליקציית הצ'אט בלי לשנות את ההגדרות האחרות שלה, מריצים את הפקודה הבאה. כדי להפעיל אותו שוב, משתמשים ב---state=active.
gcloud beta workspace-add-ons chat-app-config update --state=disabledשימוש בקובץ תצורה
כדי לשמור את ההגדרות בקובץ, או כדי לקבוע הגדרות שאין להן דגלים, מעבירים קובץ YAML או JSON לפקודה update. הקובץ משתמש בשדות של המשאב chatAppConfig, שהם אותם שדות שהפקודה describe מדפיסה.
יוצרים קובץ שמכיל את ההגדרות שרוצים לעדכן. לדוגמה, יוצרים קובץ בשם
chat_app_config.yamlעם התוכן הבא:displayName: Cymbal Assistant description: Helps manage tasks and schedules avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png state: ACTIVE errorLoggingEnabled: true interactiveFeatureConfig: supportsMultiuserSpaces: true connectionConfig: httpEndpointConfig: commonUrl: https://example.com/chat appCommands: - commandId: 1 commandType: SLASH_COMMAND command: /help description: Show available commands urlPatterns: - hostPattern: example.com pathPrefix: tasks/ allowlistedTestingPrincipals: - USER_EMAILמחליפים את
USER_EMAILבכתובת האימייל של משתמש או קבוצה בארגון ב-Google Workspace שיכולים להתקין את אפליקציית Chat ולבדוק אותה.מריצים את הפקודה
updateעם הדגל--config-file:gcloud beta workspace-add-ons chat-app-config update \ --config-file=chat_app_config.yaml
כדי להתחיל מההגדרות הנוכחיות של אפליקציית Chat, שומרים את הפלט של הפקודה describe בקובץ:
gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yamlלאחר מכן עורכים את הקובץ, מוחקים את השדות שלא רוצים לשנות ומעבירים את הקובץ לפקודה update. אם הקובץ מכיל הגדרה שהפקודה לא יכולה לעדכן, הפקודה נכשלת. לפרטים נוספים, ראו מגבלות.
הפקודה update מתעלמת מהשדה name בקובץ. הוא תמיד מעדכן את פרויקט בענן שהגדרתם ב-CLI של gcloud, כך שאתם יכולים להשתמש באותו קובץ כדי להגדיר אפליקציה ל-Chat בפרויקט אחר בענן.
איך הפקודה מחילה את השינויים
- רק ההגדרות שציינתם ישתנו. אם משתמשים בדגלים, הפקודה משנה את ההגדרות של הדגלים שמעבירים. כשמשתמשים בקובץ תצורה, הפקודה משנה את השדות שבקובץ, כך שהקובץ לא צריך להכיל את כל התצורה. הגדרות החיבור הן חריג: סוג החיבור שאתם מגדירים מחליף את הסוג הנוכחי, ומהדורת Dialogflow שאתם מגדירים מחליפה את כל ההגדרות של Dialogflow.
- הרשימות מוחלפות במלואן. אם הקובץ מכיל את השדה
appCommands,urlPatternsאוallowlistedTestingPrincipals, הרשימה בקובץ מחליפה את הרשימה הנוכחית. כדי להוסיף או להסיר בודקים ספציפיים, משתמשים בדגלים--add-allowlisted-testing-principalsו---remove-allowlisted-testing-principals. - ערך ריק מוחק הגדרה. לדוגמה, קובץ שמכיל את הערך
urlPatterns: []בקטעinteractiveFeatureConfigמסיר את כל תבניות ה-URL של התצוגה המקדימה של הקישורים. - פקודה שנכשלת לא משנה שום דבר. אם הערך לא תקין, הפקודה מדפיסה את השגיאה ומשאירה את ההגדרה כמו שהייתה.
- הבקשות מוגבלות בקצב. ה-API מגביל את מספר בקשות הקריאה והעדכון לדקה, לכל פרויקט ב-Cloud ולכל ארגון. כל פקודת
updateשולחת בקשת עדכון אחת. אם מוסיפים או מסירים בודקים באמצעות דגלים, הפקודה גם שולחת בקשת קריאה. כדי לשנות כמה הגדרות, מעבירים אותן בפקודה אחת או בקובץ אחד במקום להריץ פקודה לכל הגדרה.
מגבלות
- הפקודות נתמכות רק באפליקציות ל-Chat שנוצרו כתוספים ל-Google Workspace.
- הפקודות לא תומכות בחשבונות שירות או בהתחזות לחשבונות שירות. אתם צריכים להיכנס ל-CLI של gcloud באמצעות חשבון משתמש.
- לפרויקט בענן יש הגדרה אחת של אפליקציית Chat, והפקודות לא יכולות למחוק אותה. כדי למנוע מאנשים להשתמש באפליקציה ל-Chat, צריך להשבית אותה או למחוק את הפרויקט בענן.
- העדכון חל על אפליקציית הצ'אט בשידור חי. לפקודות אין מצב טיוטה או מצב הרצה לניסיון.
- בזמן שאפליקציית Chat מתפרסמת או נמצאת בבדיקה ב-Google Workspace Marketplace, הפקודות לא יכולות לשנות את השם המוצג, את הדמות, את התיאור, את הפקודות או את תבניות כתובות ה-URL של התצוגה המקדימה של הקישורים.
- הפקודות תומכות בהגדרות של המשאב
chatAppConfig. כדי לקבוע הגדרה שלא נכללת במשאב, צריך להשתמש במסוף Google Cloud.
פתרון בעיות
אם פקודה נכשלת, חפשו את הטקסט של הודעת השגיאה בטבלה הבאה. אם ההודעה מתחילה בסטטוס כמו INVALID_ARGUMENT, סימן ש-Google Workspace add-ons API דחה את הבקשה, והטקסט שאחרי הסטטוס מתאר את הבעיה.
| הודעת השגיאה מכילה | סיבה | פתרון |
|---|---|---|
Invalid choice: 'chat-app-config' או
Invalid choice: 'workspace-add-ons' |
הפקודה לא כוללת את beta, או שגרסת ה-CLI של gcloud לא כוללת את הפקודות. |
מתחילים את הפקודה עם gcloud beta workspace-add-ons chat-app-config. אם השגיאה נמשכת, מעדכנים את ה-CLI של gcloud לגרסה העדכנית. |
PROJECT ID |
הפרויקט מוגדר למספר פרויקט. | מגדירים את הפרויקט למזהה הפרויקט. |
Failed to parse value(s) in protobuf |
קובץ התצורה מכיל שדה שה-CLI של gcloud לא מזהה. הודעת השגיאה מציינת את שם השדה. | משווים את שם השדה לפלט של הפקודה describe. אם השדה חדש, צריך לעדכן את ה-CLI של gcloud לגרסה העדכנית. |
does not have permission to access projects instance |
ה-API דחה את הבקשה. הטקסט שאחרי ההודעה הזו מציין את הסיבה. לדוגמה:
|
בודקים את הדרישות בקטע לפני שמתחילים. |
INVALID_ARGUMENT |
אחד מהערכים לא תקין. לדוגמה, השם המוצג חייב להיות באורך של 3 עד 25 תווים, והתיאור באורך של 1 עד 40 תווים. אם ההודעה מכילה את הערך not found or deleted, מזהה הפרויקט שגוי. |
מתקנים את הערך שמתואר בהודעת השגיאה ומריצים שוב את הפקודה. |
FAILED_PRECONDITION |
האפליקציה ל-Chat לא מאפשרת את הבקשה. לדוגמה, הוא לא נוצר כתוסף ל-Google Workspace, או שהוא פורסם ב-Google Workspace Marketplace ואי אפשר לשנות את ההגדרה. | פועלים לפי ההוראות שמופיעות בהודעת השגיאה. כדי להגדיר אפליקציה ל-Chat שהיא לא תוסף ל-Google Workspace, צריך להשתמש במסוף Google Cloud או להמיר אותה. |
RESOURCE_EXHAUSTED או 429 |
ה-API קיבל יותר מדי בקשות לפרויקט בענן או לארגון בפרק זמן קצר. | מחכים דקה ומריצים שוב את הפקודה. |
איך מגדירים את האפליקציה ל-Chat באמצעות Google Workspace add-ons API
במקום להגדיר את אפליקציית הצ'אט באופן ידני במסוף Google Cloud, אתם יכולים לקרוא ולעדכן באופן פרוגרמטי את ההגדרות של אפליקציית צ'אט שנוצרה כתוסף ל-Google Workspace באמצעות המשאב chatAppConfig ב-Google Workspace add-ons API.
chatAppConfig הוא משאב יחיד (singleton) שתמיד קיים בכל פרויקט בענן. לפני ששומרים הגדרה בפעם הראשונה, המשאב מכיל הגדרה ריקה (שגם מוחזרת על ידי GetChatAppConfig אם קוראים את המשאב לפני השמירה הראשונה). מכיוון שהמשאב כבר קיים, אין צורך ליצור אותו בנפרד – משתמשים ב-UpdateChatAppConfig גם כדי לשמור את ההגדרה הראשונית וגם כדי לעדכן הגדרה קיימת.
דרישות מוקדמות ואימות
לפני שקוראים ל-GetChatAppConfig או ל-UpdateChatAppConfig, צריך להשלים את הדרישות המוקדמות הבאות:
- מפעילים את 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ו-chat.bots.getכדי לעדכן את ההגדרות (UpdateChatAppConfig).
-
- אם אתם משתמשים בספריית לקוח, התקינו את הגרסה העדכנית של ספריית הלקוח של Google Workspace add-ons API בשפה שלכם. רשימה של ספריות לקוח מופיעה במאמרי העזרה של Google Workspace add-ons API.
עדכון ההגדרות של אפליקציית 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)
מכסות שימוש
ל-methods של chatAppConfig יש מכסות לכל פרויקט. אם תחרגו מהמכסה, הבקשה תיכשל ויופיע קוד הסטטוס 429: Too many requests של HTTP. למידע על מגבלות המכסות, קראו את המאמר מגבלות השימוש ב-Google Workspace add-ons API.
פתרון בעיות במקרה של שגיאות
אם בקשת chatAppConfig נכשלת, צריך לבדוק את קוד הסטטוס של ה-HTTP ואת השדה message בתגובת השגיאה. בטבלה הבאה מפורטות שגיאות נפוצות, הסיבות להן ואיך לפתור אותן.
| קוד מצב HTTP | גורמים נפוצים | רזולוציה |
|---|---|---|
400: Bad Request (INVALID_ARGUMENT) |
|
בודקים את השדה message כדי לראות איזה שדה לא תקין, ומתקנים את הבקשה. במאמרי העזרה בנושא projects.chatAppConfig מפורטים השדות והערכים הנתמכים. |
400: Bad Request (FAILED_PRECONDITION) |
|
|
403: Forbidden (PERMISSION_DENIED) |
|
|
404: Not Found (NOT_FOUND) |
הפרויקט בענן בשם המשאב לא קיים, או שלמשתמש המאומת אין גישה אליו. | צריך לוודא שבשם המשאב מופיע מספר הפרויקט הנכון בפורמט projects/PROJECT_NUMBER/chatAppConfig, ושלמשתמש יש גישה לפרויקט ב-Cloud. |
429: Too Many Requests (RESOURCE_EXHAUSTED) |
חרגתם מהמכסה לכל פרויקט. | צריך להמתין ולנסות שוב מאוחר יותר. למידע על המגבלות, ראו מגבלות שימוש. |
שיקולים לגבי תוספים קיימים ל-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. במקום זאת, צריך להגדיר את אפליקציית הצ'אט במסוף Google Cloud, באמצעות ה-CLI של gcloud או באמצעות המשאב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.