התראות

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

סקירה כללית

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

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

  • מגדירים את כתובת ה-URL המקבלת או את מקלט הקריאה החוזרת (callback) של ה-webhook.

    זהו שרת HTTPS שמטפל בהודעות ההתראות של ה-API שמופעל כשיש שינוי במשאב.

  • מגדירים (ערוץ התראות) לכל נקודת קצה של משאב שרוצים לעקוב אחריה.

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

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

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

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

שליחת בקשות לצפייה

לכל משאב של Admin SDK API שאפשר לצפות בו יש שיטה משויכת של watch ב-URI בפורמט הבא:

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

כדי להגדיר ערוץ התראות להודעות על שינויים במשאב מסוים, צריך לשלוח בקשת POST ל-method 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", // 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 להודעת החזרה (callback), והיא חייבת להשתמש ב-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 של המשאב Activities במסמך העזרה של ה-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 של המשאב Activities בהפניית ה-API.

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

אחרי שיוצרים ערוץ התראות כדי לצפות במשאב, מ-Admin SDK API נשלחת הודעת sync כדי לציין שההתראות מתחילות. הערך של כותרת ה-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

להודעות סנכרון תמיד יש ערך 1 בכותרת ה-HTTP X-Goog-Message-Number. לכל התראות הבאות בערוץ הזה יהיה מספר הודעה גדול יותר מהקודם, אבל מספרי ההודעות לא יהיו ברצף.

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

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

התראות ה-push של Reports 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 יש כמה סוגי משאבים עם methods של 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"
}