התראות

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

סקירה כללית

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

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

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

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

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

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

נכון לעכשיו, ממשק ה-API של יומן Google תומך בהתראות על שינויים במשאבי Acl, CalendarList, אירועים והגדרות.

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

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

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

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

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

כדי להגדיר ערוץ התראות להודעות על שינויים במשאב מסוים, צריך לשלוח בקשת POST ל-method 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", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myCalendarChannelDest", // (Optional) Your channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration time.
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

צפייה בתשובה

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

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

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab"", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://www.googleapis.com/calendar/v3/calendars/my_calendar@gmail.com/events", // Version-specific ID of the watched resource.
  "token": "target=myApp-myCalendarChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

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

לפרטים נוספים על התשובה, עיינו בשיטה watch של המשאבים Acl, CalendarList, אירועים והגדרות בחומר העזר בנושא API.

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

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

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

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

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

קבלת הודעות

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

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

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

כותרות

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

כותרת תיאור
תמיד מופיע
X-Goog-Channel-ID UUID או מחרוזת ייחודית אחרת שסיפקת לזיהוי ערוץ ההתראות הזה.
X-Goog-Message-Number מספר שלם שמזהה את ההודעה עבור ערוץ ההתראות. הערך הוא תמיד 1 להודעות של sync. מספר ההודעות גדל בכל הודעה עוקבת בערוץ, אבל הם לא ברצף.
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 אסימון ערוץ התראות שהוגדר על ידי האפליקציה שלך, ואפשר להשתמש בו כדי לאמת את מקור ההתראות. מוצג רק אם הוגדר.

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

דוגמאות

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

POST https://mydomain.com/notifications // Your receiving URL.
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.

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

הסבר על אירועי התראה ב-Google Calendar API

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

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

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

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

https://www.googleapis.com/calendar/v3/channels/stop

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

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

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

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

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

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