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

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

סקירה כללית

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

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

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

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

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

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

נכון לעכשיו, Directory API תומך בהתראות על שינויים במשאב Users.

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

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

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

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

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

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

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

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

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

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

קבלת התראות

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

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

נכס תיאור
kind מזהה את המשאב הזה כמשאב User. ערך: המחרוזת הקבועה admin#directory#user.
id המזהה הייחודי של משאב המשתמש.
etag ETag של הודעת ההתראה. שונה מ-ETag של משאב המשתמש.
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.

אם השירות משתמש בספריית הלקוח של Google API ומחזירה את ה-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"
}