התראות

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

בכל בקשה ל-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 יוצרת ערוץ התראות בהצלחה, היא מחזירה את קוד הסטטוס 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.

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

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

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

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

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

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

איך לפרש את הפורמט של הודעת ההתראה

כל הודעות ההתראות כוללות קבוצה של כותרות HTTP עם תחיליות X-Goog-. סוגים מסוימים של התראות יכולים לכלול גם גוף ההודעה.

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

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.

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

• אדמין
• יומן
• drive
• קבוצות
• login
• נייד
• saml
• אסימון
• user_accounts