התראות Pub/Sub

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

מידע נוסף על Pub/Sub זמין במאמר מהו Cloud Pub/Sub

דרישות מוקדמות

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

  1. מפעילים את Pub/Sub API בפרויקט שמקבל התראות Pub/Sub.

    הפעלת ה-API

  2. לוודא שיש לכם נושא Pub/Sub שאליו אתם רוצים לשלוח התראות.

  3. השגת כתובת האימייל של חשבון השירות שמשויך לפרויקט שמכיל את הקטגוריה של Storage Transfer Service.

    1. מקצים לחשבון השירות את תפקיד ה-IAM‏ roles.pubsub.publisher לנושא Pub/Sub הרצוי.

הגדרת ההתראות

כדי להגדיר את ההגדרות של התראות Pub/Sub ב-Storage Transfer Service, משתמשים ב-Storage Transfer Service transferJobs API כדי ליצור הודעת NotificationConfig. הנושא יקבל התראות בערוץ Pub/Sub שהוגדר.

צריך לציין בהודעה אל NotificationConfig את הפרטים הבאים:

  • נושא Pub/Sub שאליו צריך לשלוח את ההתראות
  • הפורמט של ההודעה, "JSON" או "NONE"

  • סוגי האירועים הרצויים, שמתאימים לסטטוס 'הושלם' של TransferOperation.Statuses:

    • "TRANSFER_OPERATION_SUCCESS"
    • "TRANSFER_OPERATION_FAILED"
    • "TRANSFER_OPERATION_ABORTED"

הודעת NotificationConfig לדוגמה:

{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "eventTypes": ["TRANSFER_OPERATION_SUCCESS"],
     "payloadFormat": "JSON"
   },
   ...
}

מחליפים את מה שכתוב בשדות הבאים:

  • ‫project-id: מזהה הפרויקט ב-Google Cloud של ההעברה
  • ‫topic-id: שם נושא ה-Pub/Sub

מידע נוסף זמין במאמר מפרט REST של Pub/Sub ב-Storage Transfer Service.

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

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

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

מאפיינים

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

מידע נוסף על פורמט ההודעות ב-Pub/Sub זמין במאמר PubsubMessage.

שם המאפיין דוגמה תיאור
eventType TRANSFER_OPERATION_SUCCESS הסטטוס של TransferOperation, מ-NotificationConfig.EventType
payloadFormat "JSON" הפורמט של ההודעה, "JSON" או "NONE". מתוך NotificationConfig.PayloadFormat.
projectId project-3 המזהה של פרויקט המארח של ההעברה.
transferJobName transferJobs/123 שם העברת הנתונים.
transferOperationName transferOperations/456 שם פעולת ההעברה.

Payload

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

סוג המטען הייעודי (Payload) תיאור
NONE ההתראה לא כוללת מטען ייעודי (Payload).
JSON המטען הייעודי מעוצב כתגובת JSON, בפורמט application/json.

דוגמאות להגדרות של התראות Pub/Sub

התראות רק על העברות שנכשלו

כדי לקבל הודעות רק על העברות שנכשלו, שולחים TransferJob עם NotificationConfig שמסנן רק העברות שנכשלו:

// REST JSON format:
//   https://cloud.google.com/storage-transfer/docs/create-manage-transfer-program
{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "eventTypes": ["TRANSFER_OPERATION_FAILED"],
     "payloadFormat: "JSON"
   },
   ...
}

מחליפים את מה שכתוב בשדות הבאים:

  • ‫project-id: מזהה הפרויקט ב-Google Cloud של ההעברה
  • ‫topic-id: שם נושא ה-Pub/Sub

התראה על כל ההעברות שהושלמו

כדי לקבל הודעה על כל ההעברות שהושלמו, בלי קשר לסטטוס, שולחים TransferJob עם NotificationConfig בלי מסנני EventType:

// REST JSON format:
//   https://cloud.google.com/storage-transfer/docs/create-manage-transfer-program
{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "payloadFormat: "JSON"
   },
   ...
}

מחליפים את מה שכתוב בשדות הבאים:

  • ‫project-id: מזהה הפרויקט ב-Google Cloud של ההעברה
  • ‫topic-id: שם נושא ה-Pub/Sub

ביצוע פעולות שרירותיות בהעברה

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

דוגמאות לפעולות שרירותיות:

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

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

אין התחייבות שההתראות יפורסמו לפי הסדר שבו התקבלו ב-Pub/Sub.

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