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

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

סקירה כללית

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 להודעת החזרה, והיא חייבת להשתמש ב-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.

אם השירות שלכם משתמש בספריית הלקוח של 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"
}