Embedded Analytics
Embedded Analytics
Embedded Analytics
APPLIES TO: ✔
️ App owns data ✔
️ User owns data
Power BI embedded analytics allows you to embed your Power BI items such as reports, dashboards and tiles, in
a web application or in a website. You can:
Deliver compelling data experiences for your end users, enabling them to take action based on insights
from your solutions data.
Quickly and easily provide exceptional customer-facing reports, dashboards, and analytics in your own
apps by using and branding Power BI as your own.
Secure embed
Secure embed is the simplest no-code way to embed a report into any portal that accepts a URL or iFrame. The
viewer of the report must have the proper Power BI license. The viewer can interact with the report, but not edit,
save, or make any changes to it. Secure embed is available in the Power BI service.
For more advanced solutions that give your users more flexibility and control, use one of the Power BI
embedded analytics solutions described in this article.
Also known as app owns data Also known as user owns data
To authenticate app users, use your own authentication App users authenticate against Azure AD
method
App users don't need a license Each app user needs a Power BI license
Non-interactive authentication. Your app uses a service Interactive authentication. Your app uses the app user's
principal or a master user to authenticate credentials to authenticate
TIP
Get started with the Power BI embedded analytics setup tool.
IMPORTANT
Free trial tokens are limited to development testing only. Once going to production, a capacity must be purchased. Until a
capacity is purchased, the Free trial version banner will continue to appear at the top of the embedded report.
There are two types of Power BI embedded analytics offerings. Each offer includes a different type of SKU that
you use to buy a Power BI capacity:
Power BI Embedded is an Azure offer that includes A SKUs. Power BI Embedded is associated with the
embed for your customers solution.
Power BI Premium is a Microsoft Office offer that includes P or EM SKUs.
For more information about the differences between the Embedded and Premium SKUs, see Capacity and SKUs
in Power BI embedded analytics.
Next steps
Power BI Embedded Generation 2
Capacity and SKUs in Power BI embedded analytics
Tutorial: Embed Power BI content using a sample embed for your customers application
Tutorial: Embed Power BI content using a sample embed for your organization application
Power BI embedded analytics setup tool
Power BI Premium features
11/24/2022 • 2 minutes to read • Edit Online
This article lists the main Power BI Premium features. Most of the features apply to all the Power BI Premium
licenses, Premium Gen2, Premium (original version) and Premium Per User (PPU) as well as Power BI
Embedded. When a feature only works with a specific license, the required license is indicated in the description
field. If no license is listed, the feature works with any license.
IMPORTANT
If your organization is using the original version of Power BI Premium, you're required to migrate to the modern Premium
Gen2 platform. Microsoft began migrating all Premium capacities to Gen2. If you have a Premium capacity that requires
migrating, you’ll receive an email notification 60 days before the migration is scheduled to star t . For more
information see Plan your transition to Power BI Premium Gen2.
Backup and restore Backup and restore data using XMLA endpoints
Bring your own key (BYOK) Use your own keys to encrypt data
DirectQuery with dataflows Connect directly to your dataflow without having to import
its data
F EAT URE DESC RIP T IO N
Insights (preview) Explore and find insights such as anomalies and trends in
your reports
On-demand loading capabilities for large models Improve report load time by loading datasets to memory on
demand
Refresh rate The ability to refresh more than eight times a day
Streaming dataflows (preview) Connect to, ingest, mash up, model, and build reports using
near real-time data
Virtual network data gateway (preview) Connect from Microsoft Cloud to Azure using a virtual
network (VNet)
Next steps
What is Power BI Premium Gen2?
What is Power BI Premium?
What is the Power BI embedded analytics
playground?
11/24/2022 • 2 minutes to read • Edit Online
The playground gives you hands-on coding experience, and lets you embed your own reports, and interact with
Power BI client APIs giving you instant results. The playground has the following main experiences:
Developer sandbox
Explore our APIs
Showcases
Learning center
Developer sandbox
Go to the developer sandbox for hands-on experience using our client APIs. You can use the APIs with our
sample report or with your own report.
Drag and drop code snippets into the report, or type them directly into the code editor area to see how they
work.
The showcases code is open-sourced, and you can find the code behind all of them in our GitHub repository.
Learning center
The Learning center is a collection of Power BI embedded analytics resources. It's where you can dive into our
documentation, learn about our APIs, find our developer samples and videos, and learn where to get help.
Next steps
Explore the embedded analytics playground
Create an Azure Active Directory tenant to use with
Power BI
11/24/2022 • 2 minutes to read • Edit Online
NOTE
Your initial domain is part of onmicrosoft.com. You can add other domain names later. A tenant directory can have
multiple domains assigned to it.
4. Provide a Display Name and User name for your tenant Global Admin. Leave Director y role as user .
Note the password, then select Create .
5. Sign up for Power BI with the user account that you created in step 4. Go to powerbi.com and select Tr y
Power BI for free .
When you sign up, you're prompted to try Power BI Pro free for 60 days. You can opt into that to become
a Pro user, which gives you the option to start developing an embedded solution.
NOTE
Make sure you sign up with your user account's email address.
Next steps
Now that you have an Azure AD tenant, you can use this tenant to test items within Power BI. You can also
embed Power BI dashboards and reports in your app. For more information, see How to embed your Power BI
dashboards, reports, and tiles.
Register an app
Quickstart: Set up a dev environment
More questions? Try asking the Power BI Community
Set up Power BI Embedded
11/24/2022 • 5 minutes to read • Edit Online
Prerequisite
To set up a Power BI Embedded analytics environment, you need one of the following:
Azure Active directory tenant and an organizational (master) user
Power BI Pro account
NOTE
If you're already signed in, verify that you're signed in with the user you want to use for creating the Azure AD
app. To change users, select the sign out link and once the tool restarts, sign in again
To register your application for your customers, fill in the following fields:
Application Name - Give your application a name.
API access - Select the Power BI APIs (also known as scopes) that your application needs. You can select
Select all to select all the APIs. For more information about Power BI access permissions, see Permissions
and consent in the Microsoft identity platform endpoint.
Select Register . Your Azure AD app Application ID is displayed in the Summary box. Copy this value for later
use.
Step 3 - Create a workspace (optional)
Create a workspace in Power BI service:
If you already have a Power BI workspace, select Skip .
To create a workspace, enter a name for your workspace and select Create workspace . Your Workspace
name and ID appear in the Summary box. Copy these values for later use.
TIP
For the embedded analytics sample app to work as expected, you have to create a workspace using the tool.
NOTE
If you skipped the optional stages, you can still download a sample Power BI app. However, the code in the downloaded
app, will lack the properties that you didn't fill in during registration. For example, if you didn't create a workspace, the
sample app will not include the workspace ID.
Next steps
More questions? Try asking the Power BI Community
Configure credentials programmatically for Power BI
11/24/2022 • 3 minutes to read • Edit Online
NOTE
The calling user must be a dataset owner or a gateway admin. You can also use a service principal. For example, the
service principal can be the dataset owner.
Cloud data sources and their corresponding credentials are managed at the user level.
// Select a datasource
var datasources = pbiClient.Datasets.GetDatasources(datasetId).Value;
var datasource = datasources.First();
2. Build the credentials string according to the Update Datasource Examples. The contents of the credentials
string depends on the type of credentials.
.NET SDK v3
.NET SDK v2
NOTE
If you're using cloud data sources, don't follow the next steps in this section. Call Update Datasource to set the
credentials by using the gateway ID and data source ID that you obtained in step 1.
Use the AsymetricKeyEncr yptor class with the public key retrieved in Step 3 .
// Select a gateway
var gateways = pbiClient.Gateways.GetGateways().Value;
var gateway = gateways.First();
3. Build credential details by following the procedure that is described in the update credentials flow for
data sources section by using the gateway public key that you retrieved in step 2 .
4. Build the request body.
pbiClient.Gateways.CreateDatasource(gateway.Id, request);
Credential types
When you call Create Datasource or Update Datasource from the Power BI REST API on an enterprise on-
premises gateway, encrypt the credentials value by using the gateway public key.
NOTE
.NET SDK v3 can also run the following .NET SDK v2 examples.
// Windows credentials
var credentials = new WindowsCredentials(username: "john", password: "*****");
// Or
// Basic credentials
var credentials = new BasicCredentials(username: "john", password: "*****");
Key credentials
.NET SDK v3
.NET SDK v2
OAuth2 credentials
.NET SDK v3
.NET SDK v2
Anonymous credentials
.NET SDK v3
.NET SDK v2
Troubleshooting
No gateway and data source ID are found when calling get data sources
This issue means that the dataset isn't bound to a gateway. When you create a new dataset, a data source with
no credentials is created automatically on the user's cloud gateway for each cloud connection. The cloud
gateway is used to store the credentials for cloud connections.
After you create the dataset, an automatic binding is created between the dataset and a suitable gateway, which
contains matching data sources for all connections. The automatic binding fails if there's no suitable gateway or
gateways.
If you're using on-premises datasets, create the missing on-premises data sources, and bind the dataset to a
gateway manually by using Bind To Gateway.
To discover gateways that are bindable, use Discover Gateways.
Next steps
Power BI REST APIs
Azure Active Directory permissions
11/24/2022 • 3 minutes to read • Edit Online
When you register your Azure AD app, you grant it permission to access various APIs. As your needs change,
you might want to adjust these permissions. This article shows you how.
NOTE
Azure AD app permissions are only applicable for these scenarios:
Embed for your organization
Embed for your customers with the master user authentication method
In the Azure portal, you can view your app and make changes to its permissions.
1. Sign into the Azure portal.
2. Select your Azure AD tenant by selecting your account in the upper right corner of the page.
3. Select App registrations . If you can't see this option, search for it.
4. From the Owned applications tab, select your app. The application opens in the Overview tab, where
you can review the Application ID.
5. Select the View API permissions tab.
NOTE
For GCC apps, Select the APIs my organization uses tab, and search for either Microsoft Power BI Government
Community Cloud OR fc4979e5-0aa5-429f-b13a-5d1365be5566.
b. Select Delegated Permissions and add or remove the specific permissions you need.
c. When you're done, select Add permissions to save your changes.
8. To remove a permission, follow these steps:
a. Select the ellipsis (...) to the right of the permission.
b. Select Remove permission .
c. In the Remove permission pop-up window, select Yes, remove .
Next steps
Considerations when generating an embed token
Capacity and SKUs in Power BI embedded analytics
Automatically install Power BI apps when
embedding content for your organization
11/24/2022 • 2 minutes to read • Edit Online
Secure embedding
To use automatic application installation, the app creator must install the app. Then the app creator must go to
the app on PowerBI.com, navigate to the report, and get the link. All other users with access to the app that can
use the link can embed the report.
This article provides recommendations for faster rendering of reports, dashboards, and tiles in your application.
NOTE
Remember that loading time mainly depends on elements relevant to the report and data itself, including visuals, the size
of the data, and the complexity of the queries and measures. For more information, see the Power BI optimization guide.
Embed parameters
The powerbi.embed(element, config) method receives an element and a config parameter. The config parameter
includes fields that have performance implications.
Embed URL
Avoid generating the embed URL yourself. Instead, make sure you get the Embed URL by calling Get reports,
Get dashboards, or Get tiles API. The config parameter in the URL is used for performance improvements.
Permissions
Provide View permissions if you don't intend to embed a report in edit mode. This way, time isn't spent
initializing components that are only used in edit mode.
Filters, bookmarks, and slicers
Usually, report visuals are saved with cached data. Reports render the cached data while queries are executed. If
filters, bookmarks, or slicers are provided, cached data isn't used and the visuals are rendered only after the
visual query has ended.
If you embed reports with the same filters, bookmarks, and slicers, save the report with the filters, bookmarks,
and slicers already applied. When you save the report this way, it will render using the cached data that includes
the filters, bookmarks, and slicers, which improves performance.
Multiple visuals
When embedding several visuals from the same report, don't generate a new iFrame for each visual. Use a
single iFrame to render the report with the specified visuals.
When embedding multiple visuals into a single iFrame, consider the following:
Power BI uses iFrames to embed a report. Sometimes you might want to add more content between the
visuals (for example, text or graphics that don't come from the report). In that case, you may need a
different iFrame to render different visuals. For best performance, try and arrange the visuals so that you
use the fewest iFrames possible. To reduce the number of iFrames, please consider using the custom-
layout feature.
If you have visuals from different reports or different datasets, consider joining the datasets and creating
a new report so that you can include all the visuals in the same iFrame.
Another alternative, if you have non-contiguous regions, or data from multiple datasets, is to create a
dashboard and pin the visuals to it. This allows you to:
Embed the individual tiles into non-contiguous iFrames. Dashboard tiles are lighter than reports and
load faster.
Embed the entire dashboard into one iFrame. This allows you to have visuals from different reports or
datasets in one iFrame without creating a new report.
Keep in mind, however, that dashboard tiles aren't interactive and don't refresh with the same frequency
as visuals.
Query caching
Organizations with Power BI Premium capacity or Power BI Embedded capacity can take advantage of query
caching to speed up reports associated with a dataset.
Learn more about query caching in Power BI.
Preload
Use powerbi.preload() to improve the end-user performance. The method powerbi.preload() downloads
JavaScript, css files, and other items, which are used later to embed a report.
Call powerbi.preload() if you're not embedding the report immediately. For example, if the embedded Power BI
content doesn't appear in the home page, use powerbi.preload() to download and cache the items that are used
for embedding the content.
powerbi.bootstrap(element, config) allows you to start embedding before all required parameters are available.
The bootstrap API prepares and initializes the iFrame. When using the bootstrap API, it's still required to call
powerbi.embed(element, config) on the same HTML element.
For example, one of the use cases for this feature, is to run the iFrame bootstrap and the back-end calls for
embedding, in parallel.
TIP
Use the bootstrap API when it's possible to generate the iFrame before it's visible to the end user.
Measure performance
Performance events
To measure embedded performance, you may use two events:
1. Loaded event: The time until the report is initialized (the Power BI logo will disappear when the load is
finished).
2. Rendered event: The time until the report is fully rendered, using the actual data. The rendered event is fired
each time the report is re-rendered (for example, after applying filters). To measure a report, make sure you
do the calculations on the first raised event.
Cached data is rendered when available but no other event is generated.
Learn more about event handling.
Performance Analyzer
To examine the performance of the report elements, you might use the Performance Analyzer in Power BI
Desktop. The Performance Analyzer will allow you to see and record logs that measure how each of your report
elements performs.
Learn more about Performance Analyzer.
NOTE
Always remember to compare the embedded report performance to the performance on powerbi.com. This might help
you understand the origin of your performance issues
Next steps
Power BI optimization guide
How to troubleshoot Power BI embedded analytics issues
Power BI embedded analytics FAQ
Monitor Power BI Embedded
11/24/2022 • 5 minutes to read • Edit Online
When you have critical applications and business processes relying on Azure resources, you want to monitor
those resources for their availability, performance, and operation. This article describes the monitoring data
generated by Power BI Embedded and how you can use the features of Azure Monitor to analyze and alert on
this data.
TIP
You can also use the Premium Gen2 Monitoring App to monitor your Embedded Gen 2 capacity.
Monitor overview
The Over view page in the Azure portal for each Power BI Embedded instance, includes the following
information:
Resource group - The resource group the instance belongs to
Status - The status of your Power BI Embedded instance
Location - The location of your Power BI Embedded instance
Resource name - The name of your Power BI Embedded instance
SKU - The SKU your Power BI Embedded instance is using
Subscription name - Your Power BI Embedded instance subscription name
Subscription ID - Your Power BI Embedded instance subscription ID
Monitoring data
Power BI Embedded collects the same kinds of monitoring data as other Azure resources that are described in
Monitoring data from Azure resources.
See Monitoring Power BI Embedded data reference for detailed information on the metrics and logs metrics
created by Power BI Embedded.
Collection and routing
Platform metrics and the Activity log are collected and stored automatically, but can be routed to other locations
by using a diagnostic setting.
Resource Logs are not collected and stored until you create a diagnostic setting and route them to one or more
locations.
See Create diagnostic setting to collect platform logs and metrics in Azure for the detailed process for creating a
diagnostic setting using the Azure portal, CLI, or PowerShell. When you create a diagnostic setting, you specify
which categories of logs to collect. The categories for Power BI Embedded are listed in Power BI Embedded
monitoring data reference.
Using PowerShell to enable diagnostics
To enable metrics and diagnostics logging by using PowerShell, use the commands listed below. To learn more
about using PowerShell to enable diagnostics, see Create and configure a Log Analytics workspace in Azure
Monitor using PowerShell.
To enable storage of diagnostics logs in a storage account, use this command:
Set-AzDiagnosticSetting -ResourceId [your resource id] -StorageAccountId [your storage account id] -
Enabled $true
The storage account ID is the resource ID for the storage account where you want to send the logs.
To enable streaming of diagnostics logs to an event hub, use this command:
Set-AzDiagnosticSetting -ResourceId [your resource id] -ServiceBusRuleId [your service bus rule id] -
Enabled $true
To enable sending diagnostics logs to a Log Analytics workspace, use this command:
You can obtain the resource ID of your Log Analytics workspace by using the following command:
(Get-AzOperationalInsightsWorkspace).ResourceId
Analyzing metrics
You can analyze metrics for Power BI Embedded with metrics from other Azure services using metrics explorer
by opening Metrics from the Azure Monitor menu. See Getting started with Azure Metrics Explorer for details
on using this tool.
For a list of the platform metrics collected for Power BI Embedded, see Monitoring Power BI Embedded data
reference metrics
For reference, you can see a list of all resource metrics supported in Azure Monitor.
Analyzing logs
Data in Azure Monitor Logs is stored in tables where each table has its own set of unique properties.
All resource logs in Azure Monitor have the same fields followed by service-specific fields. The common schema
is outlined in Azure Monitor resource log schema The schema for Power BI Embedded resource logs is found in
the Power BI Embedded Data Reference.
The Activity log is a platform login Azure that provides insight into subscription-level events. You can view it
independently or route it to Azure Monitor Logs, where you can do much more complex queries using Log
Analytics.
For a list of the types of resource logs collected for Power BI Embedded, see Monitoring Power BI Embedded
data reference
For a list of the tables used by Azure Monitor Logs and queryable by Log Analytics, see Monitoring Power BI
Embedded data reference
Sample Kusto queries
IMPORTANT
When you select Logs from the Power BI Embedded menu, Log Analytics is opened with the query scope set to the
current Power BI Embedded resource. This means that log queries will only include data from that resource. If you want to
run a query that includes data from other Power BI Embedded resource or data from other Azure services, select Logs
from the Azure Monitor menu. See Log query scope and time range in Azure Monitor Log Analytics for details.
Here is an example of a query that is completed in less than five minutes (300,000 milliseconds).
search *
| where Type == "AzureDiagnostics"
| where ( OperationName == "QueryEnd" )
| where toint(Duration_s) < 300000
Alerts
Azure Monitor alerts proactively notify you when important conditions are found in your monitoring data. They
allow you to identify and address issues in your system before your customers notice them. You can set alerts
on metrics, logs, and the activity log.
Next steps
You can learn more about Azure resource diagnostic logging.
Monitoring Power BI Embedded data reference
Monitoring Azure resources with Azure Monitor
Embed Power BI content with service principal and
an application secret
11/24/2022 • 6 minutes to read • Edit Online
Service principal is an authentication method that can be used to let an Azure AD application access Power BI
service content and APIs.
When you create an Azure Active Directory (Azure AD) app, a service principal object is created. The service
principal object, also known simply as service principal, allows Azure AD to authenticate your app. Once
authenticated, the app can access Azure AD tenant resources.
To authenticate, the service principal uses the Azure AD app's Application ID, and one of the following:
Certificate
Application secret
This article describes service principal authentication using Application ID and Application secret.
NOTE
Azure AD recommends that you secure your backend services using certificates, rather than secret keys.
Learn more about getting access tokens from Azure AD using secret keys or certificates.
To secure your solution using a certificate, complete the instructions in this article and then follow the steps described
in Embed Power BI content with service principal and a certificate.
Method
To use service principal and an application ID embedded analytics, follow these steps:
1. Create an Azure AD app.
a. Create the Azure AD app's secret.
b. Get the app's Application ID and Application secret.
NOTE
These steps are described in step 1 . For more information about creating an Azure AD app, see create an Azure
AD app.
9. In the Add a client secret window, enter a description, specify when you want the client secret to expire,
and click Add .
10. Copy and save the Client secret value.
NOTE
After you leave this window, the client secret value will be hidden, and you'll not be able to view or copy it again.
NOTE
If you want to enable service principal access for the entire organization, skip this step.
# Required to sign in as admin
Connect-AzureAD
Enable the Allow ser vice principals to use Power BI APIs switch either for the entire organization or
for the specific security group you created in Azure AD.
IMPORTANT
Service principals have access to any tenant settings they're enabled for. Depending on your admin settings, this
includes specific security groups or the entire organization.
To restrict service principal access to specific tenant settings, allow access only to specific security groups.
Alternatively, you can create a dedicated security group for service principals, and exclude it from the desired
tenant settings.
NOTE
This section provides UI instructions. You can also add a service principal or a security group to a workspace, using the
Groups - add group user API.
1. Scroll to the workspace you want to enable access for, and from the More menu, select Workspace
access .
Login-PowerBI
NOTE
To secure your content using a certificate, follow the steps described in Embed Power BI content with service principal and
a certificate.
Next steps
Register an app
Power BI Embedded for your customers
Application and service principal objects in Azure Active Directory
Embed Power BI content with service principal and
a certificate
11/24/2022 • 3 minutes to read • Edit Online
Certificate-based authentication enables you to be authenticated by Azure Active Directory (Azure AD) with a
client certificate. The client certificate can be on a Windows, Android or iOS device, or kept in an Azure Key Vault.
Using this method of authentication allows managing certificates from a central place, using the CA, for rotation
or revocation.
You can learn more about certificates in Azure AD in the Client credential flows GitHub page.
Method
1. Embed your content with service principal.
2. Create a certificate.
3. Set up certificate authentication.
4. Get the certificate from Azure Key Vault.
5. Authenticate using service principal and a certificate.
NOTE
If you already have content that's embedded using a service principal, skip this step and advance to step 2.
2. Select Upload cer tificate and upload the .cer file you created and downloaded in step 2 of this tutorial.
The .cer file contains the public key.
certificate = keyVaultClient.GetCertificateAsync($"https://{KeyVaultName}.vault.azure.net/",
certName).Result;
secret = keyVaultClient.GetSecretAsync(certificate.SecretIdentifier.Identifier).Result;
NOTE
If you already have a certificate created by your organization, upload the .pfx file to Azure Key Vault.
NOTE
The user that signs into Visual Studio has to have Azure Key Vault permissions to get the certificate.
4. Add the account that has access to your Azure Key Vault.
Next steps
Register an app
Power BI Embedded for your customers
Application and service principal objects in Azure Active Directory
Row-level security using on-premises data gateway with service principal
Tutorial: Embed Power BI content using a sample
embed for your customers' application
11/24/2022 • 16 minutes to read • Edit Online
Embedded analytics and Power BI Embedded (the Azure offer) allow you to embed Power BI content such
as reports, dashboards and tiles, into your application.
In this tutorial, you'll learn how to:
Set up your embedded environment.
Configure an embed for your customers (also known as app owns data) sample application.
To use your application, your users won't need to sign in to Power BI or have a Power BI license.
We recommend using the embed for your customers method to embed your Power BI content, if you're an
independent software vendor (ISV) or a developer, who wants to create applications for third parties.
IMPORTANT
If you are embedding content for a national cloud, the first few steps of this tutorial are different. See Embed content for
national clouds for details.
Prerequisites
Before you start this tutorial, verify that you have both the Power BI and code dependencies listed below:
Power BI dependencies
Your own Azure Active Directory tenant.
To authenticate your app against Power BI, you'll need one of the following:
Service principal - An Azure Active Directory (Azure AD) service principal object that allows
Azure AD to authenticate your app.
Power BI Pro license - This will be your master user and your app will use it to
authenticate to Power BI.
A Power BI Premium Per User (PPU) license - This will be your master user and your app
will use it to authenticate to Power BI.
NOTE
To move to production you'll need a capacity.
Code dependencies
.NET Core
.NET Framework
Java
Node JS
Python
Method
To create an embed for your customers sample app, follow these steps:
1. Select your authentication method.
2. Register an Azure AD application.
3. Create a Power BI workspace.
4. Create and publish a Power BI report.
5. Get the embedding parameter values.
6. Service principal API access
7. Enable workspace access.
8. Embed your content.
Mechanism Your Azure AD app's service principal Your Azure AD app uses the
object allows Azure AD to authenticate credentials (username and password)
your embedded solution app against of a Power BI user, to authenticate
Power BI. against Power BI.
Power BI service access You can't access Power BI service with You can access Power BI service with
a service principal. your master user credentials.
License Doesn't require a Pro license. You can Requires a Power BI Pro or Premium
use content from any workspace that Per User (PPU) license.
you're a member or an admin of.
NOTE
Before registering your application, you'll need to decide which authentication method to use, service principal or master
user.
TIP
If you already have a workspace, you can skip this step.
To create a workspace, do the following:
1. Sign in to Power BI.
2. Select Workspaces .
3. Select Create a workspace .
4. Name your workspace and select Save .
TIP
If you already have a workspace with a report, you can skip this step.
To download a sample report and publish it to your workspace, follow these steps:
1. Open the GitHub Power BI Desktop samples folder.
2. Select Code and then select Download zip .
3. Extract the downloaded ZIP and navigate to the Samples Repor ts folder.
4. Select a report to embed, and publish it to your workspace.
Client ID
Workspace ID
Report ID
Client secret
Tenant ID
Power BI username
Power BI password
Client ID
TIP
Applies to: Service principal Master user
To get the client ID GUID (also know as application ID), follow these steps:
1. Log into Microsoft Azure.
2. Search for App registrations and select the App registrations link.
3. Select the Azure AD app you're using for embedding your Power BI content.
4. From the Over view section, copy the Application (client) ID GUID.
Workspace ID
TIP
Applies to: Service principal Master user
Alternatively, you can find the workspace ID in the Admin por tal settings by selecting Details next to the
workspace name.
Report ID
TIP
Applies to: Service principal Master user
Client secret
TIP
Applies to: Service principal Master user
NOTE
Make sure you copy the client secret value when it first appears. After navigating away from this page, the client secret
will be hidden and you'll not be able to retrieve its value.
Tenant ID
TIP
Applies to: Service principal Master user
TIP
Applies to: Service principal Master user
Obtain the username and password of the Power BI user you're using as your master user . This is the same
user you used to create a workspace and upload a report to, in Power BI service.
For an Azure AD app to be able to access the Power BI content and APIs, a Power BI admin needs to enable
service principal access in the Power BI admin portal. If you're not the admin of your tenant, get the tenant's
admin to enable the Tenant settings for you.
1. In Power BI service, select Settings > Settings > Admin por tal .
2. Select Tenant settings and then scroll down to the Developer settings section.
3. Expand Allow ser vice principals to use Power BI APIs , and enable this option.
NOTE
When using a service principal, it's recommended to limit its access to the tenant settings using a security group. To learn
more about this feature, see these sections in the service principal article:
Create an Azure AD security group
Enable the Power BI service admin settings
Step 7 - Enable workspace access
To enable your Azure AD app access objects such as reports, dashboards and datasets in the Power BI service,
add the service principal or master user, as a member or admin to your workspace.
1. Sign in to Power BI service.
2. Scroll to the workspace you want to enable access for, and from the More menu, select Workspace
access .
3. In the Access pane, depending on which authentication method you're using, copy the service principal
or master user to the Enter email address text box.
NOTE
If you're using a service principal, its name is the name you gave your Azure AD app.
4. Select Add .
NOTE
The embed for your customers sample applications only support the frameworks listed above. The React sample
application only supports the embed for your organization solution.
.NET Core
.NET Framework
Java
Node JS
Python
6. Open the embed for your customers sample app using one of these methods:
If you're using Visual Studio, open the AppOwnsData.sln file.
If you're using Visual Studio Code, open the AppOwnsData folder.
7. Open appsettings.json .
8. Depending on your authentication method, fill in the following parameter values:
PA RA M ET ER SERVIC E P RIN C IPA L M A ST ER USER
WorkspaceId The ID of the workspace with your The ID of the workspace with your
embedded report, see Workspace embedded report, see Workspace
ID ID
IMPORTANT
If you used free embed trial tokens for development, you must buy a capacity for production. Until a capacity is
purchased, the Free trial version banner will continue to appear at the top of the embedded report.
Next steps
Move to production
Embed for your organization
Embed paginated reports
Ask the Power BI Community
Tutorial: Embed Power BI content using a sample
embed for your organization application
11/24/2022 • 9 minutes to read • Edit Online
Power BI embedded analytics allows you to embed Power BI content such as reports, dashboards and tiles, into
your application.
In this tutorial, you'll learn how to:
Set up your embedded environment.
Configure an embed for your organization (also known as user owns data) sample application.
To use your application, your users will need to sign in to Power BI.
The embed for your organization solution is usually used by enterprises and big organizations, and is intended
for internal users.
IMPORTANT
If you are embedding content for a national cloud, the first few steps of this tutorial are different. See Embed content for
national clouds for details.
NOTE
The .NET Core and the .NET Framework samples will allow the end user to view any Power BI dashboard, report or tile
they have access to in Power BI service. The React TypeScript sample lets you embed only one report that your end user
already has access to on Power BI service.
Prerequisites
Before you start this tutorial, verify that you have both the Power BI and code dependencies listed below:
Power BI dependencies
Your own Azure Active Directory tenant.
One of the following licenses:
Power BI Pro
Premium Per User (PPU)
NOTE
To move to production you'll need one of the following configurations:
All users with Pro licenses.
All users with PPU licenses.
A P or EM capacity. This configuration allows all users to have free licenses.
Code dependencies
.NET Core
.NET Framework
React TypeScript
Method
To create an embed for your organization sample app, follow these steps:
1. Register an Azure AD application.
2. Create a Power BI workspace.
3. Create and publish a Power BI report.
4. Get the embedding parameter values.
5. Embed your content.
TIP
If you already have a workspace, you can skip this step.
To create a workspace, do the following:
1. Sign in to Power BI.
2. Select Workspaces .
3. Select Create a workspace .
4. Name your workspace and select Save .
TIP
If you already have a workspace with a report, you can skip this step.
To download a sample report and publish it to your workspace, follow these steps:
1. Open the GitHub Power BI Desktop samples folder.
2. Select Code and then select Download zip .
3. Extract the downloaded ZIP and navigate to the Samples Repor ts folder.
4. Select a report to embed, and publish it to your workspace.
Client ID
Client secret
Workspace ID
Report ID
Client ID
TIP
Applies to: .NET Core .NET Framework React TypeScript
To get the client ID GUID (also know as application ID), follow these steps:
1. Log into Microsoft Azure.
2. Search for App registrations and select the App registrations link.
3. Select the Azure AD app you're using for embedding your Power BI content.
4. From the Over view section, copy the Application (client) ID GUID.
Client secret
TIP
Applies to: .NET Core .NET Framework React TypeScript
NOTE
Make sure you copy the client secret value when it first appears. After navigating away from this page, the client secret
will be hidden and you'll not be able to retrieve its value.
Workspace ID
TIP
Applies to: .NET Core .NET Framework React TypeScript
Report ID
TIP
Applies to: .NET Core .NET Framework ReactTypeScript
NOTE
The embed for your organization sample applications only support the frameworks listed above. The Java, Node JS
and Python sample applications, only support the embed for your customers solution.
.NET Core
.NET Framework
React TypeScript
NOTE
If you don't have a Web platform, select Add a platform and in the Configure platforms window, select Web .
NOTE
During your first sign in, you'll be prompted to allow Azure AD permissions for the app.
3. When the embedding sample application loads, select the Power BI content you want to embed and then
select Embed .
Next steps
Embed for your customers
Embed paginated reports
Ask the Power BI Community
Tutorial: Embed Power BI content into your
application for national clouds
11/24/2022 • 3 minutes to read • Edit Online
Learn how to embed analytical content within your business process applications for the national cloud. You can
use the Power BI .NET SDK with the Power BI JavaScript API to embed a report, dashboard, or tile, into your web
applications.
Power BI supports the following national clouds:
U.S. Government Community Cloud (GCC)
U.S. Government Community Cloud High (GCC High)
U.S. Military Contractors (DoDCON)
U.S. Military (DoD)
Power BI for China cloud
To get started with this walkthrough, you need a Power BI account . If you don't have an account set up, then
depending on the type of government or country/region you can choose the right national cloud for you. You
can sign up for a U. S. government Power BI account, or a Power BI for China cloud account.
NOTE
Looking to embed a dashboard for your organization instead? See, Integrate a dashboard into an app for your
organization.
To integrate a dashboard into a web app, you use the Power BI API, and an Azure Active Directory (AD)
authorization access token to get a dashboard. Then, you load the dashboard using an embed token. The
Power BI API provides programmatic access to specific Power BI resources. For more information, see Power
BI REST API, Power BI .NET SDK, and the Power BI JavaScript API.
Download the sample
This article shows the code used in the App Owns Data sample on GitHub. To follow along with this
walkthrough, you can download the sample. We'll be using the .NET Framework/Embed for your customers
directory.
IMPORTANT
Embedding Power BI content from a Government Community Cloud (GCC), can only be done with a Microsoft 365 SKU.
Other national cloud customers can use Microsoft 365 or Azure SKUs.
Military (DoD):
1. Update applicationId (Native app applicationId), workspaceId, the username (your master user),
and password in Web.config file.
2. Add the DoDCON parameters in the web.config file as follows.
If you downloaded the Embedding for your customer sample, you would use the applicationId you get, so that
the sample can authenticate to Azure AD. To configure the sample, change the applicationId in the web.config
file.
You can see examples of these access tokens within each content item task in the
Controllers\HomeController.cs file.
Next steps
Embedding for your customers sample
Power BI JavaScript API
More questions? Try asking the Power BI Community
Tutorial: Embed a Power BI report in an application
for your customers
11/24/2022 • 12 minutes to read • Edit Online
In this tutorial, you learn how to embed a Power BI report in a .NET 5.0 application, as part of the embed-for-
your-customers (also known as an app-owns-data) solution. In an embed-for-your-customers solution, your app
users don't need to sign in to Power BI or have a Power BI license.
In this tutorial, you learn how to embed:
A Power BI report.
In an embed-for-your-customers app.
By using a service principal.
By using .NET 5.0.
With the Microsoft.Identity.Web library (this library is also supported in .NET Core).
NOTE
The full solution used in this tutorial is available from the DOTNET5-AppOwnsData-Tutorial GitHub repository.
Prerequisites
A Power BI Pro or Premium Per User (PPU) license
A Power BI workspace with a report
Your own Azure Active Directory (Azure AD) tenant
An Azure AD app
A .NET Core 5 model view controller (MVC) app
.NET Core 5 SDK or later
An integrated development environment (IDE). We recommend one of the following IDEs:
Visual Studio.
Visual Studio Code with the C# extension
Resources
In this tutorial, you use:
Power BI REST Reports API, to embed the URL and retrieve the embed token.
Microsoft Identity Web authentication library.
Power BI embedded analytics Client APIs, to embed the report.
Method
To embed Power BI content in an embed-for-your-customers solution, follow these steps:
1. Configure your Azure AD app and service principal.
2. Get the embedding parameter values.
3. Add the required NuGet packages.
4. Enable server side authentication.
5. Build your app's client side.
6. Run your application.
NOTE
To embed content for a user on a different tenant (guest user), you need to adjust the authorityUri parameter.
Client ID
To get the client ID GUID (also know as application ID), follow these steps:
1. Log into Microsoft Azure.
2. Search for App registrations and select the App registrations link.
3. Select the Azure AD app you're using for embedding your Power BI content.
4. From the Over view section, copy the Application (client) ID GUID.
Client secret
To get the client secret, follow these steps:
1. Log into Microsoft Azure.
2. Search for App registrations and select the App registrations link.
3. Select the Azure AD app you're using for embedding your Power BI content.
4. Under Manage , select Cer tificates & secrets .
5. Under Client secrets , select New client secret .
6. In the Add a client secret pop-up window, provide a description for your application secret, select when
the application secret expires, and select Add .
7. From the Client secrets section, copy the string in the Value column of the newly created application
secret. The client secret value is your client ID.
NOTE
Make sure you copy the client secret value when it first appears. After navigating away from this page, the client secret
will be hidden and you'll not be able to retrieve its value.
Workspace ID
To get the workspace ID GUID, follow these steps:
1. Sign in to Power BI service.
2. Open the report you want to embed.
3. Copy the GUID from the URL. The GUID is the number between /groups/ and /repor ts/ .
NOTE
To get the workspace ID programmatically, use the Get Groups API.
Report ID
To get the report ID GUID, follow these steps:
1. Sign in to Power BI service.
2. Open the report you want to embed.
3. Copy the GUID from the URL. The GUID is the number between /repor ts/ and /Repor tSection .
NOTE
To get the report ID programmatically, use the Get Reports In Group API.
F IL E USE
Modify the code in Startup.cs to properly initialize the authentication service provided by
Microsoft.Identity.Web .
NOTE
The code in ConfigureServices accomplishes several important things:
1. The call to AddMicrosoftWebAppCallsWebApi configures the Microsoft authentication library to acquire access tokens
(Azure AD tokens).
2. The call to AddInMemoryTokenCaches configures a token cache that the Microsoft authentication library uses to cache
access tokens and refresh tokens behind the scenes.
3. The call to services.AddScoped(typeof(PowerBiServiceApi)) configures the PowerBiServiceApi class as a service
class that can be added to other classes by using dependency injection.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;
using Microsoft.AspNetCore.Authorization;
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.UI;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.HttpsPolicy;
using Microsoft.AspNetCore.Mvc.Authorization;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using AppOwnsData.Services;
namespace AppOwnsData
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services) {
services.AddMicrosoftIdentityWebAppAuthentication(Configuration)
.EnableTokenAcquisitionToCallDownstreamApi()
.AddInMemoryTokenCaches();
services.AddScoped(typeof(PowerBiServiceApi));
services.AddControllersWithViews(options => {
var policy = new AuthorizationPolicyBuilder()
.RequireAuthenticatedUser()
.Build();
options.Filters.Add(new AuthorizeFilter(policy));
});
services.AddRazorPages()
.AddMicrosoftIdentityUI();
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
// The default HSTS value is 30 days. You might want to change this for production
scenarios. See https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
endpoints.MapRazorPages();
});
}
}
}
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"Domain": "yourtenant.onMicrosoft.com",
"TenantId": "",
"ClientId": "",
"ClientSecret": "",
"CallbackPath": "/signin-oidc",
"SignedOutCallbackPath": "/signout-callback-oidc"
},
"PowerBi": {
"ServiceRootUrl": "https://api.powerbi.com/"
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
3. Fill in the embedding parameter values obtained from Step 2 - Get the embedding parameter values.
Domain - Domain and tenant ID
TenantId - Domain and tenant ID
ClientId - Client ID
ClientSecret - Client secret
NOTE
In the preceding code, the PowerBi:ServiceRootUrl parameter is added as a custom configuration value to track the
base URL to the Power BI service. When you program against the Power BI service in the Microsoft public cloud, the URL
is https://api.powerbi.com/ . However, the root URL for the Power BI service is different in other clouds, such as the
government cloud. Therefore, the custom configuration value is stored as a project configuration value, so you can
change it as needed.
Get the Azure AD access token and call the Power BI service
In order to embed Power BI content like reports and dashboards, your app needs to get an Azure AD token. To
get the token, you need a configuration object.
The code in this section uses the .NET Core dependency injection pattern. When your class needs to use a
service, you can add a constructor parameter for that service. The .NET Core runtime takes care of passing the
service instance at run time. In this case, the constructor injects an instance of the .NET Core configuration
service by using the IConfiguration parameter, which is used to retrieve the PowerBi:ServiceRootUrl
configuration value from appsettings.json. The ITokenAcquisition parameter, which is named tokenAcquisition ,
holds a reference to the Microsoft authentication service provided by the Microsoft.Identity.Web library. The
ITokenAcquisition parameter is used to acquire access tokens from Azure AD.
The RequiredScopes field holds a string array that contains a set of delegated permissions supported by the
Power BI service API. When your application calls across the network to acquire an Azure AD token, it passes this
set of delegated permissions so that Azure AD can include them in the access token it returns.
NOTE
Verify that your Azure AD app is configured with the scopes required by your web app. For more information, see Change
your Azure AD app's permissions.
using System;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.Extensions.Configuration;
using Microsoft.Identity.Web;
using Microsoft.Rest;
using Microsoft.PowerBI.Api;
using Microsoft.PowerBI.Api.Models;
using Newtonsoft.Json;
namespace AppOwnsData.Services {
// A view model class to pass the data needed to embed a single report
public class EmbeddedReportViewModel {
public string Id;
public string Name;
public string EmbedUrl;
public string Token;
}
}
}
namespace AppOwnsData.Controllers
{
[Authorize]
public class HomeController : Controller
{
private PowerBiServiceApi powerBiServiceApi;
[AllowAnonymous]
public IActionResult Index()
{
return View();
}
// Replace these two GUIDs with the workspace ID and report ID you recorded earlier.
Guid workspaceId = new Guid("11111111-1111-1111-1111-111111111111");
Guid reportId = new Guid("22222222-2222-2222-2222-222222222222");
return View(viewModel);
}
[AllowAnonymous]
[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
public IActionResult Error()
{
return View(new ErrorViewModel { RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier
});
}
}
}
F IL E USE
@model AppOwnsData.Services.EmbeddedReportViewModel;
@section Scripts {
<!-- powerbi.min.js is the JavaScript file that loads the client-side Power BI JavaScript API
library.
Make sure that you're working with the latest library version.
You can check the latest library available in https://cdnjs.com/libraries/powerbi-client -->
<script src="https://cdn.jsdelivr.net/npm/powerbi-client@2.18.0/dist/powerbi.min.js"></script>
<!-- This script creates a JavaScript object named viewModel which is accessible to the
JavaScript code in embed.js. -->
<script>
var viewModel = {
reportId: "@Model.Id",
embedUrl: "@Model.EmbedUrl",
token: "@Model.Token"
};
</script>
<!-- This script specifies the location of the embed.js file -->
<script src="~/js/embed.js"></script>
}
The powerbi.embed function uses the models configuration object to embed your report.
1. In the wwwroot /js folder, create a file called embed.js.
2. Add the following code to the embed.js file.
$(function () {
// 1 - Get DOM object for the div that's the report container.
var reportContainer = document.getElementById("embed-container");
var config = {
type: 'report',
id: reportId,
embedUrl: embedUrl,
accessToken: token,
permissions: models.Permissions.All,
tokenType: models.TokenType.Embed,
viewMode: models.ViewMode.View,
settings: {
panes: {
filters: { expanded: false, visible: true },
pageNavigation: { visible: false }
}
}
};
});
IMPORTANT
If you used free embed trial tokens for development, you must buy a capacity for production. Until a capacity is
purchased, the Free trial version banner continues to appear at the top of the embedded report.
When your app is ready, you can move your embedded app to production.
Next steps
Embedded analytics application tokens
Move your embedded app to production
Capacity and SKUs in Power BI embedded analytics
Capacity planning in Power BI embedded analytics
Tutorial: Embed a Power BI report in an application
for your organization
11/24/2022 • 12 minutes to read • Edit Online
In this tutorial, you'll learn how to embed a Power BI report in a .NET 5.0 application, as part of the embed for
your organization (also known as user owns data) solution. In an embed for your organization solution, your
app users need to authenticate against Power BI with their own credentials.
In this tutorial, you'll learn how to embed:
A Power BI report
In an embed for your organization app
Using .NET 5.0
With the Microsoft.Identity.Web library (this library is also supported in .NET Core)
NOTE
The full solution used in this tutorial, is available from the DOTNET5-UserOwnsData-Tutorial GitHub repository.
Prerequisites
A Power BI Pro or Premium Per User (PPU) license.
NOTE
The embed for your organization solution, is not supported on capacities based on A SKUs. An A SKU can only be
used for the embed for your customers solution.
Resources
In this tutorial, you'll use:
Power BI REST Reports API - to embed the URL and retrieve the embed token.
Microsoft Identity Web authentication library.
Power BI embedded analytics Client APIs - to embed the report.
Method
To embed Power BI content in an embed for your organization solution, follow these steps:
1. Configure your Azure AD app.
2. Get the embedding parameter values.
3. Add the required NuGet packages
4. Enable server side authentication.
5. Build your app's client side.
6. Run your application
NOTE
To embed content for a user on a different tenant (a guest user), you need to adjust the authorityUri parameter.
Client ID
To get the client ID GUID (also know as application ID), follow these steps:
1. Log into Microsoft Azure.
2. Search for App registrations and select the App registrations link.
3. Select the Azure AD app you're using for embedding your Power BI content.
4. From the Over view section, copy the Application (client) ID GUID.
Client secret
To get the client secret, follow these steps:
1. Log into Microsoft Azure.
2. Search for App registrations and select the App registrations link.
3. Select the Azure AD app you're using for embedding your Power BI content.
4. Under Manage , select Cer tificates & secrets .
5. Under Client secrets , select New client secret .
6. In the Add a client secret pop-up window, provide a description for your application secret, select when
the application secret expires, and select Add .
7. From the Client secrets section, copy the string in the Value column of the newly created application
secret. The client secret value is your client ID.
NOTE
Make sure you copy the client secret value when it first appears. After navigating away from this page, the client secret
will be hidden and you'll not be able to retrieve its value.
Workspace ID
To get the workspace ID GUID, follow these steps:
1. Sign in to Power BI service.
2. Open the report you want to embed.
3. Copy the GUID from the URL. The GUID is the number between /groups/ and /repor ts/ .
NOTE
To get the workspace ID programmatically, use the Get Groups API.
Report ID
To get the report ID GUID, follow these steps:
1. Sign in to Power BI service.
2. Open the report you want to embed.
3. Copy the GUID from the URL. The GUID is the number between /repor ts/ and /Repor tSection .
NOTE
To get the report ID programmatically, use the Get Reports In Group API.
If your app previously used Microsoft.AspNetCore to authenticate, remove this package from your project by
typing:
F IL E USE
Modify the code in Star tup.cs to properly initialize the authentication service provided by
Microsoft.Identity.Web .
Add the code snippet below to your app's Star tup.cs file.
NOTE
The code in ConfigureServices accomplishes several important things:
1. The call to AddMicrosoftWebAppCallsWebApi configures the Microsoft authentication library to acquire access tokens
(Azure AD tokens).
2. The call to AddInMemoryTokenCaches configures a token cache that the Microsoft authentication library will use to
cache access tokens and refresh tokens behind the scenes
3. The call to services.AddScoped(typeof(PowerBiServiceApi)) configures the PowerBiServiceApi class as a service
class that can be added to other classes using dependency injection.
using Microsoft.Identity.Web;
using Microsoft.Identity.Web.TokenCacheProviders;
using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
using Microsoft.Identity.Web.UI;
using UserOwnsData.Services;
namespace UserOwnsData {
// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices (IServiceCollection services) {
services
.AddMicrosoftIdentityWebAppAuthentication(Configuration)
.EnableTokenAcquisitionToCallDownstreamApi(PowerBiServiceApi.RequiredScopes)
.AddInMemoryTokenCaches();
mvcBuilder.AddMicrosoftIdentityUI();
services.AddRazorPages();
}
}
}
3. Fill in the embedding parameter values obtained from Step 2 - Get the embedding parameter values.
Domain - Domain and tenant ID
TenantId - Domain and tenant ID
ClientId - Client ID
ClientSecret - Client secret
NOTE
In the code snippet above, the PowerBi:ServiceRootUrl parameter is added as a custom configuration value to track
the base URL to the Power BI service. When programming against the Power BI service in the Microsoft public cloud, the
URL is https://api.powerbi.com/. However, the root URL for the Power BI service will be different in other clouds such as
the government cloud. Therefore, this value is stored as a project configuration value so it is easy to change when
required.
Get the Azure AD access token and call the Power BI service
In order to embed Power BI content (such as reports and dashboards), your app needs to get an Azure AD token.
To get the token, you need a configuration object.
The code in this section uses the .NET Core dependency injection pattern. When your class needs to use a
service, you can add a constructor parameter for that service and the .NET Core runtime takes care of passing
the service instance at run time. In this case, the constructor is injecting an instance of the .NET Core
configuration service using the IConfiguration parameter, which is used to retrieve the PowerBi:ServiceRootUrl
configuration value from appsettings.json . The ITokenAcquisition parameter, which is named
tokenAcquisition holds a reference to the Microsoft authentication service provided by the
Microsoft.Identity.Web library and will be used to acquire access tokens from Azure AD.
The RequiredScopes field holds a string array containing a set of delegated permissions supported by the Power
BI service API. When your application calls across the network to acquire an Azure AD token, it will pass this set
of delegated permissions so that Azure AD can include them in the access token it returns.
NOTE
Verify that your Azure AD app is configured with the scopes required by your web app. For more information, see Change
your Azure AD app's permissions.
namespace UserOwnsData.Services {
// A view model class to pass the data needed to embed a single report.
public class EmbeddedReportViewModel {
public string Id;
public string Name;
public string EmbedUrl;
public string Token;
}
namespace UserOwnsData.Controllers {
[Authorize]
public class HomeController : Controller {
[AllowAnonymous]
public IActionResult Index() {
return View();
}
[AllowAnonymous]
[ResponseCache (Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
public IActionResult Error() {
return View (new ErrorViewModel { RequestId = Activity.Current?.Id ??
HttpContext.TraceIdentifier });
}
}
}
F IL E USE
@section Scripts {
<!-- powerbi.min.js is the JavaScript file that loads the client-side Power BI JavaScript API
library.
Make sure that you're working with the latest library version.
You can check the latest library available in https://cdnjs.com/libraries/powerbi-client -->
<script src="https://cdn.jsdelivr.net/npm/powerbi-client@2.21.0/dist/powerbi.min.js"></script>
<!-- This script creates a JavaScript object named viewModel which is accessible to the
JavaScript code in embed.js. -->
<script>
var viewModel = {
reportId: "@Model.Id",
embedUrl: "@Model.EmbedUrl",
token: "@Model.Token"
};
</script>
<!-- This script specifies the location of the embed.js file -->
<script src="~/js/embed.js"></script>
}
});
Next steps
Embedded analytics application tokens
Move your embedded app to production
Capacity and SKUs in Power BI embedded analytics
Capacity planning in Power BI embedded analytics
Embed Power BI paginated reports
11/24/2022 • 6 minutes to read • Edit Online
With Power BI embedded analytics, you can create Power BI content that displays paginated reports in a fully
integrated and interactive application. Embed paginated reports using the solution that works best for you,
embed for your customers or embed for your organization.
This article describes how to embed paginated reports using the embedding sample tutorials.
Prerequisites
To get started, you're required to have:
A service principal
Your own Azure Active Directory tenant setup
A capacity, with paginated reports workload enabled
NOTE
You only need to enable this workload with Power BI Premium Gen1 capacities.
If you don't have an Azure subscription, create a free account before you begin.
Method
To embed a paginated report using the sample app, follow these steps:
1. Create a workspace.
2. Create a capacity.
3. Assign a workspace to a capacity.
4. Enable paginated reports workload.
5. Create and upload your paginated report.
6. Embed content using the sample application.
As you're using a service principal to sign into your application, you'll need to create a workspace.
Your service principal must also be an admin or member of the Power BI workspaces.
Step 2 - Create a capacity
Embed for your customers
Embed for your organization
Before you import or upload a paginated report to embed, the workspace containing the report must be
assigned to a capacity. There are two types of capacity you can choose from:
Power BI Premium - For embedding a paginated report, an EM or P SKU is required. For more
information about this subscription, see What is Power BI Premium?
Azure Power BI Embedded - You can purchase a capacity from the Microsoft Azure portal. This
subscription uses the A SKUs. For details on how to create a Power BI Embedded capacity, see Create
Power BI Embedded capacity in the Azure portal.
NOTE
Power BI Embedded recently released a new version, called Embedded Gen2 . Embedded Gen2 simplifies the
management of embedded capacities, and improves the Power BI Embedded experience. For more information,
see Paginated reports.
The following table describes the resources and limits of each SKU. To determine which capacity best fits your
needs, see the which SKU should I purchase for my scenario table.
EM2/A2 with 2 1 1 5
Embedded Gen2
EM3/A3 with 4 2 2 10
Embedded Gen2
P1/A4 8 4 4 25
P2/A5 16 8 8 50
P3/A6 32 16 16 100
Once you create a capacity, you can assign your app workspace to that capacity.
To assign a capacity to a workspace using a service principal, use the Power BI REST API. When you're using the
Power BI REST APIs, make sure to use the service principal object ID.
NOTE
You can also import paginated reports into a workspace using the Power BI REST APIs.
After creating a capacity and assigning your workspace to it, you need to enable the paginated report workload
on your capacity.
1. Sign into Power BI > Admin portal > Capacity settings.
2. Select the capacity that has the workspace you want to add a paginated report to.
3. Expand Workloads .
4. Activate the paginated reports workload.
Follow the instructions in the embed content for your customers tutorial. Skip Step 4 - Create and publish a
Power BI report and use the paginated report you uploaded, instead of the sample report suggested in the
tutorial.
To use a Power BI dataset as a data source:
In the Power BI portal, set the XML A endpoint to Read Only or Read Write as described in enable
read-write for a Premium capacity. You only need to do this once per capacity.
Generate a multi-resource embed token with the dataset ID specified in the request, and the
XmlaPermissions set to Read Only.
To use a Single Sign-on (SSO) enabled data source:
SSO-enabled data sources are supported if they're either directly connected to the paginated report, or
connected to a Power BI dataset which is the data source of the paginated report. When embedding a
paginated report with SSO-enabled data sources, the identity blob for the data source must be provided
in the DatasourceIdentity when you generate a multi-resource embed token.
You must use a ser vice principal . Master user isn't supported.
Premium Per User (PPU) isn't supported.
When embedding a paginated report with a Power BI dataset, both the paginated report and the Power BI
dataset must reside in a Premium per capacity or Embedded workspace (they can reside in two different
workspaces). The user generating the embed token should have Write permissions in the workspaces of both
the report and the dataset.
Embedding a paginated report connected to Azure Analysis Services with Single Sign-on (SSO) enabled is
not supported
For a full list of supported datasets and their authentication methods, see Supported data sources for Power BI
paginated reports.
Paginated reports don't support client side events (like loaded or rendered )
Next steps
Tutorial: Embed a Power BI report in an application for your organization
Capacity and SKUs in Power BI embedded analytics
Considerations when generating an embed token
Embed Power BI content in Salesforce
11/24/2022 • 2 minutes to read • Edit Online
Prerequisites
You must be familiar with both Power BI and Salesforce. It's helpful to have experience developing with Power BI
embedded analytics and be familiar with the Salesforce environment, preferably with the Salesforce Developer
Experience (SFDX).
Next steps
Embed Power BI content into an application for your customers
Embed Power BI content into an application for your organization
Power BI embedded analytics Client APIs
Q&A in Power BI embedded analytics
11/24/2022 • 2 minutes to read • Edit Online
Power BI embedded analytics offers you a way to incorporate Q&A into an application. Your users can ask
questions using natural language, and receive immediate answers in the form of visuals like charts or graphs.
There are two modes for embedding Q&A within your application: interactive and result only . Interactive
mode allows you to type in questions and have them displayed within the visual. If you have a saved question,
or a set question you want to display, you can use the result only mode by populating the question in your
embed config.
Here's what the JavaScript code will look like.
Set question
If you use result mode with a set question, you can inject more questions into the frame. The answer to the
new question will immediately replace the previous result. A new visual is rendered matching the new question.
One example of this usage would be a frequently asked question list. The user could go through the questions
and have them answered within the same embedded part.
Code snippet for JS SDK usage:
Embed token
Create an embed token off of a dataset to start a Q&A part. For more information, see Generate token.
Next steps
Try out Q&A embedding with the JavaScript embed sample
More questions? Try asking the Power BI Community
Embed a report in a secure portal or website
11/24/2022 • 5 minutes to read • Edit Online
With the Embed option for Power BI reports, you can easily and securely embed reports in internal web portals.
These portals can be cloud-based or hosted on-premises , such as SharePoint 2019. Embedded reports
respect all item permissions and data security through row-level security (RLS) and Analysis Services tabular
model object-level security (OLS). They provide no-code embedding into any portal that accepts a URL or
IFrame.
The Embed option supports URL filters and URL settings. It allows you to integrate with portals by using a low-
code approach that requires only basic HTML and JavaScript knowledge.
3. In the Secure embed code dialog, select the value under Here's a link you can use to embed this
content . Or if you'd like to use an IFrame in a blog or website, select the value under HTML you can
paste into a website .
4. Whether a user opens a report URL directly, or one that's embedded in a web portal, report access
requires authentication. The following screen appears if a user hasn't signed in to Power BI in their
browser session. When they select Sign-In , a new browser window or tab should open. Have them check
for pop-up blockers if they don't get prompted to sign in.
5. After the user has signed in, the report opens, showing the data and allowing page navigation and filter
setting. Only users with view permission can see the report in Power BI. All row-level security (RLS) rules
are also applied. Lastly, the user needs to be correctly licensed. They need a Power BI Pro or Premium Per
User (PPU) license. Also, the report must be in a workspace that's in a Power BI Premium capacity. The
user needs to sign in each time they open a new browser window. However, after they're signed in, other
reports load automatically.
6. When you use an IFrame, you might need to edit the height , and width values to have it fit in your
portal's web page.
Grant report access
The Embed option doesn't automatically permit users to view the report. View permissions are set in the Power
BI service.
In the Power BI service, you can share embedded reports with users who require access. If you use a Microsoft
365 Group, you can list the user as a workspace member.
Licensing
To view the embedded report, you need either a Power BI Pro or Premium Per User (PPU) license. Or, the content
needs to be in a workspace that's in a Power BI Premium capacity (EM or P SKU).
pageName You can use the pageName query string parameter to set
which report page to open. You can find this value at the
report URL's end when you view a report in the Power BI
service, as shown later in this article.
URL Filters You can use URL Filters in the embed URL that you received
from the Power BI UI to filter the embed content. This way
you can build low-code integrations with only basic HTML
and JavaScript experience.
2. Append the pageName property and its value to the end of the URL.
When selected, the button calls a function to update the IFrame with an updated URL, which includes the Energy
industry filter.
report.src = newUrl;
You can add as many buttons as you'd like to create a low-code custom experience.
Next steps
Ways to share your work in Power BI
Filter a report using query string parameters in the URL
Embed with report web part in SharePoint Online
Publish to web from Power BI
Embedded analytics access tokens
11/24/2022 • 4 minutes to read • Edit Online
NOTE
When using the embed for your customers solution, you can use any authentication method to allow access to your web
app.
In the embed for your organization solution, your web app users authenticate against Azure AD using their own
credentials. They'll then have access to the Power BI content they have permission to access on Power BI service.
Azure AD token
For both embed for your customers and embed for your organization solutions, you need an Azure AD token.
This token is required for all REST API operations, and it expires after an hour.
In the embed for your customers scenario, the Azure AD token is used to generate the embed token.
In the embed for your organization scenario, the Azure AD token is used to access Power BI.
Embed token
When you're using the embed for your customers solution, your web app needs to know which Power BI content
its user can access. Use the embed token REST APIs, to generate an embed token, which specifies the following
information:
Which content your web app user can access.
The web app user's access level (view , create, or edit).
For more information, see Considerations when generating an embed token.
Authentication flows
This section describes the different authentication flows for the embed for your customers and embed for your
organization embedding solutions.
Embed for your customers
Embed for your organization
The embed for your customers solution uses a non-interactive authentication flow. Users don't sign in to Azure
AD to access Power BI. Instead, your web app uses a reserved Azure AD identity to authenticate against Azure
AD, and generate the embed token. The reserved identity can be either a service principal or a master user:
Ser vice principal
Your web app uses the Azure AD service principal object to authenticate against Azure AD and get an
app-only Azure AD token. This app-only authentication method is recommended by Azure AD.
When using a service principal, you need to enable Power BI APIs access in the Power BI service admin
settings. Enabling access allows your web app to access the Power BI REST APIs. To use API operations on
a workspace, the service principal needs to be a member or admin of the workspace.
Master user Your web app uses a user account to authenticate against Azure AD and get the Azure AD
token. The master user needs to have a Power BI Pro or a Premium Per User (PPU) license.
When using a master user, you need to define your app's delegated permissions (also known as scopes).
The master user or tenant admin has to give consent to use these permissions when using the Power BI
REST APIs.
After successful authentication against Azure AD, your web app will generate an embed token to allow its users
to access specific Power BI content.
NOTE
To embed using the embed for your customers solution, you need a capacity with an A, EM, or P SKU.
To move to production you need a capacity.
The following diagram shows the authentication flow for the embed for your customers solution.
1. Web app user authenticates against your web app (with your authentication method).
2. Your web app uses a service principal or a master user to authenticate against Azure AD.
3. Your web app gets an Azure AD token from Azure AD, and uses it to access Power BI REST APIs. Access to
the Power BI REST APIs is given according to your authentication method, which is either service principal
or master user.
4. Your web app calls an Embed Token REST API operation, requesting the embed token. The embed token
specifies which Power BI content can be embedded.
5. The REST API returns the embed token to your web app.
6. The web app passes the embed token to the user's web browser.
7. The web app user uses the embed token to access Power BI.
Next steps
Considerations when generating an embed token
Capacity and SKUs in Power BI embedded analytics
More questions? Try asking the Power BI Community
Generate an embed token
11/24/2022 • 5 minutes to read • Edit Online
NOTE
The token permissions listed in this section are not applicable for the Generate token for multiple reports API.
Access Level
Use the accessLevel parameter to determine the user's access level.
View - Grant the user viewing permissions.
Edit - Grant the user viewing and editing permissions (only applies when generating an embed token for
a report).
If you're using the Generate token for multiple reports, datasets, and target workspaces API, use the
allowEdit parameter to grant the user viewing and editing permissions.
Create - Grant the user permissions to create a report (only applies when generating an embed token
for creating a report).
For report creation, you must also supply the datasetId parameter.
Saving a copy of the report
Use the allowSaveAs boolean to let users save the report as a new report. This setting is set to false by default.
This parameter is only applicable when generating an embed token for a report.
Row Level Security
With Row Level Security (RLS), the identity you use can be different from the identity of the service principal or
master user you're using to generating the token. By using different identities, you can display embedded
information according to the user you're targeting. For example, in your application you can ask users to sign in,
and then display a report that only contains sales information if the signed in user is a sales employee.
If you're using RLS, you can sometimes leave out the user's identity (the EffectiveIdentity parameter). When you
don't use the EffectiveIdentity parameter, the token has access to the entire database. This method can be used
to grant access to users such as admins and managers, who have permission to view the entire dataset.
However, you can't use this method in every scenario. The table below lists the different RLS types, and shows
which authentication method can be used without specifying a user's identity.
The table also shows the considerations and limitation applicable to each RLS type.
C A N I GEN ERAT E A N EM B ED TO K EN
W IT H O UT SP EC IF Y IN G T H E EF F EC T IVE
RL S T Y P E USER ID? C O N SIDERAT IO N S A N D L IM ITAT IO N S
RDL (paginated reports) ✖ Master user You can't use a master user to
✔ Service principal generate an embed token for RDL.
Analysis Services (AS) on premises live ✔ Master user The user generating the embed token
connection ✖ Service principal also needs one of the following
permissions:
Gateway admin permissions
Datasource impersonate permission
(ReadOverrideEffectiveIdentity)
Analysis Services (AS) Azure live ✔ Master user The identity of the user generating the
connection ✖ Service principal embed token can't be overridden.
Custom data can be used to
implement dynamic RLS or secure
filtering.
SSO and cloud RLS ✔ Master user You must provide the following:
✖ Service principal Explicit (SSO) identity in the identity
blob property in an effective identity
object
Effective (RLS) identity (username)
NOTE
Service principals must always provide the following information:
An identity for any item with an RLS dataset.
For an SSO dataset, an effective RLS identity with the contextual (SSO) identity defined.
Next steps
Register an app
Power BI Embedded for your customers
Embed Power BI content with service principal
Connect a report to a dataset using dynamic
binding
11/24/2022 • 2 minutes to read • Edit Online
Embedding for your User owns data Access token for Power BI The user who's Azure AD
organization users token is used, must have
appropriate permissions for
all items (reports, datasets,
etc.).
Embedding for your App owns data Access token for non-Power Must include permissions
customers BI users for both the report and the
dynamically bound dataset.
Use the API for generating
an embed token for
multiple items, to generate
an embed token that
supports multiple items.
NOTE
The maximum number of data sources allowed per user is 1000. This limit implies that the combined number of datas
sources used in the dynamic binding between reports and datasets by this user cannot exceed 1000.
Next steps
If you're new to embedding in Power BI, review these tutorials to learn how to embed your Power BI content.
Embed Power BI content into an application for your customers
Embed Power BI content into an application for your organization
Export Power BI report to file
11/24/2022 • 12 minutes to read • Edit Online
The exportToFile API enables exporting a Power BI report by using a REST call. The following file formats are
supported:
.pptx (PowerPoint)
.pdf
.png
When you export to a .png, a report with multiple pages is compressed into a .zip file
Each file in the .zip represents a report page
The page names are the same as the return values of the Get Pages or Get Pages in Group APIs
IMPORTANT
The exporttofile API is only available in for Gen2 capacities. If you are using a gen1 capacity, upgrade to Gen2
Usage examples
You can use the export feature in several ways. Here are a couple of examples:
Send to print button - In your application, create a button that when clicked on triggers an export job.
The job can export the viewed report as a .pdf or a .pptx. When it's complete, the user can receive the file
as a download. Using bookmarks you can export the report in a specific state, including configured filters,
slicers, and other settings. As the API is asynchronous, it may take some time for the file to be available.
Email attachment - Send an automated email at set intervals, with an attached .pdf report. This scenario
can be useful if you want to automate sending a weekly report to executives. For more information, see
Export and email a Power BI report with Power Automate
Supported features
This section describes the operation of the following supported features:
Selecting which pages to print
Exporting a page or a single visual
Bookmarks
Filters
Authentication
Row Level Security (RLS)
Data protection
Localization
Selecting which pages to print
Specify the pages you want to print according to the Get Pages or Get Pages in Group return value. You can also
specify the order of the pages you're exporting.
Exporting a page or a single visual
You can specify a page or single visual to export. Pages can be exported with or without bookmarks.
Depending on the type of export, you need to pass different attributes to the ExportReportPage object. The table
below specifies which attributes are required for each export job.
NOTE
Exporting a single visual has the same weight as exporting a page (with or without bookmarks). This means that in terms
of system calculations, both operations carry the same value.
Bookmarks
Bookmarks can be used to save a report in a specific configuration, including applied filters and the state of the
report's visuals. You can use the exportToFile API to programmatically export a report's bookmark, in two ways:
Expor t an existing bookmark
To export an existing report bookmark, use the name property, a unique (case sensitive) identifier, which
you can get using the bookmarks JavaScript API.
Expor t the repor t's state
To export the current state of the report, use the state property. For example, you can use the
bookmark's bookmarksManager.capture method to capture the changes a specific user made to a report,
and then export it in its current state using capturedBookmark.state .
NOTE
Personal bookmarks and persistent filters are not supported.
Filters
Using reportLevelFilters in PowerBIReportExportConfiguration, you can export a report in a filtered condition.
To export a filtered report, insert the URL query string parameters you want to use as your filter, to ExportFilter.
When you enter the string, you must remove the ?filter= part of the URL query parameter.
The table below includes a few syntax examples of strings you can pass to ExportFilter .
F ILT ER SY N TA X EXA M P L E
A distinct value in one field, and a Table/Field1 eq 'value1' and Store/Territory eq 'NC' and Store/Chain
different distinct value in another field Table/Field2 eq 'value2' eq 'Fashions Direct'
Authentication
You can authenticate using a user (or master user) or a service principal.
Row Level Security (RLS )
With Row Level Security (RLS), you can export a report showing data that's only visible to certain users. For
example, if you're exporting a sales report that's defined with regional roles, you can programmatically filter the
report so that only a certain region is displayed.
To export using RLS, you must have the following permissions:
Write and reshare permissions for the dataset the report is connected to
Workspace member or admin of the workspace where the report resides
Data protection
The .pdf and .pptx formats support sensitivity labels. If you export a report with a sensitivity label to a .pdf or a
.pptx, the exported file will display the report with its sensitivity label.
A report with a sensitivity label can't be exported to a .pdf or a .pptx using a service principal.
Localization
When using the exportToFile API, you can pass your desired locale. The localization settings affect the way the
report is displayed, for example by changing formatting according to the selected local.
Concurrent requests
The exportToFile API supports concurrent export job requests. The table below shows the number of jobs you
can run at the same time, depending on the SKU your report resides on. Concurrent requests refer to report
pages. For example, 55 pages in one export request on an A4 SKU, will be processed concurrently. This process
will take roughly the same amount of time as sending 55 export requests with one page each.
A job that exceeds its number of concurrent requests doesn't terminate. For example, if you export 30 pages in
an A2 SKU, the first 25 jobs will run, and the remaining five will wait for the next execution cycle.
Only five pages of a report are processed concurrently. For example, if you're exporting a report with 50 pages,
the export job will be processed in 10 sequential intervals. When optimizing your export job, you may want to
consider executing a few jobs in parallel. For example, if you have an A1 SKU with a limit of processing 20 max
concurrent pages per export, you can process four 50 page reports at the same time. Only five pages from each
job are being processed at a given time. As a result, the overall time to complete the four jobs will be shorter
than exporting the entire report in one job.
NOTE
Exporting a Power BI report to file using the exportToFile API, is not supported for Premium Per User (PPU).
The maximum limit for concurrent paginated reports is different and discussed in Export paginated report to file.
A1 EM1 20
A2 EM2 25
A3 EM3 35
A4 P1 55
A5 P2 95
A6 P3 175
1 SKUs greater than 100 GB aren't available in all regions. To request using these SKUs in regions where they're
not available, contact your Microsoft account manager.
Code examples
When you create an export job, there are four steps to follow:
1. Sending an export request.
2. Polling.
3. Getting the file.
4. Using the file stream.
This section provides examples for each step.
Step 1 - sending an export request
The first step is sending an export request. In this example, an export request is sent for a specific page.
};
// Save the export ID, you'll need it for polling and getting the exported file
return export.Id;
}
Step 2 - polling
After you've sent an export request, use polling to identify when the export file you're waiting for is ready.
private async Task<HttpOperationResponse<Export>> PollExportRequest(
Guid reportId,
Guid groupId,
string exportId /* Get from the PostExportRequest response */,
int timeOutInMinutes,
CancellationToken token)
{
HttpOperationResponse<Export> httpMessage = null;
Export exportStatus = null;
DateTime startTime = DateTime.UtcNow;
const int c_secToMillisec = 1000;
do
{
if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes ||
token.IsCancellationRequested)
{
// Error handling for timeout and cancellations
return null;
}
// You can track the export progress using the PercentComplete that's part of the response
SomeTextBox.Text = string.Format("{0} (Percent Complete : {1}%)", exportStatus.Status.ToString(),
exportStatus.PercentComplete);
if (exportStatus.Status == ExportState.Running || exportStatus.Status == ExportState.NotStarted)
{
// The recommended waiting time between polling requests can be found in the RetryAfter header
// Note that this header is not always populated
var retryAfter = httpMessage.Response.Headers.RetryAfter;
var retryAfterInSec = retryAfter.Delta.Value.Seconds;
await Task.Delay(retryAfterInSec * c_secToMillisec);
}
}
// While not in a terminal state, keep polling
while (exportStatus.Status != ExportState.Succeeded && exportStatus.Status != ExportState.Failed);
return httpMessage;
}
if (export.Status != ExportState.Succeeded)
{
// Error, failure in exporting the report
return null;
}
// Now you have the exported file stream ready to be used according to your specific needs
// For example, saving the file can be done as follows:
/*
var pathOnDisk = @"C:\temp\" + export.ReportName + exportedFile.FileSuffix;
return exportedFile;
}
catch
{
// Error handling
throw;
}
}
Next steps
Review how to embed content for your customers and your organization:
Export paginated report to file
Embed for your customers
Embed for your organization
Export and email a Power BI report with Power Automate
More Questions? Try the Power BI Community
Export paginated report to file
11/24/2022 • 7 minutes to read • Edit Online
The exportToFile API enables exporting a Power BI paginated report by using a REST call. The following file
formats are supported:
.pptx (PowerPoint)
.pdf (and Accessible PDF, or PDF/UA)
.xlsx (Excel)
.docx (Word)
.csv
.xml
.mhtml
Image When exporting to an image, set the image format via the OutputFormat format setting. The
supported OutputFormat values are:
.tiff (default)
.bmp
.emf
.gif
.jpeg
.png
Usage examples
You can use the export feature in a variety of ways. Here are a couple of examples:
Send to print button - In your application, create a button that when clicked on triggers an export job.
The job can export the viewed report as a .pdf or a .pptx. When it's complete, the user can receive the file
as a download. Using report parameters and format settings you can export the report in a specific state,
including filtered data, custom page sizes, and other format-specific settings. As the API is asynchronous,
it may take some time for the file to be available.
Email attachment - Send an automated email at set intervals, with an attached .pdf report. This scenario
can be useful if you want to automate sending a weekly report to executives.
Supported features
Format settings
Specify a variety of format settings for each file format. The supported properties and values are equivalent to
Device Info parameters for paginated report URL parameters.
Here are two examples. The first is for exporting the first four pages of a report using the report page size to a
.pptx file. The second example is for exporting the third page of a report to a .jpeg file.
Exporting the first four pages to a .pptx
{
"format": "PPTX",
"paginatedReportConfiguration":{
"formatSettings":{
"UseReportPageSize": "true",
"StartPage": "1",
"EndPage": "4"
}
}
}
{
"format": "IMAGE",
"paginatedReportConfiguration":{
"formatSettings":{
"OutputFormat": "JPEG",
"StartPage": "3",
"EndPage": "3"
}
}
}
Report parameters
You can use the exportToFile API to programmatically export a report with a set of report parameters. This is
done using report parameter capabilities.
Here's an example for setting report parameter values.
{
"format": "PDF",
"paginatedReportConfiguration":{
"parameterValues":[
{"name": "State", "value": "WA"},
{"name": "City", "value": "Seattle"},
{"name": "City", "value": "Bellevue"},
{"name": "City", "value": "Redmond"}
]
}
}
Authentication
You can authenticate using a user (or master user) or a service principal.
Row Level Security (RLS )
When using a Power BI dataset that has Row Level Security (RLS) defined as a data source, you can export a
report showing data that's only visible to certain users. For example, if you're exporting a sales report that's
defined with regional roles, you can programmatically filter the report so that only a certain region is displayed.
To export using RLS, you must have read permission for the Power BI dataset the report is using as a data
source.
Here's an example of supplying an effective user name for RLS.
{
"format": "PDF",
"paginatedReportConfiguration":{
"identities": [
{"username": "john@contoso.com"}
]
}
}
{
"format":"PDF",
"paginatedReportConfiguration":{
"formatSettings":{
"AccessiblePDF":"true",
"PageHeight":"11in",
"PageWidth":"8.5in",
"MarginBottom":"2in"
},
"identities":[
{
"username":"john@contoso.com",
"identityBlob": {
"value": "eyJ0eX....full access token"
}
}
]
}
}
Concurrent requests
The exportToFile API supports concurrent export job requests. The maximum number of concurrent report
pages depends on the type and number of SKUs you have. It's not the same number as for other Power BI
reports. If you exceed the limit and get a Too Many Requests (429) error, try to distribute the load over time or
get a larger capacity.
when using Premium Per User (PPU), the exportToFile API allows just one request in a five-minute window.
Multiple requests within a five-minute window will result in a Too Many Requests (429) error.
Code examples
The Power BI API SDK used in the code examples can be download here.
When you create an export job, there are three steps to follow:
1. Sending an export request.
2. Polling.
3. Getting the file.
This section provides examples for each step.
Step 1 - sending an export request
The first step is sending an export request. In this example, an export request is sent for a specific page range,
size, and report parameter values.
// Save the export ID, you'll need it for polling and getting the exported file
return export.Id;
}
Step 2 - polling
After you've sent an export request, use polling to identify when the export file you're waiting for is ready.
private async Task<Export> PollExportRequest(
Guid reportId,
Guid groupId,
string exportId /* Get from the ExportToAsync response */,
int timeOutInMinutes,
CancellationToken token)
{
Export exportStatus = null;
DateTime startTime = DateTime.UtcNow;
const int secToMillisec = 1000;
do
{
if (DateTime.UtcNow.Subtract(startTime).TotalMinutes > timeOutInMinutes ||
token.IsCancellationRequested)
{
// Error handling for timeout and cancellations
return null;
}
var httpMessage =
await Client.Reports.GetExportToFileStatusInGroupWithHttpMessagesAsync(groupId, reportId,
exportId);
exportStatus = httpMessage.Body;
if (exportStatus.Status == ExportState.Running || exportStatus.Status == ExportState.NotStarted)
{
// The recommended waiting time between polling requests can be found in the RetryAfter header
// Note that this header is only populated when the status is either Running or NotStarted
var retryAfter = httpMessage.Response.Headers.RetryAfter;
var retryAfterInSec = retryAfter.Delta.Value.Seconds;
return exportStatus;
}
return null;
}
Next steps
Review how to embed content for your customers and your organization:
Export report to file
Embed for your customers
Embed for your organization
Power BI Embedded Generation 2
11/24/2022 • 2 minutes to read • Edit Online
Power BI Embedded recently released a new version of Power BI Embedded, Power BI Embedded Generation
2 , referred to as Embedded Gen2 for convenience. You can still create the original version of the Power BI
Embedded resource, called Embedded Gen 1, or create a new Embedded Gen 2 resource. You can run both types
of Power BI Embedded capacities in parallel, and assign any workspace to either a Gen1 or a Gen2 capacity”.
All of the Power BI Embedded Gen 1 capabilities such as pausing and resuming the capacity, are preserved in
Gen 2. In addition, the Gen 2 capacity resource provides the following updates and improved experience:
Enhanced performance - Better performance on any capacity size, anytime. Operations will always
perform at top speed and won't slow down when the load on the capacity approaches the capacity limits.
Greater scale - Including the following enhancements:
No limits on refresh concurrency - You no longer need to track schedules for datasets being
refreshed on your capacity
Fewer memory restrictions
Complete separation between report interaction and scheduled refreshes
Lower entr y level for paginated repor ts and AI workloads – Start with an A1 SKU and grow as
you need.
Scaling a resource instantly - Instantly scale your Power BI Embedded resource. From scaling a Gen1
resource in minutes, to scaling a Gen2 resource in seconds.
Scaling without downtime - With Embedded Gen2 you can scale your Power BI Embedded resource
without experiencing any downtime.
Improved metrics - Including clear and normalized capacity utilization data, depending only on the
complexity of the analysis operations the capacity performs. Metrics are not impacted by other factors
such as the size of the capacity, and the level of load on the system while performing analytics. When
using the improved metrics, the built-in reporting tool allows you to clearly see:
Utilization analysis
Budget planning
Chargebacks
The need to upgrade your capacity
NOTE
You can get usage metrics for Embedded Gen2 capacities by using the Premium Gen 2 Capacity Utilization
Metrics app.
Next steps
Create Power BI Embedded capacity in the Azure portal
Capacity and SKUs in Power BI embedded analytics
What is Power BI Premium?
Monitoring Power BI Embedded data reference
Plan your transition to Power BI Embedded Gen2
11/24/2022 • 2 minutes to read • Edit Online
This article provides information about key dates for migrating Power BI Embedded capacity to the latest
platform.
Over the last several months, we've been working to make many improvements to Power BI Embedded.
Changes include updates to performance, scaling, management overhead, and improved insight to utilization
metrics. This next generation of Power BI Embedded, referred to as Power BI Embedded Gen2, has officially
moved from preview to general availability as of October 4, 2021.
If your organization is using the previous version of Power BI Embedded, you're required to migrate capacities to
the modern Gen2 platform. Microsoft began migrating all Embedded capacities to Gen2 capacities. If you have a
Embedded capacity that requires migrating, you’ll receive an email notification 60 days before the
migration is scheduled to star t .
Migration notification
Following the general availability of gen2, we’ll begin to notify affected customers so that you can prepare your
organization for changes. We’ll post additional awareness, along with specific migration timelines to Microsoft
365 Message Center. Admins will receive 60 days advance notice of changes. The timeline will vary by cloud.
Next steps
What is Power BI Embedded Gen2?
Move your embedded app to production
11/24/2022 • 4 minutes to read • Edit Online
IMPORTANT
This article only applies to embed for your customers applications. If you're using the embed for your organization
scenario, you need to use either a Pro or Premium license.
After you've completed developing your application, to move to production you'll need to back your workspace
with a capacity. Note that all workspaces (the ones containing the reports or dashboards, and the ones
containing the datasets) must be assigned to a capacity.
Create a capacity
By creating a capacity, you can take advantage of having a resource for your customers. There are two types of
capacities you can choose from:
Power BI Premium - A tenant-level Microsoft 365 subscription available in two SKU families, EM and P.
When embedding Power BI content, this solution is referred to as Power BI embedding. For more
information regarding this subscription, see What is Power BI Premium?
Azure Power BI Embedded - You can purchase a capacity from the Microsoft Azure portal. This
subscription uses the A SKUs. For details on how to create a Power BI Embedded capacity, see Create
Power BI Embedded capacity in the Azure portal.
NOTE
A SKUs don't support the use of a FREE Power BI license to access to Power BI content.
Capacity specifications
The table below describes the resources and limits of each SKU. To determine which capacity best fits your
needs, see the which SKU should I purchase for my scenario table.
DIREC TQ UE
MAX RY / L IVE
M EM O RY C O N N EC T I MAX M O DEL
P ER O N ( P ER M EM O RY REF RESH
C A PA C IT Y TOTA L V- B A C K EN D F RO N T EN D DATA SET SEC O N D) 1, P ER Q UERY PA RA L L EL IS
SK US C O RES V- C O RES V- C O RES ( GB ) 1, 2, 3 2 ( GB ) 1, 2 M2
EM2/A2 2 1 1 5 7.5 2 10
EM3/A3 4 2 2 10 15 2 20
P1/A4 8 4 4 25 30 6 40
P2/A5 16 8 8 50 60 6 80
DIREC TQ UE
MAX RY / L IVE
M EM O RY C O N N EC T I MAX M O DEL
P ER O N ( P ER M EM O RY REF RESH
C A PA C IT Y TOTA L V- B A C K EN D F RO N T EN D DATA SET SEC O N D) P ER Q UERY PA RA L L EL IS
SK US C O RES V- C O RES V- C O RES ( GB ) ( GB ) M
1 The Power BI Premium Utilization and Metrics app doesn't currently expose these metrics.
2 These limits only apply to the datasets workload per capacity.
3 The Max memory per dataset (GB) column represents an upper bound for the dataset size. However, an
amount of memory must be reserved for operations such as refreshes and queries on the dataset. The
maximum dataset size permitted on a capacity may be smaller than the numbers in this column.
4 SKUs greater than 100 GB aren't available in all regions. To request using these SKUs in regions where they're
not available, contact your Microsoft account manager.
Development testing
For development testing, you can use free embed trial tokens with a Pro license or Premium Per User (PPU)
license. To embed in a production environment, use a capacity.
IMPORTANT
Free trial tokens are limited to development testing only. Once going to production, a capacity must be purchased. Until a
capacity is purchased, the Free trial version banner will continue to appear at the top of the embedded report.
The number of embed trial tokens a Power BI service principal or master user (master account) can generate, is
limited. Use the Available Features API to check the percentage of your current embedded usage. The usage
amount is displayed per service principal or master account.
If you run out of embed tokens while testing, you need to purchase a Power BI Embedded or Premium capacity.
There's no limit to the number of embed tokens you can generate with a capacity.
Next steps
Capacity and SKUs in Power BI embedded analytics
Capacity planning in Power BI embedded analytics
Considerations when generating an embed token
Capacity and SKUs in Power BI embedded analytics
11/24/2022 • 5 minutes to read • Edit Online
Power BI embedded analytics requires a capacity (A, EM, or P SKU) in order to publish embedded Power BI
content.
Capacity is a dedicated set of resources reserved for exclusive use. It offers dependable, consistent performance
for your content.
NOTE
You'll need a Power BI Pro or Premium Per User (PPU) account to publish content.
SC EN A RIO A Z URE O F F IC E
NOTE
A Power BI Pro or Premium Per User (PPU) license is needed for publishing content to a Power BI app workspace.
Only the P SKU allows free Power BI users to consume Power BI apps and shared content, in Power BI service.
Capacity considerations
For development testing, you can use free embed trial tokens with a Pro license. To embed in a production
environment, you must use a capacity.
IMPORTANT
Free trial tokens are limited to development testing only. Once going to production, a capacity must be purchased. Until a
capacity is purchased, the Free trial version banner will continue to appear at the top of the embedded report.
The table below lists payment and usage considerations per capacity.
SKU A EM P
Usage Azure resources can be: Embed in apps, and in Embed in apps, and in
Scaled up or down Microsoft applications Power BI service
Paused and resumed
C A PA C IT DATA F LO
Y DATA SET W
EM2/A2 2 1 1 5 7.5 2 10 8
EM3/A3 4 2 2 10 15 2 20 16
P1/A4 8 4 4 25 30 6 40 32
P2/A5 16 8 8 50 60 6 80 64
1 The Power BI Premium Utilization and Metrics app doesn't currently expose these metrics.
2 These limits only apply to the datasets workload per capacity.
3 The RAM per dataset (GB) column (also called the model size limit) represents an upper bound for the dataset
size. However, some memory must be reserved for operations such as dataset refreshes and queries. The
maximum dataset size permitted on a capacity may be smaller than the numbers in this column.
4 SKUs greater than 100 GB aren't available in all regions. To request using these SKUs in regions where they're
not available, contact your Microsoft account manager.
5 Learn more about parallel tasks in dataflows.
Note the amount of memory available on each node size described in the RAM (GB) column of the table. It's set
to the memory footprint limit of a single Power BI item (such as a dataset, report or dashboard), and not to the
cumulative consumption of memory. For example, in an Embedded A4 capacity, a single dataset size is limited to
25 GB, and not the total memory footprint of all datasets handled at the same time.
Embedded gen 2 memory enhancements
The amount of memory available on each node size is described in the RAM (GB) column in the SKU memory
and computing power table. With Power BI Embedded Generation 2 (also known as Embedded Gen 2), it's set to
the memory footprint limit of a single Power BI item (such as a dataset, report or dashboard), and not to the
cumulative consumption of memory. For example, in an Embedded Gen2 A4 capacity, a single dataset size is
limited to 25 GB, compared to the original Power BI Embedded capacity, where the total memory footprint of all
datasets handled at the same time was limited to 25 GB.
Next steps
Embed for your customers
Embed for your organization](embed-sample-for-your-organization.md)
Embed from apps
Capacity planning in Power BI embedded analytics
11/24/2022 • 5 minutes to read • Edit Online
Calculating the type of capacity you need for a Power BI embedded analytics deployment can be complicated.
The capacity you need depends on several parameters, some of which are hard to predict.
Some of the things to consider when planning your capacity are:
The data models you're using
The number and complexity of required queries
The hourly distribution of your application usage
Data refresh rates
Other usage patterns that are hard to predict
NOTE
This article explains how to plan what capacity you need and how to do a load testing assessment for Power BI embedded
analytics A-SKUs. To plan your capacity size for EM or P SKUs see Planning your capacity size in advance.
DIREC TQ UE
MAX RY / L IVE
M EM O RY C O N N EC T I MAX M O DEL
P ER O N ( P ER M EM O RY REF RESH
C A PA C IT Y TOTA L V- B A C K EN D F RO N T EN D DATA SET SEC O N D) 1, P ER Q UERY PA RA L L EL IS
SK US C O RES V- C O RES V- C O RES ( GB ) 1, 2, 3 2 ( GB ) 1, 2 M2
EM2/A2 2 1 1 5 7.5 2 10
EM3/A3 4 2 2 10 15 2 20
P1/A4 8 4 4 25 30 6 40
P2/A5 16 8 8 50 60 6 80
1 The Power BI Premium Utilization and Metrics app doesn't currently expose these metrics.
2 These limits only apply to the datasets workload per capacity.
3 The Max memory per dataset (GB) column (also called the model size limit) represents an upper bound for the
dataset size. However, some memory must be reserved for operations such as dataset refreshes and queries.
The maximum dataset size permitted on a capacity may be smaller than the numbers in this column.
4 SKUs greater than 100 GB aren't available in all regions. To request using these SKUs in regions where they're
not available, contact your Microsoft account manager.
Set up auto-scale
The autoscaling technique described here lets you can elastically resize your A-SKU capacity to address its
current memory and CPU needs.
Use the Update Capacity API to up-scale or down-scale the capacity SKU. See this runbook PowerShell
script capacity scale-up sample on how to use the API call to create your own up-scale and down-scale
scripts.
Use Azure Monitor alerts to track the Power BI Embedded capacity metrics:
Overload (1 if capacity’s CPU has surpassed 100% and is in overloaded state, otherwise 0)
CPU (percentage of CPU utilization)
CPU Per Workload if specific workloads (like Paginated reports) are used.
When these metrics hit the values specified in the Azure Monitor Alert rules, the rules will trigger the execution
of an up-scale or down-scale runbook script. For example, you can create a rule that invokes the upscale
capacity runbook to update the capacity to a higher SKU if Overload = 1 or if CPU = 95%. You can also create a
rule that invokes a downscale capacity runbook script to update the capacity to a lower SKU if the CPU drops
below 50% (say 45%).
You could also invoke upscale and downscale runbooks programmatically on demand before and after a dataset
refresh is executed. This could ensure your capacity has enough RAM (GB) for large datasets using that capacity.
Next steps
Capacity and SKUs in Power BI embedded analytics
Power BI Embedded performance best practices
Create Power BI Embedded capacity in the Azure
portal
11/24/2022 • 7 minutes to read • Edit Online
This article walks you through how to create a Power BI Embedded capacity in Microsoft Azure. Power BI
Embedded simplifies Power BI capabilities by helping you quickly add stunning visuals, reports, and dashboards
to your apps.
IMPORTANT
Within the next few months, all Gen1 capacities will be deprecated and only Power BI Embedded Gen2 capacities will
available. We recommend that you upgrade your embedded capacities to Gen2 using the Azure portal or the ARM API.
Prerequisites
Before you can create a capacity, you need the following:
1. An Azure Active Director y: Your subscription must be associated with an Azure Active Directory (Azure
AD) organizational tenant. Also, you need to be signed in to Azure with an account in that
tenant . Microsoft personal accounts aren't supported. To learn more, see Authentication and user
permissions.
2. A Power BI tenant: At least one account in your Azure AD tenant must be signed up for Power BI. Sign
into Power BI from that account.
3. Azure subscription: Visit Azure Free Trial to create an account, if you don't already have one.
4. Resource group: Use a resource group you already have or create a new one.
Create a capacity
NOTE
To create or manage a capacity, you must have the built-in role of contributor or higher.
Before creating a Power BI Embedded capacity, make sure you have signed into Power BI at least once.
Portal
Azure CLI
ARM template
NOTE
By default, the capacity administrator is the user creating the capacity.
You can select a different user or service principal, as capacity administrator.
The capacity administrator must belong to the tenant where the capacity is provisioned. Business to
business (B2B) users cannot be capacity administrators.
Next steps
Manage capacities
Pause and start your Power BI Embedded capacity in the Azure portal
Embed Power BI content into an application for your customers
More questions? Try asking the Power BI Community
Multi-Geo support for Power BI Embedded
11/24/2022 • 2 minutes to read • Edit Online
Multi-Geo suppor t for Power BI Embedded means that ISVs and organizations that build applications using
Power BI Embedded to embed analytics into their apps can now deploy their data in different regions around the
world.
Now, customers using Power BI Embedded can set up an A capacity using Multi-Geo options, based on the
same features and limitations that Power BI Premium supports using Multi-Geo.
The locations are also available in the Admin portal at PowerBI.com . In the Admin portal, choose Capacity
settings , and then switch to the Power BI Embedded tab.
Next steps
What is Power BI Embedded?
Create a Power BI Embedded capacity
Multi-Geo in Power BI Premium capacities
More questions? Try asking the Power BI Community
Assess your capacity load
11/24/2022 • 2 minutes to read • Edit Online
This article explains how to simplify capacity planning for Power BI embedded analytics by using the Power BI
Capacity Load Assessment Tool, created for automating load testing for Power BI embedded analytics capacities
(A, EM or P SKUs).
Next steps
Capacity and SKUs in Power BI embedded analytics
Power BI Embedded performance best practices
Scale your Power BI Embedded capacity in the
Azure portal
11/24/2022 • 2 minutes to read • Edit Online
This article walks through how to scale a Power BI Embedded capacity in Microsoft Azure. Scaling allows you to
increase or decrease the size of your capacity.
This assumes you created a Power BI Embedded capacity (A SKU ). If you haven't, see Create Power BI Embedded
capacity in the Azure portal to get started.
NOTE
This article describes the process for vertically scaling A SKUs. It doesn't talk about horizontal scaling or P SKUs.
Scale a capacity
1. Sign into the Azure portal.
2. Under Azure ser vices , select Power BI Embedded to see your capacities.
3. Select the capacity you want to scale. Notice that the current scale for each capacity is listed under SKU .
When you make your selection, information about that capacity is displayed next to it. This information
again includes the current scaling under SKU .
4. Under Scale , select Change size .
Next steps
Pause and start your Power BI Embedded capacity in the Azure portal
How to embed your Power BI dashboards, reports, and tiles.
More questions? Try asking the Power BI Community
Pause and start your Power BI Embedded capacity
in the Azure portal
11/24/2022 • 2 minutes to read • Edit Online
This article walks through how to pause and start a Power BI Embedded capacity in Microsoft Azure. This
assumes you have created a Power BI Embedded capacity. If you have not, see Create Power BI Embedded
capacity in the Azure portal to get started.
If you don't have an Azure subscription, create a free account before you begin.
NOTE
Pausing a capacity may prevent content from being available within Power BI. Make sure to unassign workspaces from
your capacity before pausing to prevent interruption.
Next steps
Scale your Power BI Embedded capacity.
How to embed your Power BI dashboards, reports and tiles.
More questions? Try asking the Power BI Community
Service principal profiles for multitenancy apps in
Power BI Embedded
11/24/2022 • 14 minutes to read • Edit Online
This article explains how an ISV or any other Power BI Embedded app owner with many customers can use
service principal profiles to map and manage each customer's data as part of their Power BI embed for your
customers solution. Service principal profiles allow the ISV to build scalable applications that enable better
customer data isolation and establish tighter security boundaries between customers. This article discusses the
advantages and the limitations of this solution.
NOTE
The word tenant in Power BI can sometimes refer to an Azure AD tenant. In this article, however, we use the term
multitenancy to describe a solution where a single instance of a software application serves multiple customers or
organizations (tenants) requiring physical and logical separation of data. . For example, the Power BI app builder can
allocate a separate workspace for each if its customers (or tenants) as we show below. These customers are not necessarily
Azure AD tenants, so don’t confuse the term multitenant application that we use here, with the Azure AD multitenant
application.
A service principal profile is a profile created by a service principal. The ISV app calls the Power BI APIs using a
service principal profile, as explained in this article.
The ISV application service principal creates a different Power BI profile for each customer, or tenant. When a
customer visits the ISV app, the app uses the corresponding profile to generate an embed token that will be
used to render a report in the browser.
Using service principal profiles enables the ISV app to host multiple customers on a single Power BI tenant. Each
profile represents one customer in Power BI. In other words, each profile creates and manages Power BI content
for one specific customer's data.
NOTE
This article is aimed at organizations that want to set up a multitenant app using service principal profiles. If your
organization already has an app that supports multitenancy, and you want to migrate to the service principal profile
model, see Migrate to the service principal profiles model.
Prerequisites
Before you can create service principal profiles, you need to:
Set up the service principal by following the first three steps of Embed Power BI content with service
principal.
From a Power BI tenant admin account, enable creating profiles in the tenant using the same security group
you used when you created the service principal.
Create a profile
Profiles can be created, updated, and deleted using Profiles REST API.
For example, to create a profile:
{"displayName":"ContosoProfile"}
A service principal can also call GET Profiles REST API to get a list of its profiles. For example:
Profile permissions
Any API that grants a user permission to Power BI items can also grant a profile permission to Power BI items.
For example, Add Group User API can be used to grant a profile permission to a workspace.
The following points are important to understand when using profiles:
A profile belongs to the service principal that created it, and can only be used by that service principal.
A profile owner can't be changed after creation.
A profile isn't a standalone identity. It needs the service principal Azure AD token to call Power BI REST APIs.
ISV apps call Power BI REST APIs by providing the service principal Azure AD token in the Authorization header,
and the profile ID in the X-PowerBI-Profile-Id header. For example:
Create a workspace
Power BI workspaces are used to host Power BI items such as reports and datasets.
Each profile needs to:
Create at least one Power BI workspace
{
"name": "ContosoWorkspace"
}
Grant access permissions to the workspace. The service principal profile must have Admin access to the
workspace.
Assign the workspace to a capacity
POST https://api.powerbi.com/v1.0/myorg/groups/f313e682-c86b-422c-a3e2-b1a05426c4a3/AssignToCapacity
HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK…wNkZUiIsg
Content-Type: application/json; charset=utf-8
X-PowerBI-Profile-Id: a4df5235-6f18-4141-9e99-0c3512f41306
{
"capacityId": "13f73071-d6d3-4d44-b9de-34590f3e3cf6"
}
POST https://api.powerbi.com/v1.0/myorg/groups/f313e682-c86b-422c-a3e2-b1a05426c4a3/imports?
datasetDisplayName=ContosoSales HTTP/1.1
Authorization: Bearer eyJ...kZUiIsg
Content-Type: multipart/form-data; boundary="8b071895-b380-4769-9c62-7e586d717ed7"
X-PowerBI-Profile-Id: a4df5235-6f18-4141-9e99-0c3512f41306
Fiddler-Encoding: base64
LS04YjA3MTg5NS1iMzgwLTQ3...Tg2ZDcxN2VkNy0tDQo=
Use dataset parameters to create a dataset that can connect to different customers' data sources. Then, use the
Update parameters API to define which customers' data the dataset connects to.
{
"datasets": [
{
"id": "3b1c8f74-fbbe-45e0-bf9d-19fce69262e3"
}
],
"reports": [
{
"id": "3d474b89-f2d5-43a2-a436-d24a6eb2dc8f"
}
]
}
Design aspects
Before setting up a profile-based multitenant solution, you should be aware of the following issues:
Scalability
Automation & operational complexity
Multi-Geo needs
Cost efficiency
Row level security
Scalability
By separating the data into separate datasets for each customer, you minimize the need for large datasets. When
the capacity gets overloaded, it can evict unused datasets to free memory for active datasets. This optimization
is impossible for a single large dataset. By using multiple datasets, you can also separate tenants into multiple
Power BI capacities if necessary.
Without profiles, a service principal is limited to 1,000 workspaces. To overcome this limit, a service principal
can create multiple profiles, where each profile can create up to 1,000 workspaces. With multiple profiles, the
ISV app can isolate each customer's content using distinct logical containers.
Once a service principal profile has access to a workspace, its parent service principal’s access to the workspace
can be removed to avoid scalability problems.
Even with these advantages, you should consider the potential scale of your application. For example, the
number of workspace items a profile can access is limited. Today, a profile has the same limits as a regular user.
If the ISV application allows end users to save a personalized copy of their embedded reports, a customer's
profile will have access to all the created reports of all its users. This model can eventually exceed the limit.
Automation and operational complexity
With Power BI profile-based separation, you might need to manage hundreds or thousands of items. Therefore,
it's important to define the processes that frequently happen in your application lifecycle management, and
ensure you have the right set of tools to do these operations at scale. Some of these operations include:
Adding a new tenant
Updating a report for some or all tenants
Updating the dataset schema for some or all tenants
Unplanned customizations for specific tenants
Frequency of dataset refreshes
For example, creating a profile and a workspace for a new tenant is a common task, which can be fully
automated with the Power BI REST API.
Multi-Geo needs
Multi-Geo support for Power BI Embedded means that ISVs and organizations that build applications using
Power BI Embedded to embed analytics into their apps can now deploy their data in different regions around the
world. To support different customers in different regions, assign the customer's workspace to a capacity in the
desired region. This task is a simple operation that doesn't involve extra cost. However, if you have customers
that need data from multiple regions, the tenant profile should duplicate all items into multiple workspaces that
are assigned to different regional capacities. This duplication may increase both cost and management
complexity.
For compliance reasons, you may still want to create multiple Power BI tenants in different regions. Read more
about multi-geo.
Cost efficiency
Application developers using Power BI Embedded need to purchase a Power BI Embedded capacity. The profile-
based separation model works well with capacities because:
The smallest object you can independently assign to a capacity is a workspace (you can't assign a report,
for example). By separating customers by profiles, you get different workspaces - one per customer. This
way, you get full flexibility to manage each customer according to their performance needs, and optimize
capacity utilization by scaling up or down. For example, you can manage large and essential customers
with high volume and volatility in a separate capacity to ensure a consistent level of service, while
grouping smaller customers in another capacity to optimize costs.
Separating workspaces also means separating datasets between tenants so that data models are in
smaller chunks, rather than a single large dataset. These smaller models enable the capacity to manage
memory usage more efficiently. Small, unused datasets can be evicted after a period of inactivity, in order
to maintain good performance.
When buying a capacity, consider the limit on the number of parallel refreshes, as refresh processes might need
extra capacity when you have multiple datasets.
Row Level Security
This article explains how to use profiles to create a separate dataset for each customer. Alternatively, ISV
applications can store all their customers' data in one large dataset and use Row-level security (RLS) to protect
each customer's data. This approach can be convenient for ISVs that have relatively few customers and small to
medium-sized datasets because:
There's only one report and one dataset to maintain
The onboarding process for new customers can be simplified
Before using RLS, however, make sure you understand its limitations. All the data for all customers are in one
large Power BI dataset. This dataset runs in a single capacity with its own scaling and other limitations.
Even if you use service principal profiles to separate your customers' data, you can still use RLS within a single
customer's dataset to give different groups access to different parts of the data. For example, you could use RLS
to prevent members of one department from accessing data of another department in the same organization.
WARNING
Be very careful when deleting a service principal. You don't want to accidentally lose data from all its associated profiles.
If you delete the service principal in the active directory, all its profiles in Power BI will be deleted. However,
Power BI won't delete the content immediately, so the tenant admin can still access the workspaces. Be careful
when deleting a service principal used in a production system, especially when you created profiles using this
service principal in Power BI. If you do delete a service principal that has created profiles, be aware that you'll
need to recreate all the profiles, provide the new profiles access to the relevant workspaces, and update the
profile IDs in the ISV application database.
Data separation
When data is separated by service principal profiles, a simple mapping between a profile and customer prevents
one customer from seeing another customer's content. Using a single service principal requires that the service
principal has access to all the different workspaces in all the profiles.
To add extra separation, assign a separate service principal to each tenant, instead of having a single service
principal access multiple workspaces using different profiles. Assigning separate service principals has several
advantages, including:
Human error or a credential leak won't cause multiple tenants' data to be exposed.
Certificate rotation can be done separately for each tenant.
However, using multiple service principals comes with a high management cost. Select this path only if you need
the extra separation. Keep in mind that the configuration of which data to show an end user is defined when you
generate the embed token, a backend-only process that end users can't see or change. Requesting an embed
token using a tenant-specific profile will generate an embed token for that specific profile, which will give you
customer separation in consumption.
One report, multiple datasets
Generally, you have one report and one dataset per tenant. If you have hundreds of reports, you'll have
hundreds of datasets. Sometimes, you might have one report format, with different datasets (for example,
different parameters or connection details). Each time you have a new version of the report, you'll need to
update all the reports for all tenants. Although you can automate this, it's easier to manage if you have just one
copy of the report. Create a workspace that contains the report to embed. During a session runtime, bind the
report to the tenant-specific dataset. Read dynamic bindings for more details.
Customizing and authoring content
When you create content, carefully consider who has permission to edit it. If you allow multiple users in each
tenant to edit, it's easy to exceed dataset limitations. If you decide to give users editing capability, monitor their
content generation closely, and scale up as needed. For the same reason, we don't recommend using this
capability for content personalization, where each user can make small changes to a report and save it for
themselves. If the ISV application allows content personalization, consider introducing workspace retention
policies for user-specific content. Retention policies make it easier to delete content when users move to a new
position, leave the company, or stop using the platform.
System-Managed identity
Instead of a service principal, you can use a user-assigned or system-assignedmanaged identity to create
profiles. Managed identities reduce the need for secrets and certificates.
Be careful when using a system-managed identity because:
If a system-assigned managed identity is accidentally turned off, you'll lose access to the profiles. This
situation is similar to a case where a service principal is deleted.
A system-assigned managed identity is connected to a resource in Azure (web app). If you delete the
resource, the identity will be deleted.
Using multiple resources (different web apps in different regions) will result in multiple identities that need
to be managed separately (each identity will have its own profiles).
Due to the above considerations, we recommend that you use a user-assigned managed identity.
Example
For an example of how to use service principal profiles to manage a multitenant environment with Power BI and
App-Owns-Data embedding, download the App owns data multitenant repository from Power BI Dev Camp
(third party site).
Next steps
Use the Power BI SDK with service principals
Migrate multitenancy apps to the service principal profiles model
Develop scalable multitenancy applications with Power BI embedding
Use the Power BI SDK with service principal profiles
11/24/2022 • 2 minutes to read • Edit Online
This article explains how to use the SDK with service principal profiles. There are two ways to connect a Power BI
client to a service principal profile. You can:
Create a client with a profile object ID
Specify the profile ID in the API request call
Once the client is associated with a profile, you can get the current service principal profile from the Power BI
client.
When you create a Power BI client with the profile object ID, every API call that uses the client is issued with the
X-PowerBI-profile-id in the request header.
For example,
GET https://powerbiapi.analysis-df.windows.net/v1.0/myorg/groups
For example,
GET https://powerbiapi.analysis-df.windows.net/v1.0/myorg/groups
In the case, the profile header will not be added to the client default headers. You need to specify it with every
API request.
Make sure you avoid duplications. For example, creating a client with a profile object ID and then specifying the
header with the API request will result in unauthorized errors.
Get the current service principal profile from Power BI client
To retrieve the current service principal profile from the SDK client, call GetServicePrincipalProfileObjectId .
Next steps
Service principal profiles in Power BI Embedded
Migrate multi-customer applications to the service
principal profiles model
11/24/2022 • 4 minutes to read • Edit Online
This article describes how you can get better scalability by migrating your Power BI embedded analytics multi-
customer apps to the service principal profiles model.
Service principal profiles make it easier to manage organizational content in Power BI and use your capacities
more efficiently.
NOTE
This article is aimed at organizations that already have an app that supports multiple customers from a single Power BI
tenant.
Not all apps benefit from the service principal model. For example, the following apps shouldn't migrate:
Small apps that maintain one service principal with a small number of objects.
Apps that use one multiple service principal per customer
Prerequisites
It's important to read about service principal profiles before you start the migration.
You also need to do the following steps:
Set up the service principal by following the first three steps of Embed Power BI content with service
principal.
From a Power BI tenant admin account, enable creating profiles in the tenant.
Migrate to service principal profiles
Migrating to service principal profiles involves the following steps:
1. Create profiles, one profile per customer.
2. Organize your workspaces.
3. Change the application code to use profiles.
4. Test your application with the profiles model.
5. Clean up redundant permissions.
Create Profiles (Required)
Use Profiles REST API with the service principal you created to create one profile for each customer.
It's a good idea to save a mapping of each data customer ID with its corresponding profile ID in your database.
You'll need this mapping later to make API calls with the tenant profile.
Organize your workspaces
The easiest way to manage your data is by maintaining one workspace per customer. If your app already uses
this model, you don't need to create new workspaces. However, you still have to provide each profile with Admin
access to the corresponding workspace using the Add Group User API.
If you don't have one workspace per customer, use the corresponding profile to call Create Group User API to
create a new workspace for each customer.
Organize items in workspaces
You should now have a profile and a workspace for each customer. If you created new workspaces in the
previous step, you need to import items (like reports and datasets) into these workspaces. The datasets you
import depend on your current solution:
If your app uses a separate dataset for each customer, the dataset design can work as it is.
If your app uses one dataset withrow level security (RLS)to provide different data to different customers,
you can get better scalability by creating a separate dataset for each customer and using profiles as
described in this article.
After overcoming scalability limitations by using profiles and separate data sources, you can get even
more data separation by using RLS with profiles.
If you rely on Dynamic RLS, the name of the profile will be returned in the DAX function UserName() .
If you use static RLS and override roles when generating the embed token, you can continue doing
this.
Once the items are ready, import them into the relevant workspaces. To automate the process, consider using
the Import API.
Validate
It's best practice to test your app thoroughly before moving it to the profiles model. Reports may load even if
there are bugs in the SaaS application code because you didn't delete the older permissions on the workspaces.
Power BI Embedded has several ways to filter data and restrict data access to specific users. Some of these
security methods are:
Row-Level Security (RLS) RLS enables you to control access to rows in a database table through
group memberships. When you embed items, you can use RLS to restrict user access to specific rows of
data. With RLS, different users can work with the same items but see different data.
Object level security (OLS) OLS enables you to hide specific tables or columns from report viewers.
You can also secure sensitive object names and metadata to prevent them from being discovered.
Workspace based isolation and multitenancy
In this scenario, each customer has their own separate dataset. Since each customer only has access to
their own workspace, no further filtering needed, though this method can be combined with RLS to
further filter data within each organization.
APPLIES TO: ✔
️ App owns data ❌ User owns data
This article explains how to embed Power BI content that uses RLS into a standard Power BI app owns data
application.
Prerequisites
For a detailed explanation on how to set up RLS, refer to Row-level security (RLS) with Power BI.
When you define your RLS roles, keep in mind that the DAX expression you use determines if the RLS model is
static or dynamic.
Let's say john@contoso.com is a user of your app. You want to give John access to data from the Eastern US
role. To embed a report for john@contoso.com, generate an embed token using the Eastern US role. The
resulting data will be filtered for [Region] = "East" .
NOTE
When you generate the embed token, you need to supply a username, but the username can be any string. Static roles
have a fixed value that isn't dependent on a username, so once the ISV determines the user's role and passes it to the
embed token, the data is filtered according to that role regardless of what username was passed.
Dynamic security
Dynamic security uses the DAX function ( username() or userprincipalname() ) to define the role.
In the user owns data scenario, the RLS model automatically filters data based on the roles of the specific user.
With app owns data, Power BI doesn't know the usernames of the ISV's customers, so you can use the
username() function to dynamically filter the data.
Create a role in Power BI Desktop using the username() function. For example, you can create a role called
CountryDynamic and define it as [CountryRegionCode] = username()
Let's say you want to give your user, jane@contoso.com, access to data for France. When you generate an
embed token for jane@contose.com, you pass the string France as the username in the CountryDynamic role.
Your data will be filtered according to [CountryRegionCode] = France.
{
"accessLevel": "View",
"identities": [
{
"username": "France",
"roles": [ "CountryDynamic"],
"datasets": [ "fe0a1aeb-f6a4-4b27-a2d3-b5df3bb28bdc" ]
}
]
}
When using dynamic security in this scenario, you only need one role for all regions. The region name is used as
the effective identity.
// Create a request for getting an embed token for the rls identity defined above
var tokenRequest = new GenerateTokenRequestV2(
reports: new List<GenerateTokenRequestV2Report>() { new GenerateTokenRequestV2Report(reportId)
},
datasets: datasetIds.Select(datasetId => new
GenerateTokenRequestV2Dataset(datasetId.ToString())).ToList(),
targetWorkspaces: targetWorkspaceId != Guid.Empty ? new
List<GenerateTokenRequestV2TargetWorkspace>() { new GenerateTokenRequestV2TargetWorkspace(targetWorkspaceId)
} : null,
identities: new List<EffectiveIdentity> { rlsIdentity }
);
return embedToken;
}
Next steps
RLS guidance
Generate an embed token More Questions? Try the Power BI Community
Implementing row-level security in embedded
paginated reports
11/24/2022 • 2 minutes to read • Edit Online
This article explains how to embed a paginated report that uses RLS (row-level security) into your app owns
data application.
NOTE
This article is only relevant for app owns data customers.
Prerequisites
This article assumes that you know how to embed a Power BI paginated report. It explains how to
generate the embed token so that the report only shows what the user has permission to access.
Paginated reports are created using the SQL Server Reporting Services engine, and not the Power BI
(Analysis Services) engine, so the RLS filtering is set up in Power BI Report Builder.
2. In the Parameter Name field enter @UserID , and in the Parameter Value add [&UserID] .
3. From the left pane, select Quer y , in the Query add the UserID parameter as part of your query, and click
OK .
NOTE
In the screenshot below the color parameter is used as an example (WHERE FinalTable.Color = @UserID). If
needed, you can create a more complex query.
Generate an embed token
When you embed a paginated report for your customers, use the Reports GenerateTokenInGroup API to get the
embed token. This token can also be used to filter some data out of the paginated report.
You can only generate a token using a ser vice principal . You can't generate a token as a master user. The
service principal has to have at least member permissions to the workspace in the Power BI service. (If the
service principal is a contributor or viewer it won't be able to generate a token).
To generate a token, assign the username field with the information you want to display. For example, in a
paginated report that has a color parameter, if you enter green in the username field, the embed token will
restrict the embedded data to just the data that has green as its value in the color column.
{
"reports": [
{
"id": "8d57615e-cfed-4d60-bd21-7dc05727193c"
}
],
"identities": [
{
"username": "green",
"reports": [
"8d57615e-cfed-4d60-bd21-7dc05727193c"
]
}
]
}
NOTE
If you generate embed token without specifying a user-id, the object-id of service principal will be used.
Next steps
Generate an embed token
Embed a report on an on-premises SQL Server
Analysis Services (SSAS)
11/24/2022 • 5 minutes to read • Edit Online
This article explains how to embed Power BI content with an on-premises Analysis Services Tabular Model live
connection into a standard Power BI app owns data application. This article applies to all live connection SSAS
models whether or not they implement RLS.
In this scenario, the database is on the SSAS (on-premises) model, and the Power BI engine connects to it via a
gateway. The security roles (RLS) and permissions, if there are any, are defined in the SSAS model, and not in
Power BI Desktop.
ISV setup
On-premises row level security is only available with a live connection, but you can create a live connection to
any database whether or not it implements RLS. This includes:
Databases with no RLS roles set up
Databases with members who belong to one or more roles
Databases with static or dynamic security roles
To embed a report from an SSAS model, you need to do the following actions:
1. Set up the gateway
2. Create a live connection
3. Generate an embed token
Master user
Service principal
Service principal profile
// Define the user identity and roles. Use one of the following:
// Create a request for getting an embed token for the rls identity defined above
var tokenRequest = new GenerateTokenRequestV2(
reports: new List<GenerateTokenRequestV2Report>() { new GenerateTokenRequestV2Report(reportId) },
datasets: datasetIds.Select(datasetId => new
GenerateTokenRequestV2Dataset(datasetId.ToString())).ToList(),
targetWorkspaces: targetWorkspaceId != Guid.Empty ? new List<GenerateTokenRequestV2TargetWorkspace>
() { new GenerateTokenRequestV2TargetWorkspace(targetWorkspaceId) } : null,
identities: new List<EffectiveIdentity> { rlsIdentity }
);
return embedToken;
}
Now you can embed your report in your app, and your report will filter data according to the permissions of the
user accessing the report.
Next steps
Generate an embed token
Embed a report with an Azure Analysis Services
(AAS) database
11/24/2022 • 4 minutes to read • Edit Online
This article explains how to embed a Power BI report that uses data stored in Azure Analysis Services (AAS), in
an embed for your customers scenario. This article is aimed at independent software developers (ISVs), who
want to embed a report with AAS data whether or not the database implements row-level security (RLS).
Prerequisites
You'll need a report with a live connection to AAS database, with or without RLS.
Follow these steps to create a new role and add the customData function to the role.
1. Create a role in the Analysis Services server.
2. In the General settings, provide a Role Name and set the database permissions to Read only.
3. In the Membership settings, add the users that are going to call the Embed Token - Generate Token API. If
you're using a service principal that's not an admin, add that as well.
4. In the Row filters settings, set your DAX query using the CUSTOMDATA() function.
Service principal
If you're using a service principal to embed the report, make sure the service principal is a server admin or role
member of AAS. To grant AAS admin permissions to the service principal, see Add a service principal to the
server administrator role. To add the service principal as a role member, go to the Membership settings.
Use the ser vice principal object ID as the username (effective identity).
NOTE
If the service principal is not an admin, and you don't want to make it an admin of the workspace when you migrate,
migrate that model into a separate workspace where you can give it admin permissions.
Use the embed token to embed the report into your app or website. Your report will filter data according to the
applied RLS in the report.
Next steps
Row-level security with Power BI Embedded
Embed a report with cloud-based RLS
paginated-reports-row-level-security
Object level security
11/24/2022 • 2 minutes to read • Edit Online
This article explains how to embed Power BI content that uses OLS in a Power BI App owns data (embed for your
customers)scenario.
In this scenario, the ISV has a table with sensitive data and metadata that they want to hide from the report
customers.
For more information on OLS go to Object level security (OLS).
Prerequisites
This article assumes that you have a report that uses OLS and that you want to embed it into an app. To create a
report that uses OLS, see Object level security (OLS).
The report can built using any of the following models:
Cloud OLS
Live connected report to Azure Analysis Services with OLS roles
Live connected report to SQL Server Analysis Services with OLS roles
// Create a request for getting an embed token for the OLS identity defined above
var tokenRequest = new GenerateTokenRequestV2(
reports: new List<GenerateTokenRequestV2Report>() { new GenerateTokenRequestV2Report(reportId)
},
datasets: datasetIds.Select(datasetId => new
GenerateTokenRequestV2Dataset(datasetId.ToString())).ToList(),
targetWorkspaces: targetWorkspaceId != Guid.Empty ? new
List<GenerateTokenRequestV2TargetWorkspace>() { new GenerateTokenRequestV2TargetWorkspace(targetWorkspaceId)
} : null,
identities: new List<EffectiveIdentity> { olsIdentity }
);
return embedToken;
}
Next steps
Object-level security in Azure Analysis Services
More questions? Try asking the Power BI Community
Troubleshoot your embedded application
11/24/2022 • 11 minutes to read • Edit Online
This article discusses some common issues that can come up when embedding content from Power BI.
Troubleshooting tools
Fiddler Trace
Fiddler is a free tool from Telerik that monitors HTTP traffic. You can see the traffic with the Power BI APIs from
the client machine. This tool may show errors and other related information.
return errorText;
}
We recommend logging the Request ID (and error details for troubleshooting). Provide the Request ID when
approaching Microsoft support.
App registration
App registration failure
Error messages within the Azure portal or the Power BI app registration page will notify you if you don't have
sufficient privileges to register your app. To register an application, you must be an admin in the Azure AD
tenant, or application registrations must be enabled for non-admin users.
Power BI Service doesn't appear in the Azure portal when registering a new App
At least one user must be signed up for Power BI. If you don't see Power BI Ser vice listed within the API list, no
user is signed up for Power BI.
What's the difference between an application object ID and a principal object ID?
When you register an Azure AD app, there are a two parameters called object ID. This section explains the
purpose of each parameter, and how to obtain it.
Application object ID
The application object ID, also known simply as object ID, is the unique ID of your Azure AD application object.
To get the application object ID, navigate to your Azure AD app, and copy it from the Overview .
Principal object ID
The principal object ID, also known simply as object ID, is the unique ID of the service principal object associated
with your Azure AD application.
To get your principal object ID, navigate to your Azure AD app, and from the Overview select the app link in
Managed application in local director y .
Connect-AzureAD
After assigning the policy, wait approximately 15-20 seconds for propagation before testing.
Generate token fails when providing effective identity
GenerateToken can fail, with effective identity supplied, for a few different reasons.
To find your tenant ID, you can use the instructions in Find the Microsoft Azure AD tenant ID and primary
domain name.
For more information, see How to: Sign in any Azure Active Directory user using the multitenant application
pattern.
Data sources
ISV wants to have different credentials for the same data source
A data source can have a single set of credentials for one master user. If you need to use different credentials,
create additional master users. Then, assign the different credentials in each of the master users contexts, and
embed using the Azure AD token of that user.
TokenExpired Access token has expired, N/A Query data Expired token
resubmit with a new access
token. Couldn't render a
report visual titled: visual
title
Typical errors when embedding for non-Power BI users (using an Embed Token)
M ESSA GE DETA IL ED M ESSA GE ERRO R C O DE REA SO N ( S)
TokenExpired Access token has expired, N/A Query data Expired token
resubmit with a new access
token. Couldn't render a
report visual titled: visual
title
Datasets
Manage which portion of the data your users can see
Any user with read permissions for a dataset can see the entire schema (tables, columns and measures) and all
the data. You can't control viewing permissions to raw and aggregated data separately in the same dataset.
To manage which portion of the data your users can view, use one of these methods:
Row-level filtering using Power BI row-level security (RLS).
Object level security (OLS).
Separate the data into different datasets. For example, you can create a dataset that only contains
aggregated data and give your users access to that dataset only.
Content rendering
To resolve rendering issues in embedded Power BI items (such as reports and dashboards), review this section.
Verify that the Power BI item loads in Power BI service
To rule out issues with your application or the embedding APIs, verify that the item can be viewed in the Power
BI service (powerbi.com).
Verify that the Power BI item loads in the Power BI embedded analytics playground
To rule out issues with your application, verify that the Power BI item can be viewed in the Power BI embedded
analytics playground.
Verify that your access token didn't expire
For security purposes, access tokens (An Azure AD token or an embed token) have a limited lifetime. You should
constantly monitor your access token and refresh it if needed. For more information see Refresh the access
token.
Performance
To get the best performing embedded content, we recommend that you follow the Power BI embedded analytics
best practices.
AADSTS70001: Application with identifier <client ID> wasn't found in the directory <directory ID>
The solution is to close the popup, wait a few seconds and try again. You might need to repeat this action a few
times. A time interval causes the issue from completing the application registration process to when it's
available to external APIs.
The following error message appears when running the sample app:
This error occurs because the only value that isn't being injected into the sample application is your user
password. Open the Web.config file in the solution and fill the pbiPassword field with your user's password.
If you get the error - AADSTS50079: The user is required to use multi-factor authentication.
You need to use an Azure AD account that doesn't have MFA enabled.
Using the Embed for your organization sample application
If you're working with the Embed for your organization experience, save and unzip the PowerBI-Developer-
Samples.zip file. Then open the PowerBI-Developer-Samples-master\User Owns Data\integrate-report-web-app
folder and run the pbi-saas-embed-report.sln file.
When you run the Embed for your organization sample app, you get the following error:
AADSTS50011: The reply URL specified in the request doesn't match the reply URLs configured for the
application: <client ID>
This error is because the redirect URL specified for the web-server application is different from the sample's
URL. If you want to register the sample application, use https://localhost:13526/ as the redirect URL.
If you want to edit the registered application, update the Azure AD-registered application, so the application can
provide access to the web APIs.
If you want to edit your Power BI user profile or data, learn how to edit your Power BI data.
If you get the error - AADSTS50079: The user is required to use multi-factor authentication.
You need to use an Azure AD account that doesn't have MFA enabled.
For more information, please see Power BI Embedded FAQ.
More questions? Try the Power BI Community
For further assistance, contact support or create a support ticket via the Azure portal and provide the error
messages you encounter.
Next steps
Power BI Embedded Frequently Asked Questions
More questions? Try the Power BI Community
Troubleshoot REST APIs
11/24/2022 • 2 minutes to read • Edit Online
Next steps
Power BI Embedded Frequently Asked Questions
More questions? Try the Power BI Community
Push datasets limitations
11/24/2022 • 2 minutes to read • Edit Online
Push datasets are ver y limited in their functionality. They're designed only for a near real-time streaming
scenario to be consumed by a streaming tile in a dashboard, and not by a Power BI report.
This article lists limitations of the Power BI REST APIs push datasets.
Limitations
Review the following list of limitations before using the push datasets APIs.
75 max columns
75 max tables
10,000 max rows per single POST rows request
1,000,000 rows added per hour per dataset
5 max pending POST rows requests per dataset
120 POST rows requests per minute per dataset
If table has 250,000 or more rows, 120 POST rows requests per hour per dataset
200,000 max rows stored per table in FIFO dataset
5,000,000 max rows stored per table in 'none retention policy' dataset
4,000 characters per value for string column in POST rows operation
Next steps
Power BI REST APIs.
Push datasets.
Datasets permissions
11/24/2022 • 3 minutes to read • Edit Online
This article describes Power BI permissions in general, and dataset permissions in the context of the Power BI
REST APIs.
Power BI permissions
Power BI has two sets of permissions:
Workspace permissions
Item permissions
Workspace permissions
Workspace permissions, also known as folder permissions or roles, are the highest level of permissions in
Power BI. These permissions override permissions that are given to a specific item in the workspace folder.
The table below lists the four types of folder roles. It shows each role's level, and the code string returned by the
Power BI REST APIs. Admin is the highest workspace permission level, and viewer is the lowest. Every
permission level includes the capabilities of the permissions below it. You can review the capabilities of each
permission in Workspace roles.
Admin 4 ReadWriteReshareExplore
Member 3 ReadWriteReshareExplore
Contributor 2 ReadWriteExplore
Viewer 1 Read
NOTE
The write permission is applied to Power BI datasets created by admin, member and contributor users in a workspace they
own. The write permission can be granted or deleted using workspace permissions only. It cannot directly be granted to,
or deleted from, a Power BI item.
TIP
Although the API permissions are identical to the Power BI service permissions, build permissions are referred to as
explore permissions in the APIs.
Description Allows the user to read the Equivalent to build Allows the user to share the
content of the dataset permissions content of the dataset with
other users who will get
read, reshare, or explore
permissions for it
ReadReshareExplore ️
✔ ️
✔ ️
✔
ReadReshare ️
✔ ❌ ️
✔
ReadExplore ️
✔ ️
✔ ❌
Read ️
✔ ❌ ❌
NOTE
To allow a user to perform write operations on a dataset, first change the workspace permissions.
Next steps
Power BI REST APIs.
Push datasets.
Power BI Developer in a Day course
11/24/2022 • 4 minutes to read • Edit Online
The Power BI Developer in a Day video-based course empowers you as an app developer with the technical
knowledge required to embed Power BI content. It comprises 2 hours 20 minutes of viewable content—available
on demand, and is free of charge. There's also a self-study kit that you can download and use to complete a
series of six hands-on labs.
The course was designed specifically for experienced app developers. So, it's an advantage if you have
development experience with:
ASP.NET
Visual C#
HTML
JavaScript
Familiarity with Power BI will be beneficial, but not essential. We'll introduce you to the core concepts.
After you complete the course, you'll know how to:
Acquire access using Azure AD apps and tokens
Work with the Power BI REST API
Embed Power BI content in your apps
Integrate Power BI content in your apps using the Power BI JavaScript API
Enforce row-level security (RLS) to ensure app users see the right data
Choose the right license to suit your requirements
Watch the welcome and introduction video to start the course.
NOTE
This video might use earlier versions of Power BI Desktop or the Power BI service.
Course outline
The course of 21 videos is organized into eight modules. We recommend you watch the videos in the recorded
sequence, starting with video 01 and ending with video 21.
Introduction
Video 01: Welcome and Course Introduction
Video 02: Self-study Kit
Module 01: Power BI Over view
Video 03: Power BI Overview - Part 1
Video 04: Power BI Overview - Part 2
Video 05: Power BI Overview - Part 3
Video 06: Power BI Overview - Part 4
Module 02: Power BI Embedded Analytics
Video 07: Power BI Embedded Analytics - Part 1
Video 08: Power BI Embedded Analytics - Part 2
Module 03: Configure Permissions
Video 09: Configure Permissions - Part 1
Video 10: Configure Permissions - Part 2
Module 04: Embed Power BI Content
Video 11: Embed Power BI Content - Part 1
Video 12: Embed Power BI Content - Part 2
Module 05: Integrate Content with the Power BI Client APIs
Video 13: Integrate Content with the Power BI Client APIs - Part 1
Video 14: Integrate Content with the Power BI Client APIs - Part 2
Module 06: Configure Data Permissions
Video 15: Configure Data Permissions - Part 1
Video 16: Configure Data Permissions - Part 2
Video 17: Configure Data Permissions - Part 3
Module 07: Automate Solution Management
Video 18: Automate Solution Management - Part 1
Video 19: Automate Solution Management - Part 2
Module 08: Power BI Embedded Analytics Licensing
Video 20: Power BI Embedded Analytics Licensing
Bonus Content
Video 21: Power BI Embedded Analytics Playground
Self-study kit
You can download and set up a self-study kit, which consists of the presentation content and six hands-on labs.
For more information, watch the Self-study Kit video.
To complete the labs, you'll need a Windows PC (Windows 7, or later) and the following software installed:
The latest version of Power BI Desktop.
Visual Studio 2015, or later. We recommend Visual Studio 2019. You can use Community edition, which is
free and suited for learning scenarios. It must have the ASP.NET and web development workload
installed.
A web browser supported by Power BI. We recommend Microsoft Edge.
Follow these steps to get set up:
1. Use this link to download the self-study kit (.zip) locally to your PC.
2. Open the file properties, and then check "unblock" (Windows may flag the file as potentially untrusted).
3. Extract the file contents to a folder in your file system. We recommend you create a folder that will be easy to
find, perhaps naming it Training . The lab documents will refer to this location as <CourseFolder> .
Once extracted, you'll have the PowerBIDevIAD folder, and within it you'll find the following folders:
Lab00A (and all other lab folders). The lab folders contain the lab document and lab resources, which may
include assets and solution files.
MySolution : This folder stores your solution files. The lab instructions will direct you when to use it.
Presentation : This folder contains the course presentation file, which is available as a PDF document.
Get started with the kit
We recommend you watch the online course first. You can refer back to the presentation theory by opening the
<CourseFolder>\PowerBIDevIAD\Presentation\PowerBIDevIAD_Presentation.pdf file. The
presentation includes five lab slides, which indicate when it's time to put the theory to practice. It also includes
many resource links to help you find related content.
When you're ready to commence the first lab, open the
<CourseFolder>\PowerBIDevIAD\Lab00A\PowerBIDevIAD_Lab00A.pdf file. This document guides you
to sign in to the Power BI service and prepare a Power BI report.
NOTE
You're responsible for having your own Power BI account. If you don't already have one, see Sign up for Power BI as an
individual.
Your account must have a Power BI Pro license, or you can still accept a Power BI Pro Trial license—an offer that can only
be accepted once. Also, your account must not have depleted the reserve of free embed tokens, available with the Power
BI Pro license.
Consider creating a Power BI account for exclusive use in the labs. You can create a free account with a public domain like
https://outlook.live.com, and then using it to sign in to Power BI and accept the Power BI Pro Trial license.
Instructor kit
Use this link to download the instructor kit (.zip) locally to your PC. You'll find classroom setup notes in slide one
of the PowerPoint slide deck.
Next steps
For more information related to this article, check out the following resources:
Questions? Try asking the Power BI Community
Suggestions? Contribute ideas to improve Power BI
Monitoring Power BI Embedded data reference
11/24/2022 • 3 minutes to read • Edit Online
See Monitor Power BI Embedded for details on collecting and analyzing monitoring data for Power BI
Embedded.
TIP
Use the Premium Gen2 Monitoring App to monitor your Embedded Gen 2 capacity.
Metrics
This section lists all the automatically collected platform metrics collected for Power BI Embedded.
Capacities Microsoft.PowerBIDedicated/capacities
Capacities
Resource Provider and Type: Microsoft.PowerBIDedicated/capacities
Metric dimensions
Power BI Embedded does not have any metrics that contain dimensions.
For information about metric dimensions, see Multi-dimensional metrics.
Resource logs
This section lists the types of resource logs you can collect for Power BI Embedded.
For reference, see a list of all resource logs category types supported in Azure Monitor.
This section lists all the resource log category types collected for Power BI Embedded.
Capacities Microsoft.PowerBIDedicated/capacities
Azure Monitor Logs tables
This section refers to all of the Azure Monitor Logs Kusto tables relevant to Power BI Embedded and available for
query by Log Analytics.
RESO URC E T Y P E N OT ES
Power BI Embedded
TA B L E DESC RIP T IO N
AzureActivity Entries from the Azure Activity log that provides insight into
any subscription-level or management group level events
that have occurred in Azure.
AzureDiagnostics Stores resource logs for Azure services that use Azure
Diagnostics mode. Resource logs describe the internal
operation of Azure resources.
For a reference of all Azure Monitor Logs / Log Analytics tables, see the Azure Monitor Log Table Reference.
Activity log
You can select Engine and/or the AllMetrics categories.
Engine
The engine category instructs the resource to log the events listed below. For each event, there are properties.
Audit Login Records all new connection to the engine events since the
trace started.
Session Initialize Records all session initialization events since the trace
started.
Vertipaq Query Begin Records all VertiPaq SE query begin events since the trace
started.
Query Begin Records all query begin events since the trace started.
Query End Records all query end events since the trace started.
Vertipaq Query End Records all VertiPaq SE query end events since the trace
started.
Audit Logout Records all disconnect from engine events since the trace
started.
Error Records all engine error events since the trace started.
Event example
The table below shows an event example.
AllMetrics
Checking the AllMetrics option logs the data of all the metrics that you can use with a Power BI Embedded
resource.
The following table lists the operations related to Power BI Embedded that may be created in the Activity log.
Schemas
Power BI Embedded uses the Power BI Dedicated schema.
Next steps
Monitor Azure Power BI Embedded
Azure resource diagnostic logging
Set-AzureRmDiagnosticSetting
Glossary for Power BI developers
11/24/2022 • 21 minutes to read • Edit Online
Power BI may introduce terminology that is unfamiliar or confusing. This glossary is a great place to look up
terminology, you might even want to keep it bookmarked. Other great resources for learning about the building
blocks that make up Power BI are Power BI service basic Concepts and Basic concepts for designers. These
articles give a high-level overview of the Power BI pieces and how they're connected.
This glossary is a community effort. Don't see a word here? Ask us to add it (you can use the documentation
feedback button at the bottom of this article).
A
Account
Use your work or school account to sign in to Power BI. Administrators manage work or school accounts in
Azure Active Directory. Your level of access is determined by the Power BI license associated with that account
and the capacity type where content is stored. See license and Premium , below.
Admin portal
The location where Power BI admins manage users, features, and settings for Power BI in their organization.
(Note: Microsoft 365, Azure, and PowerApps use admin center.)
Aggregates
When the values of multiple rows are grouped together as input on criteria to form a single value of more
significant meaning or measurement. Only implicit measures (see definition below) can be aggregated.
Aggregation
The reduction of rows in underlying data sources to fit in a model. The result is an aggregate.
Alert, alerts
A feature that notifies users of changes in the data based on limits they set. Alerts can be set on tiles pinned
from report visuals. Users receive alerts on the service and on their mobile app.
Annotate
To write lines, text, or stamps on a snapshot copy of a tile, report, or visual on the Power BI mobile app for iOS
and Android devices.
App, apps
A bundle of dashboards, reports, and datasets. It also refers to the mobile apps for consuming content, such as
Power BI app for iOS.
AppSource
Centralized online repository where you can browse and discover dashboards, reports, datasets, and apps to
download.
ArcGIS for Power BI
ArcGIS is a mapping and analytics platform created by the company ESRI. The name of the visual included in the
Power BI visuals library is called ArcGIS for Power BI.
Artifacts
See item
Auto Insights
Auto insights are now called Quick Insights.
Azure AD, Azure Active Directory
The identity service in Microsoft Azure that provides identity management and access control capabilities
through a REST-based API.
Azure Key Vault
The pay-as-you-go security solution that uses a single location (the vault) in Azure to store, secure and manage
cryptographic keys and secrets that can then be invoked by URI and used by applications for small, high-value
security data, such as authentication keys, storage account keys, data encryption keys, .pfx files, and passwords.
B
BI, business intelligence
Bookmark
A view of data captured in the Bookmarks pane of a report in Power BI Desktop or service. In Desktop, the
bookmarks are saved in the .pbix report file for sharing on the Power BI service
Breadcrumbs
The navigation at the top left to quickly navigate between reports and dashboards.
C
Capacity
A capacity is a dedicated set of resources reserved for exclusive use. It offers dependable, consistent
performance for your content.
Card (visual type )
A Power BI visual type.
Card (Power BI Home )
Power BI Home displays rectangular and square pictures that represent dashboards, reports, apps, and more.
These pictures are referred to as cards.
Certified custom visual
A Power BI custom visual that has met requirements and passed strict security testing.
Connect live
A method of connecting to SQL Server Analysis Services data models. Also called a live connection.
Connector
Power BI Desktop includes an ever-growing collection of data connectors that are built to connect to a specific
data source. Examples include: GitHub, MailChimp, Power BI dataflows, Google Analytics, Python, SQL Server,
Zendesk, and more than 100 other data sources.
Container
The areas on the navigation pane are containers. In the nav pane you'll find containers for: Favorites, Recent,
Apps, Shared with me, and Home.
Content
Content for the Power BI service is generally dashboards, reports, and apps. It can also include workbooks and
datasets.
Content list
The content index for an app.
Content view
The view in Windows Explorer that displays the most relevant content for each item based on its file name
extension or Kind association.
Continuous variable
A continuous variable can be any value between its minimum and maximum limits, otherwise it's a discrete
variable. Examples are temperature, weight, age, and time. Continuous variables can include fractions or
portions of the value. The total number of blue skateboards sold is a discrete variable since we can't sell half a
skateboard.
Correlation
A correlation tells us how the behaviors of things are related. If their patterns of increase and decrease are
similar, then they're positively correlated. And if their patterns are opposite, then they're negatively correlated.
For example, if sales of our red skateboard increase each time we run a tv marketing campaign, then sales of the
red skateboard and the tv campaign are positively correlated.
Cross-filter
Applies to visual interactions. Cross-filtering removes data that doesn't apply. For example, selecting
Moderation in the doughnut chart cross-filters the line chart. The line chart now only displays data points that
apply to the Moderation segment.
Cross-highlight
Applies to visual interactions. Cross-highlighting retains all the original data points but dims the portion that
doesn't apply to your selection. For example, selecting Moderation in the doughnut chart cross-highlights the
column chart. The column chart dims all the data that doesn't apply to the Moderation segment, and highlights
all the data that does apply to the Moderation segment.
Custom visual
Visuals that are created by the community and Microsoft. They can be downloaded from the Office store for use
in Power BI reports. You can also develop your own personalized custom visual.
D
Dashboard
In the Power BI service, a dashboard is a single page, often called a canvas, that uses visualizations to tell a story.
Because it's limited to one page, a well-designed dashboard contains only the most important elements of that
story. Dashboards can only be created and viewed in the Power BI service, not in Power BI Desktop. For more
information, see basic concepts, dashboards.
Data connector
See connectors
Data model, Excel Data Model
In Power BI content, a data model refers to a map of data structures in a table format. The data model shows the
relationships that are being used to build databases. Report designers, administrators, and developers create
and work with data models to create Power BI content.
Dataflow
Dataflows ingest, transform, integrate, and enrich big data by defining data source connections, ETL logic,
refresh schedules, and more. Formerly data pool.
Dataset
A collection of data used to create visualizations and reports.
DAX expression
Data Analysis Expressions . A Microsoft formula language used to build formulas and expressions in Power BI
Desktop, Azure Analysis Services, SQL Server Analysis Services, and Power Pivot in Excel.
Desktop or Power BI Desktop
Free Power BI tool used primarily be report designers, admins, and developers.
Diamond
Power BI Premium. The shape of the icon that signifies a workspace is a Premium capacity workspace.
Dimension
Dimensions are categorical (text) data. A dimension describes a person, object, item, products, place, and time. In
a dataset, dimensions are a way to group measures into useful categories. For our skateboard company, some
dimensions might include looking at sales (a measure) by model, color, country/region, or marketing campaign.
Drill up, drill down, drill through
In Power BI, "drill down" and "drill up" refer to the ability to explore the next level of detail in a report or visual.
"Drill through" refers to the ability to select a part of a visual and be taken to another page in the report, filtered
to the data that relates to the part of the visual you selected on the original page. Drill to details commonly
means to show the underlying records.
E
Editing View
The mode in which report designers can explore, design, build, and share a report.
Effective identity
The identity used by the generate token API to generate a token for an individual user, depending on that user's
credentials in the app. It could be a master user or service principal.
Ellipsis
Three dots - ... Selecting an ellipsis displays more menu options. Also referred to as the More actions menu.
Embed code
A common standard across the internet. In Power BI, the customer can generate an embed code and copy it to
place content such as a report visual on a website or blog.
Embed token
A string of encrypted characters that is used for authentication, which specifies the content the web app user can
access and the user’s access level.
Embedded
See Power BI Embedded.
Embedding
In the Power BI developer offering, the process of integrating analytics into apps using the Power BI REST APIs
and the Power BI SDK.
Environment
[Power BI Desktop, Power BI Mobile, the Power BI service, etc.] Another way to refer to one of the Power BI tools.
It's okay to use Power BI environment (tenant) in documentation where it may help business analysts who are
familiar with the term tenant to know it's the same thing.
Explicit measures
Power BI uses explicit measures and implicit measures (see definition below). Explicit measures are created by
report designers and saved with the dataset. They're displayed in Power BI as fields, and can therefore be used
over and over. For example, a report designer creates an explicit measure TotalInvoice that sums all invoice
amounts. Colleagues who use that dataset and who have edit access to the report, can select and use that field
to create a visual. When an explicit measure is added or dragged onto a report canvas, Power BI doesn't apply an
aggregation. Creating explicit measures requires edit access to the dataset.
F
Favorite, unfavorite
Verb meaning to add to the Favorites list for quick access to frequently visited dashboards and reports in Power
BI. When you no longer want them as a favorite, you unfavorite them.
Filter versus highlight
A filter removes data that doesn't apply. A highlight grays out the data that doesn't apply.
Focus mode
Use focus mode to pop out a visual or tile to see more detail. You can still interact with the visual or tile while in
focus mode.
Free account
See account
Full screen, full-screen mode
Use full screen mode to view Power BI content without the distraction of menus and navigation panes. Full
screen mode is sometimes referred to as TV mode.
G
Gateways or on-premises data gateways
A bridge to underlying data sources. It provides quick and secure data transfer between the Power BI service and
on-premises data sources that support refresh. Managed by IT.
H
High-density visuals
Visuals with more data points than Power BI can render. Power BI samples the data to show the shape and
outliers.
Home
The default landing page for Power BI service users. Doesn't modify anything. Can be called Power BI Home or
simply Home.
I
Inline frame, IFrame
An IFrame is component of an HTML element that allows you to embed reports and other items inside your app.
It's essentially a way to display a secondary webpage inside the main page.
Implicit measures
Power BI uses implicit measures and explicit measures (see definition above). Implicit measures are created
dynamically. For example, when you drag a field onto the report canvas to create a visual. Power BI
automatically aggregates the value using one of the built-in standard aggregations (SUM, COUNT, MIN, AVG,
etc.). Creating implicit measures requires edit access to the report.
Independent Software Vendor, ISV
A third-party software developer. An ISV can be an individual or an organization that independently creates
computer software.
Insights
See quick insights .
Item
A component type of the Power BI workspace that includes dashboards, reports, datasets, and data flows.
Formerly known as artifacts.
J
K
KPIs
Key performance indicators. A type of visual.
L
Left navigation (left nav)
The controls along the left edge of Power BI service.
License
Your level of access is determined by the Power BI license associated with your account and the capacity type
where content is stored. For example, in shared capacity, a user with a Power BI Pro license can collaborate only
with users who are also assigned a Pro license. In shared capacity, a free license enables access to only the user’s
personal workspace. However, when content is in Premium capacity, users with a Pro license can share that
content with users who are assigned a free license.
A license is assigned to a user and can be a free or Pro license. Depending on how the license was acquired, it
may be paid or unpaid. The accounts are either: per-user or organizational. Per-user accounts are available as
free or Pro. A Power BI free user is either using stand-alone Power BI Desktop or is using Power BI service stand-
alone or is using Power BI service within an organization that has a Premium organizational subscription. The
Power BI per-user Pro account is a paid monthly subscription that allows for collaboration and sharing of
content with other Pro users.
The organizational Premium (also known as Premium capacity) subscription adds a layer of features on top of
per-user licenses. For example, free per-user account holders within an organization that has a Premium
subscription, are able to do much more with Power BI than free users without Premium. For example, free users
in Premium organizational accounts, can collaborate with colleagues and can view content that's hosted on
Power BI Premium capacity.
List page or content list
One of the section pages for the elements in the nav pane. For example, Favorites, Recents, My workspace, etc.
M
Measure
A measure is a quantitative (numeric) field that can be used to do calculations. Common calculations are sum,
average, and minimum. For example, if our company makes and sells skateboards, our measures might be
number of skateboards sold and average profit per year.
Mobile app
Apps that allow you to run Power BI on iOS, Android, and Windows devices.
Modeling
[Power BI Desktop] Getting the data you've connected to ready for use in Power BI. Modeling includes creating
relationships between tables in multiple data sources, creating measures, and assigning metrics.
My workspace
The workspace for each Power BI customer to use to create content. If a customer wants to bundle anything
created here into an app, and they have designer permissions, they upload it to the appropriate workspace or
create a new one.
N
Native
Included with the product. For example, Power BI comes with a set of native visualization types. But you can also
import other types, such as Power BI visuals.
Navigation pane or nav pane
The controls along the left edge of the Power BI service.
Notification
Messages sent by and to the Power BI Notification Center.
Notification Center
The location in the service where messages are delivered to users, such as notice of sunsetting certain features.
O
OneDrive for Business vs OneDrive
OneDrive is a personal account and OneDrive for Business is for work accounts.
On-premises
The term used to distinguish local computing (in which computing resources are located on a customer's own
facilities) from cloud computing.
P
PaaS
PaaS stands for platform as a service. For example, Power BI Embedded.
Page
Reports have one or more pages. Each tab on the report canvas represents a page.
Paginated reports
Paginated reports are designed to be printed or shared. They're called paginated because they're formatted to fit
well on a page. They display all the data in a table, even if the table spans multiple pages. You can control their
report page layout exactly. Power BI Report Builder is the standalone tool for authoring paginated reports.
PBIVIZ
The file extension for a Power BI custom visual.
PBIX
The file extension for a Power BI Desktop file.
Permissions
What a user can and can't do in Power BI is based on permissions. As a consumer you won't have the same
permissions as a designer, administrator, or developer.
Phone report
The name for a Power BI report that's been formatted for viewing on the phone.
Phone view
The user interface in the Power BI service for laying out a phone report.
Pin, unpin
The action a report designer takes of placing a visual, usually from a report, onto a dashboard.
Power BI Desktop
Also referred to as Desktop. The free Windows application of Power BI you can install on your local computer
that lets you connect to, transform, and visualize your data. Used by report designers and admins. For more
information, see What is Power BI.
Power BI Embedded
A product used by developers to embed Power BI dashboards and reports into their own apps, sites, and tools.
Power BI Premium
An add-on to the Power BI Pro license that enables organizations to predictably scale BI solutions through the
purchasing of reserved hardware in the Microsoft cloud. See account.
Power BI Pro
A monthly per-user license that provides the ability to build reports and dashboards, collaborate on shared data,
keep data up-to date automatically, audit and govern how data is accessed and used, and the ability to package
content to distribute (Power BI apps). See account.
Power BI Report Builder
A free, standalone Windows Desktop application used for authoring paginated reports. Used by report
designers. For more information, see Power BI Report Builder. Power BI Report Builder can be downloaded from
the Power BI site.
Power BI Report Server
An on-premises report server with a web portal in which you display and manage reports and KPIs. It allows
organizations to build distributed, hybrid BI systems (a mix of cloud and on-premises deployments).
Power BI service
An online SaaS (Software as a service) service. For more information, see What is Power BI.
Power BI tenant
A Power BI account for an organization which has its data stored separately from other organizations but which
is accessed through a shared service.
Premium workspace
A workspace running in a capacity, signified to customers by a diamond icon.
Pro license or Pro account
See account.
Publish
Power BI service report designers bundle the contents of a Power BI workspace to make it available to others as
a Power BI app. Power BI Desktop report designers use publish to refer to sending a Power BI Desktop report in
.pbix format to the Power BI service so that they can build dashboards from it and easily share it with others.
Q
Q&A
The ability to type natural language questions about a dataset and get responses in the form of visualizations.
Appears in the Power BI service and Desktop.
Q&A virtual analyst
[Power BI Mobile] For iOS, the conversational UI for Q&A.
QR codes
[Power BI Mobile] A matrix barcode that can be generated for dashboards or tiles in the Power BI service to
identify products. QR codes can be scanned with a QR code reader, or with the Power BI Mobile app on iOS or
Android, to link directly to the dashboard or tile.
Query string parameter
Add to a URL to pre-filter the results seen in a Power BI report. In the broadest sense, a query string recovers
information from a database.
Quick Insights
Quick Insights refer to automatically generated insights that reveal trends and patterns in data.
R
R, Microsoft R
A programming language and software environment for statistical computing and graphics.
Reading View
Read-only view for reports (as opposed to Editing View).
Real-time streaming
The ability to stream data and update dashboards in real time from sources such as sensors, social media, usage
metrics, and anything else from which time-sensitive data can be collected or transmitted.
Recent
The container in the nav pane that holds all the individual items (reports, dashboards, etc.) that were accessed
last.
Related content
Shows the individual pieces of content that contribute to the current content. For example, for a dashboard, you
can see the reports and datasets providing the data and visualizations on the dashboard.
Relative links
Links from dashboard tiles to other dashboards and reports that have been shared directly or distributed
through a Power BI app. This enables richer dashboards that support drill through.
Report
A multi-perspective view into a single dataset, with visualizations that represent different findings and insights
from that dataset. It can have a single visualization or many, a single page or many pages.
Report editor
The report editor is where new reports are created and changes are made to existing reports by report
designers.
Report measures
Also called custom calculations. Excel calls these calculated fields. See also measures.
Responsive visuals
Visuals that change dynamically to display the maximum amount of data and insights, no matter the screen size.
Row-level security, RLS
Power BI feature that enables database administrators to control access to rows in a database table based on the
characteristics of the user executing a query (for example, group membership).
Administrators can configure RLS for data models imported into Power BI with Power BI Desktop.
S
SaaS
Software as a service (or SaaS) is a way of delivering applications over the internet—as a web-based service.
Also referred to as: web-based software, on-demand software, or hosted software.
Scalability
The capability of a piece of hardware or software or network to expand or shrink to meet future needs and
circumstances.
Screenshot
Simple screenshots of a report can be emailed using the send a screenshot feature.
Service
See Power BI service A standalone resource available to customers by subscription or license. A service is a
product offering delivered exclusively via the cloud.
Service principal
An identity created for use with applications, hosted services, and automated tools to access Azure resources.
The service principal tokens can be used to authenticate and grant access to specific Azure resources from a
user-app, service or automation tool, when an organization is using Azure Active Directory.
It can sometimes replace the master user to authenticate with Power BI.
Settings
The location for Power BI users to manage their own general settings, such as whether to preview new features,
set the default language, close their account, etc. Also, users manage individual settings for content assets, alerts,
and subscriptions. Represented by a cog icon.
Share, sharing
In Power BI, sharing typically means directly sharing an individual item (a dashboard or report) with one or
more people by using their email address. Requires a Power BI Pro license for sender and recipient. On mobile
devices, share can refer to native OS share functionality, such as "annotate and share."
Shared with me
The container in the nav pane that holds all the individual items that were directly shared by another Power BI
user.
Single sign-on, SSO
An authentication process that permits a user to log on to a system once with a single set of credentials to
access multiple applications or services.
Snapshot
In Power BI, a snapshot is a static image vs. a live image of a tile, dashboard, or report.
SQL Server Analysis Services (SSAS )
An online analytical data engine used in decision support and business analytics, providing the analytical data
for business reports and client applications such as Power BI, Excel, Reporting Services reports, and other data
visualization tools.
SQL Server Reporting Services (SSRS )
A set of on-premises tools and services to create, deploy, and manage report servers and paginated reports.
Streaming data
See real-time streaming.
Subscriptions, Subscribe
You can subscribe to report pages, apps, and dashboards and receive emails containing a snapshot. Requires a
Power BI Pro license.
Summarization
[Power BI Desktop] The operation being applied to the values in one column.
T
Tenant
A client organization that is served from a web service (SaaS) which also serves other client organizations, and
each organization’s data is stored in a separate database.
Tiles
A tile is a snapshot of your data, pinned to the dashboard. A tile can be created from a report, dataset,
dashboard, the Q&A box, Excel, SQL Server Reporting Services (SSRS) reports, and more.
Time series
A time series is a way of displaying time as successive data points. Those data points could be increments such
as seconds, hours, months, or years.
U
User Principal Name (UPN )
A format used to specify an internet-style name, such as User.Name@example.microsoft.com. The format
consists of a login name and domain separated by the @ symbol.
V
Value, values
Numerical data to be visualized.
Visual, visualization
A chart. Some visuals are: bar chart, treemap, doughnut chart, map.
Visual interaction
One of the great features of Power BI is the way all visuals on a report page are interconnected. If you select a
data point on one of the visuals, all the other visuals on the page that contain that data change, based on that
selection.
Visualizations pane
Name for the visualization templates that ship in the shared report canvas for Power BI Desktop and the Power
BI service. Contains small templates, also called icons, for each native visualization type.
W
Workbook
An Excel workbook to be used as a data source. Workbooks can contain a data model with one or more tables of
data loaded into it by using linked tables, Power Query, or Power Pivot.
Workspace
Containers for dashboards, reports, and datasets in Power BI. Users can collaborate on the content in any
workspace except My workspace. The contents can be bundled into a Power BI app. Those stored in Premium
capacity can be shared with Free users. Personal workspaces (under My workspace) can be hosted in Premium
capacity.
X
X -axis
The axis along the bottom, the horizontal axis.
Y
Y -axis
The axis along the side, the vertical axis.
Z
Next steps
Basic concepts for Power BI service consumer
Basic concepts for designers
Power BI Dev Camp
11/24/2022 • 3 minutes to read • Edit Online
Power BI Dev Camp (third-party site) is an educational resource for developers who want to learn more about
Power BI as a developer platform. It covers topics such as Power BI embedding and the development of Power BI
visuals and custom connectors.
This article provides links to some of the Power BI Dev Camp resources.
Tutorials
The Power BI Dev Camp tutorials are targeted towards developers who are interested in understanding how to
embed Power BI items (such as reports, dashboards and tiles) and do other basic embedding tasks.
App owns data tutorials
User owns data tutorials
App owns data embedding with .NET 5 - A tutorial that shows developers how to create a .NET 5 MVC web
application that implements Power BI embedding using the app owns data embedding model. The tutorial
covers advanced topics such as adding project support for TypeScript using node.js , and programming the
Power BI REST API to generate multi-resource access tokens.
Tabular-Object-Model-Tutorial A tutorial and sample code programming datasets using the Tabular Object
Model with Power BI Desktop and the Power BI Service via the XMLA endpoint.
PowerBI-PowerShell-Tutorial Students files for the Power BI PowerShell tutorial from Power BI Dev Camp.
Examples
The Power BI Dev Camp examples provide additional resources for developers who are looking to embed Power
BI items (such as reports, dashboards and tiles).
App owns data examples
User owns data examples
App owns data hello world - A minimal .NET 5 application example to embed either a standard Power BI
report or a paginated report. You can run and test the code in either Visual Studio Code or Visual Studio
2019. It also includes details for using a Power BI cloud other than the public cloud, which has different
URLs and different Azure ID resource IDs.
App owns data custom web API - A .NET 5 custom web API example, with a single page application (SPA)
client created using JavaScript. The custom web API interacts with the Power BI service API as a service
principal, and returns embedding data and embed tokens back to the client. This example demonstrates
collecting telemetry data from the SPA client and storing it in a custom database to monitor report
loading performance.
App owns data and RLS - An example of a web application built using .NET 5 and Power BI app owns data
embedding. Created to demonstrate how to design a security authorization model, which leverages
EffectiveIdentity and Row-level Security (RLS).
App owns data multitenant - An example of a developer project demonstrating how to use service
principal profiles to manage a multitenant environment with Power BI and App-Owns-Data embedding.
Salesforce app owns data embedding - An example of a project that demonstrates how to implement app
owns data embedding with Power BI reports. This project has been created using the Salesforce
developer experience (SFDX) and the Salesforce command line interface (CLI). The goal of this example is
to provide guidance and demonstrate best practices for developers who need to implement Power BI
embedding in a Salesforce environment.
Tenant management application for Power BI - A .NET 5 sample application that demonstrates how to
manage service principals within a large-scale Power BI embedding environment with thousands of
customer tenants.
Videos
To view the Power BI Dev Camp videos, go to the video page.
Presentations
The Power BI Dev Camp presentations can be downloaded from the Camp-Sessions GitHub repository.
Next steps
Embed Power BI content into an application for your customers
Embed Power BI content into an application for your organization
Embed a Power BI report in an application for your organization
Power BI embedded analytics playground
More Questions? Try the Power BI Community