במאמר הזה נסביר איך להשתמש בהתראות כדי לעדכן את האפליקציה כשמשאב משתנה.
סקירה כללית
Admin SDK API מספק התראות שמאפשרות לעקוב אחרי שינויים במשאבים. אפשר להשתמש בתכונה הזו כדי לשפר את ביצועי האפליקציה. כך אפשר לבטל את הרשת המיותרת ולחשב את העלויות הכרוכות בשימוש במשאבי הסקרים כדי לקבוע אם הן השתנו. בכל פעם שמשאב שנצפה משתנה, ה-Admin SDK API שולח התראה לאפליקציה שלך.
כדי להשתמש בהתראות, עליך לבצע שתי פעולות:
יש להגדיר את כתובת ה-URL המקבלת או את המקבל להתקשרות חזרה על ידי 'webhook'.
זהו שרת HTTPS שמטפל בהודעות ההתראות של ה-API שמופעלות כשמשאב משתנה.
צריך להגדיר (ערוץ התראות) לכל נקודת קצה של משאב שבה רוצים לצפות.
ערוץ מציין פרטי ניתוב של הודעות. כחלק מהגדרת הערוץ, עליך לזהות את כתובת ה-URL הספציפית שאליה ברצונך לקבל התראות. בכל פעם שמשאב של ערוץ משתנה, ה-Admin SDK API שולח הודעת התראה כבקשת
POST
לכתובת ה-URL הזו.
בשלב הזה, ב-Admin SDK API יש תמיכה בהתראות על שינויים במשאב פעילויות.
יצירת ערוצי התראות
כדי לבקש התראות, צריך להגדיר ערוץ התראות לכל משאב שרוצים לעקוב אחריו. אחרי שמגדירים את ערוצי ההתראות, ה-Admin SDK API מודיע לאפליקציה שלך אם כל משאב שנצפה משתנה.
שליחת בקשות לשעון
לכל משאב שניתן לצפות בו ב-Admin SDK API משויכת שיטת watch
, ב-URI בפורמט הבא:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
כדי להגדיר ערוץ התראות להודעות על שינויים במשאב מסוים, צריך לשלוח בקשת POST
ל-method watch
של המשאב.
כל ערוץ התראות משויך גם למשתמש מסוים וגם
למשאב מסוים (או לקבוצת משאבים). בקשת watch
לא תתבצע, אלא אם למשתמש הנוכחי
או לחשבון השירות
יש את המשאב הזה, או שיש לו הרשאה לגשת אליו.
דוגמאות
כל הבקשות לצפייה במשאב הפעילויות מופיעות בצורה הכללית:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch Authorization: Bearer auth_token_for_current_user Content-Type: application/json { "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID. "type": "web_hook", "address": "https://mydomain.com/notifications", // Your receiving URL. ... "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token. "payload": true, // (Optional) Whether to include the payload (message body) in notifications. "expiration": 3600 // (Optional) Your requested channel expiration time. }
אפשר להשתמש בפרמטרים userKey, applicationName, eventName
ו-filters
כדי לקבל התראות רק לגבי אירועים, אפליקציות או משתמשים ספציפיים.
הערה: בדוגמאות הבאות, גוף הבקשה לא מופיע בבהירות.
חשוב לשים לב לכל פעילויות האדמין:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch
צפייה בכל הפעילויות של Docs:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch
מעקב אחר פעילות אדמין של משתמש ספציפי:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch
שים לב לאירוע ספציפי, כמו שינוי סיסמה של משתמש:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD
חשוב לשים לב לשינויים במסמך ספציפי:
POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef
מאפיינים נדרשים
בכל בקשת watch
, עליכם לספק את השדות הבאים:
-
מחרוזת של נכס
id
שמזהה באופן ייחודי את ערוץ ההתראות החדש בפרויקט. מומלץ להשתמש במזהה ייחודי אוניברסלי (UUID) או במחרוזת ייחודית דומה. האורך המקסימלי: 64 תווים.ערך המזהה שמגדירים מהדהד בחזרה בכותרת ה-HTTP
X-Goog-Channel-Id
של כל הודעה שתתקבל לגבי הערוץ הזה. -
מחרוזת של מאפיין
type
שמוגדרת לערךweb_hook
. -
מחרוזת נכס
address
שמוגדרת לכתובת ה-URL שמאזינה להתראות ומגיבה להתראות מערוץ ההתראות הזה. זו כתובת ה-URL לקריאה חוזרת (callback) של התגובה לפעולה מאתר אחר (webhook), והיא חייבת להיות ב-HTTPS.חשוב לדעת: Admin SDK API יכול לשלוח התראות לכתובת ה-HTTPS הזו רק אם אישור SSL חוקי מותקן בשרת האינטרנט שלך. אישורים לא חוקיים כוללים:
- אישורים בחתימה עצמית
- אישורים שחתומים על ידי מקור לא מהימן
- אישורים שבוטלו.
- אישורים עם נושא שלא תואם לשם המארח של היעד.
מאפיינים אופציונליים
אפשר לציין גם את השדות האופציונליים הבאים בבקשת watch
:
-
מאפיין
token
שמציין ערך מחרוזת שרירותי לשימוש כאסימון ערוץ. אפשר להשתמש באסימונים של ערוצי התראות למטרות שונות. לדוגמה, אפשר להשתמש באסימון כדי לוודא שכל הודעה נכנסת מיועדת לערוץ שהאפליקציה שלך יצרה, כדי לוודא שההתראה לא מזויפת, או כדי לנתב את ההודעה ליעד הנכון בתוך האפליקציה בהתאם למטרת הערוץ הזה. האורך המקסימלי: 256 תווים.האסימון כלול בכותרת ה-HTTP של
X-Goog-Channel-Token
בכל הודעת התראה שהאפליקציה מקבלת לערוץ הזה.אם אתם משתמשים באסימונים של ערוצי התראות, מומלץ:
צריך להשתמש בפורמט קידוד שניתן להרחבה, כמו פרמטרים של שאילתה לגבי כתובת URL. דוגמה:
forwardTo=hr&createdBy=mobile
אין לכלול מידע אישי רגיש כמו אסימוני OAuth.
-
מחרוזת של מאפיין
expiration
שמוגדרת כחותמת זמן של Unix (באלפיות השנייה) של התאריך והשעה שבהם רוצים ש-Admin SDK API יפסיק לשלוח הודעות בשביל ערוץ ההתראות הזה.אם לערוץ יש מועד תפוגה, הערך הזה נכלל בתור הערך של כותרת ה-HTTP
X-Goog-Channel-Expiration
(בפורמט קריא לאנשים) בכל הודעת התראה שהאפליקציה שלך מקבלת לערוץ.
לפרטים נוספים על הבקשה, יש לעיין ב-method watch
של המשאב פעילויות בחומר העזר בנושא API.
צפייה בתשובה
אם הבקשה watch
יוצרת בהצלחה ערוץ התראות, היא מחזירה את קוד הסטטוס 200 OK
של HTTP.
גוף ההודעה של תגובת השעון מספק מידע על ערוץ ההתראות שיצרת עכשיו, כפי שמוצג בדוגמה שבהמשך.
{ "kind": "api#channel", "id": "reportsApiId", // ID you specified for this channel. "resourceId": "o3hgv1538sdjfh", // ID of the watched resource. "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource. "token": "target=myApp-myFilesChannelDest", // Present only if one was provided. "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable. }
בנוסף לנכסים ששלחת כחלק מהבקשה, המידע המוחזר כולל גם את
resourceId
וה-resourceUri
לזיהוי המשאב שעליו מתבצע מעקב
בערוץ ההתראות הזה.
אפשר להעביר את המידע שהוחזר לפעולות אחרות של ערוצי התראות, למשל כשרוצים להפסיק לקבל התראות.
לפרטים נוספים על התגובה, אפשר לעיין ב-method watch
של המשאב פעילויות בחומר העזר בנושא API.
סנכרון ההודעה
אחרי שיוצרים ערוץ התראות כדי לצפות במשאב, ה-Admin SDK API שולח הודעה sync
כדי לציין שההתראות מתחילות. ערך כותרת ה-HTTP של ההודעות האלה X-Goog-Resource-State
הוא sync
. בגלל בעיות בתזמון הרשת, יכול להיות שההודעה sync
תתקבל עוד לפני שקיבלת את התשובה של שיטת watch
.
אפשר להתעלם מההתראה sync
, אבל
אפשר גם להשתמש בה. לדוגמה, אם החלטת לא לשמור את הערוץ, אפשר להשתמש בערכים X-Goog-Channel-ID
ו-X-Goog-Resource-ID
בשיחה כדי להפסיק לקבל התראות. אפשר גם להשתמש בהתראה sync
כדי לבצע אתחול כלשהו כדי להתכונן
לאירועים מאוחרים יותר.
הפורמט של הודעות sync
שנשלחות על ידי Admin SDK API
לכתובת ה-URL לקבלת הודעות מוצג בהמשך.
POST https://mydomain.com/notifications // Your receiving URL. X-Goog-Channel-ID: channel-ID-value X-Goog-Channel-Token: channel-token-value X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires. X-Goog-Resource-ID: identifier-for-the-watched-resource X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource X-Goog-Resource-State: sync X-Goog-Message-Number: 1
הודעות סנכרון תמיד כוללות ערך X-Goog-Message-Number
של כותרת ה-HTTP של 1
. בכל התראה נוספת מהערוץ הזה יש
מספר הודעה גדול יותר מהמספר הקודם, אבל מספרי
ההודעות לא יהיו ברצף.
חידוש של ערוצי ההתראות
לערוץ התראות יכול להיות מועד תפוגה, עם ערך שנקבע לפי הבקשה שלך, או לפי מגבלות פנימיות או ברירות מחדל של ממשקי Admin SDK API (נעשה שימוש בערך המגביל יותר). זמן התפוגה של הערוץ, אם יש לו, נכלל כחותמת זמן של יוניקס
(באלפיות שנייה) במידע שמוחזר על ידי השיטה watch
. בנוסף, התאריך ושעת התפוגה נכללים (בפורמט קריא לאנשים) בכל
הודעת התראה שהאפליקציה מקבלת עבור הערוץ הזה בכותרת ה-HTTP X-Goog-Channel-Expiration
.
בשלב הזה אין דרך אוטומטית לחדש ערוץ התראות. כאשר
התוקף של הערוץ עומד לפוג, צריך להחליף אותו בערוץ חדש על ידי קריאה
לשיטה watch
. כמו תמיד, חובה להשתמש בערך ייחודי
למאפיין id
של הערוץ החדש. הערה: סביר להניח שתהיה תקופת זמן 'חפיפה' שבה שני ערוצי ההתראות של אותו משאב פעילים.
קבלת הודעות
בכל פעם שמשאב שנצפה משתנה, האפליקציה מקבלת הודעה שמתארת את השינוי. ה-Admin SDK API שולח את ההודעות האלה כבקשות של POST
ל-HTTPS אל כתובת ה-URL שציינת
בנכס address
של ערוץ ההתראות הזה.
הסבר על הפורמט של הודעות ההתראות
כל ההתראות כוללות קבוצה של כותרות HTTP עם קידומות X-Goog-
.
התראות מסוגים מסוימים יכולות לכלול גם
את גוף ההודעה.
כותרות
התראות שנשלחות על ידי Admin SDK API אל כתובת ה-URL המקבלת התראות כוללות את כותרות ה-HTTP הבאות:
כותרת | תיאור |
---|---|
תמיד מופיע | |
|
UUID או מחרוזת ייחודית אחרת שסיפקת לזיהוי ערוץ ההתראות הזה. |
|
מספר שלם שמזהה את ההודעה עבור ערוץ ההתראות. הערך הוא תמיד 1 להודעות של sync . מספר ההודעות גדל בכל הודעה עוקבת בערוץ, אבל הם לא ברצף. |
|
ערך אטום המזהה את המשאב שנצפה. המזהה הזה יציב בכל גרסאות ה-API. |
|
מצב המשאב החדש שהפעיל את ההתראה.
ערכים אפשריים:
sync או שם אירוע.
|
|
מזהה ספציפי לגרסת API של המשאב שנצפה. |
לפעמים קיימת | |
|
התאריך והשעה של תפוגת התוקף של ערוץ ההתראות, מבוטאים בפורמט קריא לאנשים. מוצג רק אם הוגדר. |
|
אסימון ערוץ התראות שהוגדר על ידי האפליקציה שלך, ואפשר להשתמש בו כדי לאמת את מקור ההתראות. מוצג רק אם הוגדר. |
הודעות התראה על 'פעילויות' מכילות את הפרטים הבאים בגוף הבקשה:
מאפיין (property) | תיאור |
---|---|
kind |
מזהה את המשאב הזה כמשאב 'פעילות'. ערך: המחרוזת הקבועה "admin#reports#activity ". |
id |
מזהה ייחודי של רשומת הפעילות. |
id.time |
שעת ההתרחשות של הפעילות. הערך הוא בפורמט תאריך ושעה לפי ISO 8601. השעה היא התאריך המלא לצד שעות, דקות ושניות, בפורמט YYYY-MM-DDThh:mm:ssTZD. לדוגמה, 2010-04-05T17:30:04+01:00. |
id.uniqueQualifier |
מזהה ייחודי אם למספר אירועים יש את אותו זמן. |
id.applicationName |
שם האפליקציה שהאירוע שייך אליה. הערכים האפשריים כוללים: |
id.customerId |
המזהה הייחודי של חשבון Google Workspace. |
actor |
המשתמש מבצע את הפעולה. |
actor.callerType |
סוג המחבר שביצע את הפעילות הרשומה בדוח. בגרסה הזו של ה-API, callerType היא בקשת הישות USER או OAuth 2LO שביצעה את הפעולה שרשומה בדוח . |
actor.email |
כתובת האימייל הראשית של המשתמש שהפעילויות שלו מדווחות. |
actor.profileId |
מזהה הפרופיל הייחודי של המשתמש ב-Google Workspace. |
ownerDomain |
הדומיין של מסוף Admin או של בעל המסמך של אפליקציית Docs. זהו הדומיין שמושפע מהאירוע בדוח. |
ipAddress |
כתובת ה-IP של המשתמש שמבצע את הפעולה. זוהי כתובת פרוטוקול האינטרנט (IP) של המשתמש כשהוא מתחבר ל-Google Workspace, והיא עשויה לשקף את המיקום הפיזי של המשתמש או לא. לדוגמה, כתובת ה-IP יכולה להיות כתובת שרת ה-proxy של המשתמש, או כתובת רשת וירטואלית פרטית (VPN). ה-API תומך ב-IPv4 וב-IPv6. |
events[] |
אירועי פעילות בדוח. |
events[].type |
סוג האירוע. השירות או התכונה של Google Workspace שאדמין משנה מזוהים בנכס type , שמזהה אירוע באמצעות הנכס eventName . |
events[].name |
שם האירוע. זהו השם הספציפי של הפעילות שמדווחת על ידי ה-API. כל eventName קשור לשירות או לתכונה ספציפיים של Google Workspace שה-API מארגן לפי סוגי אירועים.
לפרמטרים של בקשה מסוג eventName באופן כללי:
|
events[].parameters[] |
זוגות של ערכי פרמטרים לאפליקציות שונות. |
events[].parameters[].name |
שם הפרמטר. |
events[].parameters[].value |
ערך המחרוזת של הפרמטר. |
events[].parameters[].intValue |
ערך מספר שלם של הפרמטר. |
events[].parameters[].boolValue |
ערך בוליאני של הפרמטר. |
דוגמאות
הודעות התראה לגבי אירועי משאבים של פעילות מופיעות בצורה הכללית:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 0 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 398348u3tu83ut8uu38 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret08u3rv24htgh289g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName X-Goog-Resource-State: eventName X-Goog-Message-Number: 10 { "kind": "admin#reports#activity", "id": { "time": datetime, "uniqueQualifier": long, "applicationName": string, "customerId": string }, "actor": { "callerType": string, "email": string, "profileId": long }, "ownerDomain": string, "ipAddress": string, "events": [ { "type": string, "name": string, "parameters": [ { "name": string, "value": string, "intValue": long, "boolValue": boolean } ] } ] }
דוגמה לאירוע של פעילות של אדמין:
POST https://mydomain.com/notifications // Your receiving URL. Content-Type: application/json; utf-8 Content-Length: 596 X-Goog-Channel-ID: reportsApiId X-Goog-Channel-Token: 245t1234tt83trrt333 X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT X-Goog-Resource-ID: ret987df98743md8g X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json X-Goog-Resource-State: CREATE_USER X-Goog-Message-Number: 23 { "kind": "admin#reports#activity", "id": { "time": "2013-09-10T18:23:35.808Z", "uniqueQualifier": "-0987654321", "applicationName": "admin", "customerId": "ABCD012345" }, "actor": { "callerType": "USER", "email": "admin@example.com", "profileId": "0123456789987654321" }, "ownerDomain": "apps-reporting.example.com", "ipAddress": "192.0.2.0", "events": [ { "type": "USER_SETTINGS", "name": "CREATE_USER", "parameters": [ { "name": "USER_EMAIL", "value": "liz@example.com" } ] } ] }
תגובה להודעות
כדי לציין שהפעולה בוצעה בהצלחה, אפשר להחזיר כל אחד מקודי הסטטוס הבאים:
200
, 201
, 202
, 204
או
102
.
אם השירות משתמש בספריית הלקוח של Google API
ומחזיר את 500
, 502
, 503
או 504
, ה-Admin SDK API יבצע ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
כל קוד אחר של סטטוס החזרה נחשב ככשל בהודעה.
הסבר על אירועי התראה ב-Admin SDK API
בקטע הזה מופיעים פרטים על ההתראות שאפשר לקבל כשמשתמשים בהתראות ב-Admin SDK API.
התראות מה-API לדוחות מכילות שני סוגים של הודעות: הודעות סנכרון והתראות על אירועים. סוג ההודעה מצוין בכותרת ה-HTTP X-Goog-Resource-State
. הערכים האפשריים להתראות על אירועים זהים לערכים של השיטה activities.list
. לכל אפליקציה יש אירועים ייחודיים:
עצירת ההתראות
בנכס expiration
אפשר לקבוע מתי ההתראות יופסקו באופן אוטומטי. אפשר
להפסיק לקבל התראות לגבי ערוץ מסוים לפני
שהתוקף שלו פג. לשם כך, קוראים לשיטה stop
ב-URI הבא:
https://www.googleapis.com/admin/reports_v1/channels/stop
השיטה הזו מחייבת לספק לפחות את
id
ואת המאפיינים resourceId
של הערוץ, כפי שמוצג
בדוגמה שבהמשך. הערה: אם ב-Admin SDK API יש כמה סוגי משאבים עם שיטות watch
, אז יש רק שיטת stop
אחת.
רק משתמשים עם ההרשאה המתאימה יכולים לעצור ערוץ. הקפידו במיוחד על הדברים הבאים:
- אם הערוץ נוצר על ידי חשבון משתמש רגיל, רק אותו משתמש מאותו לקוח (כפי שמזוהה על ידי מזהי לקוח OAuth 2.0 באסימוני האימות) שיצר את הערוץ יכול לעצור את הערוץ.
- אם הערוץ נוצר על ידי חשבון שירות, כל משתמש מאותו לקוח יכול להפסיק את הערוץ.
דוגמת הקוד הבאה מראה איך להפסיק לקבל התראות:
POST https://www.googleapis.com/admin/reports_v1/channels/stop Authorization: Bearer CURRENT_USER_AUTH_TOKEN Content-Type: application/json { "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66", "resourceId": "ret08u3rv24htgh289g" }