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

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

סקירה כללית

‫Directory API מספק התראות Push שמאפשרות לכם לעקוב אחרי שינויים במשאבים. אתם יכולים להשתמש בתכונה הזו כדי לשפר את הביצועים של האפליקציה. היא מאפשרת לכם לבטל את העלויות הנוספות של הרשת והמחשוב שקשורות לסקר משאבים כדי לקבוע אם הם השתנו. בכל פעם שמשאב במעקב משתנה, 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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

בגוף הבקשה, מציינים את הערוץ id, את type בתור web_hook ואת כתובת ה-URL של היעד ב-address. אפשר גם לספק את הפרטים הבאים:

  • token שבו תוכלו להשתמש כטוקן של הערוץ.
  • ‫ttl ב-params כדי לבקש זמן חיים לערוץ הזה בשניות.

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

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

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",
  "type": "web_hook",
  "address": "https://mydomain.com/notifications",
  ...
  "token": "target=myApp-myFilesChannelDest",
  "params": {
    "ttl": 3600
  }
}

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

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

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

צפייה בתשובה

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4",
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event",
  "token": "target=myApp-myFilesChannelDest",
  "expiration": 1384823632000
}

גוף התשובה מכיל פרטים על הערוץ, כמו:

  • ‫id: המזהה שציינתם לערוץ הזה.
  • ‫resourceId: המזהה של המשאב שנמצא במעקב.
  • ‫resourceUri: המזהה הספציפי לגרסה של המשאב שבמעקב.
  • token: האסימון שסופק בגוף הבקשה.
  • ‫expiration: זמן התפוגה של הערוץ כחותמת זמן של מערכת Unix באלפיות השנייה.

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

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

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

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

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

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

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