התראות על שינויים במשאבים

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

סקירה כללית

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

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

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

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

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

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

בשלב זה, Google Drive API תומך בהתראות על שינויים בשיטות files ו-changes.

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

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

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

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

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

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

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

דוגמאות

דוגמת הקוד הבאה ממחישה איך להשתמש במשאב channels כדי להתחיל לבדוק אם יש שינויים במשאב files יחיד באמצעות שיטת files.watch:

POST https://www.googleapis.com/drive/v3/files/fileId/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
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-myFilesChannelDest", // (Optional) Your files channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

דוגמת הקוד הבאה ממחישה איך להשתמש במשאב channels כדי להתחיל לצפות בכל changes באמצעות השיטה changes.watch:

POST https://www.googleapis.com/drive/v3/changes/watch
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a77", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myChangesChannelDest", // (Optional) Your changes channel token.
  "expiration": 1426325213000 // (Optional) Your requested channel expiration date and time.
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

פרטים נוספים על הבקשה זמינים בקישור ל-method watch עבור השיטות files ו-changes שמופיעות ב'הפניית 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/drive/v3/files/o3hgv1538sdjfh", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1426325213000, // Actual expiration date and time as UNIX timestamp (in milliseconds), if applicable.
}

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

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

פרטים נוספים על התשובה אפשר למצוא בשיטה watch לשיטות files ו-changes שמופיעות ב'הפניית ה-API'.

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

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

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

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

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

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

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

קבלת הודעות

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

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

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

כותרות

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

כותרת תיאור
תמיד מופיע
X-Goog-Channel-ID UUID או מחרוזת ייחודית אחרת שסיפקת לזיהוי ערוץ ההתראות הזה.
X-Goog-Message-Number מספר שלם שמזהה את ההודעה עבור ערוץ ההתראות. הערך הוא תמיד 1 להודעות של sync. מספר ההודעות גדל בכל הודעה עוקבת בערוץ, אבל הם לא ברצף.
X-Goog-Resource-ID ערך אטום המזהה את המשאב שנצפה. המזהה הזה יציב בכל גרסאות ה-API.
X-Goog-Resource-State מצב המשאב החדש שהפעיל את ההתראה. ערכים אפשריים: sync, add, remove, update, trash, untrash או change .
X-Goog-Resource-URI מזהה ספציפי לגרסת API של המשאב שנצפה.
לפעמים קיימת
X-Goog-Changed פרטים נוספים על השינויים. ערכים אפשריים: content, parents, children או permissions . לא צוין עם sync הודעות.
X-Goog-Channel-Expiration התאריך והשעה של תפוגת התוקף של ערוץ ההתראות, מבוטאים בפורמט קריא לאנשים. מוצג רק אם הוגדר.
X-Goog-Channel-Token אסימון ערוץ התראות שהוגדר על ידי האפליקציה שלך, ואפשר להשתמש בו כדי לאמת את מקור ההתראות. מוצג רק אם הוגדר.

הודעות עבור files ו-changes ריקות.

דוגמאות

שינוי הודעת ההתראה לגבי מקורות מידע של files, שלא כוללים את גוף הבקשה:

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/drive/v3/files/ret08u3rv24htgh289g
X-Goog-Resource-State:  update
X-Goog-Changed: content,properties
X-Goog-Message-Number: 10

שינוי הודעת ההתראה למשאבים של changes, שכולל את גוף הבקשה:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 118
X-Goog-Channel-ID: 8bd90be9-3a58-3122-ab43-9823188a5b43
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 19 Nov 2013 01:13:52 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://www.googleapis.com/drive/v3/changes
X-Goog-Resource-State:  changed
X-Goog-Message-Number: 23

{
  "kind": "drive#changes"
}

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

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

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

הסבר על אירועי התראות בממשק של Google Drive API

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

X-Goog-Resource-State איפה הכלל מיושם? נמסרה כאשר
sync files, changes הערוץ נוצר בהצלחה. צפויים להתחיל לקבל התראות לגביו.
add files משאב נוצר או שותף.
remove files משאב קיים נמחק או שהשיתוף שלו בוטל.
update files עודכן מאפיין אחד או יותר (מטא-נתונים) של משאב.
trash files משאב הועבר לאשפה.
untrash files המשאב הוסר מהאשפה.
change changes נוסף פריט אחד או יותר ביומן השינויים.

לאירועי update, יכול להיות שכותרת ה-HTTP X-Goog-Changed תסופק. כותרת זו מכילה רשימה מופרדת בפסיקים שמתארת את סוגי השינויים שהתרחשו.

סוג השינוי מציין
content התוכן של המשאב עודכן.
properties אחד או יותר ממאפייני המשאב עודכנו.
parents אחד או יותר מתבניות ההורה של המשאב נוספו או הוסרו.
children משאב אחד או יותר שצאצאים נוספו או הוסרו.
permissions הרשאות המשאבים עודכנו.

דוגמה עם הכותרת X-Goog-Changed:

X-Goog-Resource-State: update
X-Goog-Changed: content, permissions

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

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

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

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

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

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

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

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

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