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

نظرة عامة

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

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

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

إنشاء موضوع

لإنشاء موضوع، عليك التسجيل في Reseller API باستخدام resellernotify.register method. تستخدِم الطريقة 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 مرة أخرى.

إبطال إذن الوصول لحساب خدمة

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