הרשמה לאירועים באמצעות Google Workspace Events API

בדף הזה יש סקירה כללית של Google Workspace Event API ומוסבר איך אפשר להשתמש ב-API כדי להירשם לאירועים ב-Google Workspace.

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

איך האפליקציה מקבלת אירועים

כדי לאפשר לאפליקציה לקבל אירועים של Google Workspace, צריך להשתמש Google Workspace Event API ליצירת מינויים ל-Google Workspace במשאבי אנוש.

איור של האופן שבו Google Workspace Event API מעביר אירועים.
איור 1. דוגמה לאופן שבו Google Workspace Event API שולח אירועים אפליקציית Chat.

בדוגמה הבאה, Google Workspace Event API מספק אירועים באפליקציית Google Chat דרך מינוי:

  1. אפליקציית Chat נרשם למרחב משותף ב-Chat.
  2. המרחב המשותף ב-Chat ישתנה. למשל, פורסמה הודעה חדשה במרחב.
  3. אפליקציית Chat מספקת אירוע לנושא ב Google Cloud Pub/Sub, שמשמש כנקודת הקצה להתראות של המינוי. האירוע מכילה נתונים על מה שהשתנה. לדוגמה, עבור אירוע שעוסק באירוע חדש הודעה, האירוע מכיל פרטים על המשאב Message נוצר.
  4. אפליקציית Chat מעבדת את Google Cloud הודעת Pub/Sub שמכילה את האירוע, ובמקרה הצורך, מבוצעת פעולה.

מונחים חשובים

הרשימה הבאה מפרטת את המונחים הנפוצים Google Workspace Event API:

אירוע ב-Google Workspace

שינוי במשאב של Google Workspace. אפשר להזין אירועים בפורמט הבא: CloudEvents מפרט, ויכול להיות אירוע מינוי או אירוע במחזור חיים:

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

ישות בעלת שם שעוקבת אחרי משאב מ-Google Workspace תרגום מכונה. מינוי מיוצג על ידי Subscription משאב. מינוי מוגדר לפי הפרטים הבאים:

משאב יעד
המשאב של Google Workspace שרוצים לעקוב אחריו. משאב זה מיוצג בשדה targetResource של מינוי ל-Google Workspace. כל מינוי יכול רק לעקוב אחרי משאב אחד. כדי לראות אילו משאבים של Google Workspace ב-Google Workspace Event API יש תמיכה: אירועים נתמכים ב-Google Workspace.
סוגי אירועים
סוגי השינויים שרוצים לקבל עליהם התראות לגבי השינויים משאב היעד. לדוגמה, אם נרשמת אל מרחב ב-Google Chat, אפשר לבחור אם לקבל אירועים שקשורים אליו המרחב המשותף והמשאבים הצאצאים שלו, כמו מינויים והודעות.
נקודת הקצה של ההתראה
נקודת הקצה שבה המינוי ל-Google Workspace מקבל אירועים. ב-Google Workspace Event API יש תמיכה בנושאים של Google Cloud Pub/Sub בתור נקודת קצה של התראה. למידע נוסף על השימוש ב-Google Cloud Pub/Sub, לראות את מסמכי תיעוד של Google Cloud Pub/Sub.
אפשרויות מטען ייעודי (payload)
נתוני האירועים שברצונך לקבל על משאבים שהשתנו.

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

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

משאב יעד אופן הלימוד אירועים נתמכים מגבלות (אם רלוונטי)
Google Chat
מרחבים ב-Google Chat

כדי להירשם למרחב מסוים:

//chat.googleapis.com/spaces/SPACE_ID

כדי להירשם לכל המרחבים המשותפים שבהם המשתמשים חברים:

//chat.googleapis.com/spaces/-
  • הודעות
  • מועדון החברים
  • תגובות
  • רווח

מידע נוסף מופיע במאמר בנושא הרשמה לאירועים ב-Google Chat.		 המשתמש ב-Google Chat שמאשר את המינוי צריך להיות חברים במרחב המשותף דרך Google Workspace או Google חשבון.
משתמשי Google Chat //cloudidentity.googleapis.com/users/USER_ID
  • מועדון החברים

מידע נוסף מופיע במאמר בנושא הרשמה לאירועים ב-Google Chat.

המינוי מקבל רק אירועים לגבי המשתמש שאישר את המינוי. המשתמש לא יכול לאשר מינוי בשם משתמשים אחרים.
Google Meet
חדרי ישיבות ב-Google Meet //meet.googleapis.com/spaces/SPACE_ID
  • כנסים
  • סשנים של משתתפים
  • הקלטות
  • תמלילים

מידע נוסף מופיע במאמר הרשמה לאירועים ב-Google Meet.
משתמשי Google Meet //cloudidentity.googleapis.com/users/USER_ID
  • כנסים
  • סשנים של משתתפים
  • הקלטות
  • תמלילים

מידע נוסף מופיע במאמר הרשמה לאירועים ב-Google Meet.

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

  • הבעלים של המרחב המשותף.
  • המארגן של האירוע ביומן Google שמשויך למרחב לפגישה.

המבנה של אירועים ב-Google Workspace

אירועי Google Workspace פועלים לפי CloudEvents המפרט, שזו דרך מקובלת בתחום לתיאור נתוני אירועים. Google Workspace אירועים מכילים את הדברים הבאים:

בקטע הבא מוסבר המבנה של המאפיינים והנתונים של אירועים ב-Google Workspace.

מאפייני CloudEvent

האירועים ב-Google Workspace כוללים את הפרטים הבאים: מאפיינים של CloudEvents:

מאפיין תיאור דוגמה

datacontenttype

סוג הנתונים שהועברו באירוע.

application/json

id

מזהה של CloudEvent.

spaces/AAAABBBBBBB/spaceEvents/ABCDEFGHIJKLMNO

source

מקור האירוע. לאירועים ב-Google Workspace: זהו השם המלא של מקור המידע של המינוי. //workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg

specversion

גרסת המפרט של CloudEvents שמשמשת לאירוע הזה.

1.0

subject

המשאב ב-Google Workspace שבו התרחש האירוע.

//chat.googleapis.com/spaces/AAAABBBBBBB

time

חותמת הזמן שבה האירוע התרחש, בפורמט RFC 3339.

2023-09-07T21:37:36.260127Z

type

סוג האירוע ב-Google Workspace.

google.workspace.chat.message.v1.created

נתוני אירוע

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

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

כשיוצרים מינוי, אפשר לציין כמה נתוני משאבים כלולים באירועים שהאפליקציה מקבלת:

  • הכללת נתוני המשאבים: מכילה חלק מהשדות של השינוי או את כולם. משאב. אם תבחרו לכלול נתוני משאבים, המינוי שלכם משך הזמן מוגבל ל-4 שעות לכל היותר, או ל-24 שעות אם משתמשים בכל הדומיין בהענקת גישה.
  • החרגת נתוני משאבים: מכילה רק את השם של השינוי משאב. משך המינוי הוא עד 7 ימים. כדי לקבל פרטים על האירוע, תוכלו לשלוח שאילתה על המשאב באמצעות שם המשאב.

האפשרויות האלה לנתוני אירועים מיוצגות בעמודה payloadOptions של המינוי שלך.

אירועים כהודעות Google Cloud Pub/Sub

המינויים ל-Google Workspace Event API משתמשים ב-Google Cloud Pub/Sub נושאים בתור נקודת הקצה להתראות שמקבלת את Google Workspace אירועים. האירועים מקודדים כהודעות Google Cloud Pub/Sub. האפליקציה שלך יכול לעבד את הודעת Google Cloud Pub/Sub כדי לנקוט פעולה או להשיב לה האירוע.

בדוגמה הבאה מוצגת הודעת Google Cloud Pub/Sub שמכילה אירוע שקשור להודעה מעודכנת במרחב ב-Chat:

 {
    "message":
    {
        "attributes":
        {
            "ce-datacontenttype": "application/json",
            "ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
            "ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
            "ce-specversion": "1.0",
            "ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
            "ce-time": "2023-09-07T21:37:53.274191Z",
            "ce-type": "google.workspace.chat.message.v1.updated"
        },
        "data": "EVENT_DATA",
        "messageId": "PUBSUB_MESSAGE_ID",
        "orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
        "publishTime": "2023-09-07T21:37:53.713Z"
    }
}

שימו לב לשדות הבאים:

  • attributes: מאפיינים של CloudEvent, כולל סוג האירוע. במקרה הזה, האירוע עוסק בהודעה מעודכנת המרחב המשותף.
  • data: נתוני האירוע עם פרטים לגבי העדכון משאב spaces.message, בפורמט של מחרוזת בקידוד Base64.
  • messageId: המזהה של הודעת Google Cloud Pub/Sub.

מידע נוסף על האופן שבו CloudEvents מוגדרים ב-Google Cloud Pub/Sub ההודעות מפורטות במאמר קישור בין פרוטוקולי Google Cloud Pub/Sub ל-CloudEvents.