Power BI Embedded، REST API، Service Principal و Automation

شروع جلسه؛ وقتی گزارش باید داخل نرم‌افزار خودمان زندگی کند

تا اینجا بیشتر Report را داخل Power BI Service و App منتشر کردیم. اما فرض کن یک CRM، ERP، پورتال مشتری یا نرم‌افزار SaaS با ASP.NET Core و React داریم و می‌خواهیم کاربر بدون خروج از برنامه، Dashboard خودش را همان‌جا ببیند. اینجا Power BI Embedded وارد بازی می‌شود.

در این فصل علاوه بر Embedded، سراغ REST API و Automation هم می‌رویم تا بفهمیم چطور Power BI را از یک ابزار دستی به بخشی از معماری نرم‌افزار تبدیل کنیم.

۴۹.۱. Power BI Embedded چیست؟

Embedded یعنی Report یا محتوای تحلیلی Power BI را داخل Application خودمان نمایش بدهیم؛ مثلاً داخل پورتال فروش، پنل مدیر کارخانه یا سامانه مشتریان.

۴۹.۲. چرا Embedded؟

کاربر لازم نیست بین چند سیستم جابه‌جا شود. Analytics درست کنار Workflow اصلی نرم‌افزار قرار می‌گیرد و تجربه یکپارچه‌تری می‌سازد.

۴۹.۳. مثال واقعی

۴۹.۴. دو مدل ذهنی مهم

یک سناریو این است که کاربران سازمان خودمان با هویت سازمانی به Power BI دسترسی دارند. سناریوی دیگر این است که مشتری نرم‌افزار ما لزوماً Power BI User مستقیم نیست و Application ما تجربه Embedded را مدیریت می‌کند.

جزئیات License، Capacity و قابلیت‌های مجاز باید با Tenant و مدل تجاری واقعی پروژه بررسی شوند.

۴۹.۵. معماری ساده Embedded

Browser / React
      ↓
ASP.NET Core Backend
      ↓
Microsoft identity + Power BI APIs
      ↓
Workspace / Semantic Model / Report

۴۹.۶. چرا Backend لازم است؟

Secret، Credential و منطق تولید Token نباید داخل JavaScript مرورگر قرار بگیرد. Backend باید عملیات حساس را انجام دهد و Frontend فقط اطلاعات لازم برای Embed را دریافت کند.

۴۹.۷. Authentication و Authorization

Authentication می‌گوید کاربر کیست؛ Authorization می‌گوید چه Report و چه داده‌ای حق دارد ببیند. این دو را قاطی نکن.

۴۹.۸. Microsoft Entra ID

در معماری Microsoft، هویت Application و کاربران معمولاً با Microsoft Entra ID مدیریت می‌شود. Application Registration یکی از اجزای مهم Integration است.

۴۹.۹. App Registration

Application را ثبت می‌کنیم تا شناسه و Permissionهای لازم برای تعامل با سرویس‌ها داشته باشد.

۴۹.۱۰. Service Principal

Service Principal هویت Application است؛ یعنی به جای اینکه Automation به حساب شخصی یک Developer وابسته باشد، خود Application هویت مشخص دارد.

۴۹.۱۱. چرا حساب شخصی بد است؟

اگر Developer شرکت را ترک کند، Password عوض شود یا MFA تغییر کند، Integration Production نباید از کار بیفتد.

۴۹.۱۲. Secret و Certificate

برای احراز هویت Application می‌توان بر اساس معماری و سیاست امنیتی از روش‌های مناسب مثل Secret یا Certificate استفاده کرد. Credential را هرگز در Repository یا Frontend قرار نده.

۴۹.۱۳. Least Privilege

Service Principal فقط Permission لازم را بگیرد. چون Application می‌تواند Automation انجام دهد، Permission بیش از حد خطرناک است.

۴۹.۱۴. Workspace Access

هویت Application باید طبق معماری و تنظیمات Tenant به Workspace/Artifactهای لازم دسترسی داشته باشد.

۴۹.۱۵. Embed Token

در سناریوهای Embedded مناسب، Backend اطلاعات لازم برای نمایش Report و Token محدودشده را تولید می‌کند و Frontend از آن برای Embed استفاده می‌کند.

۴۹.۱۶. Token را Log نکن

Token و Secret داده حساس هستند. Logging، Error Handling و Telemetry نباید باعث افشای آن‌ها شوند.

۴۹.۱۷. Token Lifetime

Tokenها دائمی نیستند. Frontend باید Expiration و Refresh Flow مناسب داشته باشد.

۴۹.۱۸. Frontend React

const config = {
  type: 'report',
  id: reportId,
  embedUrl: embedUrl,
  accessToken: embedToken,
  tokenType: models.TokenType.Embed
};

۴۹.۱۹. نکته امنیتی کد بالا

Frontend فقط Token کوتاه‌عمر و اطلاعات Embed را دریافت می‌کند؛ Client Secret یا Credential اصلی Application نباید به مرورگر برسد.

۴۹.۲۰. Backend ASP.NET Core

GET /api/analytics/reports/{reportKey}/embed-config

1. Authenticate current app user
2. Resolve tenant/customer permissions
3. Acquire service token securely
4. Resolve Power BI report
5. Generate permitted embed configuration
6. Return only required client data

۴۹.۲۱. Report Key بهتر از ReportId خام

Application می‌تواند یک کلید داخلی مثل SalesExecutive داشته باشد و Mapping واقعی Workspace/Report را در Configuration امن Backend نگه دارد.

۴۹.۲۲. Multi-Tenant SaaS

فرض کن نرم‌افزار را به ۲۰۰ شرکت می‌فروشیم. هر شرکت فقط باید داده خودش را ببیند. اینجا طراحی Tenant Isolation حیاتی است.

۴۹.۲۳. Tenant Isolation

۴۹.۲۴. فقط Filter در React کافی نیست

مخفی کردن Company A با Filter سمت مرورگر امنیت نیست. کاربر نباید اصلاً مجوز دریافت داده Company B را داشته باشد.

۴۹.۲۵. RLS در Embedded

در سناریوی مناسب می‌توان Identity/Role Context را به مدل امنیتی متصل کرد تا Semantic Model فقط Rowهای مجاز را برگرداند.

۴۹.۲۶. Effective Identity

مفهوم مهم این است که Backend هنگام ساخت Context نمایش، هویت یا Role مناسب مصرف‌کننده را در سناریوی پشتیبانی‌شده لحاظ کند.

۴۹.۲۷. Security Test

برای Tenant A، Tenant B، Admin و User ناشناخته Test Case بساز. امنیت Embedded بدون تست منفی کامل نیست.

۴۹.۲۸. REST API چیست؟

Power BI REST API اجازه می‌دهد بخشی از عملیات Service را از طریق نرم‌افزار انجام دهیم؛ مثلاً Inventory گرفتن، Refresh راه انداختن یا اطلاعات Artifactها را خواندن.

۴۹.۲۹. API را برای چه کارهایی استفاده می‌کنیم؟

۴۹.۳۰. REST Endpoint Concept

Application → HTTPS REST request → Power BI service → JSON response

۴۹.۳۱. Access Token برای API

برای صدا زدن API باید Token معتبر با Scope/Permission مناسب داشته باشیم. Token را با روش رسمی Identity Platform دریافت کن.

۴۹.۳۲. HttpClient در .NET

using var request = new HttpRequestMessage(HttpMethod.Get, apiUrl);
request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await httpClient.SendAsync(request);

۴۹.۳۳. HttpClientFactory

در ASP.NET Core برای Production بهتر است مدیریت HttpClient، Retry، Timeout و Resilience را اصولی انجام دهیم؛ HttpClientFactory یکی از الگوهای رایج است.

۴۹.۳۴. Error Handling

401، 403، 404، 429 و خطاهای 5xx معنی متفاوت دارند. Automation حرفه‌ای فقط Success را Handle نمی‌کند.

۴۹.۳۵. 401 و 403

401 معمولاً به Authentication/Token مربوط است؛ 403 یعنی هویت شناخته شده ولی Permission کافی ندارد.

۴۹.۳۶. 429

429 یعنی Rate Limit/Throttling. Retry کور و سریع می‌تواند اوضاع را بدتر کند؛ Backoff و سیاست مناسب لازم است.

۴۹.۳۷. Retry

Retry transient errors
→ exponential backoff
→ maximum retry count
→ log correlation id
→ alert if operation still fails

۴۹.۳۸. Idempotency Thinking

اگر Automation دوباره اجرا شد، نباید ناخواسته ده نسخه یک Artifact یا عملیات تکراری مخرب ایجاد کند.

۴۹.۳۹. Refresh Automation

می‌توان Refresh را از Workflow نرم‌افزار یا Orchestrator راه انداخت؛ مثلاً بعد از پایان ETL.

۴۹.۴۰. Refresh Flow

ETL completed
   ↓
Validate warehouse
   ↓
Trigger semantic model refresh
   ↓
Poll/check status
   ↓
Validate KPIs
   ↓
Notify success/failure

۴۹.۴۱. Trigger بدون Monitor کافی نیست

اگر فقط درخواست Refresh بفرستی و نتیجه را بررسی نکنی، Automation ناقص است.

۴۹.۴۲. Polling

اگر API عملیات Async است، Status را با فاصله منطقی بررسی کن. Polling خیلی سریع هم Rate Limit ایجاد می‌کند.

۴۹.۴۳. Correlation ID

برای عملیات مهم شناسه رهگیری نگه دار تا Logهای Application، API و Incident به هم وصل شوند.

۴۹.۴۴. Automation Log

۴۹.۴۵. Monitoring

Automation باید Metrics داشته باشد: Success Rate، Duration، API Error Rate، Token Failure و Refresh SLA.

۴۹.۴۶. Admin Automation

در سازمان بزرگ می‌توان Inventory Workspaceها، Ownerها و Artifactها را برای Governance جمع‌آوری کرد؛ Permission و APIهای مدیریتی باید طبق سیاست Tenant تنظیم شوند.

۴۹.۴۷. Governance Scanner Concept

یک Job دوره‌ای می‌تواند Metadata مجاز را جمع کند و Report Governance بسازد: Workspace بدون Owner، Dataset بدون Refresh یا Report بدون استفاده.

۴۹.۴۸. Metadata Database

Power BI APIs
   ↓
Collector Worker
   ↓
Governance SQL Database
   ↓
Power BI Governance Dashboard

۴۹.۴۹. Worker Service

برای Jobهای دوره‌ای می‌توان از Worker Service، Scheduler، Azure Function یا Orchestrator متناسب با زیرساخت استفاده کرد.

۴۹.۵۰. Background Job

Job طولانی را داخل Request کاربر نگه ندار. عملیات Async را Queue/Background Processing کن.

۴۹.۵۱. Webhook/Event Thinking

هر جا سرویس Event قابل اتکا ارائه می‌دهد، Event-driven می‌تواند بهتر از Polling دائمی باشد؛ ولی باید قابلیت واقعی سرویس موردنظر بررسی شود.

۴۹.۵۲. Cache

Metadata ثابت Report را لازم نیست برای هر Page Load دوباره از API بگیری. Cache با Expiration مناسب فشار API را کم می‌کند.

۴۹.۵۳. Embed Config Cache

اطلاعات غیرحساس قابل Cache را از Token حساس جدا کن. Token Strategy باید Expiration و Security را رعایت کند.

۴۹.۵۴. Frontend Events

کتابخانه Embedded می‌تواند Eventهای مختلفی برای تعامل Report در اختیار Application بگذارد. از آن‌ها برای UX و Telemetry استفاده کن، نه برای دور زدن Security.

۴۹.۵۵. Page Navigation

Application می‌تواند در سناریوهای مناسب Report/Page مشخص را باز کند تا کاربر مستقیماً وارد تحلیل مرتبط با Workflow شود.

۴۹.۵۶. Filter Integration

مثلاً کاربر در CRM روی Customer 1024 کلیک می‌کند و Report Embedded روی همان Customer باز می‌شود.

۴۹.۵۷. Filter امنیت نیست

دوباره تأکید: Filter برای UX است؛ Authorization/RLS برای Security.

۴۹.۵۸. Contextual Analytics

بهترین ارزش Embedded وقتی ایجاد می‌شود که Analytics با عملیات نرم‌افزار Context مشترک داشته باشد.

۴۹.۵۹. مثال CRM

CRM Customer Page
  ├─ Customer profile
  ├─ Orders
  ├─ Support tickets
  └─ Embedded analytics: revenue, churn risk, payment trend

۴۹.۶۰. Write-back

Power BI ذاتاً ابزار اصلی Transaction Entry نیست. اگر کاربر باید Action انجام دهد، آن عملیات را در Application/API کسب‌وکار طراحی کن و Report را برای Insight استفاده کن.

۴۹.۶۱. Action from Insight

مثلاً Report مشتری پرریسک را نشان می‌دهد و دکمه Application کاربر را به فرم Create Follow-up می‌برد.

۴۹.۶۲. Audit

ثبت کن چه Application/Service Principal چه عملیات مدیریتی مهمی انجام داده است؛ مخصوصاً Automationهای Production.

۴۹.۶۳. Secret Rotation

Secret/Certificate Rotation باید بدون Downtime و با Runbook انجام شود.

۴۹.۶۴. Configuration Management

۴۹.۶۵. Environment Separation

DEV/UAT/PROD باید App Registration، Workspace Mapping و Secret Strategy کنترل‌شده داشته باشند.

۴۹.۶۶. Production Safety

Automation DEV نباید به Workspace Production اشاره کند. Configuration Guard و Permission Boundary بساز.

۴۹.۶۷. Capacity و Licensing

Embedded به مدل Capacity/Licensing و نوع سناریو وابسته است. قبل از قیمت‌گذاری SaaS باید هزینه واقعی مصرف و مدل مجوز را بررسی کنی.

۴۹.۶۸. Cost per Customer

برای SaaS فقط هزینه ساخت Report را نبین؛ Capacity، Query Load، تعداد Tenant، Concurrent User و رشد داده روی Unit Economics اثر دارند.

۴۹.۶۹. Performance

Embedded Report همان مشکلات Performance معمول Power BI را دارد. Session 45 همچنان کاملاً کاربرد دارد.

۴۹.۷۰. Mobile

اگر Application موبایل‌محور است، Layout و تعداد Visualها را برای فضای Embedded واقعی طراحی کن.

۴۹.۷۱. Error UX

اگر Token Expire شد یا Report Load نشد، کاربر نباید صفحه سفید ببیند. Loading، Retry محدود و پیام خطای قابل فهم طراحی کن.

۴۹.۷۲. Observability

Frontend Error، Backend API call، Power BI operation و Correlation ID را به هم وصل کن تا Support بتواند Incident را پیدا کند.

۴۹.۷۳. پروژه شرکت هانا؛ سناریو

فرض کنیم پورتال صنعتی با React و ASP.NET Core داریم و هر کارخانه بعد از Login باید Dashboard تولید خودش را داخل همان پورتال ببیند.

۴۹.۷۴. پروژه؛ Authentication

کاربر ابتدا در Application احراز هویت می‌شود. Backend Tenant/Factory او را از Claims و Database داخلی مشخص می‌کند.

۴۹.۷۵. پروژه؛ Authorization

Backend بررسی می‌کند این کاربر مجاز به Report ProductionAnalytics هست یا نه.

۴۹.۷۶. پروژه؛ Embed

Backend با هویت Application به Power BI متصل می‌شود، Context مجاز کارخانه را اعمال می‌کند و Embed Config محدودشده برمی‌گرداند.

۴۹.۷۷. پروژه؛ React

GET /api/analytics/production/embed-config
        ↓
receive reportId + embedUrl + short-lived token
        ↓
render inside Analytics page

۴۹.۷۸. پروژه؛ RLS

FactoryId در مدل امنیتی به Identity/Context Tenant متصل می‌شود؛ Factory A نباید حتی با دستکاری JavaScript بتواند Factory B را ببیند.

۴۹.۷۹. پروژه؛ Automation

بعد از تکمیل ETL تولید، Worker Refresh مدل را Trigger می‌کند و نتیجه را تا Success/Failure پیگیری می‌کند.

۴۹.۸۰. پروژه؛ Governance Job

هر شب Job دیگری Inventory محتوای BI را جمع می‌کند و Workspaceهای بدون Owner یا Refreshهای Fail را گزارش می‌دهد.

۴۹.۸۱. معماری پیشنهادی

React SPA
   ↓ HTTPS
ASP.NET Core API
   ├─ Application auth/tenant DB
   ├─ Power BI integration service
   ├─ Secret provider
   └─ Background workers
          ↓
Microsoft identity + Power BI Service
          ↓
Governed semantic models + RLS

۴۹.۸۲. Interface پیشنهادی .NET

public interface IPowerBiEmbedService
{
    Task<EmbedConfigDto> GetReportAsync(
        Guid applicationUserId,
        string reportKey,
        CancellationToken ct);
}

۴۹.۸۳. جداسازی مسئولیت

Controller نباید تمام منطق Token، API و RLS را داخل خودش داشته باشد. Integration Service جدا تست و نگهداری را ساده‌تر می‌کند.

۴۹.۸۴. DTO

public sealed record EmbedConfigDto(
    string ReportId,
    string EmbedUrl,
    string AccessToken,
    DateTimeOffset ExpiresAt);

۴۹.۸۵. API Security

Endpoint Embed Config باید خودش Authorization داشته باشد. صرفاً دانستن reportKey نباید دسترسی ایجاد کند.

۴۹.۸۶. Rate Limiting

روی Endpointهای حساس Application هم Rate Limit و Abuse Protection متناسب با پروژه در نظر بگیر.

۴۹.۸۷. خطای رایج؛ Secret در React

یکی از خطرناک‌ترین اشتباه‌هاست؛ هر چیزی که به Browser برسد را کاربر می‌تواند مشاهده کند.

۴۹.۸۸. خطای رایج؛ Filter به جای RLS

Filter قابل تغییر است و مرز امنیتی محسوب نمی‌شود.

۴۹.۸۹. خطای رایج؛ Service Account شخصی

Integration Production را به حساب Developer وابسته نکن.

۴۹.۹۰. خطای رایج؛ API بدون Retry Policy

خطای موقت شبکه یا Throttling باعث شکست‌های غیرضروری می‌شود.

۴۹.۹۱. خطای رایج؛ Retry بی‌نهایت

Retry بدون Limit و Backoff می‌تواند Incident را بدتر کند.

۴۹.۹۲. خطای رایج؛ Trigger بدون Status

درخواست Refresh ارسال شده ولی هیچ‌کس نمی‌داند موفق شده یا نه.

۴۹.۹۳. خطای رایج؛ Tenant Isolation فقط در UI

در SaaS یک نقص امنیتی جدی است.

۴۹.۹۴. Best Practiceها

عملیات حساس را در Backend نگه دار.

Service Principal را برای Integration سازمانی بررسی کن.

Least Privilege رعایت کن.

Secret را در Secret Store نگه دار.

Token Expiration را مدیریت کن.

Tenant Isolation را چندلایه طراحی کن.

RLS را با تست منفی بررسی کن.

API Errorها و Throttling را Handle کن.

Automation را Monitor کن.

Correlation ID داشته باش.

DEV/UAT/PROD را جدا کن.

Cost و Capacity Embedded را قبل از فروش SaaS مدل کن.

۴۹.۹۵. تمرین ۱

معماری React + ASP.NET Core + Power BI Embedded را برای یک CRM رسم متنی کن و مرز Frontend/Backend را مشخص کن.

۴۹.۹۶. تمرین ۲

برای Tenant A و Tenant B چهار Test Case امنیتی طراحی کن.

۴۹.۹۷. تمرین ۳

یک API داخلی به نام /api/analytics/{reportKey}/embed-config طراحی و Authorization آن را توضیح بده.

۴۹.۹۸. تمرین ۴

Refresh Automation را با Retry، Status Check، SLA و Alert طراحی کن.

۴۹.۹۹. تمرین ۵

یک Governance Collector طراحی کن که Workspace، Report، Semantic Model، Owner و Refresh Status را در SQL ذخیره کند.

۴۹.۱۰۰. تمرین چالشی

برای SaaS با ۵۰۰ شرکت و ۵۰۰۰ کاربر، Tenant Isolation، Capacity، Cache، Token Strategy، Monitoring و Cost Model را در سطح معماری طراحی کن.

۴۹.۱۰۱. پروژه Session؛ Embedded Integration Pack

هدف این پروژه این است که Power BI را از یک Report مستقل به قابلیت Analytics داخل محصول نرم‌افزاری تبدیل کنیم.

جمع‌بندی Session 49

Power BI Embedded وقتی ارزشمند می‌شود که Analytics بخشی از تجربه نرم‌افزار باشد. ولی همین Integration سطح مسئولیت امنیتی و عملیاتی را بالا می‌برد: Token، Service Principal، Tenant Isolation، RLS، API، Retry، Monitoring و Cost باید مهندسی شوند.

Application context + Secure backend + Governed semantic model + Embedded analytics = Analytics inside the product

Session 50: پروژه نهایی End-to-End و نقشه راه حرفه‌ای Power BI؛ از Requirement تا Architecture، Model، DAX، UX، Security، Deployment، Governance و Portfolio.