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

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

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

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

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

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

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

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

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

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

//chat.googleapis.com/spaces/SPACE

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

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

//chat.googleapis.com/spaces/-

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

//cloudidentity.googleapis.com/users/USER

כאשר USER הוא המזהה ב שם המשאב של משאב user ב-Chat API. פרטים נוספים זמינים במאמר זיהוי והגדרה של משתמשי 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 מכיל את עומס העבודה של האירוע. בעומס התועלת הזה יש מידע על המשאב ב-Google Workspace שהשתנה. לדוגמה, אם נרשמתם לאירועים של חברים במרחב משותף, עומס העבודה של האירועים האלה מכיל מידע על המשאב spaces.membership שהשתנה.

נתוני המשאבים בתוכן של האירוע

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

בטבלה הבאה מפורטות דוגמאות למטענים ייעודיים (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.