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

مقدمة

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

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

---

لماذا تستخدم واجهة برمجة التطبيقات هذه؟

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

---

قبل البدء

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

• ** رمز API Token مع أذونات الاستيعاب
• معرف معرف تدفق
• حمولات الأحداث بتنسيق JSON
• تثبيت 'curl' أو Postman

---

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

Mermaid (code)

flowchart LR
    A["Cloud App / Microservice"] --> B["Streaming Ingest API"]
    B --> C["Processing Layer<br/> • Parsing<br/> • Enrichment<br/> • Masking"]
    C --> D["Routing Engine<br/> • Filters<br/> • Sampling<br/> • Rules"]
    D --> E{{"Destinations:<br/>S3 / SIEM / Elastic / Snowflake"}}

Mermaid (image)

ASCII

+--------------+       +------------------+       +----------------+       +----------------+
|  Cloud App   | --->  |  Ingest API      | --->  |   Processing   | --->  |   Routing      |
| (Logs/Events)|       | (POST /ingest)   |       | (Parse/Enrich) |       | (Rules Engine) |
+--------------+       +------------------+       +----------------+       +----------------+
                                                                               |
                                                                               v
                                                                    +----------------------+
                                                                    |    Destinations      |
                                                                    |  S3 | SIEM | DW | ES |
                                                                    +----------------------+

نقطة نهاية الإدخال

POST /v1/streams/ingest

رؤوس الطلبات

الرأس	القيمة	مطلوب	الوصف
الترخيص	Bearer <token>	نعم	API token
نوع المحتوى	application/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 موافق

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

400 طلب سيء

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

• JSON غير صالح
• تنسيق الطابع الزمني غير صحيح
• حقول source أو event المفقودة
• الحمولة تتجاوز الحد الأقصى للحجم

{
  "error": "invalid_format",
  "detail": "The 'timestamp' field must be a valid ISO 8601 string."
}

401 غير مصرح به

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

429 معدل محدود

• تقليل معدل الطلب أو الأحداث المجمعة.

مثال 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
• خطوط أنابيب الكشف عن الاحتيال أو الشذوذ في الوقت الحقيقي

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

الأعراض	السبب المحتمل	الإصلاح
لا توجد أحداث تظهر في خط الأنابيب	Wrong Stream ID	Copy the correct Stream ID
Payload rejected	Invalid JSON	Validate using jq
Missing fields	Nested structure mismatch	Review parsing rules
High latency	Large payloads or batching	Reduce batch size

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

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