התראות 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 הרצוי.

קביעת הגדרת התראות

כדי לקבוע את הגדרות ההתראות של Storage Transfer Service ב-Pub/Sub, משתמשים ב-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

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

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

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

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

מאפיינים

המאפיינים הם צמדי מפתח/ערך שכלולים בכל ההתראות שנשלחות מ-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 המטען הייעודי (payload) מפורמט כתגובת JSON, ב-application/json.

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

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

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

{
   ...
   "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:

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

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

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

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

כדי לבצע פעולה שרירותית, אתם צריכים ליצור התראת Pub/Sub באמצעות פונקציה של Cloud Functions עם טריגר של Pub/Sub, בשילוב עם פונקציה של Cloud Functions ברקע. מידע נוסף זמין במדריך של 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 כבר אין הרשאה לפרסם בנושא הזה או כשהפרויקט שהנושא בבעלותו חורג ממכסת הפרסום שלו.