Google Chat

במסמך הזה מוסבר איך לשלב את Google Chat עם Google SecOps.

הרשאות למוצר

יצירה של חשבון שירות

  1. במסוף Google Cloud , בוחרים פרויקט קיים ב- Google Cloud או יוצרים פרויקט חדש. הערה: הפרויקט שנבחר Google Cloud צריך להיות חלק מהארגון ב- Google Cloud.
  2. לוחצים על ☰ תפריט ובוחרים באפשרות APIs & Services > Credentials.
  3. בחלק העליון של הדף, לוחצים על + CREATE CREDENTIALS > Service Account (יצירת אמצעי אימות > חשבון שירות).
  4. נותנים לחשבון השירות שם שיוצג במסוף.
  5. אופציונלי: מזינים תיאור לחשבון השירות.
  6. לוחצים על CREATE, ואז על CONTINUE ועל DONE כדי לסיים את יצירת חשבון השירות.

יצירת פרטי כניסה לחשבון שירות

  1. אחרי שיוצרים את חשבון השירות, מועברים לרשימת פרטי הכניסה שאפשר להשתמש בהם עבור Google Cloud הפרויקט. בקטע Service Accounts, לוחצים על חשבון השירות החדש שיצרתם. הוא ייקרא: service-account-name@project-name-XXXXXX.iam.gserviceaccount.com
  2. לוחצים על ADD KEY > Create new key (הוספת מפתח > יצירת מפתח חדש).
  3. משאירים את האפשרות JSON מסומנת ולוחצים על CREATE (יצירה).

הפעולה הזו תתחיל את ההורדה של קובץ האישורים שיידרש לכם כדי לגשת ל-API בתור חשבון השירות הזה.

הגדרת פרויקט חדש ב-Apps Script

  1. עוברים אל Google Apps Script.
  2. יוצרים פרויקט חדש ב-Apps Script.

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

    var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

  4. פותחים את קובץ פרטי הכניסה של חשבון השירות שהורד ממסוףGoogle Cloud .

  5. מעתיקים את הערך של private_key (הערך שמתחיל ב-‎-----BEGIN PRIVATE KEY-----‎) ומדביקים אותו ב-SERVICE_ACCOUNT_PRIVATE_KEY בפרויקט Apps Script.

  6. מעתיקים את הערך של client_email מקובץ ההרשאות ומדביקים אותו ב-SERVICE_ACCOUNT_EMAIL בפרויקט Apps Script.

  7. מקשרים את פרויקט Apps Script ל Google Cloud פרויקט שיצרתם.

  8. חוזרים אל מסוף Google Cloud ובוחרים באפשרות ☰ > IAM & Admin > Settings.

  9. מעתיקים את מספר הפרויקט שמוגדר בדף הזה.

  10. בפרויקט Apps Script, בוחרים באפשרות Project (פרויקט) בתפריט Settings (הגדרות) > Project (פרויקט) ומדביקים את מספר הפרויקט בתיבת הדו-שיח Enter Project Number here (הזנת מספר הפרויקט כאן). Google Cloud

  11. לוחצים על הגדרת פרויקט.

הפעלת Google Chat API

  1. עוברים אל ☰ > APIs & Services ובוחרים באפשרות Library.
  2. מחפשים את Google Chat API ולוחצים על התוצאה היחידה.
  3. לוחצים על הפעלה.

כך מפעילים את ה-API בפרויקט.

פריסת בוט

  1. בממשק המשתמש של Apps Script, עוברים אל פריסה > פריסה חדשה.
  2. בוחרים באפשרות הוספה לסוג הפריסה החדש.
  3. מזינים שם ותיאור לפריסה ולוחצים על שמירה.
  4. אחרי שמירת הפריסה, לוחצים על קבלת מזהה לצד הפריסה שיצרתם ומעתיקים את ערך מזהה הפריסה.

מגדירים את הבוט של Google Chat:

  1. במסוף Google Cloud , עוברים אל ☰ > APIs & Services > Dashboard.
  2. ברשימת ממשקי ה-API המופעלים, בוחרים באפשרות Google Chat API.
  3. לוחצים על ניהול כדי לפתוח את דף Google Chat API.

  4. בדף שנפתח, בוחרים בכרטיסייה הגדרה ומגדירים את הבוט:

    • בשדה שם האפליקציה, מזינים Google Security Operations Chat App.
    • בשדה כתובת ה-URL של האווטאר, מזינים את הכתובת https://developers.google.com/chat/images/chat-product-icon.png.
    • בשדה תיאור, מזינים Google SecOps Chat App that can be used to send messages from Google SecOps to a Google Chat Spaces.
    • בקטע Functionality, בוחרים באפשרות App works in spaces with multiple users.
    • בקטע Connection settings (הגדרות החיבור), בוחרים באפשרות Apps Script project (פרויקט Apps Script) ומדביקים את מזהה הפריסה שהתקבל מההליך Deploy a bot (פריסת בוט).
    • בקטע הרשאות, בוחרים באפשרות אנשים וקבוצות ספציפיים בדומיין ומציינים למי תהיה אפשרות ליצור אינטראקציה עם הצ'אטבוט.
    • לוחצים על Save. הגדרת האפליקציה הושלמה.

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

אחרי שמגדירים את השילוב, אפשר להשתמש בפעולה List Spaces (רשימת החללים) כדי לאחזר את החללים שאפליקציית Google SecOps יכולה לגשת אליהם (יכולה לשלוח אליהם הודעות).

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

הגדרת שילוב של Google Chat ב-Google SecOps

הוראות מפורטות להגדרת שילוב ב-Google SecOps מופיעות במאמר הגדרת שילובים.

פרמטרים של שילוב

משתמשים בפרמטרים הבאים כדי להגדיר את השילוב:

השם המוצג של הפרמטר סוג ערך ברירת המחדל חובה תיאור
כתובת ה-URL הבסיסית של ה-API String https://chat.googleapis.com/ כן כתובת ה-URL הבסיסית של ה-API שבה משתמש השילוב כדי להתחבר לשירות Google Chat.
חשבון השירות סיסמה לא רלוונטי כן תוכן קובץ ה-JSON של חשבון השירות שבו הצ'אטבוט משתמש כדי לעבוד עם שירות Google Chat.
אימות SSL תיבת סימון סימן אישור כן אם האפשרות הזו מופעלת, צריך לוודא שאישור ה-SSL של החיבור לשירות Google Chat תקף.

פעולות

פינג

תיאור

בודקים את הקישוריות ל-Google Chat באמצעות הפרמטרים שמופיעים בדף ההגדרות של השילוב בכרטיסייה Google Security Operations Marketplace.

ריצה

הפעולה הזו לא מופעלת על ישויות, ואין לה פרמטרים של קלט חובה.

תוצאות הפעולה

תוצאת סקריפט
שם התוצאה של הסקריפט אפשרויות ערך דוגמה
is_success נכון/לא נכון is_success:False
Case Wall
סוג התוצאה ערך/תיאור סוג
הודעת פלט*

הפעולה לא אמורה להיכשל או לעצור את ההרצה של חוברת ההדרכה:

אם הפעולה בוצעה בהצלחה: "Successfully connected to the Google Chat service with the provided connection parameters!" (החיבור לשירות Google Chat בוצע בהצלחה עם פרמטרי החיבור שסופקו).

הפעולה צריכה להיכשל ולהפסיק את ההרצה של מדריך ההפעלה:

אם מדווחת שגיאה קריטית, כמו פרטי כניסה שגויים או אובדן קישוריות: "החיבור לשירות Google Chat נכשל! השגיאה היא {0}".format(exception.stacktrace)"

 כללי

הצגת רשימה של מרחבים

תיאור

רשימת המרחבים שהבוט של Google Chat שהוגדר כרגע נוסף אליהם.

פרמטרים

השם המוצג של הפרמטר סוג ערך ברירת המחדל חובה תיאור
מפתח המסנן DDL

יש לבחור טווח

ערכים אפשריים:

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

לא צוינה

ערכים אפשריים:

  • לא צוינה
  • שווה
  • מכיל
 לא מציינים את לוגיקת הסינון שרוצים להחיל. לוגיקת הסינון פועלת על סמך הערך שמוגדר בפרמטר Filter Key (מפתח סינון).
ערך המסנן String לא רלוונטי לא

מציינים באיזה ערך להשתמש במסנן.

אם נבחרה האפשרות 'שווה', הפעולה תנסה למצוא את ההתאמה המדויקת בין התוצאות.

אם האפשרות 'מכיל' נבחרה, הפעולה מנסה למצוא תוצאות שמכילות את מחרוזת המשנה שצוינה.

אם לא מציינים ערך בפרמטר הזה, המסנן לא מופעל. לוגיקת הסינון פועלת על סמך הערך שמוגדר בפרמטר Filter Key (מפתח סינון).
מספר הרשומות המקסימלי שיוחזר מספר שלם 50 לא

מציינים את מספר הרשומות שיוחזרו.

אם לא מציינים כלום, הפעולה מחזירה 50 רשומות.
הכללת חברויות של משתמשים תיבת סימון התיבה לא מסומנת לא אם האפשרות הזו מופעלת, מידע על חברות של משתמשים יתווסף לטבלה של קיר המקרים של הפעולה ולתוצאת ה-JSON.

הפעלה ב-

הפעולה הזו לא מופעלת על ישויות.

תוצאות הפעולה

תוצאת סקריפט
שם התוצאה של הסקריפט אפשרויות ערך דוגמה
is_success נכון/לא נכון is_success:False
Case Wall
סוג התוצאה ערך / תיאור סוג
הודעת פלט*

הפעולה לא אמורה להיכשל או לעצור את ההרצה של חוברת ההדרכה:

אם הנתונים זמינים (is_success=true): 'נמצאו בהצלחה מרחבים שנוספו לקריטריונים שסופקו ב-Google Chat'.

אם הנתונים לא זמינים (is_success=false): 'לא נמצאו מרחבים שעומדים בקריטריונים שצוינו ב-Google Chat'

אם לפרמטר Filter Value (ערך המסנן) אין ערך (is_success=true):

"המסנן לא הוחל כי הפרמטר 'ערך המסנן' ריק".

הפעולה צריכה להיכשל ולהפסיק את ההרצה של מדריך ההפעלה:

אם הפרמטר Filter Key (מפתח מסנן) מוגדר לערך Select One (בחירת אפשרות אחת) והפרמטר Filter Logic (לוגיקת סינון) מוגדר לערך Equal (שווה) או Contains (מכיל):

"שגיאה בהפעלת הפעולה 'רשימת מרחבים'. הסיבה: צריך לבחור שדה מהפרמטר 'מפתח מסנן'".

אם מספקים ערך לא תקין לפרמטר Max Records to Return (מספר הרשומות המקסימלי להחזרה):

‫"Error executing action "List Spaces". Reason: "Invalid value was provided for "Max Records to Return". Positive number should be provided."

אם מדווחת שגיאה קריטית, כמו פרטי כניסה שגויים, אין חיבור לשרת או שגיאה אחרת:

‪"Error executing action "List Spaces". Reason: {0}''.format(error.Stacktrace)

 כללי
Case Wall Table

שם הטבלה: המרחבים הזמינים שאליהם הבוט צורף עמודות הטבלה: {fields}

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

 כללי

שליחת הודעה

תיאור

שליחת הודעה למרחב ב-Google Chat שאליו נוספה אפליקציית Google SecOps.

פרמטרים

השם המוצג של הפרמטר סוג ערך ברירת המחדל חובה תיאור
שם המרחב String לא רלוונטי כן

מציינים את שם המרחב שאליו רוצים לשלוח את ההודעה.

דוגמה לשם של חלל: AAAAdaTsel0
טקסט ההודעה String לא רלוונטי כן מציינים את הטקסט של ההודעה שרוצים לשלוח.

הפעלה ב-

הפעולה הזו לא מופעלת על ישויות.

תוצאות הפעולה

תוצאת סקריפט
שם התוצאה של הסקריפט אפשרויות ערך דוגמה
is_success נכון/לא נכון is_success:False
Case Wall
סוג התוצאה ערך / תיאור סוג
הודעת פלט*

הפעולה לא אמורה להיכשל או לעצור את ההרצה של חוברת ההדרכה:

אם ההודעה נשלחת בהצלחה (is_success=true): "ההודעה נשלחה בהצלחה".

הפעולה צריכה להיכשל ולהפסיק את ההרצה של מדריך ההפעלה:

אם מדווחת שגיאה קריטית, כמו היעדר חיבור או פרטי כניסה שגויים: "שגיאה בהפעלת הפעולה 'שליחת הודעה'. הסיבה: {0}''.format(error.Stacktrace)

 כללי

שליחת הודעה מתקדמת

תיאור

שליחת הודעה מתקדמת למרחב ב-Google Chat על סמך מטען ייעודי (payload) בפורמט JSON של ההודעה שסופקה.

פרמטרים

השם המוצג של הפרמטר סוג ערך ברירת המחדל חובה תיאור
שם המרחב String לא רלוונטי כן

מציינים את שם המרחב שאליו רוצים לשלוח את ההודעה.

דוגמה לשם של חלל: AAAAdaTsel0
מטען ייעודי (payload) של JSON בהודעה String ‪{"cards":[{"sections":[{"widgets":[{"image":{"imageUrl":"https://..."}},{"buttons":[{"textButton":{"text":"OPEN IN GOOGLE MAPS","onClick":{"openLink":{"url":"https://..."}}}}]}]}]}]} כן

מציינים את מטען ה-JSON הייעודי שיישלח עם ההודעה.

דוגמאות למטען ייעודי (payload) של הודעות זמינות במאמר הזה.

הפעלה ב-

הפעולה הזו לא מופעלת על ישויות.

תוצאות הפעולה

תוצאת סקריפט
שם התוצאה של הסקריפט אפשרויות ערך דוגמה
is_success נכון/לא נכון is_success:False
Case Wall
סוג התוצאה ערך / תיאור סוג
הודעת פלט*

הפעולה לא אמורה להיכשל או לעצור את ההרצה של חוברת ההדרכה:

אם ההודעה נשלחת בהצלחה (is_success=True): "ההודעה נשלחה בהצלחה".

הפעולה צריכה להיכשל ולהפסיק את ההרצה של מדריך ההפעלה:

אם מטען ה-JSON שסופק לא תקין: "שגיאה בהפעלת הפעולה 'שליחת הודעה מתקדמת'. סיבה: מטען ה-JSON של ההודעה שסופק לא תקין".

אם מדווחת שגיאה קריטית, כמו היעדר חיבור או פרטי כניסה שגויים: "שגיאה בהפעלת הפעולה 'שליחת הודעה מתקדמת'. הסיבה: {0}''.format(error.Stacktrace)

 כללי

הבעיה עדיין לא נפתרה? קבלת תשובות מחברי הקהילה וממומחי Google SecOps.