במאמר הזה נסביר איך להשתמש בהתראות כדי לעדכן את האפליקציה כשמשאב משתנה.
סקירה כללית
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 הבאות:
כותרת | תיאור |
---|---|
תמיד מופיע | |
|
UUID או מחרוזת ייחודית אחרת שסיפקת לזיהוי ערוץ ההתראות הזה. |
|
מספר שלם שמזהה את ההודעה עבור ערוץ ההתראות. הערך הוא תמיד 1 להודעות של sync . מספר ההודעות גדל בכל הודעה עוקבת בערוץ, אבל הם לא ברצף. |
|
ערך אטום המזהה את המשאב שנצפה. המזהה הזה יציב בכל גרסאות ה-API. |
|
מצב המשאב החדש שהפעיל את ההתראה.
ערכים אפשריים:
sync , add , remove , update ,
trash , untrash או change
.
|
|
מזהה ספציפי לגרסת API של המשאב שנצפה. |
לפעמים קיימת | |
|
פרטים נוספים על השינויים.
ערכים אפשריים:
content ,
parents ,
children או
permissions
.
לא צוין עם sync הודעות. |
|
התאריך והשעה של תפוגת התוקף של ערוץ ההתראות, מבוטאים בפורמט קריא לאנשים. מוצג רק אם הוגדר. |
|
אסימון ערוץ התראות שהוגדר על ידי האפליקציה שלך, ואפשר להשתמש בו כדי לאמת את מקור ההתראות. מוצג רק אם הוגדר. |
הודעות עבור 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.
נמסרה כאשר | ||
---|---|---|
sync |
files , changes |
הערוץ נוצר בהצלחה. צפויים להתחיל לקבל התראות לגביו. |
add |
files |
משאב נוצר או שותף. |
|
files |
משאב קיים נמחק או שהשיתוף שלו בוטל. |
|
files |
עודכן מאפיין אחד או יותר (מטא-נתונים) של משאב. |
|
files |
משאב הועבר לאשפה. |
|
files |
המשאב הוסר מהאשפה. |
|
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" }