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

نظرة عامة

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

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

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

إنشاء موضوع

لإنشاء موضوع، عليك التسجيل في Reseller API باستخدام الطريقة resellernotify.register. تتطلّب الطريقة resellernotify.register عنوان بريد إلكتروني لحساب خدمة كمعلَمة. يمكن فقط لحسابات الخدمة التي تم تفويضها بهذه الطريقة الاشتراك في الموضوع الذي تم إنشاؤه حديثًا.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

تعرض الاستجابة الناجحة رمز الحالة HTTP 200 واستجابة JSON تحتوي على اسم موضوع النشر/الاشتراك.

في ما يلي مثال على الرد:

{
  "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"
}

الاشتراك في موضوع

بعد إنشاء موضوع النشر/الاشتراك، عليك إعداد طريقة استهلاك تطبيقك لأحداث التغيير. اختَر أحد الخيارات التالية:

  • الاشتراك في الإشعارات الفورية: يمكنك تقديم 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 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: تم الرجوع إلى إصدار سابق من رمز التخزين التعريفي الخاص بالاشتراك. على سبيل المثال، تم الرجوع من اشتراك Google Workspace Business Standard إلى اشتراك Business Starter.

  • ‫LICENSE_ASSIGNMENT_CHANGED: تم منح ترخيص لمستخدم أو إبطاله. يمكنك استخدام هذا الحدث لتتبُّع التغييرات في عدد المقاعد بشكل تفاعلي في الاشتراكات المرنة.

أسباب إلغاء الاشتراك

يتم ملء حقل "سبب إلغاء الاشتراك" عندما تكون قيمة event_type هي SUBSCRIPTION_CANCELLED. في ما يلي الأسباب المحتملة للإلغاء:

  • ‫TRANSFERRED_OUT: تم نقل العميل إلى الفوترة المباشرة أو إلى مورّد آخر.
  • PURCHASE_OF_SUBSUMING_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، مثل إساءة الاستخدام.

قيود Pub/Sub

لا نضمن ترتيب الإشعارات الفورية. قد يتم تسليم الرسائل عدة مرات، وفي الحالات القصوى، قد لا يتم تسليمها على الإطلاق. ننصحك باستخدام reseller.subscriptions.get في جميع الاشتراكات التي تم تغييرها لجلب الحالة الحالية.