התראות

סקירה כללית

ב-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 בכל המינויים שהשתנו כדי למשוך את המצב הנוכחי.