התראות

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

סקירה כללית

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

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

  • צריך להגדיר את כתובת ה-URL המקבלת או את מקלט הקריאה החוזרת (callback) מסוג 'webhook'.

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

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

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

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

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

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

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

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

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

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

צפייה בתשובה

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

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

{
  "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 עוד לפני שתקבלו את התשובה של ה-method 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

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

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

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

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

קבלת הודעות

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

איך לפרש את הפורמט של הודעות ההתראות

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

כותרות

התראות שנשלחות על ידי ממשק ה-API של יומן Google לכתובת האתר המקבלת כוללות את כותרות ה-HTTP הבאות:

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

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

הסבר על אירועי התראות של 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"
}