התראות

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

סקירה כללית

ממשק Admin SDK API מספק התראות Push שמאפשרות לכם לעקוב אחרי שינויים במשאבים. אתם יכולים להשתמש בתכונה הזו כדי לשפר את הביצועים של האפליקציה. היא מאפשרת לכם לבטל את העלויות הנוספות של הרשת והמחשוב שקשורות לסקר משאבים כדי לקבוע אם הם השתנו. בכל פעם שמשאב במעקב משתנה, Admin SDK API שולח הודעה לאפליקציה שלכם.

כדי להשתמש בהתראות פוש, צריך לבצע שני דברים:

מגדירים את כתובת ה-URL לקבלת נתונים או את מקבל הקריאה החוזרת (callback) של ה-webhook.
זהו שרת HTTPS שמטפל בהודעות ההתראה של ה-API שמופעלות כשמשאב משתנה.
מגדירים (ערוץ התראות) לכל נקודת קצה של משאב שרוצים לעקוב אחריו.
ערוץ מציין פרטי ניתוב להודעות התראה. במסגרת הגדרת הערוץ, צריך לציין את כתובת ה-URL הספציפית שבה רוצים לקבל התראות. בכל פעם שמשאב של ערוץ משתנה, ה-Admin SDK API שולח הודעת התראה כבקשה לכתובת ה-URL הזו.POST

בשלב הזה, Admin SDK API תומך בהתראות על שינויים במשאב Activities.

יצירת ערוצי התראות

כדי לבקש התראות פוש, צריך להגדיר ערוץ התראות לכל משאב שרוצים לעקוב אחריו. אחרי שמגדירים את ערוצי ההתראות, Admin SDK API מודיע לאפליקציה על כל שינוי במשאב במעקב.

שליחת בקשות לשעון

לכל משאב של Admin SDK API שאפשר לעקוב אחריו יש method משויך ב-URI מהצורה הבאה:watch

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

כדי להגדיר ערוץ התראות להודעות על שינויים במשאב מסוים, שולחים בקשת POST לשיטה watch של המשאב.

כל ערוץ התראות משויך למשתמש מסוים ולמשאב מסוים (או לקבוצה של משאבים). בקשת watch לא תצליח אלא אם המשתמש הנוכחי או חשבון השירות הם הבעלים של המשאב הזה או שיש להם הרשאה לגשת אליו.

דוגמאות

כל בקשות הצפייה במשאב Activities הן מהצורה הכללית:

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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "payload": true,
  "expiration": 3600
}

גוף הבקשה כולל את המאפיינים הבאים:

‫id: מזהה UUID או מחרוזת ייחודית דומה שמזהה את הערוץ הזה.
‫type: סוג מנגנון המסירה. הערך בשדה הזה חייב להיות web_hook.
‫address: כתובת ה-URL שאליה נשלחות ההתראות.
‫token: מחרוזת שרירותית שמועברת לכתובת היעד עם כל התראה, כדי לאמת שההתראה מגיעה ממקור מהימן.
‫payload: דגל בוליאני שמציין אם המטען הייעודי (Payload) צריך להיכלל בהתראה.
‫expiration: משך החיים בשניות של ערוץ ההתראות.

אתם יכולים להשתמש בפרמטרים 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.

שימו לב: ה-API של Admin SDK יכול לשלוח התראות לכתובת ה-HTTPS הזו רק אם מותקן בשרת האינטרנט שלכם אישור SSL תקף. אישורים לא תקינים כוללים:
- אישורים בחתימה עצמית
- אישורים שחתומים על ידי מקור לא מהימן
- אישורים שבוטלו.
- אישורים שיש להם נושא שלא תואם לשם המארח של היעד.

מאפיינים אופציונליים

אפשר גם לציין את השדות האופציונליים האלה בבקשת watch:

מאפיין token שמציין ערך מחרוזת שרירותי לשימוש כאסימון ערוץ. אפשר להשתמש בטוקנים של ערוצי התראות למטרות שונות. לדוגמה, אפשר להשתמש באסימון כדי לוודא שכל הודעה נכנסת מיועדת לערוץ שהאפליקציה שלכם יצרה – כדי לוודא שההתראה לא מזויפת – או כדי להפנות את ההודעה ליעד הנכון באפליקציה שלכם בהתאם למטרה של הערוץ הזה. האורך המקסימלי: 256 תווים.
האסימון נכלל בכותרת ה-HTTP‏ X-Goog-Channel-Token בכל הודעת התראה שהאפליקציה מקבלת עבור הערוץ הזה.

אם אתם משתמשים בטוקנים של ערוצי התראות, מומלץ:
- משתמשים בפורמט קידוד שניתן להרחבה, כמו פרמטרים של שאילתות בכתובות URL. דוגמה: forwardTo=hr&createdBy=mobile
- אסור לכלול נתונים רגישים כמו אסימוני OAuth.
הערה: אם אתם חייבים לשלוח נתונים רגישים מאוד, הקפידו להצפין אותם לפני שאתם מוסיפים אותם לטוקן.
מחרוזת מאפיין expiration שמוגדרת כחותמת זמן של Unix (במילישניות) של התאריך והשעה שבהם רוצים ש-Admin SDK API יפסיק לשלוח הודעות לערוץ ההתראות הזה.

אם לערוץ יש זמן תפוגה, הוא נכלל כערך של X-Goog-Channel-Expirationכותרת ה-HTTP (בפורמט שנוח לקריאה) בכל הודעת התראה שהאפליקציה מקבלת עבור הערוץ הזה.

הערה: ב-Admin SDK API, זמן התפוגה המקסימלי הוא 21,600 שניות. אם לא מגדירים את המאפיין expiration בבקשה, זמן התפוגה מוגדר כברירת מחדל ל-21,600 שניות אחרי השעה הנוכחית.

פרטים נוספים על הבקשה מופיעים בשיטה watch של המשאב Activities במאמר בנושא הפניית API.

צפייה בתשובה

אם בקשת watch יוצרת ערוץ התראות בהצלחה, היא מחזירה קוד סטטוס 200 OK של HTTP.

גוף ההודעה של תגובת הצפייה מספק מידע על ערוץ ההתראות שיצרתם, כמו שמוצג בדוגמה שלמטה.

{
  "kind": "api#channel",
  "id": "reportsApiId",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 3600
}

בנוסף למאפיינים ששלחתם כחלק מהבקשה, המידע שמוחזר כולל גם את resourceId ואת resourceUri כדי לזהות את המשאב שנמצא במעקב בערוץ ההתראות הזה.

הערה: הנכס resourceId הוא מזהה יציב של המשאב שלא תלוי בגרסה. המאפיין resourceUri הוא ה-URI הקנוני של המשאב שנצפה בהקשר של גרסת ה-API הנוכחית, ולכן הוא ספציפי לגרסה.

אפשר להעביר את המידע שמוחזר לפעולות אחרות בערוץ ההתראות, למשל כשרוצים להפסיק לקבל התראות.

פרטים נוספים על התגובה זמינים בשיטה watch של המשאב Activities בהפניית ה-API.

סנכרון הודעות

אחרי שיוצרים ערוץ התראות למעקב אחרי משאב, Admin SDK API שולח הודעה מסוג sync כדי לציין שההתראות מתחילות. הערך של כותרת ה-HTTP‏ X-Goog-Resource-State עבור ההודעות האלה הוא sync. בגלל בעיות בתזמון ברשת, יכול להיות שתקבלו את ההודעה sync עוד לפני שתקבלו את התגובה של השיטה watch.

אפשר להתעלם מההתראה sync, אבל אפשר גם להשתמש בה. לדוגמה, אם מחליטים שלא רוצים להמשיך לקבל התראות מהערוץ, אפשר להשתמש בערכים X-Goog-Channel-ID ו-X-Goog-Resource-ID בקריאה אל stop receiving notifications. אפשר גם להשתמש בהתראה 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. לכל התראה עוקבת בערוץ הזה יש מספר הודעה שגדול מהמספר של ההודעה הקודמת, אבל מספרי ההודעות לא יהיו עוקבים.

חידוש של ערוצי התראות

לערוץ ההתראות יכול להיות זמן תפוגה, עם ערך שנקבע לפי הבקשה שלכם או לפי מגבלות פנימיות או ברירות מחדל של Admin SDK API (הערך המגביל יותר הוא זה שמשמש). תאריך התפוגה של הערוץ, אם יש כזה, נכלל כחותמת זמן של Unix (באלפיות השנייה) במידע שמוחזר על ידי השיטה watch. בנוסף, תאריך התפוגה והשעה כלולים (בפורמט שנוח לקריאה) בכל הודעת התראה שהאפליקציה מקבלת לגבי הערוץ הזה בכותרת ה-HTTP‏ X-Goog-Channel-Expiration.

נכון לעכשיו, אין דרך אוטומטית לחדש ערוץ התראות. כשערוץ מתקרב למועד התפוגה שלו, צריך להחליף אותו בערוץ חדש באמצעות קריאה לשיטה watch. כמו תמיד, צריך להשתמש בערך ייחודי במאפיין id של הערוץ החדש. שימו לב שסביר להניח שיהיה פרק זמן של חפיפה שבו שני ערוצי ההתראות לאותו משאב יהיו פעילים.

קבלת התראות

בכל פעם שמשאב שנמצא במעקב משתנה, האפליקציה מקבלת הודעת עדכון שמתארת את השינוי. ממשק Admin SDK API שולח את ההודעות האלה כבקשות HTTPS POST לכתובת ה-URL שציינתם כמאפיין address של ערוץ ההתראות הזה.

הערה: בקשות HTTPS לשליחת התראות מציינות סוכן משתמש של APIs-Google ופועלות בהתאם להנחיות של robots.txt, כפי שמתואר במאמר סוכן המשתמש של Google APIs.

הסבר על פורמט ההודעות

כל הודעות ההתראה כוללות קבוצה של כותרות 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`	מזהה את זה כמשאב Activity. הערך: המחרוזת הקבועה '`admin#reports#activity`'.
`id`	מזהה ייחודי של רשומת הפעילות.
`id.time`	השעה שבה הפעילות התרחשה. הערך הוא בפורמט תאריך ושעה של ISO 8601. השעה היא התאריך המלא בתוספת שעות, דקות ושניות בפורמט YYYY-MM-DDThh:mm:ssTZD. לדוגמה, 2010-04-05T17:30:04+01:00.
`id.uniqueQualifier`	מזהה ייחודי אם לכמה אירועים יש את אותו זמן.
`id.applicationName`	שם האפליקציה שאליה שייך האירוע. הערכים האפשריים כוללים: admin יומן drive groups groups_enterprise login נייד saml token user_accounts
`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`	הערך הבוליאני של הפרמטר.

דוגמאות

הודעות ההתראה על אירועים במשאב Activity הן מהצורה הכללית הבאה:

POST https://mydomain.com/notifications
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
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.

אם השירות שלכם משתמש בספריית לקוחות API של Google ומחזיר 500,‏ 502,‏ 503 או 504,‏ Admin SDK API מנסה שוב עם השהיה אקספוננציאלית. כל קוד סטטוס אחר של החזרה נחשב ככשל בהודעה.

הסבר על אירועי התראות ב-Admin SDK API

בקטע הזה מפורטות הודעות ההתראה שאפשר לקבל כשמשתמשים בהתראות פוש עם Admin SDK API.

ההתראות בדחיפה של Reports API מכילות שני סוגים של הודעות: הודעות סנכרון והתראות על אירועים. סוג ההודעה מצוין בX-Goog-Resource-State כותרת ה-HTTP. הערכים האפשריים להתראות לגבי אירועים זהים לאלה של השיטה activities.list. לכל אפליקציה יש אירועים ייחודיים:

עצירת ההתראות

המאפיין expiration קובע מתי ההתראות ייפסקו אוטומטית. אתם יכולים להפסיק לקבל התראות מערוץ מסוים לפני שהתוקף שלו יפוג. לשם כך, צריך להתקשר לשיטה stop ב-URI הבא:

https://www.googleapis.com/admin/reports_v1/channels/stop

כדי להשתמש בשיטה הזו, צריך לציין לפחות את המאפיינים id וresourceId של הערוץ, כמו בדוגמה שלמטה. שימו לב: אם ל-Admin SDK API יש כמה סוגים של משאבים עם methods מסוג watch, יש רק method אחת מסוג 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"
}

התראות קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

סקירה כללית

יצירת ערוצי התראות

שליחת בקשות לשעון

דוגמאות

מאפיינים נדרשים

מאפיינים אופציונליים

צפייה בתשובה

סנכרון הודעות

חידוש של ערוצי התראות

קבלת התראות

הסבר על פורמט ההודעות

כותרות

דוגמאות

תגובה להודעות

הסבר על אירועי התראות ב-Admin SDK API

עצירת ההתראות

התראות