Automate your deployment pipeline using APIs and Azure DevOps

The Power BI deployment pipelines tool enables BI teams to build an efficient and reusable release process for their Power BI content.

To achieve continuous integration and continuous delivery (CI/CD) of content, many organizations use various automation tools, including Azure DevOps. Organizations that use Azure DevOps, can use the Power BI automation tool extension, which supports many of the deployment pipelines API operations.

You can leverage the deployment pipelines Power BI REST APIs, to integrate Power BI into your organization's automation process. Here are a few examples of what can be done using the APIs:

  • Manage pipelines from start to finish, including creating a pipeline, assigning a workspace to any stage, deploying and deleting the pipeline.

  • Assign and unassign users to and from a pipeline.

  • Integrate Power BI into familiar DevOps tools such as Azure DevOps or GitHub Actions.

  • Schedule pipeline deployments to happen automatically at a given time.

  • Deploy multiple pipelines at same time.

  • Cascade depending pipeline deployments - If you have content that's connected across pipelines, you can make sure some pipelines are deployed before others.

Deployment pipelines API functions

The deployment pipelines Power BI REST APIs, allow you to perform the following functions:

  • Get pipeline information - Retrieve information about your pipelines and their content. Getting the pipeline information will enable you to dynamically build the deployment API calls. You can also check the status of a deployment, or the deployment history.

  • Deploy - The REST calls enables developers to use any type of deployment available in the Power BI service.

  • Create and delete pipelines - Use the Create Pipeline and Delete Pipeline to perform these operations.

  • Manage workspaces - With Assign Workspace and Unassign Workspace you can assign and unassign workspaces to specific pipeline stages.

  • Manage pipeline users - Delete Pipeline User lets you remove a user from a pipeline. Update Pipeline User allows you to add a user to your pipeline.

Which deployments are supported by the APIs?

Here's a list of the different deployment types the APIs support:

  • Deploy all - A single API call that deploys all the content in the workspace to the next stage in the pipeline. For this operation, use the Deploy all API.

  • Selective deploy - Deploy only specific Power BI items (such as reports or dashboards) in the pipeline. For this operation, use the Selective deploy API.

  • Backward deploy - Use to deploy new Power BI items to the previous stage. Backward deployment only works if the Power BI items that are deployed, don't already exist in the target stage. For this operation use either the Deploy all or the Selective deploy APIs, with isBackwardDeployment set to True.

  • Update App - As part of the deployment API call, you can update the content of the app that's related to that stage. Updated Power BI items will automatically be available to your end users, once a deployment has been completed. For this operation use either the Deploy all or the Selective deploy APIs, with PipelineUpdateAppSettings.

Before you begin

Before you start using the deployment pipelines APIs, make sure you have the following:

Integrate your pipeline with Azure DevOps

To automate Power BI deployment processes from within your release pipeline in Azure DevOps, you can use one of these methods:

  • PowerShell - The script signs into Power BI using a service principal or a user.

  • Power BI automation tools - This extension works with a service principal or a user.

You can also use other Power BI REST API calls, to complete related operations such as importing a PBIX into the pipeline, updating data sources and parameters.

Use the Power BI automation tools extension

Power BI automation tools is an open source Azure DevOps extension that provides a range of deployment pipelines operations that can be performed in Azure DevOps. It eliminates the need for using APIs or scripts to manage pipelines. Each operation can be used individually to perform a simple task such as creating a pipeline, or used together in an Azure DevOps pipeline to create a more complex scenario such as creating a pipeline, assigning a workspace to the pipeline, adding users and deploying.

After adding the Power BI automation tools extension to DevOps, a service connection needs to be created. The following connections are available:

  • Service principal (recommended) - This connection authenticates using a service principal and requires the Azure AD app’s secret and application ID. When using this option, verify that the Power BI service admin settings for the service principal are enabled.

  • Username and password – Configured as a generic service connection with a username and a password. This connection method doesn’t support multi-factor authentication. Microsoft recommends using the service principal connection method as it doesn’t require storing user credentials on Azure DevOps.

Note

The Power BI automation tools extension uses an Azure DevOps service connection to store credentials. For more details, see How we store your credentials for Azure DevOps Services.

Once you enable a service connection for your Azure DevOps Power BI automation tools, you can create pipeline tasks. The extension includes the following deployment pipelines tasks:

  • Create a new pipeline

  • Assign a workspace to a pipeline stage

  • Add a user to a deployment pipeline

  • Add a user to a workspace

  • Deploy content to a deployment pipeline

  • Remove a workspace from a deployment pipeline

  • Delete a pipeline

Access the PowerShell samples

You can use the PowerShell scripts below to understand how to perform several automation processes. To view or copy the text in a PowerShell sample, use the links in this section.

You can also download the entire PowerBI-Developer-Samples GitHub folder.

PowerShell example

This section describes an example PowerShell script that deploys a dataset, report and dashboard, from the development stage to the test stage. The script then checks whether the deployment was successful.

To run a PowerShell script that performs a deployment, you'll need the components listed below. You can add any of these parts into tasks in your Azure pipeline stages.

  1. Sign in - Before you can deploy your content, you need to sign in to Power BI using a service principal or a user. Use the Connect-PowerBIServiceAccount command to sign in.

  2. Build your request body - In this part of the script you specify which Power BI items (such as reports and dashboards) you're deploying.

    $body = @{ 
        sourceStageOrder = 0 # The order of the source stage. Development (0), Test (1).   
        datasets = @(
            @{sourceId = "Insert your dataset ID here" }
        )      
        reports = @(
            @{sourceId = "Insert your report ID here" }
        )            
        dashboards = @(
            @{sourceId = "Insert your dashboard ID here" }
        )
    
        options = @{
            # Allows creating new item if needed on the Test stage workspace
            allowCreateArtifact = $TRUE
    
            # Allows overwriting existing item if needed on the Test stage workspace
            allowOverwriteArtifact = $TRUE
        }
    } | ConvertTo-Json
    
  3. Deploy - Here you perform the deployment.

    $url = "pipelines/{0}/Deploy" -f "Insert you pipeline ID here"
    $deployResult = Invoke-PowerBIRestMethod -Url $url  -Method Post -Body $body | ConvertFrom-Json
    
  4. (Optional) Deployment completion notification - As the deployment API is asynchronous, you can program the script to notify you when the deployment is complete.

    $url =  "pipelines/{0}/Operations/{1}" -f "Insert you pipeline ID here",$deployResult.id
    $operation = Invoke-PowerBIRestMethod -Url $url -Method Get | ConvertFrom-Json    
    while($operation.Status -eq "NotStarted" -or $operation.Status -eq "Executing")
    {
        # Sleep for 5 seconds
        Start-Sleep -s 5
        $operation = Invoke-PowerBIRestMethod -Url $url -Method Get | ConvertFrom-Json
    }
    

Considerations and limitations

  • Deployment using APIs is subject to the same limitations as the Power BI deployment pipelines user interface.

  • A service principal cannot configure OAuth credentials. After deploying new items, the signed in service principal becomes the owner of any deployed paginated reports and datasets. In such cases, a refresh cannot be completed.

  • Deploying dataflows using a service principal isn't supported.

  • The maximum number of Power BI items that can be deployed in a single deployment is 300.

Next steps