סקירה כללית על השירות
כשמשתמש מפעיל אינטראקציה באפליקציה מארחת נתמכת (Gmail, יומן Google, Google Drive, Google Chat, Google Docs, Google Sheets, Google Slides או Workspace Studio), המארח שולח מטען ייעודי (payload) של אירוע HTTP POST לכתובת ה-URL להחזרה (callback) שהגדרתם לתוסף (/*).
נקודת הקצה של התוסף צריכה לקבל מטען ייעודי (payload) של בקשת EventObject ולהחזיר אחד מחמשת הסוגים התקינים של תגובות JSON שמתועדים בקטע תגובה: HandleEventResponse.
חוזה נקודת הקצה של ה-webhook
| שיטה | הנתיב של נקודת הקצה | גוף הבקשה | גוף התשובה |
|---|---|---|---|
POST |
/* (או נתיב הקריאה החוזרת שהוגדר) |
EventObject |
אחד מ-5 סוגי תגובות |
בקשה: EventObject
EventObject מכיל מטא-נתונים ברמה העליונה, שדות אירועים נפוצים ופרטים לפי ההקשר של האפליקציה המארחת:
הקשר נפוץ והקשר של הרשאה
-
commonEventObject: הלוקאל של המשתמש, enum של האפליקציה המארחת (GMAIL,CALENDAR,DRIVE,CHAT,DOCS,SHEETS,SLIDES,WORKFLOW), הפלטפורמה של המשתמש, אזור הזמן, ערכי הקלט של טופס הווידג'ט (formInputs) ופרמטרים מותאמים אישית.CommonEventObject. -
authorizationEventObject: טוקני גישה של משתמשים ל-OAuth, טוקנים של מזהי משתמשים והיקפי הרשאות שהמערכת אישרה.AuthorizationEventObject.
אובייקטים מסוג אירוע באפליקציה המארחת
בהתאם לאפליקציה שמפעילה את הקריאה החוזרת (callback), אחד מאובייקטי המארח הבאים קיים:
- Gmail: מזהה ההודעה, מזהה השרשור, אסימון גישה זמני ורשימות הנמענים של ההודעה (
toRecipients,ccRecipients,bccRecipients). מידע נוסף זמין במאמרGmailEventObject. - יומן: מזהה אירוע, מזהה אירוע חוזר, מזהה יומן, פרטי המארגן, משתתפים, נתוני ועידה ונקודות כניסה.
CalendarEventObject. - Drive: קבצים או תיקיות שנבחרו (
selectedItems) ומטא-נתונים של הפריט הנוכחי של הסמן (activeCursorItem). מידע נוסף זמין במאמרDriveEventObject. - Chat: סוג האירוע (
ADDED_TO_SPACE,REMOVED_FROM_SPACE,MESSAGE,CARD_CLICKED), מטא-נתונים של המרחב, פרטי המשתמש ונתוני המטען הייעודי (payload).ChatEventObject. - Workspace Studio: הפעלות של פעולות, אירועים של מחזור חיים של טריגרים, הגדרות של רכיבים, אחזורי משאבים ומפות של נתונים משתנים.
WorkflowEventObject. - Docs: מזהה המסמך, הכותרת, דגל ההרשאה ברמת הקובץ ותבנית ה-URL התואמת.
DocsEventObject. - Sheets: מזהה הגיליון האלקטרוני, שם, דגל הרשאה ברמת הקובץ ותבנית ה-URL התואמת.
SheetsEventObject. - Slides: מזהה המצגת, שם, דגל הרשאה ברמת הקובץ ותבנית URL תואמת.
SlidesEventObject.
תשובה: HandleEventResponse
תגובת ה-HTTP שמוחזרת על ידי נקודת הקצה של ה-webhook היא אובייקט JSON בסיסי ללא תיוג, שחייב להיות מופע של אחד מחמשת סוגי התגובות הבאים:
-
RenderActions: מציג כרטיסים חדשים, מנווט בין חבילות כרטיסים או מבצע פעולות בממשק המשתמש (לדוגמה,{"action": {"navigations": [...]}}או{"renderActions": ...}). -
SubmitFormResponse: מגיב לפעולת שליחת טופס של משתמש עם הוראות לעיבוד כרטיס ואינדיקטור אופציונלי לעדכון מצב (לדוגמה,{"renderActions": {...}, "stateChanged": true}). -
GetAutocompletionResponse: מספק הצעות טקסט דינמיות לשדות של השלמה אוטומטית בווידג'ט (לדוגמה,{"autoComplete": {"items": [...]}}). -
DataActions: מבצע שינויים במסמך או פעולות במרחב ב-Chat שמופעלות על ידי הקריאה החוזרת (לדוגמה,{"hostAppDataAction": {...}}). -
AuthorizationError: מבקש מהמשתמש לאשר פרטי כניסה חיצוניים של צד שלישי או מבקש היקפי הרשאות נוספים של Google OAuth (לדוגמה,{"basicAuthorizationPrompt": {"authorizationUrl": "..."}}).
מפרט OpenAPI 3.0 עצמאי וסכימות JSON
כדי ליצור באופן אוטומטי קטעי קוד לשרת, ספריות לקוח של SDK או סכימות לאימות המטען הייעודי (payload) של נקודת הקצה החוזרת, אפשר להיעזר בקובצי המפרט הבאים:
- מפרט OpenAPI 3.0.3:
addon_callback_openapi.json - הגדרות של סכימת JSON:
endpoint_interface.schema.json- קטע סכימה של בקשה:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1EventObject - קטע של סכֵימת תשובה:
endpoint_interface.schema.json#/definitions/GoogleAppsAddonsV1HandleEventResponse
- קטע סכימה של בקשה: