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

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

סקירה כללית

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 הבאות:

שם תיאור
מוצג תמיד
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

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

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

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

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 קובע מתי ההתראות ייפסקו באופן אוטומטי. אפשר לבחור להפסיק לקבל התראות לגבי ערוץ מסוים לפני שהוא יפוג על ידי קריאה ל-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"
}