התראות

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

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

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

כל הודעות ההתראות כוללות קבוצה של כותרות 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.

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

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