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

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

לכל משאב ב-Google Drive API שאפשר להגדיר עליו מעקב משויכת שיטת 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 של הקריאה החוזרת (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 יפסיק לשלוח הודעות לערוץ ההתראות הזה.

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

לפרטים נוספים על הבקשה, אפשר לעיין בשיטה watch של 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 של files ושל changes בהפניית ה-API.

הודעת סנכרון

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

אפשר להתעלם מההתראה sync, אבל אפשר גם להשתמש בה. לדוגמה, אם מחליטים שלא רוצים לשמור את הערוץ, אפשר להשתמש בערכים X-Goog-Channel-ID ו-X-Goog-Resource-ID בקריאה אל stop receiving notifications. אפשר גם להשתמש בהתראה 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 (הערך המגביל יותר הוא זה שיילקח בחשבון). תאריך התפוגה של הערוץ, אם יש כזה, נכלל כחותמת זמן של Unix (באלפיות השנייה) במידע שמוחזר על ידי השיטה 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 ומחזיר את הערכים 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"
}