الإشعارات الفورية

توضّح هذه الصفحة كيفية استخدام الإشعارات الفورية مع Reseller API.

نظرة عامة

تستخدم واجهة برمجة تطبيقات المورّد واجهة Pub/Sub API لعرض إشعارات فورية بشأن أحداث الاشتراك في Google Workspace. على سبيل المثال، يمكنك إعداد إشعارات فورية لتلقّي إشعارات عند تغيير حالات اشتراك العملاء.

المتطلبات الأساسية

  • فعِّل واجهة برمجة التطبيقات Pub/Sub API لمشروعك على Google Cloud.
  • امنح أدوار Pub/Sub في إدارة الهوية وإمكانية الوصول لحساب الخدمة في مشروعك على السحابة الإلكترونية. يُنصح بمنح دور roles/pubsub.editor، ولكن يمكنك استخدام أذونات Pub/Sub أكثر تحديدًا.

إنشاء موضوع

لإنشاء موضوع، عليك التسجيل في 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، اضبط طريقة استهلاك تطبيقك لأحداث التغيير. عليك تحديد أحد الخيارات التالية:

  • الاشتراك في الإشعارات الفورية: يمكنك تقديم عملية ردّ الاتصال POST عبر HTTP. تستخدم خدمة 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 مشفّرة بترميز 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 في الاشتراكات التي تم تغييرها لاسترداد الحالة الحالية.