رابط دسترسی به داده ها

1) چرا یک رابط متفکر

سرعت و قابلیت پیش بینی: معیارهای تجاری و گزارش ها در SLA ها، بدون «بارگذاری دستی» قرار می گیرند.
امنیت و حریم خصوصی: PII/بیومتریک تحت کنترل، k-ناشناس بودن، مرزهای جغرافیایی.
انعطاف پذیری: مشتریان مختلف (BI، خدمات، شرکا، DS/ML) دقیقا همان چیزی را که نیاز دارند دریافت می کنند.
استفاده مجدد از «داده ها به عنوان یک محصول» با قراردادها و نسخه ها.

2) نقشه رابط (چه زمانی)

SQL/ANSI + گویش های فروشنده: تجزیه و تحلیل تعاملی، BI، ad-hoc.
REST JSON: aggregates پایدار و داده های عملیاتی، ادغام با شرکا.
GraphQL: انعطاف پذیر «انتخابی» خواندن و ناوبری گراف (ابعاد/حقایق).
gRPC (protobuf): تاخیر کم گشت و گذار آنلاین (فروشگاه ویژگی، به ثمر رساند).
فلش پرواز/پارکت بیش از HTTP/S3-presigned: تخلیه ستون سریع برای DS/ML.
OData: ابزارهای سازمانی، مدل جدول به عنوان یک سرویس.
جریانها (Kafka/Pulsar) + CDC/Webhooks: رویدادهای زمان واقعی، ادغام واکنشی.
فدراسیون (Trino/Presto): نقطه ورود به چندین منبع.

Rule: aggregates and stable slices → REST/MV, rich arbitary queries → SQL, latency low/online features → gRPC, flexible response form → GraphQL, mass binary exchange → Arrow/Parquet.

3) قراردادها و نسخه ها (semver)

سرگرد. جزئی است. PATCH برای هر API/طرح/رویداد.
MAJOR: تغییرات ناسازگار (مسیر جدید/موضوع/جدول).
جزئی: زمینه سازگار/استدلال اضافه شده است.
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 با نقشها/ماسکها (امنیت در سطح ردیف/ستون).
پیش بینی های Blizzards/BI: نام های پایدار و معانی ؛ درخواست های سنگین به preaggregation می روند.
فدراسیون (Trino/Presto): نقطه ورود واحد، اما با سیاست ها: چه دایرکتوری ها و چه ویژگی هایی در دسترس هستند.
Lakehouse (Iceberg/Delta/Hudi): سفر در زمان، بازیابی عکس فوری از طریق SQL/REST.
Квоты: بایت اسکن/پرس و جو، همزمانی، زمان دیوار.

5) GraphQL (شکل انعطاف پذیر)

ما مشتری را برای جمع آوری زمینه مورد نظر، اما بیش از کولاک/پیش بینی های آماده شده، با محدودیت عمق/استخوان اجرا می کنیم.

graphql type Query {
payments(
brand: String!, country: String, from: DateTime!, to: DateTime!,
first: Int = 200, after: String
): PaymentConnection
}

سیاست ها: عمق ≤ 5، گره کل ≤ 5k، ممنوع regex خودسرانه/مانند خطوط ؛ ما درخواست های مکرر را پنهان می کنیم.

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 ms، سازگاری دقیق offlayn↔onlayn، ویژگی TTL، حافظه پنهان LRU، توانایی و mTLS.

7) جریان و CDC

رویدادهای دامنه: "پرداخت ها. deposit_accepted'، بازی. round_finished' است.
CDC (از OLTP): تغییرات وضعیت/محدودیت در زمان واقعی.
Webhooks برای شرکای: اشتراک به aggregates (به عنوان مثال،. «شکست PSP> آستانه»).
سیاست های بازپرداخت/تأیید: دقیقا یک بار برای بحرانی، حداقل یک بار برای نظارت.

8) دریاچه ها و نمونه های بزرگ

فلش پرواز برای تخلیه سریع ستون به DS/ML.
Signed-URL به Parquet/Feather، با TTL کوتاه و درخواست امضا شده.
انتقال chunked و کنترل اندازه فایل ؛ ورود به سیستم دانلود (حسابرسی WORM).

9) فیلترها، صفحه بندی، مرتب سازی

صفحهبندی کلید) مکاننما (به جای OFFSET برای مجموعههای بزرگ.
فیلترها: لیست های سفید بر اساس فیلدها، انواع و اپراتورها ('=, IN, BETWEEN, prefix').
مرتب سازی: لیست محدودی از زمینه ها، سفارش پیش فرض.
پاسخ جزئی: «fields = نام تجاری، کشور، مقدار» بار را کاهش می دهد.

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

10) ذخیره سازی و هزینه

کش نتیجه برای درخواست قالب, غیر فعال شده توسط شناسه عکس فوری.
کش لبه/CDN برای aggregates عمومی/نیمه عمومی (بدون PII).
پارامترهای بودجه: محدودیت بایت اسکن شده، درخواست اتمام وقت، سهمیه rps/min.
اولویت بندی استخر: 'bi _ hot', 'adhoc', 'partner _ api'.

11) امنیت و حریم خصوصی

AuthN: OAuth2/OIDC (اعتبار مشتری برای خدمات، PKCE برای افراد).
AuthZ: RBAC + ABAC (ویژگی ها: نام تجاری، کشور، مجوز، نقش).
mTLS بین خدمات، TLS 1. 2 + خارج شود.
بهداشت PII: ماسک/نشانه گذاری در لایه API، ماسک ستون، K-ناشناس بودن aggregates.
Geo/tenant-isolation: درخواست مسیریابی به منطقه مجوز ؛ کلید های رمزگذاری در هر نام تجاری/منطقه.
DSAR/Legal Hold: جستجو بر اساس نشانه موضوع، اسرار برای مجموعه های انجماد.

12) قابلیت مشاهده (SLI/SLO) و حفاظت

SLI: p50/p95/p99 lat، نرخ خطا، rps، بایت اسکن شده، ضربه کش، سهمیه/محدودیت ها، سهم ستون های ماسک شده، سهم خرابی های مجوز.
SLO: تاخیر p95، تازه بودن داده ها، درخواست های موفقیت آمیز٪، اندازه حداقل گروه در پاسخ ها.
هشدارها: افزایش بایت های اسکن شده، سقوط نرخ ضربه، اسپایک 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 - به طور پیش فرض برای آپلود های بزرگ.
فشرده سازی: gzip/zstd (مذاکره از طریق 'پذیرش رمزگذاری').
مذاکره محتوا: 'Accept: application/x-parquet'.

14) متریک به عنوان API (تجزیه و تحلیل/دروازه OLAP)

معیارهای سطح بالا: GGR/NET، CR، نگه دارید، حوادث RG - به عنوان منابع با پارامترهای «نام تجاری، کشور، پنجره، گروه _ توسط».
تقریبا (HLL/TDigest) متمایز/درصد для.
کش کلیدی: '(متریک، پارامز، snapshot_id)'.

15) ویژگی iGaming - نقاط پایانی آماده

'GET/v2/payments/metrics' - خرابی/به روز رسانی توسط PSP/کشور/نام تجاری با پنجره های 7/30d.
'GET/v2/game-round/metrics' - بازی های برتر/ارائه دهندگان، مدت زمان P95، پنجره های RTP.
'GET/v2/rg/cases' - محدودیت های فعال/خود حذفی (تجمع k-ناشناس).
'POST/v1/features: get' (gRPC) - ویژگی های آنلاین برای به ثمر رساندن تقلب/توصیه.
'POST/v1/webhooks/psp-alerts' - اطلاعیه ها «میزان کاهش> آستانه».

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. مدل سازی بار: درخواست های بالا N، بایت p95/اسکن، هزینه.
4. اعتبار سنجی/کش/سهمیه: فعال به طور پیش فرض.
5. مستندات و SDK: نمونه ها، محدودیت ها، خطاها، بازپرداخت، idempotency.
6. قناری:٪ از مشتریان، آزمون رگرسیون، هشدار.
7. GA: داده ها نسخه کاتالوگ محصولات، گزارش اثرات.

18) ضد الگوهای

SQL «خام» را برای همه باز کنید - نشت PII، هزینه غیر قابل پیش بینی.
صفحه بندی افست و 'انتخاب' - درد با تاخیر و شمارش.
GraphQL بدون محدودیت عمق/هزینه.
REST، که ستون های زیادی را بدون «fields =...» باز می گرداند.
عدم وجود k-anonymity و min-group-size در aggregates.
صفر سهمیه/محدودیت ها و کش غیر فعال.
بدون نسخه/قرارداد - ما «شکستن» مشتریان با هر تغییر.
رابط یکسان برای همه کشورها/مارک ها نادیده گرفتن قوانین منطقه ای است.

19) پیاده سازی نقشه راه

0-30 روز (MVP)

1. کاتالوگ محصولات داده (متریک/برش) و قراردادهای OpenAPI/GraphQL آنها.
2. دروازه SQL با RLS/CLS، k-ناشناس بودن aggregates، سهمیه های اساسی.
3. یک نقطه پایانی REST-metric ('/payments/metrics ') + cache + pools' bi _ hot/adhoc '.
4. فروشگاه ویژگی های gRPC: خواندن 10-20 ویژگی های کلیدی آنلاین (p95 ≤ 80 میلی ثانیه).

30-90 روز

1. رابط جریان (کافکا/Webhook) برای هشدار PSP/رویدادهای بازی.

2. آپلود فلش/پارکت از URL ارائه شده ؛ کاتالوگ عکس فوری

3. دروازه فدراسیون (Trino/Presto) با سیاست های صریح.
4. قابلیت مشاهده: داشبورد SLI/SLO، هشدار در مورد هزینه/تاخیر/PII.

3-6 ماه

1. SDK (TypeScript/Python/Go) با retrays/idempotency/quotations.
2. برش های نازک GraphQL برای محصولات و شرکا.
3. gRPC/FS فرمت، مذاکره offlayn↔onlayn ؛ سایه → آزادی قناری.

4. ممیزی حریم خصوصی/DSAR ؛ دسترسی به گزارش های انطباق

20) RACI

پلت فرم داده (R): دروازه، حافظه پنهان، سهمیه، فدراسیون، قابلیت مشاهده.
حاکمیت داده (A/R): قراردادها، نسخه ها، حریم خصوصی/K-ناشناس بودن.
صاحبان دامنه (R): معناشناسی زمینه، ناورداهای تجاری، محصولات داده.
امنیت/DPO (A/R): AuthN/Z، geo-isolation، DSAR/Legal Hold.
SRE/قابلیت مشاهده (C): SLO/SLI، هشدار، ظرفیت.
تجزیه و تحلیل/BI/DS (C): مورد نیاز برای فرم/aggregates، SDK.

21) بخش های مرتبط

نمایه سازی ذخیره سازی تحلیلی، بهینه سازی پرس و جو تحلیلی، طرح های داده ها و تکامل، اعتبار سنجی داده ها، DataOps Practices، Analytics و Metrics API ها، فروشگاه ویژگی، امنیت داده ها و رمزگذاری، کنترل دسترسی، سیاست های نگهداری داده ها.

مجموع

رابط های دسترسی به داده ها که به درستی طراحی شده اند، ذخیره سازی و جریان را به یک «محصول» قابل اعتماد تبدیل می کنند: SLA قابل پیش بینی، هزینه کنترل شده، رعایت حریم خصوصی و یک زبان واحد برای تیم های محصول، تجزیه و تحلیل، انطباق و شرکا. در iGaming، این بدان معنی است که گرفتن PSP سقوط سریع تر، درک رفتار بازیکن و رعایت الزامات قانونی - بدون آپلود دستی و مهاجرت شبانه.