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) API келісімшарттары (Data & BI Contracts)
Schema: өрістер, түрлер, nullable, enum, бірліктер, валюталар.
Метриктер семантикасы: формула, көздер, агрегация терезелері, сүзгілер.
Сыйысымдылық (SEMVER): MAJOR сынады, MINOR өрістерді қосады, PATCH бекітеді.
DQ/SLA: жаңалық, толымдылық, консистенттілік, алшақтық шақтамалары.
Құпиялылық: 'pii: false', 'tokenized: 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) Сәулет
Query API («gold «/куб/фичестордың үстінен онлайн агрегаттау).
Precompute API (кесте бойынша пререндерлер, materialized views).
Events API (ағынды есептеуіштер/сигналдар).
Export API (қол қойылған түсірулер, аудит үшін WORM).
Кэш: көп қабатты (in-memory → Redis → CDN), кілт = сұрау хэш + нұсқа.
Келісу: соңғы жазбалар үшін read-your-writes, агрегаттар үшін SLA жаңалық.
5) Интерфейс және сұраулар
5. 1 Сүзгілер/агрегаттар/терезелер
'filter': күн диапазондары ('from/to' UTC, timezone aware), елдер, брендтер, ойындар, арналар, құрылғылар.
'group _ by': өлшемдері.
'metrics': KPI тізімі.
`window`: `DAY|WEEK|MONTH|ROLLING_7D|ROLLING_28D`.
'currency': 'reporting' native ', FX стратегиясы:' eod 'intraday' txn '.
'sampling': heavy-сұраулар үшін (рұқсат етілген жерде ғана).
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) Пагинация, лимиттер, сұрыптау
Пагинация: 'limit' (≤ 10k), 'cursor' (opaque), өлшемдері/күні бойынша сұрыптау.
Timeout/partial: ішінара жауаптар тек қаржылық емес KPI үшін; қаржы - не P200, не P504.
Rate limits: жаһандық/кілт бойынша/тенант бойынша; жауабында 'X-RateLimit-' бар.
7) Теңсіздік және кэш
Idempotent GET/POST-read (денесімен) с 'Idempotency-Key'.
Кэш-кілт = хэш (параметрлер + схема нұсқасы + рөл/тенант/гео).
TTL: KPI тәуелді (мысалы, 'PT15M' revenue үшін, 'PT5M' оқиғалар үшін), жаңа snapshot кезінде қалпына келтіру.
8) Консистенттілік және уақыт валютасы
Ретроспективті есептер үшін Time-travel жалауы (деректер нұсқасы).
Cut-off ережелері (күн/аптаның жабылуы).
FX: стратегияны бекітеміз, жауап ретінде курстың күні.
Clock: барлық таймстамптар - ISO-8601, TZ нұсқауы міндетті.
9) Қауіпсіздік және құпиялылық
mTLS/TLS1. 3. HMAC-сұрау/жауап денесінің қолтаңбасы (MITM/replay-ден қорғау).
RBAC/ABAC/ReBAC: рөлі + ел + бренд + мақсат; әдепкі қалқалар.
Көп жалдау (multi-tenant): схемаларды/кілттерді/квоталарды оқшаулау.
Идентификаторларды токенизациялау; жауаптарда PII тыйым салу.
Аудит: өзгермейтін сұрау логтары (WORM), 'trace _ id '/' actor '/' purpose'.
Consent/DSAR: маркетингтік төлсипаттарға арналған сүзгілер; «subject erased» жалаушасы.
10) RG/AML/Антифрод шектеулер
RG-саясат: high-risk сегменттері үшін «агрессивті» көрсеткіштерді беруге тыйым салу; агрегаттар қауіпсіз.
AML/Антифрод: сезімтал KPI шектеулі қолжетімділік, рөлдер бойынша аймақтау; тергеу үшін бөлек эндпоинттер.
Explainability: KPI/саппорт сигналдарын түсіндіру сөздігі.
11) Бақылау және SLO API
SLO: p95 latency (мысалы, кэш-хит үшін ≤ 300 мс; ауыр хит үшін ≤ 2 с), success-rate ≥ 99. 5%.
DQ: жаңалық/толымдылық/тұтастық; жауапты белгілер.
Usage: QPS, hit-rate кэш, ыстық кілттер, валидация қателері.
Алерталар: балауса өсу, өсу 4xx/5xx, KPI бойынша аномалиялар (unexpected zeros/peaks).
Tracing: 'trace _ id' DWH/фичесторға дейін.
12) Нұсқалау және үйлесімділік
Жолдары: '/v1 ', '/v2'; көші-қон терезесі бар депрекейт.
Сызбалар: жауапта 'schema _ version'; MAJOR → dual-read, көші-қон гайдтары.
KPI нұсқасы: 'kpi _ definitions' жауабында каталогтағы сілтемемен; жасырын формула өзгерістеріне тыйым салу.
13) Қателер мен мәртебелер
'400' валидациясы (жоқ метрика/өлшеу/сүзгілер комбинациясы).
'401/403' аутентификациялау/авторизациялау.
'409' нұсқалардың/саясаттардың сыйыспаушылығы.
'422' құпиялылықтың бұзылуы/consent.
'429' квотасы.
'5xx' платформасының ақаулары (trace_id және retry-қосылымымен) .
json
{
"error":"VALIDATION_FAILED",
"message":"Unknown metric: ngrx",
"hint":"metrics allowed: ggr, net_revenue,...",
"trace_id":"..."
}14) Интеграция және интерфейстер
BI: алдын ала сипатталған semantic-модельдер, коннекторлар (Looker/Power BI/Tableau) → API көзі ретінде.
ML: lightweight endpoints фич-агрегаттар үшін (point-in-time, PII жоқ).
Серіктестер: шектеулі кілттер/квоталар, гео-сүзгілер, есептер тек агрегаттық блоктармен.
Webhook/Push: «snapshot дайын», «SLO/KPI ауқымы бұзылған» нотификациялары.
15) Ресурстық эндпоинттердің үлгілері
15. 1 Түсім/кірістілік
'POST/v2/metrics/revenue' → GGR/NGR, ставкалар/ұтыстар, өлшемдер бойынша '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' → депозиттер/қорытындылар, орташа чек, chargeback rate.
15. 4 Responsible Gaming
'POST/v2/metrics/rg' → интервенциялар саны, high-risk үлесі, реакцияның орташа уақыты.
15. 5 Антифрод
'POST/v2/metrics/antifraud' → FPR/TPR, кейстер, алдын алынған шығындар.
16) Тестілеу және сапа
Келісімшарттық тесттер: enum/nullable/түрі, валюта/сағат белдеулерінің келісімділігі.
DQ-тесттер: диапазондарды, монотонды және тұтастықты бақылау.
Регресс: толеранстар бойынша v1/v2 салыстыру.
Жүктемелік: пик профильдері (турнирлер/провайдерлік ивенттер).
Қауіпсіздік: қолтаңбалар, anti-replay, fuzzing сұраулары, Логтарда Zero-PII.
17) Әдепкі құпиялылық
«Минимумы N жазбалар» (k-анонимділік) шектері бар агрегаттар.
raw идентификаторлары жоқ; тек токендер/санаттар.
DSAR: артықшылықты контур арқылы токен бойынша түсіруге/жоюға арналған API.
18) Табыс өлшемдері (KPI API)
Adoption: тікелей SQL емес, API пайдаланатын есептер/виджеттер үлесі.
Consistency: BI мен API арасындағы айырмашылық ≤ рұқсаттар.
SLO: latency/success/freshness.
Security: жауаптардағы/жауаптардағы PII нөлдік жағдайлары.
Cost: hit-rate кэш, сұрау құны,% пререндерлер.
19) RACI (мысал)
Product/Analytics (A) - KPI анықтамалары, қажеттіліктер.
Data Platform (R) - іске асыру, кэш, SLA, observability.
Domain Owners (R) - дереккөздер/келісімшарттар.
Security/DPO (A/R) - құпиялылық, қолжетімділік, аудит.
SRE (R) - квоталар, автоскейл, инциденттер.
Finance (C) - GGR/NGR/NET қаржылық семантикасы.
20) Енгізу жол картасы
0-30 күн (MVP)
1. 3-5 KPI (GGR, депозиттер, D7 ұстап қалу) таңдау.
2. Келісімшарттар мен KPI-семантиканы сипаттау; DQ/SLA қосылсын.
3. '/v1 'Query API + кэш + mTLS/HMAC іске асыру.
4. SLO (latency/success/freshness) дашбордтары, аудит/trace _ id.
30-90 күн
1. Танымал витриналардың пререндерлері (Precompute), CDN кэш.
2. Нұсқалау '/v2 ', dual-read, көші-қон нұсқасы.
3. Қол қойылған жүктеулермен және WORM-мен API экспорты.
4. BI/ML интеграциясы; квоталар/тенанттар/гео-оқшаулағыштар.
3-6 ай
1. KPI толық таксономиясы және виджеттер кітапханасы.
2. Ақылды кеңестер/автокомплиталар сүзгілері, сұраулар линтері.
3. Автоматты Release Notes KPI, толерансты бақылау v1/v2.
4. Кілттері шектеулі және RG-саясаты бар сыртқы серіктестік контур.
21) Қарсы үлгілер
Жаңа нұсқасыз және нота шығарылмайтын KPI формуласын жасырын ауыстыру.
Агрегаттар/токендер орнына PII/шикізатты қайтару.
Кэштің/пререндерлердің жоқтығы → қымбат және баяу.
Нақты ДБ-ға қатаң байланыстыру (қабаттың абстракциясы жоқ).
Келісілмеген TZ/FX → салыстыруға келмейтін сандар.
rate limits/квота жоқ → «DDOS өз».
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: false22. 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: модельдерді пайдалану, Деректер этикасы.
Жиынтығы
API аналитика және метрика - бұл «алтын» деректер мен KPI-ға қол жеткізудің келісілген, қауіпсіз және жылдам қабаты. Ол бірыңғай семантикаға, тұрақты нұсқаларға, әдепкі құпиялылыққа және өнім деңгейіндегі өнімділікке кепілдік береді - ішкі дашбордтан серіктестік панельдерге және ML-ге дейін.