التحليلات والمقاييس واجهة برمجة التطبيقات

1) لماذا طبقة API منفصلة

حقيقة واحدة لـ KPI: استبعاد «حديقة الحيوان SQL».
سرعة المنتج: الواجهات واللوحات الشريكة وعملاء الهاتف المحمول يحصلون على مجاميع دون الوصول المباشر إلى DWH.
الأمن والامتثال: الترميز، والأقنعة، والقيود الجغرافية، ومرشحات RG/AML.
التحجيم: مخبأ، مسبق، CDN، عقود مستقرة.

2) علم التصنيف: المقاييس والأبعاد والحقائق

الحقائق: الرهانات، المكاسب، الودائع، أحداث KYC، تدخلات النمو الحقيقي.
الأبعاد: التاريخ/الوقت (التقويمات)، اللعبة/المزود، العلامة التجارية/البلد، القناة/الجهاز، اللاعب (رمز).
المقاييس: GGR، NGR/NET، ARPPU، الاحتفاظ D1/D7/D30، وتواتر الإيداع، ومخاطر مكافحة الاحتيال FPR، و RG.
الوحدات: العملة (FX)، الوقت (TZ)، الحجم/العدادات (idempotent!).
دلالات KPI: تم إصلاح التعريفات في عقود BI وإصدارات KPI.

3) عقود البيانات والمؤشرات التجارية

المخطط: الحقول، الأنواع، غير القابلة للإلغاء، إينوم، الوحدات، العملات.
دلالات المقاييس: الصيغة، المصادر، نوافذ التجميع، المرشحات.
التوافق (SEMVER): فترات الراحة الرئيسية، تضيف MINOR الحقول، إصلاحات التصحيح.
DQ/SLA: النضارة، والاكتمال، والاتساق، وتحمل التناقض.
الخصوصية: "pii: fall'،" tomenized: true "، حظر إزالة الدماغ.

yaml api: analytics. v2 resource: /metrics/revenue kpi: GGR schema_version: 2. 1. 0 dimensions: [date, brand, country, provider, game]
metrics: [ggr, stakes, wins, bets_count]
sla: {freshness: PT15M, completeness: ">=99. 9%"}
privacy: {pii: false, tokenized: true}

4) الهندسة المعمارية

استعلام API (التجميع عبر الإنترنت على «الذهب «/المكعبات/fichestore).
Precompute API (المجدولة المسبقة، الآراء المجسدة).
واجهة برمجة التطبيقات للأحداث (عدادات/إشارات التدفق).
تصدير API (تحميلات موقعة، WORM للتدقيق).
Cache: in-memory → Redis → CDN, key = query hash + version.
الاتساق: اقرأ كتاباتك للتسجيلات النهائية، ونضارة SLA للمجاميع.

5) الوصلة البينية والطلبات

5. 1 مرشحات/تجميعات/نوافذ

«filter»: نطاقات التاريخ («من/إلى» UTC، المنطقة الزمنية مدركة)، البلدان، العلامات التجارية، الألعاب، القنوات، الأجهزة.
«group _ by»: الأبعاد.
«القياسات»: قائمة مؤشرات الأداء الرئيسية.
«window»: «يوم» أسبوع «الشهر» ROLLING _ 7D «ROLLING _ 28D».
"currency": "reporting" native "، FX strategy:" eod' خلال اليوم "txn'.
«sampling»: للاستفسارات الثقيلة (فقط حيثما يُسمح بذلك).

5. 2 طلب مثال

json
POST /v2/metrics/revenue
{
"range": {"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"group_by": ["date","brand","country"],
"metrics": ["ggr","bets_count","net_revenue"],
"filters": {"country":["EE","LT","LV"],"brand":["alpha","beta"]},
"currency": "reporting",
"window": "DAY"
}

5. 3 مثال على الاستجابة

json
{
"schema_version":"2. 1. 0",
"kpi_definitions":["ggr@1. 7. 0","net_revenue@1. 3. 2"],
"range":{"from":"2025-10-01","to":"2025-10-31","tz":"Europe/Kyiv"},
"data":[
{"date":"2025-10-01","brand":"alpha","country":"EE","ggr":12450. 72,"bets_count":182342,"net_revenue":10732. 11},
{"date":"2025-10-01","brand":"beta","country":"EE","ggr":...}
],
"fx":{"strategy":"eod","rate_date":"2025-10-31"},
"dq":{"freshness_sec":420,"completeness":0. 9992},
"trace_id":"3d1a-...-c79"
}

6) التثبيت، الحدود، الفرز

التثبيت: «حد» (≤10k)، «مؤشر» (غير شفاف)، الفرز حسب الأبعاد/التاريخ.
مهلة/جزئية: ردود جزئية على مؤشرات الأداء غير المالية فقط ؛ - إما P200 أو P504.
حدود الأسعار: على الصعيد العالمي/حسب المفتاح/حسب المستأجر ؛ يحتوي الرد على «X-RateLimit-».

7) الخمول والمخبأ

GET/POST-read (مع الجسم) مع «Idempotency-Key».
Cache key = hash (parametors + schema version + role/tenant/geo).
TTL: المعتمد على KPI (على سبيل المثال إعادة تعيين «PT15M» للإيرادات، «PT5M» للأحداث) بلقطة جديدة.

8) الاتساق والعملة الزمنية

علم السفر عبر الزمن للتقارير الاستعادية (نسخ البيانات).
قواعد الوقف (الإغلاق اليومي/الأسبوعي).
FX: نصلح الإستراتيجية، تاريخ الدورة في الإجابة.
الساعة: جميع الطوابع الزمنية ISO-8601، TZ مطلوب.

9) الأمن والخصوصية

mTLS/TLS1. 3، توقيع HMAC لهيئة الطلب/الاستجابة (MITM/حماية إعادة التشغيل).
RBAC/ABAC/ReBAC: الدور + البلد + العلامة التجارية + الغرض ؛ الأقنعة الافتراضية.
متعدد المستأجرين - عزل المخططات/المفاتيح/الحصص.
ترميز محددات الهوية ؛ حظر PII في الردود.
مراجعة الحسابات: سجلات الطلبات غير القابلة للتغيير (WORM)، و 'trace _ id '/' factor '/' الغرض'.
الموافقة/DSAR: مرشحات على الخصائص التسويقية ؛ علم «محو الموضوع».

10) RG/AML/Restruction antifrode

سياسات النمو الحقيقي: حظر إصدار مؤشرات «قوية» للقطاعات الشديدة الخطورة ؛ الوحدات آمنة.
AML/Antifraud: الوصول المحدود إلى مؤشرات الأداء الرئيسية الحساسة، وتقسيم المناطق حسب الدور ؛ نقاط نهاية منفصلة للتحقيقات.
إمكانية التفسير: قاموس تفسيرات دليل الأداء الكوري/إشارات الدعم.

11) قابلية الرصد وواجهة برمجة التطبيقات SLO

SLO: p95 latency (على سبيل المثال، ≤ 300 mm لضربات المخبأ ؛ ≤ 2 s للثقيل)، معدل النجاح ≥ 99. 5%.
DQ: النضارة/الاكتمال/السلامة ؛ في الرد.
الاستخدام: QPS، معدل إصابة المخبأ، المفاتيح الساخنة، أخطاء التحقق.
التنبيهات: تدهور النضارة، النمو 4xx/5xx، حالات شاذة وفقًا لـ KPI (أصفار/قمم غير متوقعة).
التتبع: «تتبع _ معرف» من طرف إلى طرف DWH/fichestore.

12) الحرث والتوافق

المسارات: '/v1 '، '/v2' ؛ مع نافذة الهجرة.
المخططات: 'schema _ version' استجابة ؛ أدلة الهجرة الرئيسية → المزدوجة القراءة.
إصدارات مؤشر الأداء الكوري: في الرد 'kpi _ definitions' مع وصلة في الدليل ؛ منع تغييرات الصيغة المخفية.

13) الأخطاء والحالات

مصداقية '400' (تركيبة مترية/قياسية/مرشحة غير موجودة).
«401/403» الإذن/الإذن.
«409» عدم توافق/سياسة.
«422» انتهاك الحقوق/الموافقة.
حصص «429».
«5xx» فشل الصفيحة (trace_id وإعادة التجربة seq.).

json
{
"error":"VALIDATION_FAILED",
"message":"Unknown metric: ngrx",
"hint":"metrics allowed: ggr, net_revenue,...",
"trace_id":"..."
}

14) التكامل والوصلات البينية

BI: نماذج دلالية موصوفة مسبقًا، موصلات (Looker/Power BI/Tableau) → API كمصدر.
ML: نقاط نهاية خفيفة الوزن للوحدات المميزة (نقطة في الوقت المناسب، بدون PII).
الشركاء: مفاتيح/حصص محدودة، مرشحات جغرافية، تقارير مجمعة فقط.
Webhook/Push: الإشعارات «لقطة جاهزة»، «نطاق SLO/KPI المكسور».

15) أمثلة على نقاط نهاية الموارد

15. 1 الإيرادات/العائد

"POST/v2/metrics' → GGR/NGR، الرهانات/المكاسب، تقاس بـ" التاريخ، العلامة التجارية، البلد، المزود، اللعبة ".

15. 2 الاحتفاظ والقمع

"POST/v2/metrics' → когорты D1/D7/D30," group _ by = [cohort _ week, brand, country] ".

15. 3 المدفوعات

"POST/v2/metrics/payments' → الودائع/السحوبات، متوسط الشيك، معدل استرداد التكاليف.

15. 4 الألعاب المسؤولة

«POST/v2/metrics/rg» → عدد التدخلات، نسبة المخاطر العالية، متوسط وقت رد الفعل.

15. 5 مضاد للرود

"POST/v2/metrics/antifraud' → FPR/TPR، الحالات، تم منع الخسائر.

16) الاختبار والجودة

اختبارات العقد: enum/nulbable/type، العملة/اتساق المنطقة الزمنية.
اختبارات DQ: التحكم في النطاقات والرتابة والنزاهة.
الانحدار: مقارنة v1/v2 على التسامح.
الحمل: ملفات تعريف الذروة (البطولات/أحداث المزود).
الأمان: التوقيعات، مكافحة إعادة التشغيل، طلبات الغموض، Zero-PII في السجلات.

17) الخصوصية افتراضيًا

المجاميع مع عتبات «الحد الأدنى من سجلات N» (k-unhonity).
لا توجد معرفات أولية ؛ الرموز/الفئات فقط.
DSAR: واجهة برمجة التطبيقات للتفريغ/الحذف عن طريق رمز من خلال حلقة مميزة.

18) مقاييس النجاح (API KPIs)

الاعتماد: نسبة التقارير/الأدوات التي تستخدم واجهة برمجة التطبيقات بدلاً من المعلومات المسبقة المباشرة.
الاتساق - التناقض بين الذكاء الاصطناعي والتسامح ≤ برمجة التطبيقات.
SLO: الامتثال لكمون/نجاح/نضارة.
الأمان: صفر من حالات مؤشر الاستثمار الدولي في الردود/السجلات.
التكلفة: معدل إصابة المخبأ، تكلفة الطلب،٪ من المسبقين.

19) RACI (مثال)

Product/Analytics (A) - KPI definitions, requires.
منصة البيانات (R) - التنفيذ، المخبأ، جيش تحرير السودان، إمكانية الرصد.
مالكو المجال (R) - المصادر/العقود.
الأمن/DPO (A/R) - الخصوصية، والوصول، ومراجعة الحسابات.
SRE (R) - الحصص، المقياس الذاتي، الحوادث.
المالية (C) هي الدلالات المالية لـ GGR/NGR/NET.

20) خارطة طريق التنفيذ

0-30 يومًا (MVP)

1. اختر 3-5 KPIs (GGR، الودائع، الاحتفاظ D7).
2. وصف العقود ودلالات KPI ؛ تمكين DQ/SLA.
3. نفذ '/v1 'استعلام API + ذاكرة التخزين المؤقت + mTLS/HMAC.
4. لوحات معلومات SLO (الكمون/النجاح/النضارة)، التدقيق/التعقب _ id.

30-90 يومًا

1. واجهات المتاجر الشعبية، CDN cache.
2. إصدار '/v2 '، مزدوج القراءة، دليل الهجرة.
3. تصدير واجهات برمجة التطبيقات مع التحميلات الموقعة و WORMs.
4. التكامل مع BI/ML ؛ الحصص/المستأجرين/العزل الجغرافي.

3-6 أشهر

1. أكمل مكتبة تصنيف وودجيت KPI.
2. نصائح ذكية/مرشحات مكتملة تلقائيًا، بطانة استعلام.
3. Automatic Release Notes KPI, control of tolerances v1/v2.
4. حلقة الشركاء الخارجيين مع المفاتيح المقيدة وسياسات النمو الحقيقي.

21) الأنماط المضادة

تغيير صيغة KPI المخفية بدون إصدار جديد وملاحظات إصدار.
إعادة PII/المواد الخام بدلاً من المجاميع/الرموز.
عدم وجود مخبأ/مسبق → مكلف وبطيء.
ربط صلب بقاعدة بيانات محددة (بدون تجريد طبقة).
غير متناسق TZ/FX → أرقام متباينة.
لا حدود/حصص للأسعار → "DDOS own'.

22) النماذج (جاهزة للاستخدام)

22. 1 سياسة SLO API (مقتطف)

yaml api: analytics. v2 slo:
p95_latency_ms: 300 success_rate: 0. 995 freshness_sec_max: 900 quotas:
per_key_qps: 50 burst: 200 privacy:
min_group_size: 25 pii_in_response: false

22. 2 OpenAPI (مقتطف)

yaml paths:
/v2/metrics/revenue:
post:
requestBody:
content:
application/json:
schema: {$ref: '#/components/schemas/RevenueQuery'}
responses:
'200': {description: 'OK', content: {application/json: {schema: {$ref:'#/components/schemas/RevenueResponse'}}}}
'422': {description:'Privacy/Consent violation'}

22. 3 قائمة مرجعية للإصدار

• تحديث دلالات KPI وتحديث الإصدار
• العقد/المخطط في الكتالوج ؛ اختبارات DQ/الانحدار باللون الأخضر
• مفاتيح ذاكرة التخزين المؤقت/TTL، المسبقات المكونة
• الوثائق وطلبات/ردود العينات
• تنبيهات SLO والحصص المدرجة
• اختبار قيود RG/AML

23) الأقسام ذات الصلة

ممارسات DataOps، التدقيق والتحديث، الأمن والتشفير، التحكم في الوصول، ترميز البيانات، سياسات الاحتفاظ، أصل البيانات والمسار، MLOps: استغلال النموذج، أخلاقيات البيانات.

المجموع

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