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

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

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

משאבי היעד הנתמכים של Chat

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

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

אירועים נתמכים ב-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

נתוני אירוע

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

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

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

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

בטבלה הבאה מוצגות דוגמאות למטענים ייעודיים (payloads) של JSON למינוי למרחב המשותף ב-Chat spaces/AAAABBBBBB. לכל אירוע שהמינוי מקבל, המטען הייעודי (Payload) מופיע בשדה 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 למרחבים משותפים מוסבר איך פועל החברות בקבוצות Google.