اعلان های فشاری

نمای کلی

Reseller API از Pub/Sub API برای ارائه اعلان‌های فشاری درباره رویدادهای مختلف اشتراک Google Workspace استفاده می‌کند. برای مثال، می‌توانید اعلان‌های فشاری را تنظیم کنید تا در صورت تغییر وضعیت اشتراک مشتریان، به شما اطلاع داده شود.

پیش نیازها

  • Pub/Sub API را برای پروژه Google Cloud خود فعال کنید.
  • نقش های Pub/Sub IAM را به حساب سرویس خود در پروژه Cloud خود اعطا کنید. اعطای roles/pubsub.editor مصالحه خوبی است (آسان و نه خیلی گسترده)، اما ممکن است بخواهید از مجوزهای Pub/Sub خاص تر استفاده کنید.

یک موضوع ایجاد کنید

برای ایجاد موضوع، باید با استفاده از روش resellernotify.register در Reseller API ثبت نام کنید. روش 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، باید نحوه مصرف برنامه‌تان از رویدادهای تغییر را تنظیم کنید. یکی از گزینه های زیر را انتخاب کنید:

  • اشتراک Push : شما یک پاسخ تماس 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 : نقطه پایانی کنترل کننده اعلان فشار شما.

یک پاسخ موفق یک کد وضعیت HTTP 200 را برمی گرداند. در زیر یک نمونه پاسخ است:

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

فرمت های اطلاع رسانی

در زیر نمونه ای از اعلان Pub/Sub آورده شده است. داده های پیام به عنوان یک رشته JSON با کدگذاری پایه 64 منتقل می شود.

{
  "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 : SKU اشتراک ارتقا یافت. برای مثال، اشتراک از Google Workspace Business Starter به Business Standard ارتقا یافت.

  • SUBSCRIPTION_DOWNGRADE : SKU اشتراک تنزل یافت. به عنوان مثال، اشتراک از Google Workspace Business Standard به Business Starter تنزل یافت.

  • LICENSE_ASSIGNMENT_CHANGED : مجوز به یک کاربر اختصاص داده شده یا از او لغو شده است. می‌توانید از این رویداد برای پیگیری تغییرات تعداد صندلی‌ها برای اشتراک‌های Flexible استفاده کنید.

دلایل لغو اشتراک

دلیل لغو اشتراک زمانی پر می شود که event_type SUBSCRIPTION_CANCELLED باشد. موارد زیر دلایل احتمالی لغو هستند:

  • TRANSFERRED_OUT : مشتری به صورت‌حساب مستقیم یا به فروشنده دیگری منتقل شده است.
  • PURCHASE_OF_SUBSUMING_SKU : مشتری به 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 به حالت تعلیق درآمده است - به عنوان مثال، سوء استفاده.

میخانه / محدودیت های فرعی

سفارش اعلان فشار تضمین نشده است. پیام‌ها ممکن است چندین بار و در شرایط شدید ارسال شوند، اصلا. توصیه می‌کنیم از reseller.subscriptions.get در همه اشتراک‌های تغییر یافته استفاده کنید تا وضعیت فعلی را به دست آورید.