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

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

סקירה כללית

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

כותרת תיאור
מוצג תמיד
X-Goog-Channel-ID מזהה ייחודי אוניברסלי (UUID) או מחרוזת ייחודית אחרת שסיפקת כדי לזהות את ערוץ ההתראות הזה.
X-Goog-Message-Number מספר שלם שמזהה את ההודעה הזו עבור ערוץ ההתראות. הערך ל-sync הודעות הוא תמיד 1. המספר של ההודעות גדל בכל פעם שמתקבלת הודעה בערוץ, אבל הם לא רציפים.
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 ומחזיר את הערך 500, 502, 503 או 504, יתבצע ניסיון חוזר ב-Google Drive API עם השהיה מעריכית. כל קוד אחר של סטטוס החזרה נחשב ככשל בהודעה.

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