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
مطلوب
اختر كيفية تجميع الأحداث:
- Count
- Sum
- Max
- Last
يحسب عدد الأحداث المستلمة.حالة الاستخدام: استدعاءات API، مشاهدات الصفحات، تحميلات الملفاتالحساب: إجمالي عدد الأحداث
string
اسم الخاصية من البيانات الوصفية للحدث التي سيتم التجميع عليها.
string
مطلوب
تسمية الوحدة لأغراض العرض في التقارير والفوترة.أمثلة: “calls”، “GB”، “hours”، “tokens”
3
Configure Event Filtering (Optional)
أعدّ معايير للتحكم في الأحداث التي يتم تضمينها في العداد.تمكين تصفية الأحداثبدّل تمكين تصفية الأحداث لتفعيل معالجة الأحداث الشرطية.اختيار منطق التصفيةحدّد كيفية تقييم الشروط المتعددة:إعداد شروط التصفية
تتيح لك تصفية الأحداث إنشاء قواعد متقدمة تحدد الأحداث التي تساهم في حسابات الاستخدام. يفيد ذلك في استبعاد أحداث الاختبار، والتصفية حسب مستويات المستخدمين، أو التركيز على إجراءات محددة.
- AND Logic
- OR Logic
يجب أن تكون جميع الشروط صحيحة حتى يتم احتساب الحدث. استخدم هذا الخيار عندما تحتاج إلى استيفاء الأحداث لعدة معايير صارمة في الوقت نفسه.مثال: احتساب استدعاءات 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
في لوحة اختيار العداد:
- انقر على Add Meters لعرض العدادات المتاحة
- حدد العداد الذي أنشأته من القائمة المنسدلة
- سيظهر العداد المحدد في إعدادات منتجك
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:نقاط أساسية لضمان الاستيعاب الموثوق
اتبع هذه الممارسات للحفاظ على دقة تتبع الاستخدام ومرونته في بيئة الإنتاج.حدد الطوابع الزمنية بعناية. احذف
timestamp للأحداث الفورية، وسيُستخدم طابع UTC الحالي افتراضيًا. حدده صراحةً (بتنسيق ISO 8601) للأحداث المؤجلة أو المجمعة حتى يُسجل الاستخدام في فترة الفوترة الصحيحة. انتبه إلى أن الفترة المقبولة ضيقة: تُرفض الأحداث التي يزيد طابعها عن ساعة في الماضي أو يتجاوز خمس دقائق في المستقبل. لا يُدعم ملء البيانات التاريخية — أرسل الأحداث المخزنة مؤقتًا خلال ساعة.تحليلات الفوترة القائمة على الاستخدام
راقب بيانات الفوترة القائمة على الاستخدام وحللها باستخدام لوحة تحليلات شاملة. تتبع أنماط استهلاك العملاء وأداء العدادات واتجاهات الفوترة لتحسين استراتيجية التسعير وفهم سلوكيات الاستخدام.تحليلات النظرة العامة
توفر علامة التبويب Overview عرضًا شاملًا لأداء الفوترة القائمة على الاستخدام:مقاييس النشاط
تتبع إحصاءات الاستخدام الرئيسية عبر فترات زمنية مختلفة:metric
يعرض نشاط الاستخدام لفترة الفوترة الحالية، ما يساعدك على فهم أنماط الاستهلاك الشهرية.
metric
يعرض إحصاءات الاستخدام التراكمية منذ بدء التتبع، ما يوفر رؤى حول النمو على المدى الطويل.
مخطط كميات العداد

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

عرض معلومات الحدث
يوفر جدول الأحداث عرضًا واضحًا لأحداث الاستخدام الفردية مع الأعمدة التالية:- اسم الحدث: الإجراء أو المُشغّل المحدد الذي أنشأ حدث الاستخدام
- معرّف الحدث: معرّف فريد لكل مثيل حدث
- معرّف العميل: العميل المرتبط بالحدث
- الطابع الزمني: وقت وقوع الحدث
يتيح لك هذا العرض تتبع أحداث الاستخدام الفردية ومراقبتها عبر قاعدة عملائك، ما يوفر شفافية حول حسابات الفوترة وأنماط الاستخدام.
تحليلات العملاء
توفر علامة التبويب Customers عرضًا جدوليًا مفصلًا لبيانات استخدام العملاء، مع المعلومات التالية:أعمدة البيانات المتاحة
string
عنوان البريد الإلكتروني للعميل لأغراض التعريف.
string
معرّف فريد لاشتراك العميل.
number
عدد الوحدات المجانية المضمنة في خطة العميل قبل تطبيق الرسوم.
currency
تكلفة كل وحدة من الاستخدام الذي يتجاوز الحد المجاني.
timestamp
الطابع الزمني لأحدث حدث استخدام للعميل.
currency
إجمالي المبلغ الذي تم تحصيله من العميل مقابل الفوترة القائمة على الاستخدام.
number
إجمالي عدد الوحدات التي استهلكها العميل.
number
عدد الوحدات التي تتجاوز الحد المجاني ويتم تحصيل رسوم مقابلها.
ميزات الجدول
- تصفية الأعمدة: استخدم ميزة “Edit Columns” لإظهار أعمدة بيانات محددة أو إخفائها
- التحديثات الفورية: تعكس بيانات الاستخدام أحدث مقاييس الاستهلاك
أمثلة على التجميع
فيما يلي أمثلة عملية على كيفية عمل أنواع التجميع المختلفة:فهم أنواع التجميع
تخدم أنواع التجميع المختلفة سيناريوهات فوترة مختلفة. اختر النوع المناسب استنادًا إلى كيفية رغبتك في قياس الاستخدام وتحصيل الرسوم مقابله.أمثلة عملية على التنفيذ
توضح هذه الأمثلة التطبيقات الواقعية لكل نوع من أنواع التجميع، مع أحداث نموذجية ونتائج متوقعة:Count Aggregation — API Calls
Count Aggregation — API Calls
السيناريو: تتبع العدد الإجمالي لطلبات APIإعداد العداد:النتيجة: تمت فوترة العميل مقابل 3 استدعاءات
- اسم الحدث:
api.call - نوع التجميع: Count
- وحدة القياس:
calls
Sum Aggregation — Data Transfer
Sum Aggregation — Data Transfer
السيناريو: الفوترة استنادًا إلى إجمالي وحدات البايت المنقولةإعداد العداد:النتيجة: تمت فوترة العميل مقابل إجمالي نقل يبلغ 1.5 GB
- اسم الحدث:
data.transfer - نوع التجميع: Sum
- الخاصية التي يتم التجميع عليها:
bytes - وحدة القياس:
GB
Max Aggregation — Peak Concurrent Users
Max Aggregation — Peak Concurrent Users
السيناريو: الفوترة استنادًا إلى أعلى عدد متزامن من المستخدمينإعداد العداد:النتيجة: تمت فوترة العميل مقابل ذروة بلغت 23 مستخدمًا متزامنًا
- اسم الحدث:
concurrent.users - نوع التجميع: Max
- الخاصية التي يتم التجميع عليها:
count - وحدة القياس:
users
أمثلة على تصفية الأحداث
- Filter by API Endpoint
- Filter by Value Range
- Complex Multi-Condition Filters
احسب استدعاءات API لنقاط نهاية محددة فقط:إعداد التصفية:النتيجة: تُحتسب الأحداث المطابقة لمعايير التصفية. ويتم تجاهل الأحداث ذات نقاط النهاية المختلفة.
- الخاصية:
endpoint - عامل المقارنة:
equals - القيمة:
/v1/orders
استكشاف الأخطاء وإصلاحها
حل المشكلات الشائعة في تنفيذ الفوترة القائمة على الاستخدام، وتأكد من دقة التتبع والفوترة.المشكلات الشائعة
تندرج معظم مشكلات الفوترة القائمة على الاستخدام ضمن الفئات التالية:- مشكلات تسليم الأحداث ومعالجتها
- مشكلات إعداد العداد
- أخطاء نوع البيانات وتنسيقها
- مشكلات معرّف العميل والمصادقة
خطوات تصحيح الأخطاء
عند استكشاف أخطاء الفوترة القائمة على الاستخدام وإصلاحها:- تحقق من تسليم الأحداث في علامة تبويب تحليلات Events
- تحقق من تطابق إعداد العداد مع بنية الحدث
- تحقق من معرّفات العملاء ومصادقة API
- راجع شروط التصفية وإعدادات التجميع
الحلول والإصلاحات
Events not showing in meter
Events not showing in meter
الأسباب الشائعة:
- لا يطابق اسم الحدث إعدادات العداد تمامًا
- تستبعد شروط تصفية الأحداث أحداثك
- معرّف العميل غير موجود في حساب Dodo Payments الخاص بك
- الطابع الزمني للحدث خارج فترة الفوترة الحالية
- تحقق من تهجئة اسم الحدث وحساسية حالة الأحرف
- راجع شروط التصفية واختبرها
- تأكد من صحة معرّف العميل ونشاطه
- تحقق من حداثة الطوابع الزمنية للأحداث وتنسيقها بشكل صحيح
Aggregation not working as expected
Aggregation not working as expected
الأسباب الشائعة:
- لا يطابق اسم Over Property مفاتيح البيانات الوصفية للحدث
- قيم البيانات الوصفية من نوع بيانات غير صحيح (سلسلة نصية بدلًا من رقم)
- خصائص البيانات الوصفية المطلوبة مفقودة
- تأكد من تطابق مفاتيح البيانات الوصفية تمامًا مع إعداد Over Property
- حوّل الأرقام النصية إلى أرقام فعلية في أحداثك
- أدرج جميع الخصائص المطلوبة في كل حدث
Filtering not working
Filtering not working
الأسباب الشائعة:
- لا تطابق أسماء خصائص التصفية البيانات الوصفية للحدث
- عامل مقارنة غير مناسب لنوع البيانات (سلسلة نصية بدلًا من رقم)
- حساسية حالة الأحرف في مقارنات السلاسل النصية
- تحقق مرة أخرى من تطابق أسماء الخصائص تمامًا
- استخدم عوامل المقارنة المناسبة لأنواع بياناتك
- ضع حساسية حالة الأحرف في الاعتبار عند تصفية السلاسل النصية
مرجع API ذي صلة
Create Meter
مرجع API لإنشاء عدادات الاستخدام وإعدادها لتتبع استهلاك العملاء.
Ingest Usage Events
مرجع API لإرسال أحداث الاستخدام إلى العدادات التي أعددتها بغرض حسابات الفوترة.