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
راجع إعدادات العداد وانقر على إنشاء العداد.
أصبح العداد الآن جاهزًا لاستقبال أحداث الاستخدام وتجميعها.
ربط العداد بمنتج
بعد إنشاء العداد، يجب ربطه بمنتج لتمكين الفوترة حسب الاستخدام. تربط هذه العملية بيانات استخدام العداد بقواعد التسعير الخاصة بفوترة العملاء. يؤسس ربط العدادات بالمنتجات اتصالًا بين تتبع الاستخدام والفوترة:- تحدد المنتجات قواعد التسعير وسلوك الفوترة
- توفر العدادات بيانات الاستخدام اللازمة لحسابات الفوترة
- يمكن ربط عدة عدادات بمنتج واحد لسيناريوهات الفوترة المعقدة
عملية إعداد المنتج
حوّل بيانات الاستخدام إلى رسوم قابلة للفوترة من خلال إعداد خيارات المنتج بشكل صحيح:1
Choose Usage-Based Billing Product Type
انتقل إلى صفحة إنشاء المنتج أو تحريره، ثم اختر حسب الاستخدام باعتباره نوع المنتج.
2
Select Associated Meter
انقر على العداد المرتبط لفتح لوحة اختيار العداد من الجانب.تتيح لك هذه اللوحة إعداد العدادات التي ستتتبع الاستخدام لهذا المنتج.
3
Add Your Meter
في لوحة اختيار العداد:
- انقر على إضافة عدادات لعرض العدادات المتاحة
- اختر العداد الذي أنشأته من القائمة المنسدلة
- سيظهر العداد المحدد في إعدادات المنتج
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) × 75.00**
تُعد الحدود المجانية مناسبة لنماذج freemium، والفترات التجريبية، أو توفير حصة أساسية للعملاء مشمولة في خطتهم.
ينطبق الحد المجاني على كل دورة فوترة، ما يمنح العملاء حصصًا جديدة شهريًا أو وفقًا لجدول الفوترة الخاص بك.
6
Save Configuration
راجع إعدادات العداد والتسعير، ثم انقر على حفظ التغييرات لإتمام الإعداد.ما يحدث بعد ذلك:
تم الآن إعداد منتجك للفوترة حسب الاستخدام، وسيتم تحصيل الرسوم من العملاء تلقائيًا بناءً على استهلاكهم المقاس.
- سيتم تتبع أحداث الاستخدام المرسلة إلى العداد وتجميعها
- ستطبق حسابات الفوترة قواعد التسعير الخاصة بك تلقائيًا
- ستتم محاسبة العملاء بناءً على الاستهلاك الفعلي خلال كل دورة فوترة
تذكّر أنه يمكنك إضافة ما يصل إلى 10 عدادات لكل منتج، ما يتيح تتبعًا متقدمًا للاستخدام عبر أبعاد متعددة مثل استدعاءات API والتخزين ووقت الحوسبة والمقاييس المخصصة.
إرسال أحداث الاستخدام
بعد إعداد العداد، يمكنك البدء بإرسال أحداث الاستخدام من تطبيقك لتتبع استخدام العملاء.بنية الحدث
يجب أن يتضمن كل حدث استخدام الحقول المطلوبة التالية:string
مطلوب
معرّف فريد لهذا الحدث المحدد. يجب أن يكون فريدًا عبر جميع الأحداث.
string
مطلوب
معرّف العميل في Dodo Payments الذي يجب إسناد هذا الاستخدام إليه.
string
مطلوب
اسم الحدث المطابق لإعدادات العداد. تؤدي أسماء الأحداث إلى تشغيل العداد المناسب.
string
طابع زمني بتنسيق ISO 8601 لوقت وقوع الحدث. تكون القيمة الافتراضية هي الوقت الحالي إذا لم يتم توفيره.
object
خصائص إضافية للتصفية والتجميع. أدرج أي قيم يُشار إليها في “Over Property” للعداد أو في شروط التصفية.
أمثلة على API لأحداث الاستخدام
أرسل أحداث الاستخدام إلى العدادات التي أعددتها باستخدام Events API:أهم الأمور التي يجب معرفتها لضمان الإدخال الموثوق
اتبع هذه الممارسات للحفاظ على دقة تتبّع الاستخدام ومرونته في بيئة الإنتاج.حدّد الطوابع الزمنية بعناية. احذف
timestamp للأحداث الآنية، وسيتم تعيينه تلقائيًا إلى وقت الإدخال. عيّنه صراحةً (بتنسيق 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
- Over Property:
bytes - وحدة القياس:
GB
Max Aggregation - Peak Concurrent Users
Max Aggregation - Peak Concurrent Users
السيناريو: الفوترة استنادًا إلى أعلى عدد متزامن من المستخدمينإعداد العداد:النتيجة: تمت فوترة العميل مقابل 23 مستخدمًا متزامنًا في ذروة الاستخدام
- اسم الحدث:
concurrent.users - نوع التجميع: Max
- Over Property:
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 لإرسال أحداث الاستخدام إلى العدادات التي أعددتها لإجراء حسابات الفوترة