הגדרת Google Chat API

כל אפליקציה שאתם יוצרים ב-Google Chat צריכה פרויקט משלה ב-Google Cloud עם Chat API מופעל ומותאם.

כדי לבצע קריאות ל-API לקריאה בלבד עם אימות משתמשים, כמו קבלת מרחבים ורשימת הודעות, צריך רק להפעיל את ה-API וליצור לקוח OAuth.

כדי לבצע קריאות ל-API ליצירה, לעדכון ולמחיקה, או כדי לפרוס ולבדוק אפליקציית Chat אינטראקטיבית (שנוצרה כתוסף ל-Google Workspace שמרחיב את Chat), צריך גם להגדיר את Chat API. בהגדרות התצורה של Chat API מציינים את כל הפרטים על אפליקציית Chat, כולל השם המוצג, האווטאר, נקודות הקצה של הפריסה והתכונות האינטראקטיביות.

דרישות מוקדמות

• חשבון Google Workspace בתוכנית Business או Enterprise עם גישה ל-Google Chat.
• יוצרים פרויקט ב-Google Cloud.
• הגדרת מסך ההסכמה ל-OAuth
• הפעלת Google Chat API

בחירת שם מוצג, דמות ותיאור לאפליקציית Chat

כשמפעילים את Chat API, מגדירים את הפרטים של אפליקציית Chat שמוצגים למשתמשים ב-Chat, כולל שם לתצוגה, דמות ותיאור. הפרטים האלה מופיעים רק ב-Chat. כדי לפרסם את אפליקציית Chat ב-Marketplace, צריך גם לציין את הפרטים שמופיעים בדף האפליקציה ב-Marketplace.

לפני שמגדירים אפליקציה ל-Chat, צריך להכין את המידע הבא:

שדה	תיאור	פורמט
שם האפליקציה	השם המוצג של אפליקציית Chat.	עד 25 תווים אלפאנומריים
כתובת ה-URL של האווטאר	התמונה שמוצגת כדמות של אפליקציית Chat.	כתובת URL מסוג HTTPS שמפנה לתמונה גרפית מרובעת (PNG או JPEG). הגודל המומלץ הוא ‎256 x 256 פיקסלים ומעלה.
תיאור	תיאור קצר של מטרת אפליקציית הצ'אט.	עד 40 תווים אלפאנומריים

השם, התמונה והתיאור של האפליקציה ל-Chat מוצגים למשתמשים בממשק המשתמש של Chat. בבקשות כתיבה מסוימות ל-Chat API, ‏ Chat משתמש במידע הזה כדי לשייך את הפעולות שאפליקציית Chat מבצעת ב-Chat.

לדוגמה, אם מבצעים קריאה ל-method‏ spaces.create(), השם של אפליקציית Chat מופיע בתיאור של מי שיצר את המרחב, כמו שמוצג בתמונה הבאה:

איור 1. הודעת השיוך שמוצגת ב-Chat כשמשתמשים בשיטה spaces.create() כדי ליצור מרחב בשם משתמש.

כדי לקיים אינטראקציה עם אפליקציות ל-Chat, המשתמשים יכולים גם לראות את המידע הזה או להשתמש בו בדרכים הבאות:

• מזכירים את אפליקציית Chat באמצעות @ כדי לצרף אותה למרחב או לשלוח לה הודעה.
• מחפשים את אפליקציית Chat ומתחילים איתה צ'אט ישיר. בתפריט אפליקציות, בצ'אטים ישירים מוצגים השם והדמות של אפליקציית Chat.
• בסרגל הכתיבה, המשתמשים יכולים לעיין באפליקציות ל-Chat ולראות את השם, הדמות והתיאור שלהן.

הגדרת אפליקציית Chat במסוף Google Cloud

אחרי שמקבלים את פרטי אפליקציית Chat, פותחים את פרויקט בענן ומגדירים את Chat API:

1. במסוף Google Cloud, עוברים לדף Chat API ולוחצים על Configuration:

   מעבר לדף ההגדרה של Chat API

2. בקטע Application info (פרטי האפליקציה), ממלאים את השדות App name (שם האפליקציה), Avatar URL (כתובת ה-URL של האווטאר) ו-Description (תיאור).

3. בקטע תכונות אינטראקטיביות, מגדירים אם אפליקציית הצ'אט מגיבה לאינטראקציות של המשתמשים:

   הערה: אם אפליקציית Chat שלכם קוראת רק ל-Chat API ולא מקבלת אינטראקציות מהמשתמשים או מגיבה להן, אל תפעילו את האפשרות הפעלת תכונות אינטראקטיביות ודלגו לשלב הבא.

   כדי ליצור אפליקציית צ'אט אינטראקטיבית, מפעילים את האפשרות הפעלת תכונות אינטראקטיביות ופועלים לפי השלבים הבאים:

   1. בקטע Functionality (פונקציונליות):
      • אופציונלי: בוחרים באפשרות דף הבית של אפליקציית התמיכה כדי להציג כרטיס בדף הבית בכרטיסייה דף הבית של צ'אטים אישיים באפליקציית Chat.
      • בוחרים באפשרות הצטרפות למרחבים ולשיחות קבוצתיות כדי לאפשר התקנה ושימוש באפליקציית Chat. כברירת מחדל, המשתמשים יכולים להתקין את האפליקציה ל-Chat ולשלוח לה הודעות במרחב ייעודי בינם לבין האפליקציה. המשתמשים יכולים גם להוסיף את האפליקציה ל-Chat למרחבים עם כמה אנשים ולקיים איתה אינטראקציה.

   2. בקטע הגדרות הקישור, בוחרים את הארכיטקטורה שרוצים להשתמש בה כדי לקבל אובייקטים של אירועים מ-Chat:

      • כדי להשתמש בשירות HTTP, בוחרים באפשרות כתובת URL של נקודת קצה (endpoint) בפרוטוקול HTTP ומזינים כתובת URL.
      • כדי להשתמש בפרויקט של Google Apps Script, בוחרים באפשרות Apps Script ומזינים מזהה פריסה של הפרויקט.
      • כדי להשתמש בסוכן Dialogflow, בוחרים באפשרות Dialogflow, בוחרים באפשרות Dialogflow CX או Dialogflow ES ומזינים את שם המשאב של הסוכן.
      • כדי להשתמש ב-Pub/Sub, בוחרים באפשרות Cloud Pub/Sub ומזינים את שם הנושא.
      אזהרה: אם מזהה הפריסה של Apps Script כבר מופיע, פרויקט הענן מקושר לתוסף קיים של Google Workspace. אם תעדכנו את מזהה הפריסה ב-Chat API, מזהה הפריסה יתעדכן גם בתוסף שלכם, וזה עלול להשפיע על כרטיס המוצר ב-Google Workspace Marketplace. כדי לבדוק את הגדרת התוסף, אפשר לעיין במאמר הגדרת האפליקציה ב-Google Workspace Marketplace SDK.

   3. אופציונלי: כדי להפנות אובייקטים של אירועים לנקודות קצה או לפונקציות ספציפיות, עוברים אל הגדרות חיבור > טריגרים ומזינים או מעדכנים את נקודות הקצה או הפונקציות של הקריאה החוזרת עבור טריגרים של צ'אט:

      הערה: ב-Apps Script, אם לא מעדכנים את הטריגרים, צריך להטמיע את פונקציות הקריאה החוזרת שמוגדרות כברירת מחדל ומאוכלסות בסעיף הזה (למשל onMessage,‏ onAddedToSpace,‏ onRemovedFromSpace,‏ onAppCommand ו-onAppHome).
      • דף הבית של האפליקציה (אם האפשרות תמיכה בדף הבית של האפליקציה מופעלת): משתמש פותח את הכרטיסייה דף הבית בצ'אט ישיר עם אפליקציית Chat.
      • נוספה למרחב: משתמש מוסיף את אפליקציית Chat לשיחה קבוצתית או למרחב, או מתקין את אפליקציית Chat לצ'אטים אישיים.
      • הודעה: משתמש שולח הודעה לאפליקציית Chat. לדוגמה, משתמש שולח הודעה ישירה לאפליקציית Chat או מתייג את אפליקציית Chat במרחב עם כמה אנשים.
      • הוסר מהמרחב: משתמש מסיר את ההתקנה של אפליקציית Chat או מסיר אותה ממרחב.
      • פקודה לאפליקציה: משתמש מפעיל פקודה מהירה, פקודה דרך שורת הפקודות או פעולה בהודעה מאפליקציית Chat.

   4. אופציונלי: מוסיפים תכונות אינטראקטיביות אחרות, כמו הצעה לפרומפט, פקודות (פקודות מהירות, פקודה דרך שורת הפקודות ופעולות בהודעות) או תצוגה מקדימה של קישורים.

   5. בקטע Visibility (חשיפה), מציינים את כתובת האימייל כדי שתוכלו להתקין ולבדוק את האפליקציה ל-Chat לפני הפרסום ב-Google Workspace Marketplace. אתם יכולים לציין עד חמישה אנשים, או קבוצה אחת או יותר ב-Google Workspace של הארגון.

4. אופציונלי: בקטע Logs, מסמנים את תיבת הסימון Log errors to Logging כדי להשתמש ב-Google Cloud Logging. מידע נוסף מופיע במאמר בנושא שאילתת יומני שגיאות של אפליקציות ל-Chat.

5. לוחצים על שמירה.

אחרי ששומרים את ההגדרה, כל מי שצוין בהגדרת החשיפה של Chat API יכול להתקין את אפליקציית Chat, לבדוק אותה או להשתמש בה. כדי להתחיל לבדוק את אפליקציית Chat ולנפות בה באגים, אפשר לעיין במאמר בנושא בדיקת תכונות אינטראקטיביות באפליקציות ל-Google Chat.

שיקולים לגבי תוספים קיימים ל-Google Workspace

אפליקציות ל-Chat דורשות הגדרה שונה בהשוואה לתוספים של Google Workspace שמרחיבים את האפליקציות האחרות של Google Workspace. אם התוסף מרחיב אפליקציות אחרות של Google Workspace, כדאי לשקול את הדרישות הבאות להגדרת אפליקציית Chat:

• גם משתמשים פרטיים וגם אדמינים ב-Google Workspace צריכים להיות מסוגלים להתקין את התוסף שלכם מ-Marketplace. אתם מגדירים את הגדרות ההתקנה האלה ב-Google Workspace Marketplace SDK.
• אפליקציות ל-Chat לא משתמשות בשם ובלוגו שאתם מגדירים לאפליקציות אחרות של Google Workspace באובייקט addons.common של קובץ המניפסט.
• בתוספים שפורסמו ב-Google Workspace Marketplace, אי אפשר לשמור טיוטה של שינויים בהגדרות התצורה של Google Chat API. אחרי שמעדכנים ושומרים את הגדרות התצורה של Chat API, אפליקציית Chat המעודכנת זמינה מיידית לכל המשתמשים הקיימים. כדי לעדכן את כרטיס המוצר ב-Marketplace, אפשר ליצור טיוטה לפני ששולחים שינויים.
• אם יצרתם את התוסף באמצעות Apps Script:
  • צריך להשתמש באותו מזהה פריסה של Apps Script שבו השתמשתם בשאר הגדרות התוסף.
  • אי אפשר להשתמש בכלי לעריכת סקריפטים של Apps Script כדי להתקין פריסות לבדיקה ב-Chat. במקום זאת, צריך להתקין אותם ישירות מממשק המשתמש של Chat.
• אם יצרתם את התוסף באמצעות שירות HTTP, אל תכללו במניפסט ובפריסות שאתם יוצרים באמצעות Google Workspace add-ons API פרטים על הגדרת אפליקציית Chat. פריסות HTTP שאתם מציינים ב-Google Workspace Marketplace SDK משמשות רק לאפליקציות אחרות של Google Workspace.

איך נותנים לאנשים אחרים הרשאה להגדיר את Chat API

אתם יכולים לתת למשתמשים ספציפיים גישה לדף ההגדרות של אפליקציות ל-Chat על ידי הקצאת תפקיד בממשק לניהול זהויות והרשאות גישה (IAM) ב-Google Cloud: בעלים של אפליקציות ל-Chat או צפייה באפליקציות ל-Chat. משתמשים שהתפקידים האלה הוקצו להם לא יכולים לעבור לדף ההגדרות של אפליקציות ל-Chat באמצעות לוח הבקרה APIs & Services, אבל הם יכולים לגשת לדף ההגדרות באמצעות מעבר למסוף Google Cloud עבור פרויקט Cloud המארח של האפליקציה ל-Chat, באופן הבא:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

כאשר PROJECT_ID הוא מזהה הפרויקט של פרויקט Google Cloud שבו מתארחת אפליקציית Chat.

משתמשים עם תפקידים בפרויקט יכולים גם לגשת לדף ההגדרות של האפליקציה.

משתמשים עם תפקידים מותאמים אישית שכוללים את ההרשאות resourcemanager.projects.(get|update) לא יכולים לגשת להגדרות של אפליקציית Chat. לתפקידים בהתאמה אישית, משתמשים בהרשאות chat.bots.(get|update).

נושאים קשורים

• בחירת ארכיטקטורה של אפליקציה ל-Chat
• קבלת אינטראקציות של משתמשים ושליחת תגובות אליהן
• בדיקת תכונות אינטראקטיביות באפליקציות ל-Google Chat

אפליקציות ל-Chat שהן לא תוספים: הגדרה של Google Chat API

אם אתם מנהלים אפליקציית Chat שהיא לא תוסף ל-Google Workspace, ההגדרה שלכם משתמשת בנקודת קצה אחת לכל אירועי האינטראקציה, ולא בטריגרים לכל אירוע:

1. במסוף Google Cloud, עוברים לדף Configuration של Chat API:

   מעבר לדף ההגדרה של Chat API

2. בקטע תכונות אינטראקטיביות, מפעילים את האפשרות הפעלת תכונות אינטראקטיביות.

3. מבטלים את הסימון של Build this Chat app as a Google Workspace add-on (פיתוח אפליקציית Chat כתוסף ל-Google Workspace). תיפתח תיבת דו-שיח שבה תתבקשו לאשר את הפעולה. בתיבת הדו-שיח, לוחצים על השבתה.

4. בקטע פונקציונליות, בוחרים באפשרות תמיכה בדף הבית של האפליקציה או באפשרות הצטרפות למרחבים ולשיחות קבוצתיות לפי הצורך.

5. בקטע הגדרות חיבור, מציינים נקודת קצה אחת לאפליקציית Chat (כתובת URL של נקודת קצה מסוג HTTP, מזהה פריסה של Apps Script, שם נושא של Cloud Pub/Sub או Dialogflow).

6. מגדירים את האפשרויות פקודות, תצוגה מקדימה של קישורים, חשיפה ויומנים (אלה אפשרויות לא חובה), ואז לוחצים על שמירה.

כדי לשדרג אפליקציית Chat שהיא לא תוסף לתוסף ל-Google Workspace שמרחיב את Google Chat, אפשר לעיין במאמר בנושא המרת אפליקציית Google Chat לתוסף ל-Google Workspace.