במאמר הזה מוסבר איך להשתמש בהתראות שמודיעות לאפליקציה על שינויים במשאב.
סקירה כללית
ה-Admin SDK API כולל התראות שמאפשרות לך לעקוב אחר שינויים במשאבים. התכונה הזו יכולה לעזור לך לשפר את הביצועים של האפליקציה. כך תוכלו לבטל את הרשת המיותרת ולחשב את העלויות הכרוכות בשימוש במשאבי הסקרים כדי לקבוע אם הן השתנו. בכל פעם שמשאב שנצפה משתנה, האפליקציה מקבלת הודעה מ-Admin SDK API.
כדי להשתמש בהתראות, עליך לבצע שתי פעולות:
צריך להגדיר את כתובת ה-URL המקבלת או את מקלט הקריאה החוזרת (callback) מסוג '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
שים לב לכל הפעילויות של מסמכים:
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
יוצרת בהצלחה ערוץ התראות, היא מחזירה קוד סטטוס HTTP 200 OK
.
גוף ההודעה של תגובת השעון מספק מידע על ערוץ ההתראות שיצרת עכשיו, כפי שמוצג בדוגמה שבהמשך.
{ "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
לזיהוי המשאב שנצפה
בערוץ ההתראות הזה.
אפשר להעביר את המידע שהוחזר לפעולות אחרות של ערוצי התראות, למשל כשרוצים להפסיק לקבל התראות.
לפרטים נוספים על התגובה, אפשר לקרוא את השיטה watch
של המשאב פעילויות בחומר העזר בנושא API.
סנכרון ההודעה
אחרי שיוצרים ערוץ התראות לצפייה במשאב, ה-Admin SDK API שולח את ההודעה sync
כדי לציין שההתראות מתחילות. ערך כותרת ה-HTTP X-Goog-Resource-State
של ההודעות האלה הוא sync
. בגלל בעיות בתזמון הרשת, יכול להיות שתקבלו את ההודעה sync
עוד לפני שתקבלו את התשובה של ה-method 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
הודעות סנכרון תמיד כוללות ערך כותרת HTTP של X-Goog-Message-Number
הוא 1
. כל אחת מההודעות הבאות בערוץ הזה כוללת
מספר הודעה גדול מהמספר הקודם, אבל מספרי
ההודעות לא יהיו רציפים.
חידוש ערוצי ההתראות
לערוץ התראות יכול להיות מועד תפוגה, עם ערך שנקבע על סמך הבקשה שלך, או באמצעות מגבלות פנימיות או ברירות מחדל של ממשק API של Admin SDK (נעשה שימוש בערך המגביל יותר). זמן התפוגה של הערוץ, אם יש לו, נכלל כחותמת זמן של Unix
(באלפיות שנייה) במידע שמוחזר על ידי השיטה watch
. בנוסף, התאריך ושעת התפוגה נכללים (בפורמט קריא לאנשים) בכל הודעת התראה שהאפליקציה מקבלת לגבי הערוץ הזה בכותרת ה-HTTP X-Goog-Channel-Expiration
.
כרגע אין דרך אוטומטית לחדש ערוץ התראות. כשתאריך התפוגה של הערוץ
מתקרב, צריך להחליף אותו בערוץ חדש על ידי קריאה
ל-method watch
. כמו תמיד, צריך להשתמש בערך ייחודי
למאפיין id
של הערוץ החדש. חשוב לזכור שיכול להיות
מצב זמן של "חפיפה" שבו שני ערוצי ההתראות
של אותו משאב פעילים.
קבלת הודעות
בכל פעם שמשאב שנצפה משתנה, האפליקציה מקבלת הודעה שמתארת את השינוי. ה-Admin SDK API שולח את ההודעות האלה כבקשות POST
ל-HTTPS לכתובת ה-URL שציינת
כנכס address
של ערוץ ההתראות הזה.
איך לפרש את הפורמט של הודעות ההתראות
כל ההודעות כוללות קבוצה של כותרות HTTP עם קידומות X-Goog-
.
סוגים מסוימים של התראות עשויים לכלול גם
את גוף ההודעה.
כותרות
התראות שמתפרסמות דרך Admin SDK API בכתובת ה-URL המקבלת את ההודעות כוללות את כותרות ה-HTTP האלה:
כותרת | תיאור |
---|---|
מוצג תמיד | |
|
מזהה ייחודי אוניברסלי (UUID) או מחרוזת ייחודית אחרת שסיפקת כדי לזהות את ערוץ ההתראות הזה. |
|
מספר שלם שמזהה את ההודעה הזו עבור ערוץ ההתראות. הערך ל-sync הודעות הוא תמיד 1 . המספר של ההודעות גדל בכל פעם שמתקבלת הודעה בערוץ, אבל הם לא רציפים. |
|
ערך אטום שמזהה את המשאב שנצפה. המזהה הזה יציב בגרסאות ה-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 עם השהיה מעריכית.
כל קוד אחר של סטטוס החזרה נחשב ככשל בהודעה.
הסבר על אירועי התראות ל-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" }