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

نمای کلی

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

پیش‌نیازها

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

ایجاد تاپیک

برای ایجاد یک موضوع، باید با استفاده از متد resellernotify.register در API مربوط به Reseller ثبت نام کنید. متد 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 همچنین امکان لغو ثبت حساب‌های سرویس را با استفاده از نقطه پایانی 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 از این فراخوانی برای اطلاع‌رسانی به برنامه شما در مورد رویدادهای جدید استفاده می‌کند.
  • اشتراک در 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 : پروژه گوگل کلود شما.
  • SUBSCRIPTION_NAME : یک نام شناسایی برای اشتراک شما.
  • TOPIC_NAME : موضوع میخانه/زیرموضوعی که قبلاً ایجاد کرده‌اید.
  • PUSH_NOTIFICATION_ENDPOINT : نقطه پایانی کنترل کننده اعلان فشار شما.

یک پاسخ موفق، کد وضعیت 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 : سطح SKU اشتراک کاهش یافت. برای مثال، سطح اشتراک از Google Workspace Business Standard به Business Starter کاهش یافت.

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

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

دلیل لغو اشتراک زمانی که event_type SUBSCRIPTION_CANCELLED باشد، نمایش داده می‌شود. دلایل لغو ممکن عبارتند از:

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

محدودیت‌های انتشار/زیرمجموعه

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