התראות

סקירה כללית

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

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

  • מפעילים את Pub/Sub API בפרויקט ב-Google Cloud.
  • מקצים לחשבון השירות תפקידי IAM ב-Pub/Sub בפרויקט ב-Cloud. הקצאת התפקיד 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"
}

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

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

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

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