קבלת התראות

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

סקירה כללית

‫Google Calendar API מספק התראות Push שמאפשרות לכם לעקוב אחרי שינויים במשאבים. אתם יכולים להשתמש בתכונה הזו כדי לשפר את הביצועים של האפליקציה. היא מאפשרת לכם לבטל את העלויות הנוספות של הרשת והמחשוב שקשורות לסקר משאבים כדי לקבוע אם הם השתנו. בכל פעם שמשאב שנמצא במעקב משתנה, יומן Google API שולח הודעה לאפליקציה שלכם.

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

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

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

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

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

בשלב הזה, יומן Google API תומך בהתראות על שינויים במשאבים ACL,‏ CalendarList,‏ Events ו-Settings.

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

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

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

לכל משאב ב-Google Calendar API שאפשר להגדיר לו מעקב משויכת method‏ watch ב-URI מהצורה הבאה:

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

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

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

דוגמה

כדי להתחיל לעקוב אחרי שינויים באוסף של אירועים ביומן נתון:

POST https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events/watch
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-myCalendarChannelDest",
  "expiration": 1426325213000
}

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

  • token שבו תוכלו להשתמש כטוקן של הערוץ.
  • זמן expiration התפוגה של הערוץ שביקשת, באלפיות השנייה.

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

בכל בקשת watch, צריך לציין את השדות הבאים:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

לפרטים נוספים על הבקשה, אפשר לעיין בשיטה watch של המשאבים ACL,‏ CalendarList,‏ Events ו-Settings בהפניית ה-API.

צפייה בתשובה

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab",
  "resourceId": "o3hgv1538sdjfh",
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events",
  "token": "target=myApp-myCalendarChannelDest",
  "expiration": 1426325213000
}

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

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

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

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

פרטים נוספים על התגובה מופיעים בשיטה watch במשאבים ACL,‏ CalendarList,‏ Events ו-Settings ב-API Reference.

הודעת סנכרון

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

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

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

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

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

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

קבלת התראות

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

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

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

כותרות

הודעות ההתראה שמתפרסמות על ידי Google Calendar API בכתובת ה-URL לקבלת ההודעות כוללות את כותרות ה-HTTP הבאות:

כותרת תיאור
מוצג תמיד
X-Goog-Channel-ID מזהה ייחודי אוניברסלי (UUID) או מחרוזת ייחודית אחרת שסיפקתם כדי לזהות את ערוץ ההתראות הזה.
X-Goog-Message-Number מספר שלם שמזהה את ההודעה בערוץ ההתראות הזה. הערך הוא תמיד 1 עבור הודעות sync. מספרי ההודעות גדלים בכל הודעה עוקבת בערוץ, אבל הם לא רציפים. Message
X-Goog-Resource-ID ערך אטום שמזהה את המשאב שנמצא במעקב. המזהה הזה יציב בכל גרסאות ה-API.
X-Goog-Resource-State הסטטוס החדש של המשאב שהפעיל את ההתראה. ערכים אפשריים: sync,‏ exists או not_exists.
X-Goog-Resource-URI מזהה ספציפי לגרסת ה-API של המשאב שנמצא במעקב.
לפעמים קיים
X-Goog-Channel-Expiration התאריך והשעה של תפוגת ערוץ ההתראות, בפורמט קריא לאנשים. מוצג רק אם הוא מוגדר.
X-Goog-Channel-Token אסימון של ערוץ ההתראות שהוגדר על ידי האפליקציה, שאפשר להשתמש בו כדי לאמת את מקור ההתראה. מוצג רק אם הוא מוגדר.

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

דוגמה

שינוי הודעת התזכורת לגבי אוסף אירועים שעבר שינוי:

POST https://mydomain.com/notifications
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: 4ba78bf0-6a47-11e2-bcfd-0800200c9a66
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events
X-Goog-Resource-State:  exists
X-Goog-Message-Number: 10

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

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

אם השירות שלכם משתמש בספריית לקוחות של Google API ומחזיר 500,502, 503 או 504,‏ Google Calendar API מנסה שוב עם נסיגה אקספוננציאלית. כל קוד סטטוס אחר של החזרה נחשב ככשל בהודעה.

הסבר על אירועי התראות ביומן Google API

בקטע הזה מפורטות הודעות ההתראה שאפשר לקבל כשמשתמשים בהתראות פוש עם Google Calendar API.

X-Goog-Resource-State האפליקציה הרלוונטית המסירה מתבצעת כאשר
sync רשימות של בקרת גישה (ACL), רשימות של יומנים, אירועים, הגדרות. הערוץ החדש נוצר בהצלחה. מעכשיו אפשר לקבל התראות.
exists רשימות של בקרת גישה (ACL), רשימות של יומנים, אירועים, הגדרות. משאב השתנה. השינויים האפשריים כוללים יצירה של משאב חדש, או שינוי או מחיקה של משאב קיים.

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

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

https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop

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

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

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

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

POST https://www.googleapis.com/workspace/calendar/api/v3/reference/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

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