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

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

סקירה

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

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

  • מגדירים את כתובת ה-URL המקבלת או את מקלט הקריאה החוזרת (callback) מסוג 'webhook'.

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

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

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

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

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

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

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

לכל משאב של Google Drive API שניתן לצפות בו משויכת method 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 של ה-methods 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 ל-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

הודעות הסנכרון תמיד כוללות את ערך כותרת ה-HTTP של X-Goog-Message-Number, שהוא 1. בכל התראה עוקבת עבור הערוץ הזה יש מספר הודעה גדול יותר מזה הקודם, אבל מספרי ההודעות לא יהיו רציפים.

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

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

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

קבלת הודעות

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

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

בשיטה הזו צריך לספק לפחות את המאפיינים id ו-resourceId של הערוץ, כפי שמוצג בדוגמה הבאה. הערה: אם ל-Google Drive API יש כמה סוגי משאבים עם methods של 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"
}