התראות

סקירה כללית

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

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

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

יצירת נושא

כדי ליצור נושא, עליך להירשם לממשק ה-API למפיצים באמצעות השיטה 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, צריך להגדיר את האופן שבו האפליקציה משתמש באירועי השינוי שלכם. בחר אחת מהאפשרויות הבאות:

  • דחיפת מינוי: אתם מספקים קריאה חוזרת (callback) מסוג POST של HTTP. שימושים ב-Pub/Sub הקריאה החוזרת (callback) הזו כדי להודיע לאפליקציה שלך על אירועים חדשים.
  • 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 רגילה.

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

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

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

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

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

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

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

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

מגבלות ב-Pub/Sub

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