Skip to main content
يرسل مخطط API Gateway حدث استخدام إلى Dodo Payments لكل استدعاء API تعالجه خدمتك، ويحوّل مقياس Count هذه الأحداث إلى رسم لكل استدعاء لكل عميل. استخدمه لتتبّع استخدام نقاط نهاية API، ولتحديد حدود المعدل، ولفوترة استخدام API. يأتي ضمن حزمة npm @dodopayments/ingestion-blueprints باسم trackAPICall()، التي ترسل حدثًا واحدًا لكل استدعاء، وcreateBatch()، التي تضع الأحداث في قائمة انتظار عند أحجام الطلبات الكبيرة.

حالات الاستخدام

يناسب مخطط API Gateway السيناريوهات التالية:

API-as-a-Service

تتبّع عدد الاستدعاءات لكل عميل على منصة API وحاسب بحسب عدد الاستدعاءات.

Rate Limiting

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

Performance Monitoring

سجّل أوقات الاستجابة ورموز الحالة مع كل حدث، بحيث تظهر معدلات الأخطاء بجانب بيانات الفوترة.

Multi-Tenant SaaS

حاسب العملاء على استهلاكهم لـ API عبر نقاط نهاية مختلفة.
يحتاج كل حدث إلى معرّف عميل Dodo Payments الخاص بالعميل الذي تحاسبه، والذي يبدأ بـ cus_. خزّنه مع سجل المستخدم عند إنشاء العميل، ومرّره كـ customerId.

البدء السريع

لتتبّع استدعاءات API، ثبّت الحزمة، وأنشئ مقياسًا، وأرسل حدثًا لكل استدعاء.
1

Install the SDK

ثبّت حزمة Dodo Payments Ingestion Blueprints:
2

Get Your API Keys

أنشئ مفتاح API لـ Dodo Payments ضمن Developer → API Keys في لوحة تحكم Dodo Payments، وخزّنه في متغير البيئة DODO_PAYMENTS_API_KEY. استخدم مفتاح وضع الاختبار أثناء التطوير. يعمل مفتاح وضع الاختبار مع test_mode فقط.
3

Create a Meter

في لوحة تحكم Dodo Payments، انتقل إلى Products → Meters وانقر على Create Meter. اضبط هذه الحقول:
  • Meter Name: اسم وصفي، مثل API Calls.
  • Event Name: api_call، أو اسم تختاره. يجب أن يطابق eventName في التعليمات البرمجية لديك تمامًا (مع مراعاة حالة الأحرف).
  • Aggregation Type: Count، للفوترة بحسب عدد الاستدعاءات.
  • Measurement Unit: الوحدة الظاهرة في الفواتير، مثل calls.
لعدّ بعض الاستدعاءات فقط، فعّل Enable Event Filtering وأضف شروطًا إلى مفاتيح البيانات الوصفية مثل endpoint أو method أو status_code.
4

Track API Calls

أنشئ مثيلًا واحدًا من Ingestion باستخدام مفتاح API واسم الحدث، ثم اختر نمطًا: حدث واحد لكل استدعاء، أو دفعة لأحجام الاستخدام الكبيرة، أو برمجية وسيطة لـ Express.js تتتبّع كل طلب. في البرمجية الوسيطة، يأتي req.user من برمجية المصادقة الوسيطة، ويجب أن يكون id الخاص به معرّف عميل Dodo Payments. تُرسل الطلبات من دون مستخدم مسجّل الدخول باستخدام معرّف العميل anonymous، الذي لا يطابق أي عميل.

الإعداد

إعداد Ingestion

مرّر هذه الخيارات إلى new Ingestion():
string
مطلوب
مفتاح API الخاص بـ Dodo Payments من لوحة التحكم.
string
وضع البيئة: test_mode أو live_mode. الإعداد الافتراضي هو test_mode. بينما تستخدم حزم Dodo Payments SDK الإعداد الافتراضي live_mode، لذا اضبط live_mode صراحةً في بيئة الإنتاج.
string
مطلوب
اسم الحدث الذي يطابق Event Name للمقياس (مع مراعاة حالة الأحرف). يستخدم كل حدث يرسله هذا المثيل الاسم نفسه.

خيارات تتبّع استدعاء API

مرّر هذه الخيارات إلى trackAPICall() وbatch.add():
string
مطلوب
معرّف عميل Dodo Payments المطلوب تحصيل الرسوم منه مقابل الاستدعاء، مثل cus_123.
object
بيانات وصفية اختيارية حول استدعاء API، مثل نقطة النهاية والطريقة ورمز الحالة ووقت الاستجابة. يجب أن تكون كل قيمة سلسلة أو رقمًا أو قيمة منطقية. ترفض API الكائنات المتداخلة والمصفوفات وقيم null.

إعداد الدفعة

يضع createBatch(ingestion, options) الأحداث في قائمة انتظار داخل الذاكرة ويعيد كائنًا بثلاث طرق: تضع add() حدثًا في قائمة الانتظار، وترسل flush() الأحداث الموجودة في قائمة الانتظار، وترسل cleanup() الأحداث وتوقف المؤقت. يرسل التفريغ طلب ingest واحدًا لكل حدث، بالتوازي.
number
عدد الأحداث الموجودة في قائمة الانتظار الذي يؤدي إلى تفريغ فوري. الإعداد الافتراضي: 100.
number
عدد المللي ثانية التي يجب انتظارها بعد أحدث add() قبل تفريغ الدفعة. يعيد كل add() تشغيل المؤقت. الإعداد الافتراضي: 5000 (5 ثوانٍ).

أفضل الممارسات

استخدم التجميع للأحجام الكبيرة: بالنسبة إلى التطبيقات ذات حركة المرور العالية، استخدم createBatch(). يعيد batch.add() النتيجة فورًا، لذا لا تضيف التتبّع زمن استجابة إلى معالج الطلبات لديك.
تحتفظ الدفعة بالأحداث في الذاكرة حتى يتم تفريغها، ولا تعيد محاولة إرسال الأحداث التي يفشل إرسالها. يسجّل التفريغ التلقائي الخطأ باستخدام console.error. ويؤدي استدعاء flush() أو cleanup() إلى طرحه.
نظّف الدفعات عند إيقاف التشغيل: استدعِ batch.cleanup() عند إيقاف تشغيل تطبيقك، حتى يتم تفريغ الأحداث المعلّقة بدلًا من فقدانها.
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦