התראות Pub/Sub ל-Cloud Storage

הגדרה

בדף הזה תוכלו לקרוא סקירה כללית על התראות Pub/Sub ל-Cloud Storage.

סקירה כללית

התראות Pub/Sub משמשות לשליחת מידע אל Pub/Sub לגבי שינויים שבוצעו באובייקטים בקטגוריות. המידע הזה מתווסף בתור הודעות לנושא Pub/Sub שבחרתם. לדוגמה, אתם יכולים לעקוב אחרי אובייקטים שנוצרים ונמחקים בקטגוריה. כל התראה כוללת מידע שמתאר גם את האירוע שהפעיל את ההתראה וגם את האובייקט שהשתנה.

אפשר לשלוח התראות לכל נושא Pub/Sub בכל פרויקט שבו יש לכם את ההרשאות המתאימות. אחרי שההודעות מתקבלות בנושא ה-Pub/Sub, אפליקציות רשומות לנושא יכולות לקבל את ההודעה המשויכת. במאמר בנושא הגדרת התראות Pub/Sub ל-Cloud Storage מוסבר איך מחברים קטגוריות של Cloud Storage לנושא Pub/Sub.

אפשרויות אחרות להתראות

ההרשמה להתראות Pub/Sub מציעה דרך גמישה להפעלת התראות ופעולות בתגובה לשינויים בקטגוריה. אבל אפשר להשתמש גם באפשרויות הבאות:

  • ‫פונקציות Cloud Run: אם רוצים להפעיל רק פונקציה עצמאית פשוטה בתגובה לאירועים, ולא רוצים לנהל נושא Pub/Sub, מומלץ להשתמש בפונקציות Cloud Run. בעזרת פונקציות Cloud Run תוכלו להפעיל פונקציות #C,‏ Go,‏ Java,‏ Node.js,‏ Python,‏ PHP ו-Ruby בכל פעם שאובייקט בקטגוריה שלכם משתנה. שימו לב שהקטגוריה חייבת להיות שייכת לאותו פרויקט כמו פונקציות Cloud Run. תוכלו להיעזר בהדגמה של אופן השימוש בפונקציות של Cloud Run עם Cloud Storage במדריך הזה.

הגדרות של התראות

הגדרת התראה היא כלל שמצורף לקטגוריה ומציין את:

  • הנושא ב-Pub/Sub שבו מתקבלות התראות
  • האירועים שמפעילים את ההתראה לשליחה
  • המידע שכלול בהתראות

אפשר לשייך כמה הגדרות של התראות לכל קטגוריה. אפשר להגדיר עד 100 הגדרות של התראות בקטגוריה מסוימת, ועד 10 הגדרות של התראות להפעלה של אירוע ספציפי.

לדוגמה, אם הגדרתם התראה ששולחת התראות על מחיקה לנושא Pub/Sub מסוים, תוכלו להגדיר באותה קטגוריה עוד התראה ששולחת התראות על מחיקה, הפעם לנושא אחר. אבל תקבלו הודעת שגיאה אם תנסו ליצור יותר מ-10 הגדרות של התראה לאותה פעולה. בנוסף להגדרות האלה, תוכלו להגדיר התראה לאירועים אחרים (כמו יצירת אובייקטים), ששולחת התראות לאותם נושאי Pub/Sub שאליהם שלחתם את התראות המחיקה, או לנושאים אחרים.

לכל הגדרה של התראה יש מזהה שהוא מספר שלם. המספר השלם הזה מוחזר במקרים הבאים:

  • כשיוצרים את הגדרת ההתראה
  • כשמציגים ברשימה את ההגדרות של ההתראות שמצורפות לקטגוריה
  • במאפיין notificationConfig שכלול בכל התראה שמופעלת על ידי הגדרת ההתראה

היצירה והמחיקה של הגדרות של התראות מחיקה מקדמות את מספר המטא-גנרציה של הקטגוריה.

סוגי אירועים

אלה סוגי האירועים שנתמכים ב-Cloud Storage:

סוג האירוע תיאור
OBJECT_FINALIZE מתרחש כשנוצר אובייקט חדש בקטגוריה (או כשאובייקט קיים נוצר מחדש). זה כולל העתקה, שכתוב או שחזור של אובייקט קיים. האירוע הזה לא יופעל במקרה של העלאה שנכשלה.
OBJECT_METADATA_UPDATE מתרחש כשהמטא-נתונים של אובייקט קיים משתנים.
OBJECT_DELETE מתרחש כשאובייקט נמחק באופן סופי. זה כולל גם אובייקטים שמוחלפים או נמחקים כחלק מהגדרות מחזור החיים של הקטגוריה. זה לא כולל אובייקטים לא עדכניים (ראו OBJECT_ARCHIVE) או העלאות מרובות חלקים שבוטלו.
OBJECT_ARCHIVE מתרחש רק אם האפשרות object versioning מופעלת בקטגוריה. האירוע הזה מציין שהגרסה הפעילה של אובייקט לא עדכנית – בגלל שהיא הוגדרה באופן מפורש כ'לא עדכנית' או כי העלאה של אובייקט באותו שם החליפה את האובייקט הקיים.

לגבי אירועים אחרים ב-Cloud Storage, כמו פעולות בקטגוריה או קריאה של אובייקטים, אפשר להפעיל את הסוג המתאים של יומן הביקורת ביומני הביקורת של Cloud ולנתב את יומני הביקורת ל-Pub/Sub באמצעות מסנן.

החלפה של אובייקטים

כשמחליפים אובייקט קיים באובייקט חדש באותו שם, מופעלים שני אירועים נפרדים: האירוע OBJECT_FINALIZE מופעל לגרסה החדשה של האובייקט והאירוע OBJECT_ARCHIVE או OBJECT_DELETE מופעלים לאובייקט שהוחלף. המאפיין overwroteGeneration של האירוע OBJECT_FINALIZE מספק את מספר הגנרציה של האובייקט שהוחלף. המאפיין overwrittenByGeneration של האירוע, OBJECT_ARCHIVE או OBJECT_DELETE, מספק את מספר הגנרציה של האובייקט החדש.

פורמט ההתראות

ההתראות שנשלחות לנושא Pub/Sub כוללות שני חלקים:

  • המאפיינים: קבוצה של צמדי מפתח/ערך שמתארים את האירוע.
  • המטען הייעודי (Payload) : מחרוזת שמכילה את המטא-נתונים של האובייקט שהשתנה.

מאפיינים

המאפיינים הם צמדי מפתח/ערך שכלולים בכל ההתראות שנשלחות מ-Cloud Storage לנושא Pub/Sub. ההתראות תמיד כוללות את הקבוצה הבאה של צמדי מפתח/ערך, בלי קשר למטען הייעודי (Payload) של ההתראה:

שם המאפיין דוגמה תיאור
notificationConfig projects/_/buckets/foo/notificationConfigs/3 מזהה של הגדרת ההתראה שהפעילה את ההתראה הזאת.
eventType OBJECT_FINALIZE סוג האירוע שהתרחש. בקטע סוגי אירועים תוכלו לעיין ברשימת הערכים האפשריים.
payloadFormat JSON_API_V1 הפורמט של המטען הייעודי (Payload) של האובייקט. בקטע מטען ייעודי (Payload) תוכלו לעיין ברשימה של הערכים האפשריים.
bucketId foo שם הקטגוריה שמכילה את האובייקט שהשתנה.
objectId bar שם האובייקט שהשתנה.
objectGeneration 123456 מספר הגנרציה של האובייקט שהשתנה.
eventTime 2021-01-15T01:30:15.01Z שעת התרחשות האירוע בפורמט RFC 3339.

לפעמים ההתראות מכילות את הקבוצה הבאה של צמדי מפתח/ערך, בלי קשר למטען הייעודי (Payload) של ההתראה:

שם המאפיין דוגמה תיאור
overwriteByGeneration 107458 מספר הגנרציה של האובייקט שהחליף את האובייקט שההתראה הזו מתייחסת אליו. המאפיין הזה מופיע רק במקרה של החלפה, באירועים מסוג OBJECT_ARCHIVE או OBJECT_DELETE.
overwroteGeneration 352947 מספר הגנרציה של האובייקט שהוחלף באובייקט שההתראה הזו מתייחסת אליו. המאפיין הזה מופיע רק במקרה של החלפה, באירועי OBJECT_FINALIZE.

בנוסף למאפיינים שלמעלה, הגדרת התראה יכולה לכלול עד 10 מאפיינים מותאמים אישית. אפשר להגדיר מאפיינים מותאמים אישית כשיוצרים הגדרת התראות באמצעות הדגל --custom-attributes בפקודת gcloud storage או על ידי העברת האובייקט custom_attributes בגוף בקשת ה-JSON POST notificationConfigs.

Payload

המטען הייעודי (Payload) הוא מחרוזת שמכילה את המטא-נתונים של האובייקט שהשתנה. כשיוצרים הגדרת התראה צריך לציין את סוג המטען הייעודי (Payload) שייכלל בהתראות שההגדרה הזו מפעילה. אפשר לציין מטען ייעודי (Payload) מהסוגים הבאים:

סוג המטען הייעודי (Payload) תיאור
NONE ההתראה לא כוללת מטען ייעודי (Payload).
JSON_API_V1 המטען הייעודי (Payload) יהיה מחרוזת בתקן UTF-8 שתכיל את ייצוג המשאב של המטא-נתונים של האובייקט.

בהתראות של OBJECT_DELETE, המטא-נתונים שכלולים במטען הייעודי (Payload) מייצגים את המטא-נתונים של האובייקט כפי שהיו לפני המחיקה, בתוספת המאפיין timeDeleted. בכל ההתראות האחרות, המטא-נתונים שכלולים במטען הייעודי (Payload) מייצגים את המטא-נתונים של האובייקט אחרי ביצוע השינוי.

לדוגמה, נניח שיש לכם הגדרת התראה שעוקבת אחרי אירועי OBJECT_METADATA_UPDATE. אם משתמש משנה את המאפיין contentType של אובייקט מ-binary/octet-stream ל-video/mp4, נשלחת התראת OBJECT_METADATA_UPDATE והמטא-נתונים במטען הייעודי (Payload) כוללים את הערך "contentType":"video/mp4".

התחייבויות מסירה

כשמוסיפים הגדרת התראה, יכול להיות שיעברו עד 30 שניות לפני ש-Cloud Storage יתחיל לשלוח התראות שקשורות אליה. אחרי שהשליחה מתחילה, Cloud Storage מבטיח לפחות מסירה אחת ל-Pub/Sub. גם ב-Pub/Sub יש אפשרות של לפחות מסירה אחת לנמען, כך שיכול להיות שתקבלו כמה הודעות עם כמה מזהים, שמייצגות את אותו אירוע ב-Cloud Storage.

אין התחייבות שההתראות יפורסמו לפי הסדר שבו התקבלו ב-Pub/Sub. אם אתם מתכננים לשנות את האובייקט ב-Cloud Storage על סמך התראה, מומלץ להשתמש במספרי הגנרציה והמטא-גנרציה של האובייקט כתנאים מוקדמים לבקשת העדכון.

אם אי אפשר לשלוח התראות לנושא Pub/Sub מסוים באופן עקבי, יכול להיות שההתראה תימחק מ-Cloud Storage אחרי 7 ימים. כשל במסירה עשוי לקרות כשנושא Pub/Sub כבר לא קיים, כשל-Cloud Storage כבר אין הרשאה לפרסם בנושא הזה או כשהפרויקט שהנושא בבעלותו חורג ממכסת הפרסום שלו.

המאמרים הבאים