התראות

סקירה כללית

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

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

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

יצירת נושא

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

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

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

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

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

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

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

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

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

הרשמה לנושא

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

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

תגובה מוצלחת מחזירה קוד סטטוס 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 למפיצים.
  • RENEWAL_WITH_TYPE_CANCEL: ההתחייבות של הלקוח הסתיימה והשירות שלו בוטל בסוף תקופת ההתחייבות.
  • RESELLER_INITIATED: המפיץ השעה את המינוי באופן ידני.
  • TRIAL_ENDED: תוקף תקופת הניסיון של הלקוח פג, והלקוח לא בחר בחבילה ללא תקופת ניסיון.
  • OTHER: הלקוח הושעה מסיבה פנימית של Google, למשל, ניצול לרעה.

מגבלות של Pub/Sub

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