במסמך הזה מוסבר איך להשתמש בהתראות שמיידעות את כאשר משאב משתנה.
סקירה כללית
Admin SDK API מספק התראות שעוזרות לעקוב אחרי שינויים במשאבים. אפשר להשתמש בתכונה הזו כדי לשפר את הביצועים של את האפליקציה שלך. הוא מאפשר להסיר את הרשת הנוספת והמחשוב העלויות הכרוכות בעריכת סקרים כדי לקבוע אם הן השתנו. בכל פעם שמשאב שנצפה משתנה, Admin SDK API שולח הודעה אל תרגום מכונה.
כדי להשתמש בהתראות, צריך לבצע שתי פעולות:
הגדרה של כתובת ה-URL המקבלת או ה-webhook של מכשיר הקריאה החוזרת (callback).
הזה הוא שרת HTTPS שמטפל בהודעות ההתראות של ה-API, מופעל כשהמשאב משתנה.
מגדירים (ערוץ התראות) לכל נקודת קצה של משאב שרוצים שעון.
ערוץ מציין פרטי ניתוב עבור התראה הודעות. כחלק מהגדרת הערוץ, עליך לציין את כתובת האתר הספציפית שבה שרוצים לקבל התראות. בכל פעם שהמשאב של הערוץ משתנה, נשלחת הודעת התראה מ-Admin SDK API בתור
POST
בקשה לכתובת ה-URL הזו.
בשלב הזה, Admin SDK API תומך בהתראות לגבי שינויים ב- משאב הפעילויות.
יצירת ערוצי התראות
כדי לבקש התראות, צריך להגדיר ערוץ התראות לכל משאב שאחריו רוצים לעקוב. אחרי שמגדירים את ערוצי ההתראות למעלה, ה-Admin SDK API יודיע לאפליקציה כאשר משאב כלשהו שנצפה שינויים.
שליחת בקשות לשעון
לכל משאב של Admin SDK API ניתן לצפייה יש
method watch
ב-URI בצורה הבאה:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
כדי להגדיר ערוץ התראות עבור הודעות על שינויים
משאב מסוים, לשלוח בקשת POST
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 לקריאה חוזרת של 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
(בטקסט קריא לאנשים) ) בכל הודעת התראה שמקבלת עבור הערוץ הזה.
לפרטים נוספים על הבקשה, אפשר לעיין בשיטה 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
לזיהוי המשאב שצופים בו
ערוץ התראות.
אפשר להעביר את המידע שהוחזר לערוץ התראות אחר פעולות, כמו מצבים שבהם רוצים להפסיק לקבל התראות.
לפרטים נוספים על התשובה, אפשר לעיין בwatch
למשאב פעילויות בהפניה ל-API.
סנכרון ההודעה
אחרי שיוצרים ערוץ התראות כדי לצפות במשאב,
נשלחת הודעת sync
על ידי Admin SDK API כדי לציין ש
ההתראות מתחילות. ה-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 שולח את התגים האלה
הודעות בתור HTTPS POST
כבקשות לכתובת ה-URL שציינת
נכס address
להודעה הזו
.
איך לפרש את הפורמט של הודעת ההתראה
כל הודעות ההתראות כוללות קבוצה של כותרות HTTP שיש להן
X-Goog-
קידומות.
סוגים מסוימים של התראות יכולים לכלול גם
גוף ההודעה.
כותרות
הודעות של התראות שנשלחו על ידי Admin SDK API אל הנמען כתובת ה-URL כוללת את כותרות ה-HTTP הבאות:
שם | תיאור |
---|---|
מוצג תמיד | |
|
UUID או מחרוזת ייחודית אחרת שסיפקת כדי לזהות את הכתובת הזו ערוץ התראות. |
|
מספר שלם שמזהה את ההודעה לגבי ההתראה
. הערך הוא תמיד 1 עבור הודעות sync . ההודעה
המספרים עולים בכל הודעה נוספת בערוץ, אבל
לא ברצף. |
|
ערך אטום המזהה את המשאב שנצפה. המזהה הזה הוא יציבות בכל גרסאות API. |
|
מצב המשאב החדש שגרם לשליחת ההתראה.
ערכים אפשריים:
sync או שם אירוע.
|
|
מזהה ספציפי לגרסת ה-API של המשאב שנצפה. |
לפעמים | |
|
התאריך והשעה של פקיעת התוקף של ערוץ ההתראות, מצוינים ב- בפורמט קריא לאנשים. מוצג רק אם מוגדר. |
|
אסימון ערוץ ההתראות שהוגדר על ידי האפליקציה שלך, וגם שאפשר להשתמש בו כדי לאמת את מקור ההתראה. הצגה רק אם מוגדר. |
הודעות התראות על פעילויות מכילות את המידע הבא בגוף הבקשה:
נכס | תיאור |
---|---|
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
ומחזירה את ה-Admin SDK API, 500
, 502
, 503
או 504
ניסיונות חוזרים עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
כל קוד סטטוס אחר של החזרה נחשב לכשל בהודעה.
הסבר על אירועי התראות של Admin SDK API
בקטע הזה אנחנו מפרטים על הודעות ההתראות שאפשר לקבל לקבל כשהם משתמשים בהתראות עם Admin SDK API.
התראות שנשלחות באמצעות ה-API לדוחות מכילות שני סוגים של הודעות: סנכרון הודעות והתראות על אירועים. סוג ההודעה מצוין בכותרת ה-HTTP X-Goog-Resource-State
. הערכים האפשריים של התראות על אירועים זהים לאלה של ה-method activities.list
. לכל אפליקציה יש אירועים ייחודיים:
עצירת ההתראות
המאפיין expiration
קובע מתי ההתראות ייפסקו באופן אוטומטי. אפשר
לבחור להפסיק לקבל התראות לגבי ערוץ מסוים לפני שהוא
יפוג על ידי קריאה ל-method stop
במספר
ב-URI הבא:
https://www.googleapis.com/admin/reports_v1/channels/stop
לשיטה זו עליך לספק לפחות את
id
והמאפיינים resourceId
, כפי שמוצג
לדוגמה. הערה: אם ה-Admin SDK API כולל כמה סוגים של
משאבים שיש להם watch
methods, יש רק אחת
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" }