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

نظرة عامة

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

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

  • تفعيل Pub/Sub API لمشروعك على Google Cloud
  • يمكنك منح أدوار Pub/Sub IAM لحساب الخدمة الخاص بك المشروع على السحابة الإلكترونية. من خلال منح دور 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 يحتوي على اسم الموضوع على خدمة 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"
}

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

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

  • دفع الاشتراك: يمكنك توفير استدعاء 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. عادي.

  • 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 على جميع الاشتراكات التي تم تغييرها لسحب الحالية.