התראות

סקירה כללית

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

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

  • מפעילים את Pub/Sub API לפרויקט ב-Google Cloud.
  • נותנים לחשבון השירות תפקידי Pub/Sub IAM בפרויקט Cloud. הקצאת התפקיד roles/pubsub.editor היא פשרה טובה (קלה ולא רחבה מדי), אבל יכול להיות שתרצו להשתמש בהרשאות Pub/Sub ספציפיות יותר.

יצירת נושא

על מנת ליצור נושא צריך להירשם ב-Seller API באמצעות ה-method resellernotify.register. השיטה resellernotify.register מתייחסת לכתובת אימייל של חשבון שירות כפרמטר. רק חשבונות שירות המורשים בשיטה הזו יכולים להירשם לנושא החדש שיצרתם.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

תשובה מוצלחת מחזירה את קוד הסטטוס 200 של HTTP ותגובת JSON שמכילה את שם נושא ה-Pub/Sub שלכם.

דוגמה לתגובה:

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

כדי לתת הרשאה לחשבונות שירות נוספים להשתמש בנושא שלך, אפשר להתקשר שוב אל resellernotify.register.

שלילת הגישה לחשבון שירות

ה-API של המפיץ מאפשר גם לבטל רישום של חשבונות שירות באמצעות נקודת הקצה resellernotify.unregister:

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

הרשמה לנושא

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

  • מינוי Push: אתם מספקים קריאה חוזרת (callback) של HTTP מסוג POST. Pub/Sub משתמש בקריאה החוזרת הזו כדי לעדכן את האפליקציה לגבי אירועים חדשים.
  • Pull subscription (שליפת מינוי): האפליקציה מבצעת מדי פעם קריאת HTTP כדי לקבל את כל השינויים שבתור.

הנה דוגמה לבקשת הרשמה לנושא:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

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

  • PROJECT: הפרויקט שלכם ב-Google Cloud.
  • SUBSCRIPTION_NAME: שם מזהה של המינוי שלך.
  • TOPIC_NAME: נושא ה-Pub/Sub שיצרתם בעבר.
  • PUSH_NOTIFICATION_ENDPOINT: נקודת הקצה של ה-handler של ההתראות.

תגובה מוצלחת מחזירה קוד סטטוס HTTP 200. זו דוגמה לתגובה:

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

פורמטים של התראות

דוגמה להתראה ב-Pub/Sub נתוני ההודעה משודרים כמחרוזת JSON בקידוד base64.

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

זהו האובייקט message.data לדוגמה לאחר פענוח הקוד:

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

סוגי אירועים

הרשימה הבאה כוללת את כל סוגי האירועים האפשריים:

  • NEW_SUBSCRIPTION_CREATED: נוצר מינוי חדש.
  • SUBSCRIPTION_TRIAL_ENDED: תקופת הניסיון של המינוי הסתיימה.
  • PRICE_PLAN_SWITCHED: הלקוח עבר מתוכנית גמישה לתוכנית שנתית. האירוע לא מופעל אם הלקוח עובר מתוכנית מסוג התחייבות לתוכנית גמישה כחלק מהחידוש.
  • COMMITMENT_CHANGED: ההתחייבות השנתית הוגדלה או הופחתה.
  • SUBSCRIPTION_RENEWED: המינוי השנתי חודש.
  • SUBSCRIPTION_SUSPENDED: המינוי מושעה. בודקים את השדה subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: השעיה בוטלה עבור מינוי שהושעה בעבר.
  • SUBSCRIPTION_CANCELLED: המינוי בוטל. בודקים את השדה subscription_cancellation_reason. יכול לשמש גם לזיהוי העברות.

  • SUBSCRIPTION_CONVERTED: המינוי הומר. דוגמאות למקרים כאלה:

    • המרת המינוי הישיר למינוי של המפיץ.
    • המרת מינוי בתשלום למבצע חסד.
    • המרת המינוי אונליין למינוי אופליין.

  • SUBSCRIPTION_UPGRADE: המק"ט של המינוי שודרג. לדוגמה, המינוי שודרג מ-Google Workspace Business Starter ל-Business Standard.

  • SUBSCRIPTION_DOWNGRADE: המק"ט של המינוי שודרג לאחור. לדוגמה, המינוי שודרג לאחור מ-Google Workspace Business Standard ל-Business Starter.

  • LICENSE_ASSIGNMENT_CHANGED: הרישיון הוקצה למשתמש או בוטל ממנו. אפשר להשתמש באירוע הזה כדי לעקוב באופן תגובתי אחר השינויים בספירת העמדות במינויים גמישים.

סיבות לביטול המינוי

הסיבה לביטול המינוי מאוכלסת כשהערך של event_type הוא SUBSCRIPTION_CANCELLED. אלה הסיבות האפשריות לביטול:

  • TRANSFERRED_OUT: הלקוח עבר לחיוב ישיר או למפיץ אחר.
  • PURCHASE_OF_SUBSUMING_SKU: הלקוח שדרג למק"ט שמחליף מק"ט אחר. לדוגמה, אם לקוח עם Google Workspace Business Starter ו-Google Vault משדרג ל-Google Workspace Business Plus, המינוי ל-Vault הוא כלול ב-Google Workspace Business Plus.
  • RESELLER_INITIATED: המפיץ ביטל את המינוי.
  • OTHER: המינוי בוטל מסיבה שאינה רשומה.

סיבות להשעיית המינוי

הסיבה להשעיית המינוי מאוכלסת כשהערך של event_type הוא SUBSCRIPTION_SUSPENDED. אלה הסיבות האפשריות להשעיה:

  • PENDING_TOS_ACCEPTANCE: הלקוח לא התחבר ולא אישר את התנאים וההגבלות של Google Workspace Resold.
  • RENEWAL_WITH_TYPE_CANCEL: ההתחייבות של הלקוח הסתיימה והשירות בוטל בסוף התקופה.
  • RESELLER_INITIATED: המפיץ השעה את המינוי באופן ידני.
  • TRIAL_ENDED: פג תוקף תקופת הניסיון של הלקוח, והלקוח לא בחר תוכנית ללא תקופת ניסיון.
  • OTHER: הלקוח הושעה מסיבה פנימית של Google – לדוגמה, התנהלות פוגעת.

מגבלות Pub/Sub

הסדר של ההתראות לא מובטח. ההודעות עשויות להישלח מספר פעמים ובמצבים קיצוניים, בכלל לא. כדי לקבל את המצב הנוכחי, מומלץ להשתמש ב-reseller.subscriptions.get בכל המינויים שהשתנו.