Деректерге қатынау интерфейстері
1) Не үшін ойластырылған интерфейс
Жылдамдығы мен болжамдылығы: бизнес-метриктер мен есептер SLA-ға «қолмен түсірусіз» салынады.
Қауіпсіздік және құпиялылық: PII/биометрия бақылауда, k-анонимділік, гео-шекара.
Икемділік: әртүрлі клиенттер (BI, сервистер, серіктестер, DS/ML) өздеріне қажет нәрселерді алады.
Қайталап пайдалану: келісімшарттар мен нұсқалары бар «өнім ретіндегі деректер».
2) Интерфейстердің картасы (қашан не)
SQL/ANSI + вендорлық диалектілер: интерактивті талдау, BI, ad-hoc.
REST JSON: тұрақты агрегаттар және операциялық деректер, серіктестермен интеграция.
GraphQL: икемді «таңдаулы» оқу және навигация бағандары (өлшемдер/фактілер).
gRPC (protobuf): online-сервингтің төмен жасырындылығы (Feature Store, скоринг).
Arrow Flight/Parquet over HTTP/S3-presigned: DS/ML үшін жылдам бағанды «дамбалар».
OData: enterprise-құралдар, «кесте қызмет ретінде» моделі.
Streams (Kafka/Pulsar) + CDC/Webhooks: нақты уақыттағы оқиғалар, реактивті интеграциялар.
Federation (Trino/Presto): көптеген көздерге кірудің бірыңғай нүктесі.
Ереже: агрегаттар және тұрақты кесінділер → REST/MV, бай еркін сұрау → SQL, төмен жасырындылық/онлайн-фич → gRPC, икемді жауап → GraphQL, жаппай екілік алмасу → Arrow/Parquet.
3) Келісімшарттар мен нұсқалар (semver)
`MAJOR. MINOR. Әрбір API/схема/оқиға үшін PATCH '.
MAJOR: үйлесімсіз өзгерістер (жаңа жол/топик/кесте).
MINOR: үйлесімді өріс/дәлел қосу.
PATCH: сипаттамаларды/лимиттерді түзету.
Келісімшарттар: сызбаны, сүзгілерді, лимиттерді, жекелікті, 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) Аналитикаға қолжетімділік (SQL және федерация)
Рөлдері/маскалары бар SQL-шлюз (row/column-level security).
Вьюхи/проекция под BI: тұрақты атаулар және семантика; heavy-сұраулар алдын ала тіркеуге кетеді.
Federation (Trino/Presto): бірыңғай кіру нүктесі, бірақ саясатпен: қандай каталогтар және қандай функциялар қол жетімді.
Lakehouse (Iceberg/Delta/Hudi): time-travel, SQL/REST арқылы snapshot-алу.
Квоты: scanned bytes/query, concurrency, wall-time.
5) GraphQL (икемді пішін)
Клиентке қажетті алаңды жинауға береміз, бірақ дайындалған шұңқырлардың/проекциялардың үстінен, тереңдігі/сүйектерінің лимиттерімен орындаймыз.
graphql type Query {
payments(
brand: String!, country: String, from: DateTime!, to: DateTime!,
first: Int = 200, after: String
): PaymentConnection
}Саясат: depth ≤ 5, total nodes ≤ 5k, жолдар бойынша еркін regex/like тыйым салынады; жиі сұрауларды кешіреміз.
6) gRPC/Feature Store (төмен жасырындылық)
Антифрод/ұсынымдар/RG үшін онлайн-фичи.
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; }Талаптар: p95 ≤ 50-100 мс, дәл оффлайн, онлайн, TTL фич, LRU кэш, idempotency және mTLS.
7) Ағындар және CDC
Домен оқиғалары: 'payments. deposit_accepted`, `game. round_finished`.
CDC (ALTP-ден): near-real-time мәртебелерінің/лимиттерінің өзгеруі.
Серіктестерге арналған Webhooks: агрегаттарға жазылу (мысалы, «PSP істен шығуы> табалдырығы»).
Ретрациялардың/растаулардың саясаты: exactly-once үшін сыни, at-least-once үшін мониторинг.
8) Көлдер және ірі іріктемелер
DS/ML жылдам колонналық түсіру үшін Arrow Flight.
Parquet/Feather-де Presigned-URL, қысқа TTL және қол қойылған сұрау.
Chunked transfer және файл өлшемін бақылау; жүктеу журналы (WORM-аудит).
9) Сүзгілер, пагинация, сұрыптау
Үлкен жиынтықтарға арналған OFFSET орнына Keyset-пагинация (меңзер).
Сүзгілер: өрістер, типтер және операторлар бойынша whitelists ('=, IN, BETWEEN, prefix').
Сұрыптау: өрістердің шектеулі тізімі, default тәртібі.
Partial response: 'fields = brand, country, amount' пайдалы жүктемені азайтады.
http
GET /v2/game-rounds? brand=X&from=...&to=...&first=1000&after=eyJkYXRlIjoi...10) Кэштеу және құны
Шаблондық сұраулар үшін Result cache, жаңалық белгісі бойынша мүгедектік (snapshot id).
Edge-кэш/CDN (PII-сіз).
Budget-параметрлері: scanned bytes лимиті, сұрау уақыты, rps/мин квотасы.
Пулдардың басымдығы: 'bi _ hot', 'adhoc', 'partner _ api'.
11) Қауіпсіздік және құпиялылық
AuthN: OAuth2/OIDC (client credentials for services, PKCE for people).
AuthZ: RBAC + ABAC (атрибуттары: бренд, ел, лицензия, рөлі).
Сервистер арасындағы mTLS, TLS 1. 2 + сыртқа.
PII-гигиена: API-қабаттағы маскалар/токенизация, бағаналы маскалар, агрегаттардың k-анонимділігі.
Geo/tenant-оқшаулау: лицензия аймағына сұрау маршруты; брендке/аймаққа шифрлау кілттері.
DSAR/Legal Hold: субъект белгісі бойынша іздеу, жинақтарды мұздату құпиялары.
12) Бақылау (SLI/SLO) және қорғау
SLI: p50/p95/p99 lat, error-rate, rps, bytes scanned, cache hit, квоталар/лимиттер, бүркемеленген бағандардың үлесі, авторизация бойынша істен шығу үлесі.
SLO: p95 жасырындылық, деректердің жаңаруы,% сәтті сұраулар, жауаптарда min-group-size.
Алерталар: scanned bytes өсуі, hit-rate құлдырауы, 429/5xx секірісі, PII-ге қол жеткізу әрекеттері, курстардың ағуы.
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) Форматтар және компрессия
JSON сыйысымдылығы үшін; CSV - тек шағын және күрделі емес экспорт үшін.
Parquet/Arrow - әдепкі үлкен жүктеулер үшін.
Compression: gzip/zstd ('Accept-Encoding' арқылы келіссөздер).
Content-negotiation: `Accept: application/x-parquet`.
14) API (Analytics/OLAP-шлюз) сияқты метриктер
Жоғарғы деңгей өлшемдері: GGR/NET, CR, ұстап тұру, RG оқиғалары - 'brand, country, window, group _ by' параметрлері бар ресурстар ретінде.
Approx (HLL/TDigest) для distinct/percentiles.
Кілті бар кэш: '(metric, params, snapshot_id)'.
15) iGaming ерекшелігі - дайын эндпоинттер
'GET/v2/payments/metrics' - 7/30d терезелері бар PSP/ел/бренд бойынша істен шығулар/апрустар.
'GET/v2/game-rounds/metrics' - топ-ойындар/провайдерлер, p95 ұзақтығы, RTP-терезелер.
'GET/v2/rg/cases' - белсенді шектеулер/өздігінен жою (k-жасырын агрегаттар).
'POST/v1/features: get' (gRPC) - фрод/рекоммендердің скорингі үшін онлайн-фичи.
'POST/v1/webhooks/psp-alerts' - «decline rate> шегі» ескертулері.
16) Келісімшарттардың үлгілері
GraphQL сұрауы: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) Жаңа интерфейсті жариялау процесі
1. ADR: проблема/құндылық/клиенттер/қауіпсіздік/құн.
2. Келісім-шарт: схема, сүзгілер, лимиттер, жекелік, SLO, нұсқалар.
3. Жүктемелік модельдеу: top-N сұраулар, p95/скан-байт, құны.
4. Валидация/кеш/квота: әдепкі бойынша қосу.
5. Құжаттама және SDK: мысалдар, лимиттер, қателер, ретра, теңсіздік.
6. Canary: клиенттердің%, регресс-тесттер, тәуекелдер.
7. GA: Data Products каталогындағы нұсқа, әсерлер бойынша есеп.
18) Қарсы үлгілер
Барлығына «шикі» SQL ашу - PII жылыстауы, болжауға келмейтін құн.
OFFSET-пагинация және 'SELECT' - жасырындылық пен есеп бойынша ауырсыну.
GraphQL тереңдігі/құны шектелмейді.
'fields =...' жоқ тым көп бағандарды қайтаратын REST.
Агрегаттарда k-анонимділіктің және min-group-sizin болмауы.
Нөлдік квоталар/лимиттер және ажыратылған кэш.
Нұсқалау/келісімшарттар жоқ - әрбір өзгерісте клиенттерді «сындырамыз».
Барлық елдер/брендтер үшін бір интерфейс - өңірлік ережелердің игноры.
19) Енгізу жол картасы
0-30 күн (MVP)
1. Data Products каталогы (метриктер/кесінділер) және олардың OpenAPI/GraphQL келісімшарттары.
2. RLS/CLS бар SQL-шлюз, агрегаттардың k-анонимділігі, базалық квоталар.
3. Бір REST-метрикалық эндпоинт ('/payments/metrics ') + кэш + пулы' bi _ hot/adhoc '.
4. gRPC Feature Store: 10-20 негізгі онлайн-фич (p95 ≤ 80 мс) оқу.
30-90 күн
1. PSP оқиғаларына/ойын оқиғаларына арналған стрим-интерфейстер (Kafka/Webhook).
2. Arrow/Parquet presigned-URL-мен түсіру; snapshot каталогы.
3. Айқын саясаткерлері бар Federation-шлюзі (Trino/Presto).
4. Бақылануы: дашборд SLI/SLO, құн/жасырындылық/PII-ге арналған алерттар.
3-6 ай
1. SDK (TypeScript/Python/Go) ретраларымен/теңсіздігімен/квоталарымен.
2. Өнімдер мен серіктестерге арналған жұқа GraphQL кесінділері.
3. gRPC/FS кеңейту, оффлайн онлайн келісу; shadow → canary релиздері.
4. Құпиялылық аудиті/DSAR; қолжетімділік бойынша комплаенс есептері.
20) RACI
Data Platform (R): шлюздер, кэш, квоталар, федерация, бақылау.
Data Governance (A/R): келісімшарттар, нұсқалар, құпиялылық/k-анонимділік.
Domain Owners (R): өріс семантикасы, бизнес-инварианттар, Data Products.
Security/DPO (A/R): AuthN/Z, геоқшаулау, DSAR/Legal Hold.
SRE/Observability (C): SLO/SLI, алерта, capacity.
Analytics/BI/DS (C): нысандарға/агрегаттарға қойылатын талаптар, SDK.
21) Байланысты бөлімдер
Аналитикалық қоймаларды индекстеу, Аналитикалық сұрау салуларды оңтайландыру, Деректер схемалары және олардың эволюциясы, Деректерді валидациялау, DataOps-практикасы, API аналитикасы және метрикасы, Feature Store, Деректер қауіпсіздігі және шифрлау, Қолжетімділікті бақылау, Деректерді сақтау саясаты.
Жиынтығы
Деректерге қолжетімділіктің дұрыс жобаланған интерфейстері сақтау орындары мен ағындарды сенімді «өнімге» айналдырады: болжамды SLA, бақыланатын құн, құпиялылықты сақтау және өнім командалары, аналитика, комплаенс және әріптестер үшін бірыңғай тіл. iGaming-те бұл PSP-тің ақауларын жылдам ұстауды, ойыншылардың мінез-құлқын түсінуді және реттеушілердің талаптарын орындауды білдіреді - қолмен түсірусіз және түнгі көші-қонсыз.