התראות

במסמך הזה מוסבר איך להשתמש בהתראות שמיידעות את כאשר משאב משתנה.

סקירה כללית

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 הבאות:

שם תיאור
מוצג תמיד
X-Goog-Channel-ID UUID או מחרוזת ייחודית אחרת שסיפקת כדי לזהות את הכתובת הזו ערוץ התראות.
X-Goog-Message-Number מספר שלם שמזהה את ההודעה לגבי ההתראה . הערך הוא תמיד 1 עבור הודעות sync. ההודעה המספרים עולים בכל הודעה נוספת בערוץ, אבל לא ברצף.
X-Goog-Resource-ID ערך אטום המזהה את המשאב שנצפה. המזהה הזה הוא יציבות בכל גרסאות API.
X-Goog-Resource-State מצב המשאב החדש שגרם לשליחת ההתראה. ערכים אפשריים: sync או שם אירוע.
X-Goog-Resource-URI מזהה ספציפי לגרסת ה-API של המשאב שנצפה.
לפעמים
X-Goog-Channel-Expiration התאריך והשעה של פקיעת התוקף של ערוץ ההתראות, מצוינים ב- בפורמט קריא לאנשים. מוצג רק אם מוגדר.
X-Goog-Channel-Token אסימון ערוץ ההתראות שהוגדר על ידי האפליקציה שלך, וגם שאפשר להשתמש בו כדי לאמת את מקור ההתראה. הצגה רק אם מוגדר.

הודעות התראות על פעילויות מכילות את המידע הבא בגוף הבקשה:

נכס תיאור
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 באופן כללי:
  • אם לא צוין eventName, הדוח יחזיר את כל המופעים האפשריים של eventName.
  • כשמבקשים eventName, התשובה של ה-API מחזירה את כל הפעילויות שמכילות את eventName. ייתכן שלפעילויות שהוחזרו יהיו נכסים אחרים של 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"
}