Upload a local PBIX file using the import API
We are currently previewing a new REST API that will allow a developer to programmatically upload a Power BI designer file (PBIX) to a user’s workspace. This new API is called the Import API and it is currently available in our beta version of the Power BI API. The vision for the import API is that it will allow a developer to take a package of content like a PBIX or Excel file, import it into a user’s Power BI workspace. This will split the package into its individual parts like datasets and reports. It will then provide a metadata link between the actual import operation and the objects that were created from it.
Let’s look at an example of how to call the import REST API to import a PBIX file. In this example, I will be using a tool called fiddler.
- To import a PBIX file we must form a “POST” request to https://api.powerbi.com/beta/myorg/imports
- The POST request for PBIX takes two parameters:
- datasetDisplayName which is the name you want the resulting dataset to have after the import is complete.
- nameConflict which is the behavior that you want to happen if the name of that dataset already exists. The options are:
- Abort – fails the post request and returns 409 conflict status
- Overwrite – replaces the dataset and report that is in the user’s workspace with the contents of the PBIX file.
- Ignore (default) – ignores the conflicting name and creates the dataset and report anyway.
- The request also requires the standard authorization header with bearer token (https://msdn.microsoft.com/en-US/library/mt203565.aspx). The required security scope for this operation is: Create content (preview).
- The final request with all of its headers will look something like this:
- As you can see, the content type for this operation is multipart/form-data (http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2). The body of the request will include all the bytes of the file and looks something like this:
- When the request is executed, you will receive a 202 accepted response. This does not mean that the import has completed. The import operation is actually run asynchronously. 202 means that it has been queued. In the response body you will also receive the import ID which can be used to monitor the status of the import:
- To check the status, you need to make a GET call to “https://api.powerbi.com/beta/myorg/imports/1db51a3d-94ea-4a43-9df2-10ab08c1922a”. This call requires the following permission scope: View content properties (preview).
- If the import is complete, you will see a JSON response that will look something like this:
- The response includes all the information about the report and dataset that was created. It even includes a deep link to view the report in the Power BI UI.
- In the service itself, the user will also see the newly created artifacts:
- You can also see the metadata for all your imports by making a “GET” call on https://api.powerbi.com/beta/myorg/imports.
The import REST API is in early preview and we will be making improvements and adding new functionality to it as time moves on. Please let our team know any feedback that you may have.
