התראות בדחיפה

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

סקירה

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

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

  • יש להגדיר את כתובת ה-URL המקבלת או את המקבל להתקשרות חזרה על ידי 'webhook'.

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

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

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

בשלב הזה, ב-Directory API יש תמיכה בהתראות על שינויים במשאב משתמשים.

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

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

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

לכל משאב של Directory API שניתן לצפייה משויכת לו שיטת watch ב-URI בפורמט הבא:

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

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

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

דוגמאות

כל הבקשות לצפייה למשאב User בדומיין יחיד הן בפורמט הכללי:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

צריך להשתמש בפרמטרים domain ו-event כדי לציין את הדומיין והסוג של האירוע שרוצים לקבל התראות לגביהם.

כל הבקשות לצפייה למשאב 'משתמש' עבור לקוח מופיעות בפורמט הכללי:

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
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.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

צריך להשתמש בפרמטרים customer ו-event כדי לציין את המזהה הייחודי של חשבון Google של הלקוח ואת סוג האירוע שרוצים לקבל עליו התראות.

הערכים האפשריים של event הם:

  • add: אירוע שנוצר על ידי משתמש
  • delete: אירוע שנמחק על ידי משתמש
  • makeAdmin: אירוע שינוי סטטוס של אדמין של משתמש
  • undelete: אירוע שמחיקתו בוטלה על ידי משתמש
  • update: אירוע שמשתמש עודכן

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

שים לב לאירועים שנוצרו על ידי משתמשים בדומיין mydomain.com:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

מעקב אחרי אירועים שנוצרו על ידי משתמשים עבור הלקוח my_customer:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

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

בכל בקשת watch, עליכם לספק את השדות הבאים:

  • מחרוזת של נכס id שמזהה באופן ייחודי את ערוץ ההתראות החדש בפרויקט. מומלץ להשתמש במזהה ייחודי אוניברסלי (UUID) או במחרוזת ייחודית דומה. האורך המקסימלי: 64 תווים.

    ערך המזהה שמגדירים מהדהד בחזרה בכותרת ה-HTTP X-Goog-Channel-Id של כל הודעה שתתקבל לגבי הערוץ הזה.

  • מחרוזת של מאפיין type שמוגדרת לערך web_hook.

  • מחרוזת נכס address שמוגדרת לכתובת ה-URL שמאזינה להתראות ומגיבה להתראות מערוץ ההתראות הזה. זו כתובת ה-URL לקריאה חוזרת (callback) של התגובה לפעולה מאתר אחר (webhook), והיא חייבת להיות ב-HTTPS.

    חשוב לשים לב ש-Directory API יכול לשלוח התראות לכתובת ה-HTTPS הזו רק אם בשרת האינטרנט שלך מותקן אישור SSL תקין. אישורים לא חוקיים כוללים:

    • אישורים בחתימה עצמית
    • אישורים שחתומים על ידי מקור לא מהימן
    • אישורים שבוטלו.
    • אישורים עם נושא שלא תואם לשם המארח של היעד.

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

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

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

    האסימון כלול בכותרת ה-HTTP של X-Goog-Channel-Token בכל הודעת התראה שהאפליקציה מקבלת לערוץ הזה.

    אם אתם משתמשים באסימונים של ערוצי התראות, מומלץ:

    • צריך להשתמש בפורמט קידוד שניתן להרחבה, כמו פרמטרים של שאילתה לגבי כתובת URL. דוגמה: forwardTo=hr&createdBy=mobile

    • אין לכלול מידע אישי רגיש כמו אסימוני OAuth.

  • מחרוזת של מאפיין expiration שמוגדרת כחותמת זמן של Unix (באלפיות השנייה) של התאריך והשעה שבהם רוצים שה-Directory API יפסיק לשלוח הודעות בשביל ערוץ ההתראות הזה.

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

לפרטים נוספים על הבקשה, יש לעיין ב-method watch של המשאב משתמשים בחומר העזר בנושא API.

צפייה בתשובה

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

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

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

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

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

אפשר להתעלם מההתראה sync, אבל אפשר גם להשתמש בה. לדוגמה, אם החלטת לא לשמור את הערוץ, אפשר להשתמש בערכים X-Goog-Channel-ID ו-X-Goog-Resource-ID בשיחה כדי להפסיק לקבל התראות. אפשר גם להשתמש בהתראה sync כדי לבצע אתחול כלשהו כדי להתכונן לאירועים מאוחרים יותר.

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

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

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

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

קבלת הודעות

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

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

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

כותרות

התראות שמתפרסמות על ידי ה-Directory 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 אסימון ערוץ התראות שהוגדר על ידי האפליקציה שלך, ואפשר להשתמש בו כדי לאמת את מקור ההתראות. מוצג רק אם הוגדר.

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

מאפיין (property) תיאור
kind מזהה את המשאב הזה כמשאב של משתמש. ערך: המחרוזת הקבועה "admin#directory#user".
id המזהה הייחודי של משאב המשתמש.
etag ETag של הודעת ההתראה. שונה מה-ETag של משאב User.
primaryEmail זוהי כתובת האימייל הראשית של המשתמש.

דוגמאות

הודעות התראה לאירועי משאב User מופיעות בצורה הכללית:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
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/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

דוגמה לאירוע שנמחק על ידי משתמש:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

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

כדי לציין שהפעולה בוצעה בהצלחה, אפשר להחזיר כל אחד מקודי הסטטוס הבאים: 200, 201, 202, 204 או 102.

אם השירות משתמש בספריית הלקוח של API של Google ומחזיר 500, 502, 503 או 504, ה-Directory API יבצע ניסיון חוזר עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). כל קוד אחר של סטטוס החזרה נחשב ככשל בהודעה.

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

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

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

השיטה הזו מחייבת לספק לפחות את id ואת המאפיינים resourceId של הערוץ, כפי שמוצג בדוגמה שבהמשך. שימו לב: אם ב-Directory API יש כמה סוגי משאבים עם שיטות watch, אז יש רק שיטת stop אחת.

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

  • אם הערוץ נוצר על ידי חשבון משתמש רגיל, רק אותו משתמש מאותו לקוח (כפי שמזוהה על ידי מזהי לקוח OAuth 2.0 באסימוני האימות) שיצר את הערוץ יכול לעצור את הערוץ.
  • אם הערוץ נוצר על ידי חשבון שירות, כל משתמש מאותו לקוח יכול להפסיק את הערוץ.

דוגמת הקוד הבאה מראה איך להפסיק לקבל התראות:

POST https://www.googleapis.com/admin/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}