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

نظرة عامة

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

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

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

إنشاء موضوع

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

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

توفّر واجهة برمجة تطبيقات المورّد أيضًا إمكانية إلغاء تسجيل حسابات الخدمة باستخدام نقطة نهاية resellernotify.unregister:

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

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

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

  • الاشتراك المدفوع: يمكنك تقديم رد اتصال HTTP POST. تستخدم ميزة "النشر/الاشتراك" معاودة الاتصال هذه لإعلام تطبيقك بالأحداث الجديدة.
  • اشتراك سحب الاشتراك: يُجري تطبيقك استدعاء 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: موضوع النشر/الاشتراك الذي أنشأته سابقًا
  • PUSH_NOTIFICATION_ENDPOINT: نقطة نهاية معالج الإشعارات الفورية

تعرض الاستجابة الناجحة رمز حالة HTTP 200. فيما يلي مثال على الرد: 

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

أشكال الإشعارات

في ما يلي مثال على إشعار النشر/الاشتراك. ويتم نقل بيانات الرسالة كسلسلة 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، مثل إساءة الاستخدام.

قيود النشر/الاشتراك

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