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

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

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

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

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

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

Choose Usage-Based Billing Product Type

انتقل إلى صفحة إنشاء المنتج أو تحريره، ثم اختر حسب الاستخدام باعتباره نوع المنتج.
2

Select Associated Meter

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

Add Your Meter

في لوحة اختيار العداد:
  1. انقر على إضافة عدادات لعرض العدادات المتاحة
  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=تحصيل0.50 = **تحصيل 75.00**
تُعد الحدود المجانية مناسبة لنماذج freemium، والفترات التجريبية، أو توفير حصة أساسية للعملاء مشمولة في خطتهم.
ينطبق الحد المجاني على كل دورة فوترة، ما يمنح العملاء حصصًا جديدة شهريًا أو وفقًا لجدول الفوترة الخاص بك.
6

Save Configuration

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

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

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

بنية الحدث

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

أمثلة على 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 للأحداث الآنية، وسيتم تعيينه تلقائيًا إلى وقت الإدخال. عيّنه صراحةً (بتنسيق ISO 8601) عند ملء البيانات السابقة أو إرسال الأحداث المتأخرة/المجمّعة، حتى يُسجّل الاستخدام ضمن فترة الفوترة الصحيحة.
أرسل البيانات الوصفية المجمّعة كأرقام، وليس كسلاسل نصية. يجب أن تكون أي خاصية يشير إليها Over Property الخاص بالعداد (Sum وMax وLast) من نوع رقمي — { "tokens": 150 }، وليس { "tokens": "150" }. لن تُجمّع القيم النصية.

تحليلات الفوترة المستندة إلى الاستخدام

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

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

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

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

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

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

Meter quantities chart showing usage trends over time with purple gradient visualization
يعرض مخطط كميات العداد اتجاهات الاستخدام بمرور الوقت، ويتضمن الميزات التالية:
  • تصور السلاسل الزمنية: تتبّع أنماط الاستخدام عبر الأيام أو الأسابيع أو الأشهر
  • دعم عدادات متعددة: اعرض البيانات من عدادات مختلفة في الوقت نفسه
  • تحليل الاتجاهات: حدّد ارتفاعات الاستخدام والأنماط ومسارات النمو
يضبط المخطط مقياسه تلقائيًا استنادًا إلى حجم الاستخدام والنطاق الزمني المحدد، ما يوفر رؤية واضحة لكل من التقلبات الصغيرة والتغيرات الكبيرة في الاستخدام.

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

Events table showing event names, IDs, and pagination controls for detailed event analysis
توفر علامة تبويب Events رؤية تفصيلية لأحداث الاستخدام الفردية:

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

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

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

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

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

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

ميزات الجدول

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

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

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

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

تخدم أنواع التجميع المختلفة سيناريوهات فوترة مختلفة. اختر النوع المناسب استنادًا إلى الطريقة التي تريد بها قياس الاستخدام وفرض الرسوم عليه.

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

توضح هذه الأمثلة تطبيقات واقعية لكل نوع من أنواع التجميع، مع أحداث نموذجية ونتائج متوقعة.
السيناريو: تتبّع العدد الإجمالي لطلبات APIإعداد العداد:
  • اسم الحدث: api.call
  • نوع التجميع: Count
  • وحدة القياس: calls
أحداث نموذجية:
النتيجة: تمت فوترة العميل مقابل 3 استدعاءات
السيناريو: الفوترة استنادًا إلى إجمالي وحدات البايت المنقولةإعداد العداد:
  • اسم الحدث: data.transfer
  • نوع التجميع: Sum
  • Over Property: bytes
  • وحدة القياس: GB
أحداث نموذجية:
النتيجة: تمت فوترة العميل مقابل إجمالي نقل يبلغ 1.5 GB
السيناريو: الفوترة استنادًا إلى أعلى عدد متزامن من المستخدمينإعداد العداد:
  • اسم الحدث: concurrent.users
  • نوع التجميع: Max
  • Over Property: 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 لإرسال أحداث الاستخدام إلى العدادات التي أعددتها لإجراء حسابات الفوترة
آخر تعديل في ٣١ يوليو ٢٠٢٦