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

این صفحه نحوه استفاده از اعلان‌های فوری با رابط برنامه‌نویسی کاربردی فروشندگان (Reseller API) را شرح می‌دهد.

نمای کلی

رابط برنامه‌نویسی کاربردی فروشنده (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 ثبت نام کنید. این متد یک آدرس ایمیل حساب کاربری سرویس را به عنوان پارامتر دریافت می‌کند. فقط حساب‌های کاربری سرویس که توسط این متد مجاز شده‌اند می‌توانند در موضوع شما مشترک شوند.

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 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 is suspended. See subscription_suspension_reasons .
  • SUBSCRIPTION_SUSPENSION_REVOKED : تعلیق لغو شد.
  • SUBSCRIPTION_CANCELLED : اشتراک لغو شد. به subscription_cancellation_reason مراجعه کنید. همچنین می‌تواند انتقال‌ها را تشخیص دهد.
  • SUBSCRIPTION_CONVERTED : اشتراک تبدیل شد. مثال‌هایی از موارد:
    • اشتراک مستقیم را به اشتراک نمایندگی فروش تبدیل کنید.
    • اشتراک پولی را به پیشنهاد ویژه تبدیل کنید.
    • اشتراک آنلاین را به اشتراک آفلاین تبدیل کنید.
  • SUBSCRIPTION_UPGRADE : کد اشتراک ارتقا یافت. مثال: Google Workspace Business Starter به Business Standard.
  • SUBSCRIPTION_DOWNGRADE : Subscription SKU was downgraded. Example: Google Workspace Business Standard to Business Starter.
  • LICENSE_ASSIGNMENT_CHANGED : مجوز اعطا یا لغو شد. برای ردیابی تغییرات تعداد صندلی‌ها برای اشتراک‌های انعطاف‌پذیر استفاده می‌شود.

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

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

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

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

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