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

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

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

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

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

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

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

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

ב-Google Workspace Event API יש תמיכה במשאבי היעד הבאים לצ'אט:

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

//chat.googleapis.com/spaces/SPACE

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

 המשתמש ב-Chat שמאשר את המינוי צריך להיות חברים במרחב המשותף דרך Google Workspace או Google חשבון.
כל המרחבים המשותפים של המשתמש

//chat.googleapis.com/spaces/-

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

//cloudidentity.googleapis.com/users/USER

כאשר USER הוא המזהה שם המשאב של משאב ה-API ל-Chat 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 עשויה גם לקבל אירועים מרובים. אירוע באצווה הוא אירוע שמייצג הרבה אירועים מאותו סוג שמתרחשים בסרטון Shorts פרק זמן מסוים. המטען הייעודי (Payload) של אירוע באצווה מכיל רשימה של כל הנתונים שהשתנו במשאבי אנוש.

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

נתוני אירוע

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

כשהמינוי שלך ל-Google Workspace מקבל אירוע מ- Chat, data מכיל את המטען הייעודי (payload) של האירוע. המטען הייעודי כולל מידע על המשאב של Google Workspace שהשתנה. לדוגמה, אם נרשמתם ל- אירועי חברות במרחב, המטען הייעודי (payload) של האירועים האלה מכיל מידע על 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, המינוי לא לקבל את אירועי החברות האלה. כדי להבין איך עובד החברות בקבוצות Google, אפשר לעיין במאמר הבא: מצרפים למרחבים משותפים קבוצות ב-Google.