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

توضّح هذه الصفحة كيفية استخدام الإشعارات الفورية مع واجهة برمجة تطبيقات المورّد.

نظرة عامة

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

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

إنشاء موضوع

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

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