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

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

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

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

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

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

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

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

מונחים נפוצים שמשמשים ב-Google Workspace Events API כוללים:

אירוע ב-Google Workspace

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

אירוע שקשור למינוי

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

אירוע במחזור חיים

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

מינוי ל-Google Workspace

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

משאב היעד

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

סוגי אירועים

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

נקודת קצה של התראות

נקודת הקצה שבה המינוי ל-Google Workspace מקבל אירועים. ‫Google Workspace Events API תומך בנושאים של Google Cloud Pub/Sub כנקודת קצה של התראות. מידע נוסף על שימוש ב-Google Cloud Pub/Sub זמין במאמרי העזרה של Google Cloud Pub/Sub.

אפשרויות של מטען ייעודי (payload)

נתוני האירועים שרוצים לקבל לגבי משאבים שהשתנו.

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

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

מידע נוסף זמין במדריכים הבאים:

• הרשמה לאירועים ב-Chat
• הרשמה לאירועים ב-Drive
• הרשמה לאירועים ב-Meet

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

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

• מאפיינים של CloudEvent.
• נתונים על משאב Google Workspace שהשתנה כתוצאה מהאירוע

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

מאפייני CloudEvent

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

נתוני אירוע

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

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

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

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

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

המינויים ל-Google Workspace Events 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 Protocol Binding for CloudEvents.

נושאים קשורים

• בחירת היקפי הרשאות של Google Workspace Events API
• יצירת מינוי ל-Google Workspace