התראות

בדף הזה מוסבר איך להשתמש בהתראות פוש עם Reseller API.

סקירה כללית

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

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

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

יצירת נושא

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

  • הרשמה לקבלת עדכונים: אתם מספקים קריאה חוזרת (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 של הודעות הפוש.

תגובה מוצלחת מחזירה קוד סטטוס 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 dependent 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 ו-Vault משדרג ל-Business Plus, שכולל את Vault.
  • ‫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 במינויים שהשתנו כדי לאחזר את המצב הנוכחי.