במאמר הזה מוסבר איך להשתמש בהתראות שמודיעות לאפליקציה על שינויים במשאב.
סקירה כללית
Google Drive API כולל התראות שמאפשרות לך לעקוב אחר שינויים במשאבים. התכונה הזו יכולה לעזור לך לשפר את הביצועים של האפליקציה. כך תוכלו לבטל את הרשת המיותרת ולחשב את העלויות הכרוכות בשימוש במשאבי הסקרים כדי לקבוע אם הן השתנו. בכל פעם שמשאב שנצפה משתנה, האפליקציה שלך מקבלת הודעה מ-Google Drive API.
כדי להשתמש בהתראות, עליך לבצע שתי פעולות:
צריך להגדיר את כתובת ה-URL המקבלת או את מקלט הקריאה החוזרת (callback) מסוג '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
יוצרת בהצלחה ערוץ התראות, היא מחזירה קוד סטטוס 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/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
עוד לפני שתקבלו את התשובה של ה-method 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
הודעות סנכרון תמיד כוללות ערך כותרת HTTP של X-Goog-Message-Number
הוא 1
. כל אחת מההודעות הבאות בערוץ הזה כוללת
מספר הודעה גדול מהמספר הקודם, אבל מספרי
ההודעות לא יהיו רציפים.
חידוש ערוצי ההתראות
לערוץ התראות יכול להיות מועד תפוגה, עם ערך שנקבע לפי בקשתך, או לפי מגבלות פנימיות או ברירות מחדל של ממשק API של Google Drive (נעשה שימוש בערך המגביל יותר). זמן התפוגה של הערוץ, אם יש לו, נכלל כחותמת זמן של Unix
(באלפיות שנייה) במידע שמוחזר על ידי השיטה watch
. בנוסף, התאריך ושעת התפוגה נכללים (בפורמט קריא לאנשים) בכל הודעת התראה שהאפליקציה מקבלת לגבי הערוץ הזה בכותרת ה-HTTP X-Goog-Channel-Expiration
.
כרגע אין דרך אוטומטית לחדש ערוץ התראות. כשתאריך התפוגה של הערוץ
מתקרב, צריך להחליף אותו בערוץ חדש על ידי קריאה
ל-method watch
. כמו תמיד, צריך להשתמש בערך ייחודי
למאפיין id
של הערוץ החדש. חשוב לזכור שיכול להיות
מצב זמן של "חפיפה" שבו שני ערוצי ההתראות
של אותו משאב פעילים.
קבלת הודעות
בכל פעם שמשאב שנצפה משתנה, האפליקציה מקבלת הודעה שמתארת את השינוי. Google Drive API שולח את ההודעות האלה כבקשות POST
ל-HTTPS לכתובת ה-URL שציינת בתור
הנכס address
של ערוץ ההתראות הזה.
איך לפרש את הפורמט של הודעות ההתראות
כל ההודעות כוללות קבוצה של כותרות HTTP עם קידומות X-Goog-
.
סוגים מסוימים של התראות עשויים לכלול גם
את גוף ההודעה.
כותרות
הודעות של התראות שנשלחות על ידי Google Drive API לכתובת האתר המקבלת כוללות את כותרות ה-HTTP הבאות:
כותרת | תיאור |
---|---|
מוצג תמיד | |
|
מזהה ייחודי אוניברסלי (UUID) או מחרוזת ייחודית אחרת שסיפקת כדי לזהות את ערוץ ההתראות הזה. |
|
מספר שלם שמזהה את ההודעה הזו עבור ערוץ ההתראות. הערך ל-sync הודעות הוא תמיד 1 . המספר של ההודעות גדל בכל פעם שמתקבלת הודעה בערוץ, אבל הם לא רציפים. |
|
ערך אטום שמזהה את המשאב שנצפה. המזהה הזה יציב בגרסאות ה-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
.
אם השירות משתמש בספריית הלקוח של Google API
ומחזיר את הערך 500
, 502
, 503
או 504
, יתבצע ניסיון חוזר ב-Google Drive API עם השהיה מעריכית.
כל קוד אחר של סטטוס החזרה נחשב ככשל בהודעה.
הסבר על אירועים של התראות ב-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" }