הודעות שנשלחות מהאפליקציה

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

סקירה כללית

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

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

  • מגדירים את כתובת ה-URL לקבלת הודעות או את מקלט הקריאה החוזרת ('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

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

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

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

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

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

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

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

המאפיין 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"
}