Verilənlərə giriş interfeysləri
1) Nə üçün düşünülmüş interfeys
Sürət və proqnozlaşdırılabilirlik: biznes metriklər və hesabatlar «əl boşaltmaları» olmadan SLA-ya uyğundur.
Təhlükəsizlik və məxfilik: nəzarət altında PII/biometrik, k-anonimlik, geo-sərhədlər.
Çeviklik: müxtəlif müştərilər (BI, xidmətlər, tərəfdaşlar, DS/ML) tam olaraq ehtiyaclarını əldə edirlər.
Təkrar istifadə: müqavilələr və versiyalarla «məhsul kimi məlumatlar».
2) Interfeys xəritəsi (nə zaman)
SQL/ANSI + vendor dialektləri: interaktiv analitika, BI, ad-hoc.
REST JSON: sabit aqreqatlar və əməliyyat məlumatları, tərəfdaşlarla inteqrasiya.
GraphQL: çevik «seçici» oxu və qraf naviqasiya (ölçü/faktlar).
gRPC (protobuf): aşağı gizli online serving (Feature Store, scoring).
Arrow Flight/Parquet over HTTP/S3-presigned: DS/ML üçün sürətli sütun «damps».
OData: enterprise alətləri, model «xidmət kimi cədvəl».
Streams (Kafka/Pulsar) + CDC/Webhooks: real vaxt hadisələri, reaktiv inteqrasiya.
Federation (Trino/Presto): bir çox mənbələrə vahid giriş nöqtəsi.
Qayda: aqreqatlar və sabit kəsiklər → REST/MV, zəngin ixtiyari sorğular → SQL, aşağı gecikmə/online ficks → gRPC, çevik cavab forması → GraphQL, kütləvi ikili mübadilə → Arrow/Parquet.
3) Müqavilələr və versiyalar (semver)
`MAJOR. MINOR. Hər bir API/sxem/hadisə üçün PATCH '.
MAJOR: Uyğunsuz dəyişikliklər (yeni yol/topik/cədvəl).
MINOR: Uyğun sahə/arqument əlavələri.
PATCH: təsvirlər/limitlər düzəlişləri.
Müqavilələr qeyd edir: sxem, filtrlər, limitlər, gizlilik, 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) Analitikaya giriş (SQL və Federasiya)
Rollar/maskalarla SQL-şlyuz (row/column-level security).
BI altında Viuhi/proyeksiyalar: sabit adlar və semantika; heavy-sorğular əvvəlcədən birləşməyə gedir.
Federation (Trino/Presto): vahid giriş nöqtəsi, lakin siyasətçilərlə: hansı kataloqlar və hansı xüsusiyyətlər mövcuddur.
Lakehouse (Iceberg/Delta/Hudi): SQL/REST vasitəsilə time-travel, snapshot-ekstraksiya.
Квоты: scanned bytes/query, concurrency, wall-time.
5) GraphQL (çevik forma)
Müştəriyə istədiyiniz sahəni toplamağa icazə veririk, lakin hazırlanmış çubuqlar/proyeksiyalar üzərində, dərinlik/sümük limitləri ilə icra edirik.
graphql type Query {
payments(
brand: String!, country: String, from: DateTime!, to: DateTime!,
first: Int = 200, after: String
): PaymentConnection
}Siyasətlər: depth ≤ 5, total nodes ≤ 5k, sətirlərdə ixtiyari regex/like qadağan; tez-tez sorğular.
6) gRPC/Feature Store (aşağı gecikmə)
Anti-frod/tövsiyələr/RG üçün onlayn Ficks.
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; }Tələblər: p95 ≤ 50-100 ms, dəqiq oflayn uyğunluq online, TTL fich, LRU cache, idempotency və mTLS.
7) Axınlar və CDC
Domen hadisələri: 'payments. deposit_accepted`, `game. round_finished`.
CDC (ALTP-dən): near-real-time status/limitlərin dəyişdirilməsi.
Tərəfdaşlar üçün Webhooks: aqreqatlara abunə (məsələn, «PSP uğursuzluqları> eşik»).
Retraj/təsdiq siyasəti: kritik üçün exactly-once, monitorinq üçün at-least-once.
8) Göllər və böyük nümunələr
DS/ML-də sürətli sütun boşaltmaları üçün Arrow Flight.
Parquet/Feather-də Presigned-URL, qısa TTL və imzalanmış sorğu ilə.
Chunked transfer və fayl ölçüsü nəzarət; download jurnalı (WORM-audit).
9) Filtrlər, paginasiya, çeşidləmə
Böyük dəstlər üçün OFFSET əvəzinə Keyset pagination (kursor).
Filtrlər: sahələrə, növlərə və operatorlara görə whitelists ('=, IN, BETWEEN, prefix').
Sıralama: sahələrin məhdud siyahısı, default sifariş.
Partial response: 'fields = brand, country, amount' yükü azaldır.
http
GET /v2/game-rounds? brand=X&from=...&to=...&first=1000&after=eyJkYXRlIjoi...10) Caching və dəyəri
Result cache şablon sorğular üçün, təravət token (snapshot id) əlil.
Edge-cache/CDN ictimai/yarı ictimai aqreqatlar üçün (PII olmadan).
Budget parametrləri: scanned bytes limiti, sorğu vaxtı, rps/dəq kvotaları.
Hovuzların prioritetləşdirilməsi: 'bi _ hot', 'adhoc', 'partner _ api'.
11) Təhlükəsizlik və məxfilik
AuthN: OAuth2/OIDC (xidmətlər üçün client credentials, insanlar üçün PKCE).
AuthZ: RBAC + ABAC (atributlar: marka, ölkə, lisenziya, rol).
mTLS xidmətlər arasında, TLS 1. 2 + xaricə.
PII-gigiyena: API qatında maskalar/tokenizasiya, sütun maskaları, aqreqatların k-anonimliyi.
Geo/tenant-izolyasiya: lisenziya bölgəsinə sorğuların marşrutlaşdırılması; marka/region şifrələmə açarları.
DSAR/Legal Hold: subyektin token axtarış, dəsti dondurmaq üçün sirləri.
12) Müşahidə (SLI/SLO) və müdafiə
SLI: p50/p95/p99 lat, error-rate, rps, bytes scanned, cache hit, kvotalar/limitlər, maskalı dinamiklərin payı, avtorizasiya uğursuzluqlarının payı.
SLO: p95 gecikmə, məlumatların təzəliyi,% uğurlu sorğular, cavablarda min-qrup-size.
Alertlər: scanned bytes böyüməsi, hit-rate düşməsi, 429/5xx sıçrayışı, PII girişinə cəhd, kursor sızması.
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 və sıxılma
JSON uyğunluq üçün; CSV - yalnız kiçik və sadə ixrac üçün.
Parquet/Arrow - böyük boşaltmalar üçün default.
Compression: gzip/zstd ('Accept-Encoding' vasitəsilə danışıqlar).
Content-negotiation: `Accept: application/x-parquet`.
14) API kimi metriklər (Analytics/OLAP-şlyuz)
Üst səviyyəli metriklər: GGR/NET, CR, saxlama, RG hadisələri - 'brand, country, window, group _ by' parametrləri olan resurslar kimi.
Approx (HLL/TDigest) для distinct/percentiles.
Açarlı cache: '(metric, params, snapshot_id)'.
15) iGaming xüsusiyyətləri - hazır end-pointlər
'GET/v2/payments/metrics' - 7/30d pəncərələri ilə PSP/ölkə/marka üzrə uğursuzluqlar/yüksəlişlər.
'GET/v2/game-rounds/metrics' - top oyunlar/provayderlər, p95 müddət, RTP pəncərələri.
'GET/v2/rg/cases' - aktiv məhdudiyyətlər/özünü istisna (k-anonim aqreqatlar).
'POST/v1/features: get' (gRPC) - frod/rekommender skorinqi üçün onlayn fişlər.
'POST/v1/webhooks/psp-alerts' - bildirişlər «decline rate> eşik».
16) Müqavilə nümunələri
GraphQL sorğu nazik kəsmə: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) Yeni interfeysin dərc edilməsi prosesi
1. ADR: problem/dəyər/müştərilər/təhlükəsizlik/dəyər.
2. Müqavilə: sxem, filtrlər, limitlər, gizlilik, SLO, versiyalar.
3. Yükləmə modelləşdirilməsi: top-N sorğular, p95/tarama baytları, dəyəri.
4. Validation/cache/kvota: default aktiv.
5. Sənədləşmə və SDK: nümunələr, limitlər, səhvlər, retralar, idempotentlik.
6. Canary:% müştərilər, reqressiya testləri, risklər.
7. GA: Data Products kataloqunda versiya, effektlər hesabatı.
18) Anti-nümunələr
Bütün «xam» SQL açın - PII sızması, gözlənilməz qiymət.
OFFSET-paginasiya və 'SELECT' - gizlilik və hesaba görə ağrı.
GraphQL heç bir məhdudiyyət dərinlik/dəyəri.
Çox çox sütun qaytaran REST 'fields =...'.
aqreqatlarda k-anonimlik və min-group-size olmaması.
Sıfır kvota/limitlər və qapalı cache.
Heç bir versiya/müqavilə yoxdur - hər dəyişiklik zamanı müştəriləri «sındırırıq».
Bütün ölkələr/markalar üçün eyni interfeys regional qaydaların icraçısıdır.
19) Tətbiqi yol xəritəsi
0-30 gün (MVP)
1. Data Products kataloqu (metriklər/dilimlər) və onların OpenAPI/GraphQL müqavilələri.
2. RLS/CLS ilə SQL-şlyuz, k-anonimlik aqreqatları, əsas kvotalar.
3. Bir REST metrik end point ('/payments/metrics ') + cache + hovuzlar' bi _ hot/adhoc '.
4. gRPC Feature Store: oxu 10-20 əsas online fich (p95 ≤ 80 ms).
30-90 gün
1. PSP alertləri/oyun hadisələri üçün axın interfeysləri (Kafka/Webhook).
2. Arrow/Parquet presigned-URL ilə boşaltma; snapshot kataloqu.
3. Federation-şlyuz (Trino/Presto) açıq siyasətçilərlə.
4. Müşahidə: SLI/SLO dashboard, dəyər/gecikmə/PII üçün alert.
3-6 ay
1. Retras/idempotent/kvotalarla SDK (TypeScript/Python/Go).
2. Məhsullar və tərəfdaşlar üçün nazik GraphQL dilimləri.
3. gRPC/FS genişləndirilməsi, online oflayn koordinasiya; shadow → canary relizlər.
4. Gizlilik auditi/DSAR; giriş üzrə komplayens hesabatları.
20) RACI
Data Platform (R): şlyuzlar, cache, kvotalar, federasiya, müşahidə.
Data Governance (A/R): müqavilələr, versiyalar, gizlilik/k-anonimlik.
Domain Owners (R): Sahə semantikası, biznes invariantları, Data Products.
Security/DPO (A/R): AuthN/Z, geo-izolyasiya, DSAR/Legal Hold.
SRE/Observability (C): SLO/SLI, alert, capacity.
Analytics/BI/DS (C): forma/aqreqat tələbləri, SDK.
21) Əlaqəli bölmələr
Analitik anbarların indeksləşdirilməsi, Analitik sorğuların optimallaşdırılması, Verilənlərin sxemləri və onların təkamülü, Verilənlərin validasiyası, DataOps təcrübələri, API analitikası və metrikası, Feature Store, Verilənlərin təhlükəsizliyi və şifrələmə, Giriş nəzarəti, Verilənlərin saxlanması siyasəti.
Yekun
Düzgün dizayn edilmiş məlumat giriş interfeysləri anbarları və axınları etibarlı bir «məhsula» çevirir: proqnozlaşdırıla bilən SLA, nəzarət olunan dəyər, məxfiliyə riayət və məhsul komandaları, analitiklər, uyğunluq və tərəfdaşlar üçün vahid dil. iGaming-də bu PSP uğursuzluqlarını daha sürətli tutmaq, oyunçuların davranışlarını başa düşmək və tənzimləyicilərin tələblərini yerinə yetirmək deməkdir - əl yükləmələri və gecə miqrasiyaları olmadan.