התראות

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

לפרטים נוספים על הבקשה, אפשר לעיין בשיטה watch עבור המשאבים Acl, CalendarList, Events (אירועים) ו-Settings (הגדרות) בהפניה ל-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, Events (אירועים) ו-Settings (הגדרות) בהפניה ל-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. כל התראה נוספת מערוץ זה מספר הודעה גדול יותר מזה של ההודעה הקודמת, אבל ההודעה המספרים לא יהיו רציפים.

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

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

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

קבל התראות

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

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

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

כותרות

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

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

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

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

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

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

המאפיין expiration קובע מתי ההתראות ייפסקו באופן אוטומטי. אפשר לבחור להפסיק לקבל התראות לגבי ערוץ מסוים לפני שהוא יפוג על ידי קריאה ל-method stop במספר ב-URI הבא:

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

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