התראות

במאמר הזה מוסבר איך להשתמש בהתראות שמודיעות לאפליקציה על שינויים במשאב.

סקירה כללית

ה-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 האלה:

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

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

מאפיין (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 באופן כללי:
  • אם לא צוין 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 ומחזיר את הערך 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"
}