إنتقل إلى المحتوى الرئيسي

استيعاب الأحداث عبر واجهة برمجة تطبيقات البث

مقدمة​

استخدم واجهة برمجة التطبيقات (API) هذه لإرسال بيانات الأحداث إلى خط أنابيب للمعالجة والتصفية والإثراء والتوجيه.

تدعم نقطة النهاية هذه الاستيعاب في الوقت الفعلي بإنتاجية عالية وتدعم أحداث JSON المنظمة وشبه المنظمة. وهي مثالية للتطبيقات السحابية، والخدمات الصغيرة، وأجهزة إنترنت الأشياء، أو أي نظام يصدر قياسات عن بُعد.

وظائف واجهة برمجة التطبيقات​

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

قبل البدء​

تأكد من أن لديك:

  • رمز واجهة برمجة تطبيقات (API Token) مع أذونات استيعاب
  • معرف دفق (Stream ID)
  • حمولات أحداث بتنسيق JSON
  • تثبيت curl أو Postman

نظرة عامة على خط الأنابيب​

flowchart LR
    A["التطبيق السحابي / الخدمة الصغيرة"] --> B["واجهة برمجة تطبيقات استيعاب البث"]
    B --> C["طبقة المعالجة<br/> • التحليل<br/> • الإثراء<br/> • الإخفاء"]
    C --> D["محرك التوجيه<br/> • المرشحات<br/> • أخذ العينات<br/> • القواعد"]
    D --> E{{"الوجهات:<br/>S3 / SIEM / Elastic / Snowflake"}}

نقطة نهاية الاستيعاب​

POST /v1/streams/ingest

رؤوس الطلبات​

الرأسالقيمةمطلوبالوصف
AuthorizationBearer <token>نعمرمز واجهة برمجة التطبيقات
Content-Typeapplication/jsonنعمحمولة JSON
X-Stream-Id<your-stream-id>نعمخط الأنابيب المستهدف

نص الطلب​

{
  "timestamp": "2025-02-12T14:32:15Z",
  "source": "payments-app",
  "event": {
    "transactionId": "txn_30921",
    "status": "approved",
    "latency_ms": 182,
    "amount": 499,
    "currency": "USD"
  },
  "metadata": {
    "env": "prod",
    "team": "payments"
  }
}

ملاحظات​

  • timestamp: تنسيق ISO 8601
  • event: بيانات الحدث الرئيسية (أزواج القيمة والمفتاح)
  • الحجم الأقصى للحمولة: 1 ميجابايت

الاستجابة​

200 OK​

{
  "status": "accepted",
  "ingested_bytes": 527,
  "stream_id": "a0c3b4de-1923-4ff1-8dba-f92ad912d20f"
}

400 Bad request​

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

  • JSON غير صالح
  • تنسيق الطابع الزمني غير صحيح
  • حقول المصدر أو الحدث مفقودة
  • الحمولة تتجاوز الحجم الأقصى
{
  "error": "invalid_format",
  "detail": "The 'timestamp' field must be a valid ISO 8601 string."
}

401 Unauthorized​

  • الرمز مفقود أو منتهي الصلاحية.

429 Rate limited​

  • قلل معدل الطلبات أو أحداث الدُفعات.

مثال cURL​

curl -X POST "https://api.example.com/v1/streams/ingest" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Stream-Id: $STREAM_ID" \
  -d @event.json

حالات الاستخدام الشائعة​

  • استيعاب السجلات من الخدمات الصغيرة
  • بث القياسات عن بُعد من أجهزة إنترنت الأشياء
  • تطبيع الأحداث من الأنظمة الموزعة
  • توجيه الأحداث المُثريّة إلى SIEM أو S3 أو Elastic أو Snowflake
  • خطوط أنابيب الكشف عن الاحتيال أو الحالات الشاذة في الوقت الفعلي

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

الأعراضالسبب المحتملالإصلاح
لا تظهر أي أحداث في خط الأنابيبمعرف الدفق خاطئانسخ معرف الدفق الصحيح
الحمولة مرفوضةJSON غير صالحتحقق من الصحة باستخدام jq
حقول مفقودةعدم تطابق البنية المتداخلةراجع قواعد التحليل
زمن انتقال طويلحمولات كبيرة أو دفعاتقلل حجم الدفعة

الخطوات التالية​

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