API վիճակագրություններ և վերլուծաբաններ ՝ իրադարձություններ, ագրեգատներ, ռենտենշեն

Հոդվածի ամբողջական տեքստը

1) Ինչու՞ են արտաքին API վերլուծաբանները

Գործընկերներ/պրովայդերներ ՝ SLA բովանդակություն, RTP, ներգրավվածություն։

• Մարքեթինգը/CRM 'ձգողական արշավներ, հիմնված մետրիկի վրա (DAU, ավանդային ձագար)։
• Վիրահատություններ/ֆինանսներ ՝ near-real-time GGR/NGR, վճարումների հաջողությունը, webhuks ճամբարները։
• Արտադրանքը 'in-app-ի վիճակագրությունը, A/B վահանակները։
• Նպատակը անվտանգ և կանխատեսելի է իրադարձություններ և ագրեգատներ տալ հասկանալի սեմանտիկայով և SLA-ով։

---

2) Մատների վրա ճարտարապետությունը

Producers (PAM/Wallet/RGS/Payments/Kafka/CDC)
│
Ingestion API ──Stream (Kafka/Pulsar) ──Lakehouse (Delta/Iceberg)
│                 └─OLAP (ClickHouse/BigQuery/Trino)
└────────────────────────────────────Aggregation/Query API
(cache, RBAC/RLS, rate limits)

Իրադարձությունները ՝ at-leport-once, «event _ id/idempotency _ key»։

• Ագրեգատները ՝ կանխատեսելի rollup 'a (1m/5m/1h/1d) + on-the-fly։
• Retenshen 'cohron շարժիչը Gold-Lines-ի վերևում։

Кэш: CDN/edge + ETag/`Cache-Control`, server-side TTL.

---

3) Իրադարձությունների մոդել 'նվազագույն ստանդարտ

3. 1 Ընդհանուր դաշտեր

json
{
"event_id":"uuid",  "event_type":"bet. settled",  "occurred_at":"2025-10-23T16:21:05Z",  "ingested_at":"2025-10-23T16:21:06Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_19f3",   // псевдо-ID
"trace_id":"tr_a1b2c3",  "schema_version":"1. 3. 0",  "payload":{...}
}

Կանոնները ՝ UTC timestamps, «player _ id» - կեղծանուն, գումար minor units-ում։

3. 2 Հիմնական տեսակներ

---

4) Ingestion API (երրորդ կողմի աղբյուրների համար)

Ուղարկելով իրադարձությունների տուփը

POST /v1/events:batch
Headers: X-Idempotency-Key: ev_20251023_001
[
{"event_id":"...","event_type":"bet. placed",...},  {"event_id":"...","event_type":"bet. settled",...}
]
→ 202 { "accepted":2, "duplicates":0, "trace_id":"tr_a1b2" }

Երաշխիքներ ՝ at-leport-once; կրկնօրինակները ֆիլտրվում են Silver-ում 'event _ id։

---

5) Aggregation API: Time-series և reses։

5. 1 Թայմսերիա (ժամանակի մետրեր)

GET /v1/analytics/timeseries
?metric=ggr    // ggr, ngr, dau, deposits_success, rtp
&granularity=5m  // 1m/5m/1h/1d
&from=2025-10-22T00:00:00Z&to=2025-10-23T00:00:00Z
&filters=region:EU,brand_id:brand-7,provider_id:studio_x
&group_by=brand_id
→ 200 {
"metric":"ggr",  "granularity":"5m",  "series":[
{"ts":"2025-10-22T00:00:00Z","brand_id":"brand-7","value_minor":120030},   {"ts":"2025-10-22T00:05:00Z","brand_id":"brand-7","value_minor":98020}
],  "next_cursor":null
}

5. 2 Խաչմերուկներ/կացիններ (group-by)

GET /v1/analytics/slice
?metric=rtp &dim=game_id &from=2025-10-22&to=2025-10-23
&limit=50&order=-value
→ 200 { "items":[{"game_id":"g_01","value":0. 956},...] }

5. 3 Ձագեր (funnel)

POST /v1/analytics/funnel
{
"steps":[
{"event":"payment. intent"},   {"event":"payment. authorized"},   {"event":"payment. captured"},   {"event":"wallet. credit", "reason":"deposit"}
],  "window_sec": 3600,  "filters":{"region":"EU","brand_id":"brand-7"}
}
→ 200 {
"total": 12450,  "steps": [
{"name":"intent", "count":12450, "rate":1. 0},   {"name":"authorized", "count":11020, "rate":0. 885},   {"name":"captured", "count":10110, "rate":0. 811},   {"name":"credited", "count":10050, "rate":0. 807}
]
}

5. 4 Լիմիտներ և քեշներ

Rate limit per token/brand/region.

«ETag» պատասխանները. աջակցություն 'If-None-Match'։

• Cash TTL-ը կախված է «granularity» -ից (օրինակ, 5m 35TTL 60-120 s)։

---

6) Retenshen և cogorts ՝ կանոններ և API

6. 1 Սահմանումներ (կոնվենցիա)

DAU/WAU/MAU: ակտիվ, եթե լիներ «bet»։ placed 'կամ' wallet. credit (deposit)` или `session. started '35N րոպե։

Cohronby first deposit (հաճախ LTV) կամ by registration (ներգրավման համար)։

• Retention D1/D7/D30: Կոգորտից մասնաբաժինը վերադարձավ օրվա պատուհանում +/- մեջբերում է բրենդի գաղտնի գոտում։
• Կրկնվող այցելությունները համարվում են պատուհանի յուրահատուկ «player _ id»։

6. 2 API cogorts

POST /v1/analytics/retention
{
"cohort":"first_deposit",  "start_date":"2025-09-01",  "end_date":"2025-09-30",  "return_event":"bet. placed",  "days":[1,7,14,30],  "filters":{"region":"EU","brand_id":"brand-7"}
}
→ 200 {
"cohort":"first_deposit",  "rows":[
{"cohort_date":"2025-09-01","size":1820,"d1":0. 36,"d7":0. 22,"d14":0. 18,"d30":0. 12},   {"cohort_date":"2025-09-02","size":1714,"d1":0. 35,"d7":0. 23,"d14":0. 19,"d30":0. 13}
]
}

6. 3 LTV/կուտակումներ

GET /v1/analytics/ltv? cohort=first_deposit&currency=EUR&horizon=90d
→ 200 { "cohorts":[{"date":"2025-09-01","ltv_minor":[0,150,230,280,...]}] }

---

7) Մետրանտիկան (որպեսզի չխոսի)

Բոլորը UTC-ում են, որը ցույց է տալիս արժույթը և minor units; ջերմունակությունը լուծվում է FX-ի փոփոխությամբ Express Lake-ում։

---

8) Տարբերությունը, ֆիլտրը և համատեղելիությունը

Ճանապարհը '; նոր մետրերը/դաշտերը optional են։

Фильтры: `brand_id, region, provider_id, game_id, method, currency, device, geo`.

Պագինացիա ՝ cursor-based («next _ cursor»)։

• Breaking-ը պարունակում է միայն '/v2 '+ Deprecation/Sunset վերնագրեր և changelog։

---

9) Անվտանգություն և հասանելիություն

OAuth2 Client Credentials (կարճ), mTSA-ի համար B2B-ի համար։

RBAC/ABAC 'մետրերի/կտրվածքների թույլտվություն; RSA ֆիլտրը 'brand/region "։

• PII: API-ը չի տալիս PII, միայն ագրեգատները/կեղծ-ID-ը անհրաժեշտության դեպքում։
• Նստավայրը 'հարցումների երթուղայնացումը տարածաշրջանում; քրոսոմային տվյալները արգելված են։
• Rate limits և քվոտաներ, anti-abuz; WORM-ի հասանելի աուդիտը։

---

10) ՍԼՈ և դիտարկումը

SLO կենտրոններ

"GET/timeseries gran = 5m 'p95 35500-800 ms," GET/slice "p95-1-2 s (գագաթներ մինչև 50-100 դիրք)," POST/retention "(ամիս) p95-3-5 s, թարմություն rollup' s: p95 2-5 րոպե" ocurred _ at "։

Մետրիկները ՝ latency p50/p95/p99, error-rate (4xx/5xx), cache-hit, հարցումներ/skan-բայթ (OLAP), «freshness lag» յուրաքանչյուր rollup 'y։

Լոգները 'կառուցվածքային, «trace _ id», հարցման ֆիլտրեր (առանց PII), սկանների հաշիվը։

---

11) Քեշը, նախնական հաշվարկները, արժեքը

Rollup-աղյուսակները ՝ 1m/5m/1h/1d առանցքային մետրերով, արագ «timeseries» են։

Materialized views-ը ծանր կտրվածքների/կոհորտի համար։

• ETag + max-age; հաշմանդամություն ունեցող անձանց մոտ տեղի է ունենում հակիրճ։
• «hot/cold» ռազմավարությունը, տաք հարցումները OLAP-warehouse-ում։ արխիվը Lake-ում է։
• «Սկան Բայթի» սահմանափակումը հարցման համար։ նշումներ պլանավորողին։

---

12) Կառուցումը (embedded) և արտահանումը

Ներկառուցված վիզետները signed URL/iFrame-ի միջոցով RSA-tocens-ի հետ։

• CSV/Parquet էքսպորտը առաջադրանքների վրա (job API), չափի սահմանափակումներով և ժամանակավոր հղումներով։
• Webhook-ծանուցումներ արտահանման պատրաստակամության մասին։

---

13) Չեկ թերթերը

Ճարտարապետություն

• Իրադարձությունների միասնական սխեմա, semver, registry; dedup «event _ id»։
• Rollup 's և materialized views-ը առաջին գործի տակ։
• RFC/RBAC/ABAC, նստավայր, խառնաշփոթ։
• Քաշ (ETag/TTL), rate limits, քվոտաներ։

Սեմանտիկան

• GGR/NGR/RTP/DAU/retention-ի սահմանումները հետևյալն են։
• Արժույթը 'minor units; FX-ը գրանցվում է իրադարձության պահին։
• Retention-ը UTC-ում, հաշվի առնելով բրենդի-թայմզոնները ցուցադրման մեջ։

Վիրահատություններ

• SLO/dashbords թարմ և լատենտ։
• WORM-աուդիտ հասանելի/ֆոսֆոր։
• DR/xaoc-ուսմունքները 'rollup, հարցումների մի շարք, որոնք ուշացել են։

---

14) Anti-patterns (կարմիր դրոշներ)

«Հում» OLTP աղյուսակները ուղղակիորեն տրվում են API-ում։

• Չհամաձայնեցված սահմանումները թիմերի միջև։
• Պապուպի և watermarks-ի բացակայությունը կրկնակի/կորցրած իրադարձություններ է։
• Անթույլատրելի on-the-fly ագրեգացիան առանց քեշի/քվոտի բացատրվում է թանկարժեք և դանդաղ հարցումներով։
• Քրոս-ռեգիոնային միավորումը առանց բնակության քաղաքականության։
• PII/խաղացողի մանրամասները հանրային պատասխաններում։
• Հանգիստ breaking-changes առանց '/v2 "և Deprecation-ի։

---

15) Մինի-սպեկ (TL; DR)

Իրադարձությունները ՝ «/v1/events: batch »(at-leport-once,« event _ id »)։

Թայմսերիա:

Կտրվածքներ:

Վորոնկի '«/v1/anport.ru/funnel »(պատուհան, քայլեր, ֆիլտրեր)։

Retenshen/cohorts: '//v1/anport.ru/retention "(+ LTV)։

Անվտանգություն ՝ OAuth2 + mTSA, RTS, per brand/region, WORM աուդիտ։

SLO: p95 ≤ 0. 5-2 s; թարմություն 2-5 ռուբլիներ

---

API վիճակագրությունն ու վերլուծաբանները ոչ թե «MS FROM brone _ table» են, այլ մեթրիկի պայմանագիրը 'կայուն իրադարձություններ, որոնք կանխորոշված են և քողարկված ագրեգատներ, խստորեն սահմանված ռենտեն և ճենապակյա, անվտանգություն (RFC/RBAC) և բնակություն, որոնք հասկանալի են SLLO-ում։ Այսպիսով, դուք տալիս եք տվյալները արագ, էժան և կանխատեսելի 'գործընկերներ, ապրանքներ և BI, առանց հակասական մեկնաբանությունների և առանց արտահոսքի կամ ծանրաբեռնվածության ռիսկի։