We’re excited to share some new APIs that are now enabled in Power BI and describe how you can use them in your applications. Below, we’ll talk about the new APIs we’ve added to let developers upload content to Power BI programmatically and to integrate tiles into their applications. The new APIs are in the Beta namespace so we can get your feedback and iterate the designs as needed.
All of the Power BI APIs mentioned below require an application registered in AAD. Your application needs to login a Power BI user and make the API calls to access the user’s account.
Let start with a roundup of REST APIs we’ve added or updated recently:
Imports API
In case you missed it, we added the Imports API a little while ago. With the imports API you can upload a Power BI desktop file to the Power BI service. This is great if you’d like to publish a report automatically using a console application. For more information, see Upload a local PBIX file using the import API.
GET https://api.powerbi.com/beta/myorg/imports
GET https://api.powerbi.com/beta/myorg/imports/import
Dashboards API
The new Dashboards API allows you list the dashboards in a user’s account. This gives you a list of DashboardIDs, and their user defined names.
GET https://api.powerbi.com/beta/myorg/dashboards
Tiles and Tile APIs
The new Tiles API allows you to list tiles on a specific dashboard, including their friendly name and an embed URL (more on that below). The Tile API enables you to retrieve detailed properties of a specific tile and to refresh the tile data.
GET https://api.powerbi.com/beta/myorg/dashboards/{DashboardID}/tiles
GET https://api.powerbi.com/beta/myorg/dashboards/{DashboardID}/tiles/{TileID}
Groups API
The new Groups API lets you list the Groups a user belongs to. In the PowerBI.com user experience you see it’s possible to place content either in a personal workspace or a group workspace. Just like you can access content in a personal workspace, you can do the same for content in a group.
GET https://api.powerbi.com/V1/myorg/groups
GET https://api.powerbi.com/V1/myorg/groups/{groupID}
Anywhere you call ../myorg/… to call into a personal workspace, you can make those same API calls in a group by adding …groups/{group DI}/… to the method call.
Integrating tiles into Applications
Often developers want to integrate content from a user’s Power BI account into their own application UI. Our new tile API allows you to do just that for tiles that are on a user’s dashboards. You can leverage this to add personalized BI content from your user’s Power BI account into your application. You can enable experiences like: when a user clicks on the tile integrated into your application, they can drill through to the underlying Power BI report to see details if something needs to be investigated right away.
To use the tile integration APIs, as a developer you would do the following:
1) In your application, login the user using Azure Active Directory. The AAD team has a great post with quick starts for virtually any platform.
2) Let the user pick the tile(s) they want to show in your application UI.
-
- Use the Dashboards API to list the dashboards the user has access to.
- Use the Tiles API to list the tiles on the user’s dashboards.
- This will give you an ‘embedUrl’ property. Here’s an example tile embed URL:
-
-
https://app.powerbi.com/embed?dashboardId=c2411ca0-f4fc-4b6f-b2f1-02f62281290d&tileId=9a6b1f88-08b6-47c4-986d-d185b9fa9fbb
3) Add an iFrame in your application that points to the embed URL for the tile
var iframe = document.getElementById(‘iFrameEmbedTile’); iframe.src = embedTileUrl + “&width=” + width + “&height=” + height; iframe.onload = postActionLoadTile;
When making this call, add the width and height you want the tile to have to match the width and height you set on the iFrame. You must handle the onload event in your code. If you miss this step, you’ll get an ‘infinite spinney’.
4) When the iFrame sends the loaded event, post a message containing the AccessToken to the iFrame.
// get the access token. accessToken = document.getElementById(‘MainContent_accessTokenTextbox’).value; // construct the push message structure var m = { action: “loadTile” , accessToken: accessToken , height: 500 , width: 722 }; message = JSON.stringify(m); // push the message. iframe = document.getElementById(‘iFrameEmbedTile’); iframe.contentWindow.postMessage(message, “*”);
You’ll see the tile render in your application. The tile will automatically scale to fit within your application based on the height and width you provide. You should keep the tile size larger than the smallest tile size in Power BI dashboards. Power BI tiles have a ratio of 13:9 (width:height). Keeping that in mind will optimize your results.
5) Handle user interactions with the tile by listening for the tileClicked post message
// listen for message to receive tile click messages. if (window.addEventListener) { window.addEventListener(“message”, receiveMessage, false); } else { window.attachEvent(“onmessage”, receiveMessage); } //The embedded tile posts messages for clicks to parent window. Listen and handle as appropriate function receiveMessage(event) { messageData = JSON.parse(event.data); if (messageData.event === “tileClicked”) { window.open(messageData.navigationUrl); } }
The navigationUrl property returns to you a URL you can use to open the report or Q&A from which the tile was pinned. This enables you to build a ‘drill to details’ type scenario. Alternatively, you can open the dashboard the tile is on by building the URL to the dashboard manually following the scheme:
urlVal = “https://app.powerbi.com/dashboards/{0}”; urlVal = urlVal.replace(“{0}”, dashboardId); window.open(urlVal);
You can review our Sample on GitHub to see a working example end to end.
Filtering tiles integrated into your application
Often when you’re building your application, you want to filter the content to match your UI. We’ve added an initial filter capability for tiles, reports and Q&A. For example, if you have a tile that shows quarterly sales trends for all products, you can use the filter to filter the tile to show data for a specific product. The filter supported at the time of writing is a single categorical value in ODATA syntax.
Passing a filter to an iFrame
https://app.powerbi.com/embed?dashboardId=c2411ca0-f4fc-4b6f-b2f1-02f62281290d&tileId=9a6b1f88-08b6-47c4-986d-d185b9fa9fbb}&$filter={FieldName} eq ‘{FieldValue}’
The FieldName must be in the data model. The FieldName must not include spaces or special characters. Fields are contained in tables, so your FieldName should be specified as TableName/FieldName. So if you have a table called “Cars” that contains a field “car”, you would use the FieldName “Cars/car”. The filter is ANDed with any existing filters already applied to the tile, report or Q&A. Since the filter will be ANDed to other filter clauses already in the query – be aware this can result in no data being shown: know your model :).
When you use a filter as specified, the navigationUrl for the tile will be updated to include the filter. The filter will be passed to the report or Q&A if they are opened using the navigationUrl.
We’re excited to get this preview into your hands early. We’d love to hear your feedback, let us know what additional capabilities you want. Submit your suggestions at https://support.powerbi.com.
Resources:
Power BI REST API documentation Get the sample Integrate a tile documentation Azure Active Directory quick starts