במסמך הזה מוסבר איך להשתמש בהתראות שמיידעות את כאשר משאב משתנה.
סקירה כללית
Google Drive API מספק התראות שעוזרות לעקוב שינויים במשאבים. אפשר להשתמש בתכונה הזו כדי לשפר את הביצועים של את האפליקציה שלך. הוא מאפשר להסיר את הרשת הנוספת והמחשוב העלויות הכרוכות בעריכת סקרים כדי לקבוע אם הן השתנו. בכל פעם שמשאב שנצפה משתנה, Google Drive API שולח התראה תרגום מכונה.
כדי להשתמש בהתראות, צריך לבצע שתי פעולות:
הגדרה של כתובת ה-URL המקבלת או ה-webhook של מכשיר הקריאה החוזרת (callback).
הזה הוא שרת HTTPS שמטפל בהודעות ההתראות של ה-API, מופעל כשהמשאב משתנה.
מגדירים (ערוץ התראות) לכל נקודת קצה של משאב שרוצים שעון.
ערוץ מציין פרטי ניתוב עבור התראה הודעות. כחלק מהגדרת הערוץ, עליך לציין את כתובת האתר הספציפית שבה שרוצים לקבל התראות. בכל פעם שהמשאב של הערוץ משתנה, Google Drive API שולח הודעת התראה בתור
POST
בקשה לכתובת ה-URL הזו.
נכון לעכשיו, Google Drive API תומך בהתראות על שינויים
files
ו-changes
.
יצירת ערוצי התראות
כדי לבקש התראות, צריך להגדיר ערוץ התראות לכל משאב שאחריו רוצים לעקוב. אחרי שמגדירים את ערוצי ההתראות למעלה, Google Drive API יודיע לבקשה שלכם בכל פעם שמישהו יצפה במשאבים שינויים.
שליחת בקשות לשעון
לכל משאב של Google Drive API שניתן לצפייה יש
method watch
ב-URI בצורה הבאה:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
כדי להגדיר ערוץ התראות עבור הודעות על שינויים
משאב מסוים, לשלוח בקשת POST
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 לקריאה חוזרת של 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
(בטקסט קריא לאנשים) ) בכל הודעת התראה שמקבלת עבור הערוץ הזה.
לפרטים נוספים על הבקשה, אפשר לעיין בשיטה watch
ל-methods 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
ל-methods 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
. כל התראה נוספת מערוץ זה
מספר הודעה גדול יותר מזה של ההודעה הקודמת, אבל ההודעה
המספרים לא יהיו רציפים.
חידוש ערוצי ההתראות
לערוץ התראות יכול להיות מועד תפוגה עם ערך
נקבעים לפי הבקשה שלכם או לפי מגבלות פנימיות של Google Drive API
או ברירות המחדל (המערכת תשתמש בערך המגביל יותר). תפוגת התוקף של הערוץ
שעה, אם יש לה, נכללת כחותמת זמן של יוניקס
(באלפיות שנייה) במידע שהוחזר באמצעות השיטה watch
. בנוסף,
התאריך ושעת התפוגה נכללים (בפורמט קריא לאנשים) בכל
הודעת התראה שהאפליקציה מקבלת לגבי הערוץ הזה
כותרת HTTP X-Goog-Channel-Expiration
.
בשלב זה אין דרך אוטומטית לחדש ערוץ התראות. מתי
התוקף של הערוץ עומד לפוג, עליכם להחליף אותו בערוץ חדש על ידי שליחת קריאה
השיטה watch
. כמו תמיד, צריך להשתמש בערך ייחודי עבור
מאפיין id
של הערוץ החדש. שימו לב: סביר להניח
להיות 'חפיפה'. פרק זמן שבו שני ערוצי ההתראות של
פעילים.
קבל התראות
בכל פעם שמשאב שנצפה משתנה, האפליקציה שלכם מקבלת
הודעת התראה שמתארת את השינוי. Google Drive API שולח את
הודעות בתור HTTPS POST
כבקשות לכתובת ה-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
אם השירות משתמש בספריית הלקוח של Google API
ומחזירה את ה-API של Google Drive, 500
,502
, 503
או 504
ניסיונות חוזרים עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
כל קוד סטטוס אחר של החזרה נחשב לכשל בהודעה.
הסבר על אירועי התראות של Google Drive API
בקטע הזה אנחנו מפרטים על הודעות ההתראות שאפשר לקבל לקבל כשמשתמשים בהתראות עם ממשק ה-API של Google Drive.
נמסרה כאשר | ||
---|---|---|
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
קובע מתי ההתראות ייפסקו באופן אוטומטי. אפשר
לבחור להפסיק לקבל התראות לגבי ערוץ מסוים לפני שהוא
יפוג על ידי קריאה ל-method stop
במספר
ב-URI הבא:
https://www.googleapis.com/drive/v3/channels/stop
לשיטה זו עליך לספק לפחות את
id
והמאפיינים resourceId
, כפי שמוצג
לדוגמה שלמטה. לתשומת ליבכם, אם ה-API של Google Drive כולל כמה סוגים של
משאבים שיש להם watch
methods, יש רק אחת
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" }