پرس‌وجوی داده جدول برای گزارش‌گیری

هدف

خواندن داده‌های یک جدول از یک محیط از طریق منبع دادهٔ فقط‌خواندنی گزارش‌گیری، تا یک یکپارچه‌سازی بیرونی گزارش‌گیری یا تحلیلی بتواند جدول‌هایی را که اجازهٔ خواندنشان را دارد فهرست کند، ستون‌های یک جدول را بشناسد، صفحه‌هایی از سطرها را بگیرد و یک پرس‌وجوی ذخیره‌شده را اجرا کند، بی‌هیچ دسترسی نوشتنی.

پیش‌نیازها

• یک ثبت برنامهٔ بیرونی با اسکوپ 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 روی جدول نیست. از فیلدهای طرح‌وارهٔ جدول استفاده کنید.

سناریوهای مرتبط

• ثبت یک برنامهٔ بیرونی.
• اتصال یک گزارش به یک جدول (سازنده).