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

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

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

מקורות מידע נתמכים לטירגוט ב-Chat

Google Workspace Event API תומך במינויים הבאים:

  • מרחבים משותפים, מיוצגים בתור משאבים של space
  • משתמשים, מיוצגים כמשאבי Cloud Identity API user

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

מינויים ל-Google Workspace מאפשרים לקבל ב-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

נתוני אירוע

בקטע הזה מתוארים נתוני אירועים ומטענים ייעודיים (payloads) לאירועים ב-Chat.

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

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

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

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

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

משתמש מפרסם במרחב המשותף הודעה שבה כתוב 'שלום עולם'.

google.workspace.chat.message.v1.created

כולל נתוני משאבים
{
    "message":
    {
        "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD",
        "sender":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "createTime": "2023-09-07T21:37:36.260127Z",
        "text": "Hello world",
        "thread":
        {
            "name": "spaces/AAAABBBBBB/threads/EEEEEEEEEEEE"
        },
        "space":
        {
            "name": "spaces/AAAABBBBBB"
        },
        "argumentText": "Hello world"
    }
}
לא כולל נתוני משאבים
{
    "message":
    {
        "name": "spaces/AAAABBBBBB/messages/CCCCCCCCC.DDDDDDDDD"
    }
}
משתמש הופך למנהל/ת של המרחב המשותף.

google.workspace.chat.membership.v1.updated

כולל נתוני משאבים
{
    "membership":
    {
        "name": "spaces/AAAABBBBBB/members/1234567890987654321",
        "state": "JOINED",
        "member":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "createTime": "1970-01-01T00:00:00Z",
        "role": "ROLE_MANAGER"
    }
}
לא כולל נתוני משאבים
{
    "membership":
    {
        "name": "spaces/AAAABBBBBB/members/1234567890987654321"
    }
}
משתמש מעדכן את התיאור של המרחב המשותף ל'צוות המכירות של Cymbal Labs'. google.workspace.chat.space.v1.updated
כולל נתוני משאבים
{
    "space":
    {
        "name": "spaces/AAAABBBBBB",
        "displayName": "Cymbal Sales",
        "spaceThreadingState": "THREADED_MESSAGES",
        "spaceType": "SPACE",
        "spaceDetails":
        {
            "description": "Sales team for Cymbal Labs."
        },
        "spaceHistoryState": "HISTORY_ON"
    }
}
לא כולל נתוני משאבים
{
    "space":
    {
        "name": "spaces/AAAABBBBBB"
    }
}
שני משתמשי Chat נוספו למרחב המשותף בו-זמנית. google.workspace.chat.membership.v1.batchCreated
כולל נתוני משאבים
{
    "memberships": [
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/1234567890987654321",
            "state": "JOINED",
            "member":
            {
                "name": "users/1234567890987654321",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        },
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/987654321234567890",
            "state": "JOINED",
            "member":
            {
                "name": "users/987654321234567890",
                "type": "HUMAN"
            },
            "createTime": "1970-01-01T00:00:00Z",
            "role": "ROLE_MEMBER"
          }
        }
    ]
}
לא כולל נתוני משאבים
{
    "memberships": [
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/1234567890987654321"
          }
        },
        {
          "membership": {
            "name": "spaces/AAAABBBBBB/members/98765432123456789019"
          }
        }
    ]
}
משתמש מגיב להודעה עם האמוג'י 😊. google.workspace.chat.reaction.v1.created
כולל נתוני משאבים
{
    "reaction":
    {
        "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
        "user":
        {
            "name": "users/1234567890987654321",
            "type": "HUMAN"
        },
        "emoji":
        {
            "unicode": "😊"
        }
    }
}
השמטת נתוני משאבים
{
    "reaction":
    {
        "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
    }
}
משתמשים מגיבים להודעה באמוג'י 😊 ובאמוג'י 😸. google.workspace.chat.reaction.v1.batchCreated
כולל נתוני משאבים
{
    "reactions": [
        {
          "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222",
            "user":
            {
                "name": "users/1234567890987654321",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😊"
            }
          }
        },
        {
          "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
            "user":
            {
                "name": "users/98765431234564321",
                "type": "HUMAN"
            },
            "emoji":
            {
                "unicode": "😸"
            }
          }
        }
    ]
}
השמטת נתוני משאבים
{
    "reactions": [
      {
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/1111111111111111.222222222222222"
        },
        "reaction": {
            "name": "spaces/AAAABBBBBB/messages/123456789.123456789/reactions/3333333333333333.444444444444444",
        }
      }
    ]
}

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