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

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

סקירה כללית

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 (בפורמט קריא לאנשים) בכל הודעת התראה שהאפליקציה מקבלת לגבי הערוץ הזה.

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

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

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