Maglumat giriş interfeýsleri
1) Näme üçin oýlanyşykly interfeýs
Tizlik we öňünden aýdylýanlygy: iş metrikleri we hasabatlar "el bilen düşürilmezden" SLA-a gabat gelýär.
Howpsuzlyk we gizlinlik: PII/biometriýa gözegçilik astynda, k-anonimlik, geo-serhetler.
Çeýeligi: dürli müşderiler (BI, hyzmatlar, hyzmatdaşlar, DS/ML) zerur zatlary alýarlar.
Gaýtadan ulanmak: şertnamalar we wersiýalar bilen "önüm hökmünde maglumatlar".
2) Interfeýs kartasy (haçan)
SQL/ANSI + wendor dialektleri: interaktiw analitika, BI, ad-hoc.
REST JSON: Durnukly agregatlar we iş maglumatlary, hyzmatdaşlar bilen integrasiýa.
GraphQL: çeýe "saýlama" okamak we nawigasiýa grafasy (ölçegler/faktlar).
gRPC (protobuf): pes gizlinlik online-serwing (Feature Store, skoring).
Arrow Flight/Parquet over HTTP/S3-presigned: DS/ML üçin çalt sütünli "damplar".
OData: enterprise-gurallar, "hyzmat hökmünde tablisa" modeli.
Akymlar (Kafka/Pulsar) + CDC/Webhooks: hakyky wagtdaky wakalar, reaktiw integrasiýa.
Federasiýa (Trino/Presto): köp çeşmelere girmegiň ýeke nokady.
Düzgün: agregatlar we durnukly dilimler → REST/MV, baý esassyz soraglar → SQL, pes gizlinlik/onlaýn çyzgylar → gRPC, çeýe jogap görnüşi → GraphQL, köpçülikleýin ikilik alyş-çalyş → Arrow/Parquet.
3) Şertnamalar we wersiýalar (semver)
`MAJOR. MINOR. Her bir API/shema/waka üçin PATCH '.
MAJOR: gabat gelmeýän üýtgeşmeler (täze ýol/topik/tablisa).
MINOR: gabat gelýän meýdanlar/argumentler.
PATCH: düşündirişleri/çäkleri düzetmek.
Şertnamalar: shema, süzgüçler, çäkler, gizlinlik, SLO.
yaml openapi: "3. 0. 3"
info: {title: "Analytics API", version: "2. 4. 0"}
paths:
/v2/payments/metrics:
get:
parameters:
- {name: brand, in: query, schema: {type: string}, required: true}
- {name: country, in: query, schema: {type: string}}
- {name: from, in: query, schema: {type: string, format: date-time}}
- {name: to, in: query, schema: {type: string, format: date-time}}
- {name: group_by, in: query, schema: {type: string, enum: [psp,status,day]}}
- {name: limit, in: query, schema: {type: integer, default: 500}}
responses:
"200": {description: "OK"}
x-slo: {p95_latency_ms: 1200, freshness_max: "PT5M"}
x-privacy: {pii: false, min_group_size: 20}4) Analitika elýeterliligi (SQL we federasiýa)
Rolly/maskaly SQL-şlýuzy (row/column-level security).
BI aşagyndaky wuhi/proýeksiýalar: durnukly atlar we semantika; heavy-soraglar agregasiýadan öň gidýär.
Federasiýa (Trino/Presto): giriş nokady, ýöne syýasatçylar bilen: haýsy kataloglar we haýsy funksiýalar bar.
Lakehouse (Iceberg/Delta/Hudi): SQL/REST arkaly wagt-syýahat, snapshot-ekstraksiýa.
Квоты: scanned bytes/query, concurrency, wall-time.
5) GraphQL (çeýe görnüş)
Müşderä zerur meýdany ýygnamaga berýäris, ýöne taýýarlanan çeňňekleriň/proýeksiýalaryň üstünde, çuňlugyň/süňkleriň çäkleri bilen ýerine ýetirýäris.
graphql type Query {
payments(
brand: String!, country: String, from: DateTime!, to: DateTime!,
first: Int = 200, after: String
): PaymentConnection
}Syýasatlar: depth ≤ 5, total nodes ≤ 5k, özbaşdak regex/like hatlaryny gadagan edýäris; ýygy-ýygydan soraýarys.
6) gRPC/Feature Store (pes gizlinlik)
Antifrod/teklipleri/RG skoring üçin onlaýn fiçalar.
proto service FeatureStore {
rpc GetFeatures (FeatureRequest) returns (FeatureResponse);
}
message FeatureRequest { string user_tok = 1; repeated string features = 2; }
message FeatureResponse { map<string, FeatureValue> values = 1; int64 ts_micros = 2; }Talaplar: p95 ≤ 50-100 ms, takyk utgaşdyrylmagy awtonom, onlaýn, TTL surat, LRU nagt, idempotency we mTLS.
7) Akymlar we CDC
Domen wakalary: 'payments. deposit_accepted`, `game. round_finished`.
CDC (ALTP-den): near-real-time statuslarynyň/çäkleriniň üýtgemegi.
Hyzmatdaşlar üçin webhooks: agregatlara ýazylmak (mysal üçin, "PSP şowsuzlyklary> bosagasy").
Retraý/tassyklama syýasaty: kritikler üçin exactly-once, gözegçilik üçin at-least-once.
8) Köller we uly nusgalar
DS/ML-de çalt sütün düşürmek üçin Arrow Flight.
Parquet/Feather-de Presigned-URL, gysga TTL we gol çekilen haýyş bilen.
Chunked transfer we faýl ululygyna gözegçilik etmek; download magazineurnaly (WORM-audit).
9) Süzgüçler, paginasiýa, sortlamak
Uly toplumlar üçin OFFSET ýerine Keyset-paginasiýa (kursor).
Süzgüçler: meýdanlar, görnüşler we operatorlar boýunça whitelists ('=, IN, BETWEEN, prefix').
Sortlama: çäkli meýdan sanawy, default tertibi.
Partial response: 'fields = brand, country, amount' iş ýüküni azaldar.
http
GET /v2/game-rounds? brand=X&from=...&to=...&first=1000&after=eyJkYXRlIjoi...10) Kesmek we bahasy
Şablon soraglary üçin result cache, täzelik belligi boýunça maýyp bolýarys (snapshot id).
Jemgyýetçilik/ýarym jemgyýetçilik agregatlary üçin Edge-keş/CDN (PII-siz).
Budget-parametrleri: scanned bytes çägi, haýyşyň wagty, rps/min kwotalary.
Howuzlaryň ileri tutulmagy: 'bi _ hot', 'adhoc', 'partner _ api'.
11) Howpsuzlyk we gizlinlik
AuthN: OAuth2/OIDC (hyzmatlar üçin client credentials, adamlar üçin PKCE).
AuthZ: RBAC + ABAC (atributlar: marka, ýurt, ygtyýarnama, rol).
Hyzmatlaryň arasynda mTLS, TLS 1. 2 + daşarky.
PII-arassaçylyk: API gatlagynda maskalar/tokenizasiýa, sütünli maskalar, agregatlaryň k-anonimligi.
Geo/tenant-izolýasiýa: haýyşlaryň ygtyýarnama sebitine ugrukdyrylmagy; Marka/sebit üçin şifrlemek açarlary.
DSAR/Legal Hold: subýektiň belligi boýunça gözleg, toplumlary doňdurmagyň syrlary.
12) Syn etmek (SLI/SLO) we goramak
SLI: p50/p95/p99 lat, error-rate, rps, bytes scanned, cache hit, kwotalar/limitler, gizlenen sütünleriň paýy, ygtyýarlylygyň şowsuzlyklarynyň paýy.
SLO: p95 gizlinlik, maglumatlaryň täzeligi, üstünlikli haýyşlaryň% -i, jogaplarda min-group-size.
Alertler: scanned bytes ösüşi, hit-rate güýji, 429/5xx köpelmegi, PII-e girmek synanyşyklary, kursorlaryň syzmagy.
yaml slo:
p95_latency_ms: 1200 success_rate: 0. 995 freshness_max: "PT5M"
privacy:
pii_allowed: false min_group_size: 20 quotas:
rps: 50 max_scanned_mb: 25613) Formatlar we gysyş
JSON gabat gelmek üçin; CSV - diňe kiçi we ýönekeý eksportlar üçin.
Parquet/Arrow - Uly ýükler üçin standart.
Compression: gzip/zstd ('Accept-Encoding' arkaly gepleşikler).
Content-negotiation: `Accept: application/x-parquet`.
14) API ýaly metrikler (Analytics/OLAP-şlýuz)
GGR/NET, CR, saklamak, RG hadysalary - 'brand, country, window, group _ by' parametrleri bolan çeşmeler hökmünde.
Approx (HLL/TDigest) для distinct/percentiles.
Açary bolan keş: '(metric, params, snapshot_id)'.
15) iGaming aýratynlyklary - taýýar endpointler
'GET/v2/payments/metrics' - 7/30d penjireli PSP/ýurt/marka boýunça şowsuzlyklar/şowsuzlyklar.
'GET/v2/game-rounds/metrics' - iň ýokary oýunlar/üpjün edijiler, p95 dowamlylygy, RTP penjireleri.
'GET/v2/rg/cases' - işjeň çäklendirmeler/öz-özüni aýyrmalar (k-anonim agregatlar).
'POST/v1/features: get' (gRPC) - frod/rekommender skoringi üçin onlaýn fiçalar.
'POST/v1/webhooks/psp-alerts' - "decline rate> bosagasy" habarnamalary.
16) Şertnamalaryň mysallary
GraphQL soragy inçe kesildi:graphql query {
payments(brand:"X", country:"TR", from:"2025-10-01", to:"2025-10-31", first:500) {
edges { node { day totalAmount declines psp } cursor }
pageInfo { hasNextPage endCursor }
}
}json
{"event_id":"...","occurred_at":169..., "brand":"X","psp":"Papara","status":"declined","amount":"100. 00","currency":"TRY"}
/flight/v1/query? dataset=gold. payments&from=...&to=...&brand=X&format=arrow17) Täze interfeýsi çap etmek prosesi
1. ADR: mesele/gymmaty/müşderiler/howpsuzlyk/gymmaty.
2. Şertnama: shema, süzgüçler, çäkler, gizlinlik, SLO, wersiýalar.
3. Ýük modellemek: top-N soraglar, p95/skan-baýtlar, bahasy.
4. Kwota/Kesh: Standart ýaly açyň.
5. Dokumentasiýa we SDK: mysallar, çäkler, ýalňyşlyklar, retralar, idempotentlik.
6. Canary:% müşderiler, regress synaglary, aladalar.
7. GA: Data Products katalogyndaky wersiýa, effektler boýunça hasabat.
18) Anti-patternler
"Çig" SQL-i hemmeler üçin açyň - PII syzmagy, öňünden aýdyp bolmajak bahasy.
OFFSET-paginasiýa we 'SELECT' - gizlinlik we hasap agyrysy.
GraphQL çuňlugy/bahasy çäklendirilmän.
'fields =...' -siz gaty köp sütüni yzyna gaýtarýan REST.
Agregatlarda k-adynyň aýdylmazlygy we min-group-size.
Nol kwotalary/çäkleri we öçürilen nagt pul.
Wersiýa/şertnama ýok - her üýtgeşmede müşderileri "döwýäris".
Ähli ýurtlar/markalar üçin şol bir interfeýs sebitleýin düzgünleriň ignorydyr.
19) Durmuşa geçirmegiň ýol kartasy
0-30 gün (MVP)
1. Data Products katalogy (metrikler/bölekler) we olaryň OpenAPI/GraphQL şertnamalary.
2. RLS/CLS bilen SQL-şlýuz, agregatlaryň k-anonimligi, esasy kwotalar.
3. Bir REST-metrik endpoint ('/payments/metrics ') + kesh + pula' bi _ hot/adhoc '.
4. gRPC Feature Store: 10-20 esasy onlaýn surat okamak (p95 ≤ 80 ms).
30-90 gün
1. PSP alertleri/oýun wakalary üçin akym interfeýsleri (Kafka/Webhook).
2. Arrow/Parquet presigned-URL-den düşürmek; snapshotlar katalogy.
3. Federasiýa-şlýuzy (Trino/Presto) aç-açan syýasatçylar bilen.
4. Syn edilişi: SLI/SLO dashbord, bahasy/gizlinligi/PII üçin aladalar.
3-6 aý
1. SDK (TypeScript/Python/Go).
2. Önümler we hyzmatdaşlar üçin inçe GraphQL bölekleri.
3. gRPC/FS giňeltmek, onlaýn offline utgaşdyrmak; shadow → canary relizleri.
4. Gizlinlik barlagy/DSAR; elýeterlilik boýunça utgaşma hasabatlary.
20) RACI
Data Platform (R): şlýuzlar, nagt pul, kwotalar, federasiýa, gözegçilik.
Data Governance (A/R): şertnamalar, wersiýalar, gizlinlik/k-anonimlik.
Domain Owners (R): meýdan semantikasy, iş üýtgemeleri, Data Products.
Howpsuzlyk/DPO (A/R): AuthN/Z, geo-izolýasiýa, DSAR/Legal Hold.
SRE/Observability (C): SLO/SLI, alertler, capacity.
Analytics/BI/DS (C): formalar/agregatlar üçin talaplar, SDK.
21) Baglanyşykly bölümler
Analitik ammarlary indekslemek, Analitik soraglary optimizirlemek, Maglumat shemalary we olaryň ewolýusiýasy, Maglumatlary tassyklamak, DataOps-praktikalar, Analitika we metrika API, Aýratynlyk dükany, Maglumat howpsuzlygy we şifrlemek, Giriş gözegçiligi, Maglumatlary saklamak syýasaty.
Jemi
Dogry dizaýn edilen maglumatlara girmek interfeýsleri ammarlary we akymlary ygtybarly "önüme" öwürýär: öňünden aýdyp boljak SLA, gözegçilik edilýän baha, gizlinligi berjaý etmek we önüm buýruklary, analitikler, gabat gelýänler we hyzmatdaşlar üçin bir dil. iGaming-de bu PSP şowsuzlyklaryny has çalt tutmagy, oýunçylaryň özüni alyp barşyna düşünmegi we düzgünleşdirijileriň talaplaryny ýerine ýetirmegi aňladýar - el bilen düşürmezden we gijeki göçmezden.