تجزیه و تحلیل و معیارهای API

1) چرا یک لایه API جداگانه

حقیقت واحد برای KPI: حذف «باغ وحش SQL».
سرعت محصول: جبهه ها، پانل های شریک، مشتریان تلفن همراه بدون دسترسی مستقیم به DWH جمع می شوند.
امنیت و انطباق: نشانه گذاری، ماسک، محدودیت های جغرافیایی، فیلترهای RG/AML.
مقیاس بندی: کش، پیش فروش، CDN، قراردادهای پایدار.

2) طبقه بندی: معیارها، ابعاد، حقایق

حقایق: شرط ها، برنده ها، سپرده ها، رویدادهای KYC، مداخلات RG.
ابعاد: تاریخ/زمان (تقویم)، بازی/ارائه دهنده، نام تجاری/کشور، کانال/دستگاه، پخش (نشانه).
معیارهای: GGR، NGR/NET، ARPPU، نگهداری D1/D7/D30، فرکانس سپرده، FPR ضد تقلب، خطر RG.
واحد: ارز (FX)، زمان (TZ)، حجم/شمارنده (idempotent!).
معناشناسی KPI: تعاریف در قراردادهای BI، نسخه های KPI ثابت هستند.

3) داده ها و قراردادهای BI

طرح: زمینه ها، انواع، nullable، enum، واحدها، ارزها.
معناشناسی معیارها: فرمول، منابع، پنجرههای تجمیع، فیلترها.
سازگاری (SEMVER): شکاف های عمده، MINOR زمینه ها، رفع PATCH را اضافه می کند.
DQ/SLA: طراوت، کامل بودن، سازگاری، تحمل اختلاف.
حریم خصوصی: 'pii: نادرست'، 'tokenized: درست'، ممنوعیت detokenization.

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).
API Precompute (پیش فرض های برنامه ریزی شده، نمایش های تحقق یافته).
رویدادهای API (شمارنده جریان/سیگنال).
صادرات API (آپلود امضا شده، WORM برای حسابرسی).
کش: در حافظه → Redis → CDN، کلید = هش پرس و جو + نسخه.
سازگاری: خواندن و نوشتن برای ضبط نهایی، طراوت SLA برای aggregates.

5) رابط و درخواست

5. 1 فیلترها/تجمع/پنجره ها

'filter': محدوده تاریخ ('از/به' UTC، منطقه زمانی آگاه)، کشورها، مارک ها، بازی ها، کانال ها، دستگاه ها.
'group _ by': ابعاد.
«metrics»: لیست KPI ها.
'window': 'روز' هفته 'ماه' نورد _ 7D 'نورد _ 28D'.
'ارز': 'گزارش' مثبت '، استراتژی FX:' eod 'intraday' 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)، 'مکان نما' (مات)، مرتب سازی بر اساس ابعاد/تاریخ.

اتمام وقت/جزئی: پاسخهای جزئی فقط برای KPI های غیر مالی ؛ امور مالی - P200 یا P504

محدودیت نرخ: جهانی/با کلید/توسط مستاجر ؛ پاسخ شامل 'X-RateLimit-' است.

7) Idempotence و کش

Idempotent GET/POST-read (با بدن) با 'Idempotency-Key'.
کلید کش = هش (پارامترها + نسخه طرح + نقش/مستاجر/جغرافیایی).
TTL: KPI وابسته (به عنوان مثال «PT15M» برای درآمد، «PT5M» برای رویدادها)، با عکس فوری جدید تنظیم مجدد.

8) ثبات و واحد زمان

پرچم سفر زمان برای گزارش های گذشته نگر (نسخه های داده).
قوانین قطع (بسته شدن روز/هفته).
FX: ما استراتژی را اصلاح می کنیم، تاریخ دوره در پاسخ.
ساعت: تمام timestamps ISO-8601 هستند، TZ مورد نیاز است.

9) امنیت و حریم خصوصی

mTLS/TLS1 است. 3، امضای HMAC بدن درخواست/پاسخ (حفاظت MITM/پخش).

RBAC/ABAC/ReBAC: نقش + کشور + نام تجاری + هدف ؛ ماسک های پیش فرض

Multi-tenant - طرحواره ها/کلیدها/سهمیه ها را جدا کنید.

نشانه گذاری شناسه ها ؛ ممنوعیت PII در پاسخ ها

حسابرسی: سیاهههای مربوط به درخواست تغییر ناپذیر (WORM)، 'ردیابی _ id '/' بازیگر '/' هدف'.
رضایت/DSAR: فیلتر بر ویژگی های بازاریابی ؛ «موضوع حذف شد» پرچم.

10) RG/AML/ضد محدودیت

سیاستهای RG: ممنوعیت انتشار شاخصهای «تهاجمی» برای بخشهای پرخطر ؛ واحدها در امان هستند.

AML/Antifraud: دسترسی محدود به KPI های حساس، منطقه بندی بر اساس نقش ؛ نقاط پایانی جداگانه برای تحقیقات

توضیح پذیری: فرهنگ لغت توضیحات KPI/سیگنال برای پشتیبانی.

11) قابلیت مشاهده و API SLO

SLO: تأخیر p95 (به عنوان مثال ≤ 300 میلی ثانیه برای بازدیدهای حافظه پنهان ؛ ≤ 2 ثانیه برای سنگین)، میزان موفقیت ≥ 99. 5%.

DQ: طراوت/کامل بودن/یکپارچگی ؛ برچسب ها در پاسخ

استفاده: QPS، نرخ ضربه کش، کلید های داغ، خطاهای اعتبار سنجی.
هشدارها: تخریب طراوت، رشد 4xx/5xx، ناهنجاری ها با توجه به KPI (صفرها/قله های غیر منتظره).
ردیابی: 'trace _ id' پایان به پایان به DWH/fichestore.

12) نسخه و سازگاری

مسیرها: '/v1 '، '/v2' ؛ پنجره مهاجرت را حذف کنید.
طرحوارهها: 'schema _ version' در پاسخ ؛ MAJOR → دوگانه خواندن، راهنماهای مهاجرت.

نسخه های KPI: در پاسخ 'kpi _ definitions' با یک لینک در دایرکتوری ؛ جلوگیری از تغییرات فرمول پنهان

13) خطاها و وضعیت

'400' اعتبار (متریک/اندازه گیری/فیلتر ترکیبی غیر موجود).
'401/403' تأیید اعتبار/مجوز.
'409' ناسازگاری/سیاست.
'42' نقض حق بیمه/رضایت.
'429' نقل قول.
"خرابی 5xx 'platform (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/revenue' → GGR/NGR, bets/wins, measured by 'date, brand, country, provider, game'.

15. 2 نگهداری و قیف

'POST/v2/metrics/retention' → когорты 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/nullable/type، ثبات ارز/منطقه زمانی.
تست DQ: کنترل محدوده، یکنواختی و یکپارچگی.
رگرسیون: مقایسه v1/v2 در تحمل.
بار: پروفایل اوج (مسابقات/رویدادهای ارائه دهنده).
امنیت: امضا، ضد پخش، درخواست fuzzing، صفر PII در سیاهههای مربوط.

17) حریم خصوصی به طور پیش فرض

Aggregates با آستانه «حداقل N رکورد» (k-anonymity).
بدون شناسه خام ؛ فقط نشانه ها/دسته ها.
DSAR: API برای تخلیه/حذف توسط نشانه از طریق یک حلقه ممتاز.

18) معیارهای موفقیت (API KPIs)

پذیرش: نسبت گزارش ها/ویدجت ها با استفاده از API به جای SQL مستقیم.
سازگاری - اختلاف بین BI و تحمل ≤ API.
SLO: انطباق با تاخیر/موفقیت/طراوت.
امنیت: صفر موارد PII در پاسخ/سیاهههای مربوط.
هزینه: نرخ ضربه کش، هزینه درخواست،٪ از متقاضیان.

19) RACI (به عنوان مثال)

محصول/تجزیه و تحلیل (A) - تعاریف KPI، الزامات.
بستر داده (R) - پیاده سازی، حافظه پنهان، SLA، قابلیت مشاهده.
صاحبان دامنه (R) - منابع/قراردادها.
امنیت/DPO (A/R) - حریم خصوصی، دسترسی، ممیزی.
SRE (R) - سهمیه بندی، مقیاس خودکار، حوادث.
امور مالی (C) معانی مالی از GGR/NGR/NET است.

20) پیاده سازی نقشه راه

0-30 روز (MVP)

1. 3-5 KPI را انتخاب کنید (GGR، سپرده، نگهداری D7).
2. توصیف قراردادها و معانی KPI ؛ فعال کردن DQ/SLA.
3. اجرای «/v1 »پرس و جو API + کش + mTLS/HMAC.
4. داشبورد SLO (تاخیر/موفقیت/طراوت)، audit/trace _ id.

30-90 روز

1. پیش محاسبه فروشگاه های محبوب، ذخیره سازی CDN.
2. نسخه «/v2 »، دوگانه خواندن، راهنمای مهاجرت.
3. صادرات API ها با آپلود های امضا شده و WORM ها.
4. ادغام با BI/ML ؛ سهمیه/مستاجران/geo-isolators.

3-6 ماه

1. طبقه بندی KPI و کتابخانه ویجت را کامل کنید.
2. راهنمایی های هوشمند/فیلترهای تکمیل خودکار، پرس و جو linter.
3. یادداشت انتشار خودکار KPI، کنترل تحمل v1/v2.
4. حلقه شریک خارجی با کلید های محدود و سیاست های RG.

21) ضد الگوهای

فرمول KPI پنهان بدون نسخه جدید و انتشار یادداشت ها تغییر می کند.
بازگشت PII/مواد خام به جای aggregates/tokens.
فقدان کش/prerenders → گران و آهسته است.
اتصال سخت به یک پایگاه داده خاص (بدون انتزاع لایه).

TZ/FX متناقض → اعداد متفاوت

بدون محدودیت نرخ/سهمیه → «خود DDOS».

22) قالب (آماده برای استفاده)

22. 1 سیاست API SLO (قطعه)

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 Practices، Audit and Versioning، Security and Encryption، Access Control، Tokenization داده ها، سیاست های نگهداری، Data Origin and Path، MLOps: بهره برداری از مدل، اخلاق داده ها.

مجموع

API های تحلیلی و متریک یک لایه قراردادی، امن و سریع دسترسی به داده های طلا و KPI ها هستند. این تضمین معانی یکنواخت، نسخه های پایدار، حفظ حریم خصوصی پیش فرض و عملکرد سطح محصول - از داشبورد داخلی به پانل های شریک و ML است.