数据访问接口

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故障，了解玩家的行为并满足监管机构的要求-无需手动卸载和夜间迁移。