數據訪問接口

1）為什麼要有周到的界面

速度和可預測性：業務指標和報告堆疊在SLA中，沒有「手動卸載」。
安全和隱私：PII/生物識別控制，k匿名，地理邊界。
靈活性：不同的客戶（BI、服務、合作夥伴、DS/ML）正好得到他們需要的東西。
重復使用：具有合同和版本的「數據作為產品」。

2）接口映射（何時）

SQL/ANSI+供應商方言：交互式分析，BI，ad-hoc。
REST JSON：穩定的聚合和操作數據,與合作夥伴集成。
GraphQL：靈活的「選擇性」讀取和導航圖（測量/事實）。
gRPC （protobuf）：在線伺服器的低潛伏率（功能商店,評分）。
Arrow Flight/Parquet over HTTP/S3-presigned：DS/ML的快速柱「轉儲」。
OData：企業工具，表即服務模型。
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下的vyuhi/投影：穩定的名稱和語義；重量級請求用於預聚合。
Federation （Trino/Presto）：單一入口點,但具有以下策略：哪些目錄和哪些功能可用。
湖房（Iceberg/Delta/Hudi）：通過SQL/REST進行時間旅行，快照提取。

Квоты: 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/功能商店（低潛伏期）

用於反親友計分/推薦/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毫秒，精確的offlayn↔onlayn一致性，TTL信息，LRU緩存，idempotency和mTLS。

7）流和CDC

域事件： 'payments。deposit_accepted`, `game.round_finished`.

CDC（來自OLTP）：近實時的狀態/限制變化。
合作夥伴的Webhooks：訂閱單元（例如「PSP錯誤>閾值」）。
Retrais/確認策略： exactly-once用於關鍵,at-least-once用於監控。

8）湖泊和主要樣本

Arrow Flight用於DS/ML中的快速柱式卸載。
Parquet/Feather上的Presigned-URL，帶有短的TTL和簽名的查詢。
轉接和文件大小控制；下載日誌（WORM審核）。

9）過濾器,分割,分類

對於大型集合，Keyset分離（遊標）而不是OFFSET。
過濾器：跨領域，類型和語句（'=，IN，BETWEEN，prefix'）的白人主義者。
排序：字段限制列表，默認順序。
部分響應：'fields=品牌，國家，amount'減少了有效載荷。

http
GET /v2/game-rounds? brand=X&from=...&to=...&first=1000&after=eyJkYXRlIjoi...

10）緩存和成本

結果教程用於模式查詢，我們通過新鮮令牌（snapshot id）致殘。
用於公共/半公共單元（無PII）的邊緣緩存/CDN。
Budget參數：掃描字節限制，請求定時器，rps/min配額。
池優先級為'bi_hot'、'adhoc'、'partner_api'。

11）安全和隱私

AuthN：OAuth2/OIDC（服務客戶端，人員PKCE）。
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。
Alerts：掃描字節上升、命中率下降、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: 256

13）格式和壓縮

JSON兼容性；CSV僅適用於小型和簡單的出口。
Parquet/Arrow-大型卸載的默認值。
Compression：gzip/zstd（通過「接受編碼」進行談判）。

Content-negotiation: `Accept: application/x-parquet`.

14）作為API的度量（Analytics/OLAP網關）

頂級度量標準：GGR/NET、CR、保留、RG事件-作為具有「品牌、鄉村、窗口、組」參數的資源。

Approx (HLL/TDigest) для distinct/percentiles.

鍵緩存：「（metric，params，snapshot_id）」。

15） iGaming特點-現成的端點

「GET/v2/payments/metrics」-根據PSP/國家/品牌使用 7/30d窗口的故障/應用程序。
「GET/v2/game-rounds/metrics」是頂級遊戲/提供商，p95持續時間，RTP窗口。
「GET/v2/rg/cases」-主動限制/自我體驗（k匿名聚合）。
「POST/v1/功能：get」（gRPC）是用於評分Frod/Recommender的在線遊戲。
「POST/v1/webhooks/psp-alerts」-「decline rate>閾值」通知。

16）合同示例

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=arrow

17）發布新界面的過程

1.ADR：問題/價值/客戶/安全/成本。
2.合同：電路，過濾器，限制，隱私，SLO，版本。
3.負載仿真：top-N查詢,p95/scan字節,成本。
4.驗證/kesh/配額：默認啟用。
5.文檔和SDK：示例，限制，錯誤，撤回，等效性。
6.金絲雀：客戶百分比，反向測試，Alerta。
7.GA：數據產品目錄中的版本,效果報告。

18）反模式

向所有人打開「原始」SQL-PII泄漏,成本不可預測。
OFFSET分期和「SELECT」是潛伏期和計數的痛苦。
GraphQL沒有深度/成本限制。
REST，返回的揚聲器太多，沒有「字段=……」。
在聚合中不存在k匿名和min-group-size。
零配額/限制和禁用緩存。
沒有version/合同-每次更改時「打破」客戶。
所有國家/品牌的相同界面忽略了區域規則。

19）實施路線圖

0-30天（MVP）

1.數據產品目錄（度量/切片）及其OpenAPI/GraphQL合同。
2.具有RLS/CLS的SQL網關，聚合的k匿名性，基本配額。
3.一個REST度量端口（'/payments/metrics'）+緩存+池'bi_hot/adhoc'。
4.gRPC Feature Store：閱讀10-20個關鍵在線信息（p95 ≤ 80 ms）。

30-90天

1.PSP Alert/遊戲事件的流接口（Kafka/Webhook）。
2.Arrow/Parquet從presigned-URL上載；snapshot目錄。
3.具有明確策略的聯邦網關（Trino/Presto）。
4.可觀察性：SLI/SLO dashboard，價值/潛在性/PII的差分。

3-6個月

1.SDK（TypeScript/Python/Go）具有撤回/等效性/配額。
2.適用於產品和合作夥伴的薄GraphQL切片。
3.擴展gRPC/FS，協調offlayn↔onlayn；shadow→canary發行版。
4.隱私審計/DSAR；可用性合規報告。

20) RACI

數據平臺（R）：網關、緩存、配額、聯合、可觀察性。
數據管理（A/R）：合同，版本，隱私/k匿名。
域所有者（R）：字段語義，業務不變性，數據產品。
安全/DPO （A/R）： AuthN/Z, geo隔離,DSAR/Legal Hold。
SRE/觀察力（C）：SLO/SLI，Alerta，能力。
分析/BI/DS （C）：表格/聚合要求,SDK。

21）相關部分

分析存儲索引、優化分析查詢、數據模式及其演變、數據驗證、DataOps實踐、API分析和指標、功能存儲、數據安全和加密、訪問控制、存儲策略。

底線

正確設計的數據訪問界面將存儲和流轉換為可靠的「產品」：可預測的SLA，可控制的成本，隱私合規性以及針對產品團隊，分析，合並和合作夥伴的統一語言。在iGaming中，這意味著更快地捕獲PSP故障，了解玩家的行為並滿足監管機構的要求-無需手動卸載和夜間遷移。