הרשמה לאירועים של Google Chat

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

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

אירועים נתמכים ב-Chat

מינויים ל-Google Workspace מאפשרים לקבל אירועים לגבי סוגי השינויים הבאים ב-Chat:

  • הודעות חדשות, מעודכנות או שנמחקו במרחב.
  • תגובות חדשות או תגובות שהוסרו להודעה.
  • חברים חדשים, מעודכנים או שהוסרו מהמרחב.
  • שינויים במרחב שאליו נרשמתם, כמו שם או תיאור מעודכנים של המרחב.

משאבים שאפשר לעקוב אחרי אירועים שקורים בהם

כדי לקבל אירועים, צריך לציין משאב של Chat למעקב, שנקרא משאב היעד של המינוי.

‫Google Workspace Events API תומך במשאבי היעד הבאים של Chat:

משאב היעד אופן הלימוד מגבלות
רווח

//chat.googleapis.com/spaces/SPACE

כאשר SPACE הוא המזהה ב שם המשאב של משאב Chat API space. אפשר לאתר את המזהה בכתובת ה-URL של המרחב או באמצעות ה-method‏ spaces.list().

 משתמש Chat או אפליקציית Chat שמאשרים את המינוי צריכים להיות חברים בחלל באמצעות חשבון Google Workspace או חשבון Google. תמיכה:
כל המרחבים של משתמש

//chat.googleapis.com/spaces/-

 המינוי מקבל רק אירועים של המרחבים שבהם המשתמש הוא חבר דרך חשבון Google Workspace או חשבון Google. תומך רק באימות משתמש.
משתמש

//cloudidentity.googleapis.com/users/USER

כאשר USER הוא המזהה ב שם המשאב של משאב Chat API user. פרטים נוספים זמינים במאמר בנושא זיהוי משתמשי Google Chat וציון שלהם.

המנוי מקבל רק אירועים שקשורים למשתמש שאישר את המנוי. משתמש לא יכול לאשר מינוי בשם משתמשים אחרים. תומך רק באימות משתמש.

סוגי אירועים ליצירת מינויים

כשיוצרים מינוי, משתמשים בשדה eventTypes[] כדי לציין אילו סוגי אירועים רוצים לקבל. סוגי האירועים מעוצבים לפי המפרט של CloudEvents, למשל google.workspace.APPLICATION.RESOURCE.VERSION.ACTION.

לדוגמה, כדי לקבל אירועים לגבי משתמשים שמצטרפים למרחב ב-Chat, צריך לציין את המרחב כמשאב היעד ואת סוג האירוע כ-google.workspace.chat.membership.v1.created. כדי לקבל אירועים לגבי משתמש מסוים שמצטרף למרחב כלשהו, צריך לציין את המשתמש כמשאב היעד ואת סוג האירוע כ-google.workspace.chat.membership.v1.created. מידע נוסף על אופן הפעולה של אירועים זמין במאמר מבנה האירועים ב-Google Workspace.

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

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

google.workspace.chat.message.v1.created

space.message
הודעה מתעדכנת.

google.workspace.chat.message.v1.updated

space.message
הודעה נמחקת.

google.workspace.chat.message.v1.deleted

space.message
נוצרת תגובה.

google.workspace.chat.reaction.v1.created

space.message.reaction
תגובה באמוג'י נמחקת.

google.workspace.chat.reaction.v1.deleted

space.message.reaction
המשתמש יצורף למרחב.

google.workspace.chat.membership.v1.created

space.membership
הפרטים של משתתף במרחב עודכנו.

google.workspace.chat.membership.v1.updated

space.membership
משתמש הוסר מהמרחב.

google.workspace.chat.membership.v1.deleted

space.membership
המרחב המשותף מתעדכן.

google.workspace.chat.space.v1.updated

space
המרחב נמחק.

google.workspace.chat.space.v1.deleted

space
מינויים למשתמשים  
המשתמש מצטרף למרחב.

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

google.workspace.chat.membership.v1.created

space.membership
החברות של המשתמש במרחב המשותף מתעדכנת.

google.workspace.chat.membership.v1.updated

space.membership
המשתמש יוסר כחבר ישיר במרחב.

google.workspace.chat.membership.v1.deleted

space.membership

סוגי אירועים באצווה (פלט בלבד)

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

לדוגמה, אם משתמש מוסיף 20 משתמשים למרחב בו-זמנית, יכול להיות שאפליקציית Chat תקבל אירוע אצווה (google.workspace.chat.membership.v1.batchCreated). מטען הנתונים של האירוע מכיל רשימה של כל משאבי Membership המשתמשים החדשים שנוצרו כשהמשתמש הוסיף את החברים למרחב.

מקבלים אירוע אצווה לכל סוג אירוע שנרשמים אליו, כך שלא צריך לציין אירועי אצווה כשיוצרים מינוי. לדוגמה, אם נרשמתם למינוי של תגובות חדשות (google.workspace.chat.reaction.v1.created), אפליקציית Chat מוגדרת באופן אוטומטי לקבל אירועי תגובה בקבוצות (google.workspace.chat.reaction.v1.batchCreated).

בטבלה הבאה מוצגים אירועים אפשריים של קבוצות למינוי:

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

google.workspace.chat.message.v1.batchCreated
כמה הודעות מתעדכנות.

google.workspace.chat.message.v1.batchUpdated
כמה הודעות נמחקות.

google.workspace.chat.message.v1.batchDeleted
נוצרות כמה תגובות באמוג'י.

google.workspace.chat.reaction.v1.batchCreated
נמחקו כמה תגובות באמוג'י.

google.workspace.chat.reaction.v1.batchDeleted
כמה משתתפים נוספו למרחב המשותף שאליו נרשמתם, או שהמשתמש שאליו נרשמתם נוסף לכמה מרחבים.

google.workspace.chat.membership.v1.batchCreated
מתעדכנים כמה מינויים במרחב המשותף שאליו נרשמתם או אצל המשתמש שאליו נרשמתם.

google.workspace.chat.membership.v1.batchUpdated
מספר משתמשים הוסרו מהמרחב המשותף שהמשתמש רשום אליו, או שהמשתמש הוסר מכמה מרחבים.

google.workspace.chat.membership.v1.batchDeleted
במרחב יש כמה עדכונים.

google.workspace.chat.space.v1.batchUpdated

נתוני אירוע

בקטע הזה מתוארים נתוני אירועים ומטענים לדוגמה של אירועים ב-Chat.

כשמינוי ל-Google Workspace מקבל אירוע מ-Chat, השדה data מכיל את מטען הייעודי (payload) של האירוע. מטען הנתונים הזה מכיל מידע על משאב Google Workspace שהשתנה. לדוגמה, אם נרשמתם לאירועים שקשורים לחברות במרחב, מטען הייעודי (payload) של האירועים האלה מכיל מידע על משאב spaces.membership שעבר שינוי.

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

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

בטבלה הבאה מופיעות דוגמאות למטענים ייעודיים (payloads) של JSON להרשמה למינוי של מרחב ב-Chat‏ spaces/AAAABBBBBB. לכל אירוע שהמינוי מקבל, המטען הייעודי (payload) מופיע בשדה data של האירוע:

דוגמה סוג האירוע מטען ייעודי (payload) של JSON

משתמש מפרסם הודעה במרחב עם הכיתוב "Hello world".

google.workspace.chat.message.v1.created

כולל נתוני משאבים:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID",
        "sender":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/SPACE_ID/threads/THREAD_ID"
        },
        "space":
        {
            "name": "spaces/SPACE_ID"
        },
        "argumentText": "Hello world"
    }
}

לא כולל נתוני משאבים:

{
    "message":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID"
    }
}
משתמש הופך למנהל של מרחב.

google.workspace.chat.membership.v1.updated

כולל נתוני משאבים:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID",
        "state": "JOINED",
        "member":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}

לא כולל נתוני משאבים:

{
    "membership":
    {
        "name": "spaces/SPACE_ID/members/MEMBER_ID"
    }
}
משתמש מעדכן את התיאור של המרחב ל'צוות המכירות של Cymbal Labs'. google.workspace.chat.space.v1.updated

כולל נתוני משאבים:

{
    "space":
    {
        "name": "spaces/SPACE_ID",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}

לא כולל נתוני משאבים:

{
    "space":
    {
        "name": "spaces/SPACE_ID"
    }
}
שני משתמשים ב-Chat נוספו למרחב באותו הזמן. google.workspace.chat.membership.v1.batchCreated

כולל נתוני משאבים:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID",
            "state": "JOINED",
            "member":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}

לא כולל נתוני משאבים:

{
    "memberships": [
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        },
        {
          "membership": {
            "name": "spaces/SPACE_ID/members/MEMBER_ID"
          }
        }
    ]
}
משתמש מגיב להודעה באמוג'י 😊. google.workspace.chat.reaction.v1.created

כולל נתוני משאבים:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        "user":
        {
            "name": "users/USER_ID",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}

לא כולל נתוני משאבים:

{
    "reaction":
    {
        "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
    }
}
המשתמשים מגיבים להודעה באמוג'י 😊 ובאמוג'י 😸. google.workspace.chat.reaction.v1.batchCreated

כולל נתוני משאבים:

{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
            "user":
            {
                "name": "users/USER_ID",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}

לא כולל נתוני משאבים:

{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID"
        },
        "reaction": {
            "name": "spaces/SPACE_ID/messages/MESSAGE_ID/reactions/REACTION_ID",
        }
      }
    ]
}

מגבלות
  • במינויים למשתמשים, אירועים לגבי חברים חדשים בצ'אטים ישירים או בצ'אטים קבוצתיים ללא שם (google.workspace.chat.membership.v1.created), מופעלים רק אחרי פרסום ההודעה הראשונה.
  • כדי לקבל אירועים שקשורים לחברות במרחב, המשתמש או אפליקציית Chat צריכים להיות חברים ישירים במרחב. אם הם נוספו, עודכנו או הוסרו בעקיפין מהמרחב דרך קבוצה ב-Google, המינוי לא יקבל את אירועי החברות האלה. כדי להבין איך עובד החברות בקבוצות Google, אפשר לקרוא את המאמר בנושא צירוף קבוצות מ'קבוצות Google' למרחבים משותפים.