واجهات الوصول إلى البيانات

1) لماذا واجهة مدروسة

السرعة والقدرة على التنبؤ: تتناسب مقاييس وتقارير الأعمال التجارية مع اتفاقات جنوب السودان، بدون «تحميلات يدوية».
الأمن والخصوصية: PII/biometrics تحت السيطرة، k-unhonity، geo-boundaries.
المرونة: يحصل العملاء المختلفون (BI، الخدمات، الشركاء، DS/ML) على ما يحتاجون إليه بالضبط.
إعادة استخدام «البيانات كمنتج» مع العقود والنسخ.

2) خريطة الواجهة (متى ماذا)

SQL/ANSI + لهجات البائع: تحليلات تفاعلية، BI، مخصصة.
REST JSON: مجاميع ثابتة وبيانات تشغيلية، عمليات تكامل مع الشركاء.
الرسم البياني QL: الرسم البياني المرن «الانتقائي» للقراءة والملاحة (الأبعاد/الحقائق).
gRPC (protobuf): زمن انتقال منخفض لركوب الأمواج عبر الإنترنت (Feature Store، scoring).
Arrow Flight/Parquet over HTTP/S3-presigned: مقالب الأعمدة السريعة لـ DS/ML.
OData: أدوات المؤسسة، نموذج الجدول كخدمة.
Streams (Kafka/Pulsar) + CDC/Webhooks: أحداث في الوقت الفعلي، اندماجات تفاعلية.
الاتحاد (ترينو/بريستو): نقطة دخول واحدة إلى مصادر متعددة.

القاعدة: المجاميع والشرائح المستقرة → REST/MV، والاستفسارات التعسفية الغنية → SQL، وميزات زمن الوصول المنخفض/عبر الإنترنت → gRPC، ونموذج الاستجابة المرنة → GraphQL، والتبادل الثنائي الجماعي → Arrow/Parquet.

3) العقود والنسخ (نصف هاتف)

الرائد. قاصر. 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 مع أدوار/أقنعة (أمن على مستوى الصف/العمود).
إسقاطات العواصف الثلجية/الأسعار الثابتة: أسماء ثابتة ودلالات ؛ الطلبات الثقيلة تذهب إلى مرحلة ما قبل التقنين.
الاتحاد (Trino/Presto): نقطة دخول واحدة، ولكن مع السياسات: ما هي الأدلة والميزات المتاحة.
Lakehouse (Iceberg/Delta/Hudi): السفر عبر الزمن، واسترجاع لقطات سريعة عبر SQL/REST.
Квоты: مسح بايت/استعلام، متزامن، وقت الحائط.

5) الرسم البياني QL (شكل مرن)

نعطي العميل جمع المجال المطلوب، ولكن التنفيذ على العواصف الثلجية/الإسقاطات المعدة، مع حدود العمق/العظام.

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

السياسات: العمق ≤ 5، مجموع العقد ≤ 5k، يحظر التعسف في التنقيب/مثل السطور ؛ نخزن الطلبات المتكررة.

6) gRPC/Feature Store (زمن انتقال منخفض)

ميزات على الإنترنت لتسجيل مكافحة الاحتيال/التوصيات/النمو الحقيقي.

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) التدفقات ومراكز السيطرة على الأمراض والوقاية منها

أحداث المجال: المدفوعات. deposit_accepted'، لعبة. round_finished'.
مركز السيطرة على الأمراض (من OLTP): الحالة/الحد من التغييرات في الوقت الفعلي تقريبًا.
الشبكات الشبكية للشركاء: الاشتراك في المجاميع (على سبيل المثال «فشل PSP> العتبة»).
سياسات إعادة التدوير/الاعتراف: مرة واحدة بالضبط للرصد الحرج ومرة واحدة على الأقل.

8) البحيرات والعينات الكبيرة

رحلة السهم لتفريغ العمود السريع إلى DS/ML.
تم التوقيع على URL إلى Parquet/Feather، مع TTL قصير والطلب الموقع.
التحويل المقطوع والتحكم في حجم الملف ؛ سجل التنزيل (تدقيق WORM).

9) المرشحات، التثبيت، الفرز

استعداد الكيزيت (المؤشر) بدلاً من OFFSET للمجموعات الكبيرة.
المرشحات: القائمة البيضاء حسب الحقول والأنواع والمشغلين ('=, IN, BETWEEN, prefix').
الفرز: قائمة محدودة من الحقول، ترتيب افتراضي.
الاستجابة الجزئية: «الحقول = العلامة التجارية، البلد، الكمية» تقلل الحمولة.

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

10) التخزين المؤقت والتكلفة

مخبأ النتيجة لطلبات القالب، معطل بواسطة معرف اللقطة.
Edge cache/CDN للتجمعات العامة/شبه العامة (بدون PII).
معايير الميزانية: حد البايت الممسوح ضوئيًا، مهلة الطلب، حصص rps/min.
إعطاء الأولوية للمجمعات: 'bi _ hot'، 'adhoc'،' partner _ api '.

11) الأمن والخصوصية

AuthN: OAuth2/OIDC (أوراق اعتماد العملاء للخدمات، PKCE للأشخاص).
AuthZ: RBAC + ABAC (السمات: العلامة التجارية، البلد، الترخيص، الدور).
TLS بين الخدمات، TLS 1. 2 + خارج.
نظافة PII: الأقنعة/الترميز على طبقة API، وأقنعة العمود، وإخفاء هوية k من المجاميع.
العزل الجغرافي/المستأجر: توجيه الطلبات إلى منطقة الترخيص ؛ مفاتيح التشفير لكل ماركة/منطقة.
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-Encoding').
التفاوض على المحتوى: "قبول: الطلب/x-parquet'.

14) مقاييس API (بوابة التحليلات/OLAP)

مقاييس المستوى الأعلى: GGR/NET، CR، عقد، حوادث RG - كموارد مع المعلمات «العلامة التجارية، البلد، النافذة، المجموعة _ حسب».
تقريبًا (HLL/TDiest) для متميزة/مئوية.
ذاكرة التخزين المؤقت الرئيسية: «(مقياس، بارامات، snapshot_id)».

15) خصوصية iGaming - نقاط النهاية الجاهزة

"GET/v2/payments/metrics' - الإخفاقات/التحديثات بواسطة PSP/country/brand بنوافذ 7/30d.
"GET/v2/game-rounds/metrics' - أفضل الألعاب/المزودين، مدة p95، نوافذ RTP.
«GET/v2/rg/cases» - القيود النشطة/الاستبعادات الذاتية (مجاميع k-unhonous).
"POST/v1/features: get' (gRPC) - ميزات عبر الإنترنت لتسجيل الاحتيال/التوصية.
"POST/v1/webhooks/psp-allerts' - الإشعارات" معدل الانخفاض> العتبة ".

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 bytes، التكلفة.
4. التحقق/التخزين المؤقت/الحصص: التمكين افتراضيًا.
5. التوثيق و SDK: أمثلة، حدود، أخطاء، إعادة طباعة، غباء.
6. كناري:٪ من العملاء، اختبارات الانحدار، التنبيهات.
7. GA: إصدار كتالوج منتجات البيانات، تقرير التأثيرات.

18) الأنماط المضادة

افتح SQL «الخام» للجميع - تسريبات PII، تكلفة لا يمكن التنبؤ بها.
التعويض عن الاستعداد و «الاختيار» - الألم عن طريق الكمون والعد.
الرسم البياني QL بدون قيود العمق/التكلفة.
REST، الذي يعيد الكثير من الأعمدة بدون «حقول =»....
عدم الكشف عن هويته وحجم مجموعته في المجاميع.
حصص/حدود صفرية ومخبأ معاق.
لا يوجد إصدار/عقود - نحن «نقطع» العملاء مع كل تغيير.
نفس الواجهة لجميع البلدان/العلامات التجارية هي تجاهل للقواعد الإقليمية.

19) خارطة طريق التنفيذ

0-30 يومًا (MVP)

1. كتالوج منتجات البيانات (المقاييس/الشرائح) وعقود OpenAPI/GraphQL الخاصة بهم.
2. بوابة SQL مع RLS/CLS، عدم الكشف عن هوية المجاميع، الحصص الأساسية.
3. نقطة نهاية REST-metric ('/payments/metrics') + cache + pools' bi _ hot/adhoc'.
4. متجر ميزات gRPC: قراءة 10-20 ميزة رئيسية عبر الإنترنت (p95 ≤ 80 ms).

30-90 يومًا

1. دفق الواجهات (كافكا/ويب هوك) لتنبيهات PSP/أحداث اللعبة.
2. تحميلات السهم/الباركيت من عنوان URL المقدم ؛ كتالوج لقطة.
3. بوابة الاتحاد (ترينو/بريستو) بسياسات صريحة.
4. قابلية الملاحظة: لوحة القيادة SLI/SLO، تنبيهات حول التكلفة/زمن الكمون/PII.

3-6 أشهر

1. SDK (TypeScript/Python/Go) مع إعادة الطباعة/الخصوصية/الحصص.
2. شرائح رقيقة من الرسم البياني QL للمنتجات والشركاء.
3. تمديد برنامج العمل/الخدمات المالية، offlayn↔onlayn التفاوض ؛ إصدارات shadow→canary.
4. مراجعة الخصوصية/DSAR ؛ تقارير الامتثال للوصول.

20) RACI

منصة البيانات (R): بوابات، مخبأ، حصص، اتحاد، قابلية للمراقبة.
إدارة البيانات (A/R): العقود والنسخ والخصوصية/عدم الكشف عن الهوية.
مالكو المجال (R): دلالات المجال، ثوابت الأعمال، منتجات البيانات.
Security/DPO (A/R): AuthN/Z, geo-isolation, DSAR/Legal Hold.
SRE/Observability (C): SLO/SLI، تنبيهات، قدرة.
التحليلات/BI/DS (C): متطلبات الاستمارات/المجاميع، SDK.

21) الأقسام ذات الصلة

فهرسة التخزين التحليلية، تحسين الاستعلام التحليلي، مخططات البيانات والتطور، التحقق من صحة البيانات، ممارسات عمليات البيانات، واجهات برمجة التطبيقات التحليلية والمقاييس، متجر الميزات، أمن البيانات والتشفير، التحكم في الوصول، سياسات الاحتفاظ بالبيانات.

المجموع

تحول واجهات الوصول إلى البيانات المصممة بشكل صحيح التخزين والتدفقات إلى «منتج» موثوق: اتفاقيات SLA يمكن التنبؤ به، والتكلفة الخاضعة للرقابة، والامتثال للخصوصية، ولغة واحدة لفرق المنتج والتحليلات والامتثال والشركاء. في iGaming، هذا يعني أن اصطياد PSP يتعطل بشكل أسرع، وفهم سلوك اللاعب وتلبية المتطلبات التنظيمية - بدون تحميلات يدوية وهجرات ليلية.