الاستعلام عن بيانات الجداول لأغراض التقارير

الهدف

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

المتطلبات المسبقة

• تسجيل تطبيق خارجي مُنح النطاق reporting.read (أو modelapps.read الذي يمنح قراءة التقارير أيضًا) ودورًا يحق له قراءة الجداول التي يحتاجها. راجع تسجيل تطبيق خارجي.
• رمز وصول حُصل عليه لذلك التسجيل مع طلب النطاق باسمه.
• معرّف البيئة التي تريد قراءة بياناتها.

واجهة التقارير

كل العمليات محصورة في بيئة واحدة وللقراءة فقط. أمران يحددان ما تحصل عليه: النطاق يفتح الواجهة أصلًا، ودور التطبيق يحدد أي الجداول وأي الصفوف، تمامًا كما لشخص يستخدم تطبيقًا. رمزٌ فيه النطاق بلا دور لا يصل إلى أي صف.

العملية	الطلب	النتيجة
سرد الجداول	GET /environments/{environmentId}/reporting/entities	الجداول التي يحق لدورك قراءتها (الاسم المنطقي، اسم العرض، اسم الجمع).
وصف أعمدة جدول	GET /environments/{environmentId}/reporting/entities/{entity}/schema	كل عمود: الاسم المنطقي، اسم العرض، نوع البيانات، وهل هو الحقل الأساسي، والجدول الهدف للبحث.
قراءة مجموعة بيانات	POST /environments/{environmentId}/reporting/entities/{entity}/dataset	columns وrows، مع totalCount وpageNumber وpageSize.
تشغيل استعلام محفوظ	POST /environments/{environmentId}/saved-queries/{logicalName}/run	سجلات الاستعلام المحفوظ أو مجموعاته.

طلب مجموعة بيانات

الجسم استعلام: select (الأعمدة التي تريدها)، وfilter (رابط وشروط، كلٌّ منها حقل وعامل وقيمة)، وorder (حقول، تصاعدية أو تنازلية)، وpage (number وsize):

{
  "select": ["nw_name", "nw_company"],
  "filter": { "connector": "And",
              "conditions": [{ "field": "nw_company", "operator": "Equals", "value": "Analytical Engines" }] },
  "order": [{ "field": "nw_name", "descending": false }],
  "page": { "number": 1, "size": 50 }
}

مع select تصف columns تلك الأعمدة بالضبط وبذلك الترتيب. يعود عمود الخيارات رقمًا، وبجانبه تسميته تحت <العمود>__text. ومن totalCount تعرف عدد الصفحات.

استعلام محفوظ

الاستعلام الذي صممه صانعٌ وحفظه يُشغَّل باسمه المنطقي. الجسم اختياري ولا يستطيع إلا تضييقه: يُضاف filter الإضافي إلى المحفوظ ولا يحل محله أبدًا، ويختار page صفحة. ويجيب الاستعلام المجمّع بمجموعاته ومقاييسها، فيستطيع التكامل طلب المجاميع بدل جمع الصفوف بنفسه.

ما الذي يحدث خلف الكواليس

لا يُنشئ مصدر بيانات التقارير شيئًا ولا يعدّل ولا يحذف. يتحقق كل طلب أولًا من نطاق الرمز، ثم يقرأ عبر المسار نفسه الذي تستخدمه شاشات المنصة، فتحدد أذونات الدور وسياساتها الصفوف. ولا تُقرأ إلا البيئة المذكورة في المسار.

حل المشكلات

• 403 مع modelapps.reporting.forbidden. لا يحمل الرمز reporting.read ولا modelapps.read. اطلب النطاق باسمه عند طلب الرمز: الرمز المطلوب بلا scope لا يحمل أي نطاق.
• 403 مع modelapps.record.forbidden. النطاق موجود، لكن دور التطبيق لا يحق له قراءة ذلك الجدول. امنح الدور القراءة عليه في هذه البيئة.
• جدول غائب عن القائمة. لا يحق للدور قراءته، أو أنه غير موجود في هذه البيئة.
• 400 بسبب حقل غير معروف. حقل في select أو filter أو order ليس من الجدول. استخدم حقلًا من مخطط الجدول.

سيناريوهات ذات صلة

• تسجيل تطبيق خارجي.
• ربط تقرير بجدول (الصانع).