Skip to main content

API Reference — Events Ingestion

يمكنك الوصول إلى وثائق API الكاملة لاستيعاب أحداث الاستخدام واختبار طلبات استيعاب الأحداث واستجاباتها تفاعليًا.

API Reference — Meters Creation

استكشف وثائق API الكاملة لإنشاء العدادات واختبر طلبات إنشاء العدادات واستجاباتها تفاعليًا.

إنشاء عداد

تحدد العدادات كيفية تجميع أحداث الاستخدام وقياسها لأغراض الفوترة. قبل إنشاء عداد، خطط لاستراتيجية تتبع الاستخدام:
  • حدّد أحداث الاستخدام التي تريد تتبعها
  • حدّد كيفية تجميع الأحداث (العدد، المجموع، وغير ذلك)
  • حدّد متطلبات التصفية لأي حالات استخدام محددة

إنشاء العداد خطوة بخطوة

اتبع هذا الدليل لإعداد عداد الاستخدام الخاص بك:
1

Configure Basic Information

أعدّ التفاصيل الأساسية للعداد.
string
مطلوب
اسم واضح ووصفّي يحدد ما يتتبعه هذا العداد.أمثلة: “Tokens”، “API Calls”، “Storage Usage”، “Compute Hours”
string
شرح مفصل لما يقيسه هذا العداد.مثال: “يحسب كل طلب POST /v1/orders يجريه العميل”
string
مطلوب
معرّف الحدث الذي سيؤدي إلى تشغيل هذا العداد.أمثلة: “token”، “api.call”، “storage.usage”، “compute.session”
يجب أن يطابق اسم الحدث تمامًا الاسم الذي ترسله في أحداث الاستخدام. أسماء الأحداث حساسة لحالة الأحرف.
2

Configure Aggregation Settings

حدّد كيفية احتساب العداد للاستخدام من أحداثك.
string
مطلوب
اختر كيفية تجميع الأحداث:
يحسب عدد الأحداث المستلمة.حالة الاستخدام: استدعاءات API، مشاهدات الصفحات، تحميلات الملفاتالحساب: إجمالي عدد الأحداث
string
اسم الخاصية من البيانات الوصفية للحدث التي سيتم التجميع عليها.
هذا الحقل مطلوب عند استخدام أنواع التجميع Sum أو Max أو Last.
string
مطلوب
تسمية الوحدة لأغراض العرض في التقارير والفوترة.أمثلة: “calls”، “GB”، “hours”، “tokens”
3

Configure Event Filtering (Optional)

أعدّ معايير للتحكم في الأحداث التي يتم تضمينها في العداد.
تتيح لك تصفية الأحداث إنشاء قواعد متقدمة تحدد الأحداث التي تساهم في حسابات الاستخدام. يفيد ذلك في استبعاد أحداث الاختبار، والتصفية حسب مستويات المستخدمين، أو التركيز على إجراءات محددة.
تمكين تصفية الأحداثبدّل تمكين تصفية الأحداث لتفعيل معالجة الأحداث الشرطية.اختيار منطق التصفيةحدّد كيفية تقييم الشروط المتعددة:
يجب أن تكون جميع الشروط صحيحة حتى يتم احتساب الحدث. استخدم هذا الخيار عندما تحتاج إلى استيفاء الأحداث لعدة معايير صارمة في الوقت نفسه.مثال: احتساب استدعاءات API حيث user_tier = "premium" و endpoint = "/api/v2/users"
إعداد شروط التصفية
1

Add Condition

انقر على إضافة شرط لإنشاء قاعدة تصفية جديدة.
2

Configure Property Key

حدّد اسم الخاصية من البيانات الوصفية للحدث.
3

Select Comparator

اختر من العوامل المتاحة:
  • equals — تطابق تام
  • not_equals — عامل استبعاد
  • greater_than — مقارنة رقمية
  • greater_than_or_equals — مقارنة رقمية (شاملة)
  • less_than — مقارنة رقمية
  • less_than_or_equals — مقارنة رقمية (شاملة)
  • contains — تحتوي السلسلة على سلسلة فرعية
  • does_not_contain — عامل استبعاد السلسلة
4

Set Comparison Value

حدّد القيمة المستهدفة للمقارنة.
5

Add Groups

استخدم إضافة مجموعة لإنشاء مجموعات شروط إضافية للمنطق المعقد.
يجب تضمين الخصائص المصفاة في البيانات الوصفية للحدث حتى تعمل الشروط بشكل صحيح. سيتم استبعاد الأحداث التي تفتقد إلى الخصائص المطلوبة من العد.
4

Create Meter

راجع إعدادات العداد وانقر على Create Meter.
أصبح عدادك الآن جاهزًا لاستقبال أحداث الاستخدام وتجميعها.

ربط العداد بمنتج

بعد إنشاء العداد، يجب ربطه بمنتج لتمكين الفوترة القائمة على الاستخدام. تربط هذه العملية بيانات الاستخدام الخاصة بالعداد بقواعد التسعير لفوترة العملاء. يؤدي ربط العدادات بالمنتجات إلى إنشاء الصلة بين تتبع الاستخدام والفوترة:
  • تحدد المنتجات قواعد التسعير وسلوك الفوترة
  • توفر العدادات بيانات الاستخدام اللازمة لحسابات الفوترة
  • يمكن ربط عدة عدادات بمنتج واحد لسيناريوهات الفوترة المعقدة

عملية إعداد المنتج

حوّل بيانات الاستخدام إلى رسوم قابلة للفوترة من خلال إعداد خيارات المنتج بشكل صحيح:
1

Choose Usage-Based Billing Product Type

انتقل إلى صفحة إنشاء المنتج أو تحريره، وحدد Usage Based Billing كنوع التسعير.
2

Select Associated Meter

انقر على Associated Meters لفتح لوحة اختيار العداد.تتيح لك هذه اللوحة إعداد العدادات التي ستتتبع الاستخدام لهذا المنتج.
3

Add Your Meter

في لوحة اختيار العداد:
  1. انقر على Add Meters لعرض العدادات المتاحة
  2. حدد العداد الذي أنشأته من القائمة المنسدلة
  3. سيظهر العداد المحدد في إعدادات منتجك
4

Configure Price Per Unit

حدد سعر كل وحدة من الاستخدام الذي يتتبعه العداد.
number
مطلوب
حدد المبلغ الذي سيتم تحصيله مقابل كل وحدة يقيسها العداد.مثال: يعني تحديد سعر بقيمة $0.50 لكل وحدة ما يلي:
  • استهلاك 1,000 وحدة = 1,000 × $0.50 = تحصيل $500.00
  • استهلاك 500 وحدة = 500 × $0.50 = تحصيل $250.00
  • استهلاك 100 وحدة = 100 × $0.50 = تحصيل $50.00
5

Set Free Threshold (Optional)

حدد حصة استخدام مجانية قبل بدء الفوترة.
number
عدد الوحدات التي يمكن للعملاء استهلاكها مجانًا قبل بدء حساب الاستخدام المدفوع.آلية العمل:
  • الحد المجاني: 100 وحدة
  • سعر الوحدة: $0.50
  • استخدام العميل: 250 وحدة
  • الحساب: (250 - 100) × $0.50 = تحصيل $75.00
تُعد الحدود المجانية مناسبة لنماذج freemium أو الفترات التجريبية أو توفير حصة أساسية للعملاء مضمنة في خطتهم.
ينطبق الحد المجاني على كل دورة فوترة، ما يمنح العملاء حصصًا جديدة شهريًا أو وفقًا لجدول الفوترة الخاص بك.
6

Save Configuration

راجع إعدادات العداد والتسعير، ثم انقر على Save Changes لإتمام الإعداد.
تم الآن إعداد منتجك للفوترة القائمة على الاستخدام، وسيتم تحصيل الرسوم من العملاء تلقائيًا استنادًا إلى استهلاكهم المقاس.
ما يحدث بعد ذلك:
  • ستُتتبع أحداث الاستخدام المرسلة إلى العداد وتُجمع
  • ستطبق حسابات الفوترة قواعد التسعير تلقائيًا
  • ستُحصّل الرسوم من العملاء استنادًا إلى الاستهلاك الفعلي خلال كل دورة فوترة
يمكنك إضافة ما يصل إلى 50 عدادًا لكل منتج، ما يتيح تتبع الاستخدام المتقدم عبر أبعاد متعددة مثل استدعاءات API والتخزين ووقت الحوسبة والمقاييس المخصصة.

إرسال أحداث الاستخدام

بعد إعداد العداد، يمكنك البدء في إرسال أحداث الاستخدام من تطبيقك لتتبع استخدام العملاء.

بنية الحدث

يجب أن يتضمن كل حدث استخدام الحقول المطلوبة التالية:
string
مطلوب
معرّف فريد لهذا الحدث المحدد. يجب أن يكون فريدًا بين جميع الأحداث.
string
مطلوب
معرّف عميل Dodo Payments الذي يجب إسناد هذا الاستخدام إليه.
string
مطلوب
اسم الحدث المطابق لإعدادات العداد. تؤدي أسماء الأحداث إلى تشغيل العداد المناسب.
string
طابع زمني بتنسيق ISO 8601 يحدد وقت وقوع الحدث. يُستخدم طابع UTC الحالي افتراضيًا إذا لم يتم توفيره. يجب أن يقع ضمن الساعة الماضية والخمس دقائق القادمة — وتُرفض الطوابع الزمنية خارج هذه الفترة.
object
خصائص إضافية للتصفية والتجميع. أدرج أي قيم يُشار إليها في شرط “Over Property” أو شروط التصفية للعداد.

أمثلة على Usage Events API

أرسل أحداث الاستخدام إلى العدادات التي أعددتها باستخدام Events API:

نقاط أساسية لضمان الاستيعاب الموثوق

اتبع هذه الممارسات للحفاظ على دقة تتبع الاستخدام ومرونته في بيئة الإنتاج.
استخدم event_ids حتمية وغير قابلة لتكرار العملية. يجب أن يكون event_id فريدًا بين جميع الأحداث، ويعمل كمفتاح لضمان عدم تكرار العملية. يُعامل استخدام event_id مُعاد على أنه تكرار، ولا يُحتسب مرة أخرى، لذلك لا تؤدي إعادة المحاولة إلى تحصيل الرسوم مرتين. اشتق المعرّف من الإجراء بدلًا من استخدام قيمة عشوائية، مثل `${customer_id}_${action}_${timestamp}`.
جمّع الأحداث، بما يصل إلى 1,000 حدث لكل طلب. تفرض نقطة النهاية /events/ingest حدًا أقصى ثابتًا يبلغ 1,000 حدث لكل طلب. وتُرفض الدفعات الأكبر من ذلك، لذا قسّم الأحجام الكبيرة على عدة استدعاءات. بالنسبة لأحمال العمل الكبيرة، خزّن الأحداث مؤقتًا وأرسلها على دفعات بدلًا من إرسال طلب واحد لكل حدث.
أعد المحاولة عند أخطاء 5xx و429، وليس عند أخطاء 4xx الأخرى. أعد المحاولة عند أخطاء الخادم (5xx) وحدود المعدل (429) مع تأخير أُسّي. لا تُعد محاولة أخطاء التحقق 400/422 — فبيانات الحمولة غير صحيحة وستفشل في كل مرة. أصلحها وأعد إرسالها. ضع الأحداث التي تستمر في الفشل بعد إعادة المحاولات في قائمة انتظار حتى لا يُفقد أي منها.
حدد الطوابع الزمنية بعناية. احذف timestamp للأحداث الفورية، وسيُستخدم طابع UTC الحالي افتراضيًا. حدده صراحةً (بتنسيق ISO 8601) للأحداث المؤجلة أو المجمعة حتى يُسجل الاستخدام في فترة الفوترة الصحيحة. انتبه إلى أن الفترة المقبولة ضيقة: تُرفض الأحداث التي يزيد طابعها عن ساعة في الماضي أو يتجاوز خمس دقائق في المستقبل. لا يُدعم ملء البيانات التاريخية — أرسل الأحداث المخزنة مؤقتًا خلال ساعة.
أرسل البيانات الوصفية المجمعة كأرقام، وليس كسلاسل نصية. يجب أن تكون أي خاصية يُشار إليها بواسطة Over Property للعداد (Sum أو Max أو Last) من نوع رقمي — { "tokens": 150 }، وليس { "tokens": "150" }. لن تُجمع القيم النصية.

تحليلات الفوترة القائمة على الاستخدام

راقب بيانات الفوترة القائمة على الاستخدام وحللها باستخدام لوحة تحليلات شاملة. تتبع أنماط استهلاك العملاء وأداء العدادات واتجاهات الفوترة لتحسين استراتيجية التسعير وفهم سلوكيات الاستخدام.

تحليلات النظرة العامة

توفر علامة التبويب Overview عرضًا شاملًا لأداء الفوترة القائمة على الاستخدام:

مقاييس النشاط

تتبع إحصاءات الاستخدام الرئيسية عبر فترات زمنية مختلفة:
metric
يعرض نشاط الاستخدام لفترة الفوترة الحالية، ما يساعدك على فهم أنماط الاستهلاك الشهرية.
metric
يعرض إحصاءات الاستخدام التراكمية منذ بدء التتبع، ما يوفر رؤى حول النمو على المدى الطويل.
استخدم محدد الفترة الزمنية لمقارنة الاستخدام عبر أشهر مختلفة وتحديد الاتجاهات الموسمية أو أنماط النمو.

مخطط كميات العداد

مخطط كميات العداد يوضح اتجاهات الاستخدام بمرور الوقت مع تصور بتدرج أرجواني
يعرض مخطط كميات العداد اتجاهات الاستخدام بمرور الوقت، مع الميزات التالية:
  • تصور السلاسل الزمنية: تتبع أنماط الاستخدام عبر الأيام أو الأسابيع أو الأشهر
  • دعم عدة عدادات: عرض بيانات من عدادات مختلفة في الوقت نفسه
  • تحليل الاتجاهات: تحديد ارتفاعات الاستخدام والأنماط ومسارات النمو
يضبط المخطط مقياسه تلقائيًا استنادًا إلى حجم الاستخدام والنطاق الزمني المحدد، ما يوفر رؤية واضحة للتقلبات الصغيرة وتغيّرات الاستخدام الكبيرة.

تحليلات الأحداث

جدول الأحداث يعرض أسماء الأحداث ومعرّفاتها وعناصر التحكم في ترقيم الصفحات لتحليل الأحداث بالتفصيل
توفر علامة التبويب Events رؤية تفصيلية لأحداث الاستخدام الفردية:

عرض معلومات الحدث

يوفر جدول الأحداث عرضًا واضحًا لأحداث الاستخدام الفردية مع الأعمدة التالية:
  • اسم الحدث: الإجراء أو المُشغّل المحدد الذي أنشأ حدث الاستخدام
  • معرّف الحدث: معرّف فريد لكل مثيل حدث
  • معرّف العميل: العميل المرتبط بالحدث
  • الطابع الزمني: وقت وقوع الحدث
يتيح لك هذا العرض تتبع أحداث الاستخدام الفردية ومراقبتها عبر قاعدة عملائك، ما يوفر شفافية حول حسابات الفوترة وأنماط الاستخدام.

تحليلات العملاء

توفر علامة التبويب Customers عرضًا جدوليًا مفصلًا لبيانات استخدام العملاء، مع المعلومات التالية:

أعمدة البيانات المتاحة

string
عنوان البريد الإلكتروني للعميل لأغراض التعريف.
string
معرّف فريد لاشتراك العميل.
number
عدد الوحدات المجانية المضمنة في خطة العميل قبل تطبيق الرسوم.
currency
تكلفة كل وحدة من الاستخدام الذي يتجاوز الحد المجاني.
timestamp
الطابع الزمني لأحدث حدث استخدام للعميل.
currency
إجمالي المبلغ الذي تم تحصيله من العميل مقابل الفوترة القائمة على الاستخدام.
number
إجمالي عدد الوحدات التي استهلكها العميل.
number
عدد الوحدات التي تتجاوز الحد المجاني ويتم تحصيل رسوم مقابلها.

ميزات الجدول

  • تصفية الأعمدة: استخدم ميزة “Edit Columns” لإظهار أعمدة بيانات محددة أو إخفائها
  • التحديثات الفورية: تعكس بيانات الاستخدام أحدث مقاييس الاستهلاك

أمثلة على التجميع

فيما يلي أمثلة عملية على كيفية عمل أنواع التجميع المختلفة:

فهم أنواع التجميع

تخدم أنواع التجميع المختلفة سيناريوهات فوترة مختلفة. اختر النوع المناسب استنادًا إلى كيفية رغبتك في قياس الاستخدام وتحصيل الرسوم مقابله.

أمثلة عملية على التنفيذ

توضح هذه الأمثلة التطبيقات الواقعية لكل نوع من أنواع التجميع، مع أحداث نموذجية ونتائج متوقعة:
السيناريو: تتبع العدد الإجمالي لطلبات APIإعداد العداد:
  • اسم الحدث: api.call
  • نوع التجميع: Count
  • وحدة القياس: calls
الأحداث النموذجية:
النتيجة: تمت فوترة العميل مقابل 3 استدعاءات
السيناريو: الفوترة استنادًا إلى إجمالي وحدات البايت المنقولةإعداد العداد:
  • اسم الحدث: data.transfer
  • نوع التجميع: Sum
  • الخاصية التي يتم التجميع عليها: bytes
  • وحدة القياس: GB
الأحداث النموذجية:
النتيجة: تمت فوترة العميل مقابل إجمالي نقل يبلغ 1.5 GB
السيناريو: الفوترة استنادًا إلى أعلى عدد متزامن من المستخدمينإعداد العداد:
  • اسم الحدث: concurrent.users
  • نوع التجميع: Max
  • الخاصية التي يتم التجميع عليها: count
  • وحدة القياس: users
الأحداث النموذجية:
النتيجة: تمت فوترة العميل مقابل ذروة بلغت 23 مستخدمًا متزامنًا

أمثلة على تصفية الأحداث

احسب استدعاءات API لنقاط نهاية محددة فقط:إعداد التصفية:
  • الخاصية: endpoint
  • عامل المقارنة: equals
  • القيمة: /v1/orders
الحدث النموذجي:
النتيجة: تُحتسب الأحداث المطابقة لمعايير التصفية. ويتم تجاهل الأحداث ذات نقاط النهاية المختلفة.

استكشاف الأخطاء وإصلاحها

حل المشكلات الشائعة في تنفيذ الفوترة القائمة على الاستخدام، وتأكد من دقة التتبع والفوترة.

المشكلات الشائعة

تندرج معظم مشكلات الفوترة القائمة على الاستخدام ضمن الفئات التالية:
  • مشكلات تسليم الأحداث ومعالجتها
  • مشكلات إعداد العداد
  • أخطاء نوع البيانات وتنسيقها
  • مشكلات معرّف العميل والمصادقة

خطوات تصحيح الأخطاء

عند استكشاف أخطاء الفوترة القائمة على الاستخدام وإصلاحها:
  1. تحقق من تسليم الأحداث في علامة تبويب تحليلات Events
  2. تحقق من تطابق إعداد العداد مع بنية الحدث
  3. تحقق من معرّفات العملاء ومصادقة API
  4. راجع شروط التصفية وإعدادات التجميع

الحلول والإصلاحات

الأسباب الشائعة:
  • لا يطابق اسم الحدث إعدادات العداد تمامًا
  • تستبعد شروط تصفية الأحداث أحداثك
  • معرّف العميل غير موجود في حساب Dodo Payments الخاص بك
  • الطابع الزمني للحدث خارج فترة الفوترة الحالية
الحلول:
  • تحقق من تهجئة اسم الحدث وحساسية حالة الأحرف
  • راجع شروط التصفية واختبرها
  • تأكد من صحة معرّف العميل ونشاطه
  • تحقق من حداثة الطوابع الزمنية للأحداث وتنسيقها بشكل صحيح
الأسباب الشائعة:
  • لا يطابق اسم Over Property مفاتيح البيانات الوصفية للحدث
  • قيم البيانات الوصفية من نوع بيانات غير صحيح (سلسلة نصية بدلًا من رقم)
  • خصائص البيانات الوصفية المطلوبة مفقودة
الحلول:
  • تأكد من تطابق مفاتيح البيانات الوصفية تمامًا مع إعداد Over Property
  • حوّل الأرقام النصية إلى أرقام فعلية في أحداثك
  • أدرج جميع الخصائص المطلوبة في كل حدث
الأسباب الشائعة:
  • لا تطابق أسماء خصائص التصفية البيانات الوصفية للحدث
  • عامل مقارنة غير مناسب لنوع البيانات (سلسلة نصية بدلًا من رقم)
  • حساسية حالة الأحرف في مقارنات السلاسل النصية
الحلول:
  • تحقق مرة أخرى من تطابق أسماء الخصائص تمامًا
  • استخدم عوامل المقارنة المناسبة لأنواع بياناتك
  • ضع حساسية حالة الأحرف في الاعتبار عند تصفية السلاسل النصية

مرجع API ذي صلة

Create Meter

مرجع API لإنشاء عدادات الاستخدام وإعدادها لتتبع استهلاك العملاء.

Ingest Usage Events

مرجع API لإرسال أحداث الاستخدام إلى العدادات التي أعددتها بغرض حسابات الفوترة.
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦