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

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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