התראות

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

סקירה כללית

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

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

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

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

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

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

בשלב הזה, Google Calendar 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 תווים.

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

  • מחרוזת של מאפיין 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 Calendar 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.

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

אחרי שיוצרים ערוץ התראות למעקב אחרי משאב, 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

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

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

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

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

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

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

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

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

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

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

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

כדי להשתמש בשיטה הזו, צריך לציין לפחות את המאפיינים id וresourceId של הערוץ, כמו בדוגמה שלמטה. שימו לב: אם ל-Google Calendar API יש כמה סוגים של משאבים עם שיטות 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"
}