Interfacce di accesso ai dati
1) Perché un'interfaccia elaborata
Velocità e prevedibilità: le metriche aziendali e i report vengono inseriti in SLA, senza scaricare manualmente.
Sicurezza e privacy: PII/biometria sotto controllo, k-anonimato, geo-confini.
Flessibilità: i clienti diversi (BI, servizi, partner, DS/ML) ottengono esattamente ciò di cui hanno bisogno.
Riutilizzo: «dati come prodotto» con contratti e versioni.
2) Scheda interfaccia (quando cosa)
SQL/ANSI + dialetti venditori: analisi interattiva, BI, ad hoc.
RESTJSON: aggregazioni e dati operativi stabili, integrazioni con i partner.
GraphQL - Lettura flessibile «selettiva» e grafica di navigazione (misurazioni/fatti).
gRPC (protobuf) - Bassa latitanza online-cerving (Feature Store).
Arrow Flight/Parket over HTTP/S3-presented - Dump a colonne veloci per DS/ML.
Utensili enterprise, modello di tabella come servizio.
Streams (Kafka/Pulsar) + CDC/Webhooks: eventi in tempo reale, integrazioni reattive.
Federazione (Trino/Preto) - Un unico punto di accesso a più origini.
Regola: aggregazioni e tagli stabili /MV, ricche richieste arbitrarie di SQL, bassa latitanza/ on-line, una forma flessibile di risposta al , uno scambio binario di massa su Arrow/Parket.
3) Contratti e versioni (semver)
`MAJOR. MINOR. PATCH'per ogni API/schema/evento.
MAGGIORE - Modifiche incompatibili (nuovo percorso/top/tabella).
MINOR - Aggiungi campi o argomenti compatibili.
PATCH - Modifica descrizioni/limiti.
I contratti registrano schemi, filtri, limiti, privacy, 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) Accesso all'analista (SQL e federazione)
Gateway SQL con ruoli/maschere (row/column-level security).
I nomi stabili e la semantica; Le query heavy vengono inviate in pre-attività.
Federazione (Trino/Preto) - Un unico punto di accesso, ma con regole: quali directory e quali funzioni sono disponibili.
Lakehouse (Iceberg/Delta/Hudi): time-travel, recupero snapshot tramite SQL/REST.
Квоты: scanned bytes/query, concurrency, wall-time.
5) GraphQL (flessibile)
Diamo al cliente il campo giusto, ma eseguiamo sopra le proiezioni preparate, con limiti di profondità/ossa.
graphql type Query {
payments(
brand: String!, country: String, from: DateTime!, to: DateTime!,
first: Int = 200, after: String
): PaymentConnection
}Policy: depth 5, total nodes n' 5k, vietare regex/like casuali a righe; Chiariamo frequenti richieste.
6) gRPC/Feature Store (bassa latitudine)
Fici online per l'antifrode/raccomandazioni/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; }Requisiti: p95, 50-100 ms, coerenza esatta del , TTL Fich, cache LRU, idempotency e .
7) Flussi e CDC
Eventi di dominio: 'payments. deposit_accepted`, `game. round_finished`.
CDC (da OLTP) - Consente di modificare gli stati/limiti in near-real-time.
Webhooks per i partner: sottoscrizione di aggregazioni (ad esempio, guasti PSP> soglia).
Criteri di rilascio/conferma: exactly-once per critici, at-least-once per il monitoraggio.
8) Laghi e grandi campionamenti
Arrow Flight per scaricare rapidamente le colonne in DS/ML.
Presigned-URL su Parket/Feather, con TTL breve e richiesta firmata.
Chunked transfer e controllo delle dimensioni del file Registro download (WORM).
9) Filtri, paginazioni, ordinamenti
Paginazione Keyset (cursore) invece di OFFSET per set di grandi dimensioni.
Filtri: whitelists per campi, tipi e operatori ('=, IN, BETWEEN, prefix').
Ordinamento: elenco limitato dei campi, default ordine.
Partial response: 'fields = brand, country, amount', riduce il carico utile.
http
GET /v2/game-rounds? brand=X&from=...&to=...&first=1000&after=eyJkYXRlIjoi...10) Cache e costo
Result cache per le richieste di modello, invalidante per il tocco di freschezza (snapshot id).
Edge cache/CDN per unità pubbliche/semideserte (senza PII).
Opzioni budget: limite di scanned byties, timeout della query, quote rps/min
Priorità dei pool: «bi _ hot», «adhoc», «partner _ api».
11) Sicurezza e privacy
AuthN OAuth2/OIDC (client credentials per servizi, PKCE per persone).
AuthZ RBAC + ABAC (attributi: marchio, paese, licenza, ruolo).
mTLS tra i servizi, TLS 1. 2 + fuori.
Igiene PII: maschere/tokenizzazione su livello API, maschere invertebrate, k-anonimato apparecchiature.
Isolamento geo/tenant: routing delle richieste nella regione della licenza; chiavi di crittografia per marchio/regione.
DSAR/Legale Hold - Cerca il token del soggetto, i segreti per congelare i set.
12) Osservabilità (SLI/SLO) e protezione
SLI: p50/p95/p99 lat, error-rate, rps, byts scanned, cache hit, quote/limiti, percentuale di colonne mascherate, percentuale di errori di autorizzazione.
SLO: p95 latitanza, freschezza dei dati,% di richieste di successo, min-group-size sulle risposte.
Alert: crescita scanned byties, calo hit-rate, picco 429/5xx, tentativi di accesso al PII, fuoriuscite di cursori.
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) Formati e compressione
JSON per la compatibilità; CSV è solo per piccoli e semplici esportatori.
Parket/Arrow è l'impostazione predefinita per carichi di grandi dimensioni.
Compressione: gzip/zstd (negoziazione tramite «Accept-Encoding»).
Content-negotiation: `Accept: application/x-parquet`.
14) Metriche come API (Analytics/OLAP-gateway)
Metriche di livello superiore: GGR/NET, CR, ritenzione, incidenti RG - come risorse con i parametri «brand, country, window, group _ by».
Approx (HLL/TDigest) для distinct/percentiles.
Cache con chiave: '(metric, params, snapshot _ id)'.
15) Particolare iGaming - endpoint finiti
"GET/v2/payments/metrics' - guasti/apruzzi per PSP/paese/marchio con 7/30d finestre.
"GET/v2/game-rounds/metrics' - top game/provider, p95 durata, finestre RTP.
«GET/v2/rg/case» è un vincolo attivo/auto-esclusione (unità k-anonime).
'POST/v1/features: get '(gRPC) è un file online per la compilazione di from/ricommenditore.
«POST/v1/webhooks/psp-alerts» - notifiche «decline rate> soglia».
16) Esempi di contratti
GraphQL richiesta taglio sottile: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) Processo di pubblicazione di una nuova interfaccia
1. ADR: problema/valore/client/sicurezza/costo.
2. Contratto: schema, filtri, limiti, privacy, SLO, versioni.
3. Modellazione di carico: top-N query, p95/scan byte, costo.
4. Valuta/cash/quote - Abilita per impostazione predefinita.
5. Documentazione e SDK: esempi, limiti, errori, retrai, idempotenza.
6. Canary:% clienti, test di regress, alert.
7. GA: versione nella directory Data Products, report sugli effetti.
18) Anti-pattern
Aprire SQL crude a tutti - fughe PII, costo imprevedibile.
PAGINAZIONE OFFSET e «SELECT» - Dolore latitante e contabile.
GraphQL senza limiti di profondità/costo.
RESTA che restituisce troppe colonne senza «fields =...».
Assenza di k-anonimato e min-group-size nelle unità.
Zero quote/limiti e cache disattivata.
Niente versioning/contratti - «rompiamo» i clienti ogni volta che cambiano.
Stessa interfaccia per tutti i paesi/marchi - ignorare le regole regionali.
19) Road map di implementazione
0-30 giorni (MVP)
1. La directory di Data Products e i relativi contratti.
2. Gateway SQL con RLS/CLS, k-anonimato degli aggregati, quote di base.
3. Un REST endpoint ('/payments/metrics') + cache + pool'bi _ hot/adhoc '.
4. Feature Store: lettura di 10-20 file chiave online (p95-80 ms).
30-90 giorni
1. Interfacce strim (Kafka/Webhook) per gli eventi PSP/giochi.
2. Arrow/Parquet di caricamento da un URL presigned; il catalogo dei snapshot.
3. Gateway Trino/Preto con regole esplicite.
4. Osservabilità: dashboard SLI/SLO, alert per costo/latenza/PII.
3-6 mesi
1. SDK (TypeScript/Python/Go) con retrai/idipotenza/quote.
2. Sottili tagli GraphQL per prodotti e partner.
3. Allungamento della gRPC/FS, allineamento delle offlayn↔onlayn; shadow→canary i comunicati.
4. Controllo privacy/DSAR; Report della compilazione sulla disponibilità.
20) RACI
Data Platform (R) - gateway, cache, quote, federazione, osservabilità.
Data Governance (A/R) - Contratti, versioni, privacy/k-anonimato.
Domain Owners (R) - Semantica dei campi, invarianti aziendali, Data Products.
Sicurezza/DPO (A/R): AuthN/Z, isolamento geo, DSAR/Legale Hold.
SRE/Osservabilità (C): SLO/SLI, alert, capacity.
Analytics/BI/DS (C): requisiti di forma/aggregazione, SDK.
21) Partizioni correlate
Indicizzazione dello storage analitico, Ottimizzazione delle richieste analitiche, Schemi di dati e loro evoluzione, Convalida dei dati, Utilizzo delle applicazioni, Analisi e metriche API, Feature Store, Sicurezza dei dati e crittografia, Controllo degli accessi, Regole di storage.
Totale
Le interfacce di accesso correttamente progettate trasformano lo storage e i flussi in un prodotto affidabile: SLA prevedibile, costo controllato, privacy e un unico linguaggio per i team di prodotto, gli analisti, la compliance e i partner. In iGaming significa catturare più velocemente i guasti PSP, comprendere il comportamento dei giocatori e soddisfare i requisiti dei regolatori - senza scarichi manuali o migrazioni notturne.