Edit

Share via

Automate your deployment pipeline for Power BI items by using APIs

  • Article

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

Note

The deployment pipelines APIs listed here only apply to Power BI items. For Fabric APIs, see the Fabric API documentation.

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

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

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

  • Assign and unassign users to and from a pipeline.

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

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

  • Deploy multiple pipelines at the same time.

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

Prerequisites

Before you use the deployment pipelines APIs, make sure of the following:

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 enables 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 enable developers to use any type of deployment available in the Fabric service.

  • Create and delete pipelines - Use 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 deployment types do the APIs support?

The APIs support the following deployment types:

  • 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 - Deploys only specific items, such as reports or dashboards, in the pipeline. For this operation, use the Selective deploy API.

  • Backward deploy - Deploys new items to the previous stage. Backward deployment only works if the 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 related to that stage. Updated items are automatically available to your end users, after a deployment is complete. For this operation, use either the Deploy all or the Selective deploy APIs, with PipelineUpdateAppSettings.

Integrate your pipeline with Azure DevOps

To automate the deployment processes from within your release pipeline in Azure DevOps, use one of these methods:

  • PowerShell - The script signs into Fabric 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

The Power BI automation tools extension is an open source Azure DevOps extension that provides a range of deployment pipelines operations that can be performed in Azure DevOps. The extension eliminates the need for APIs or scripts to manage pipelines. Each operation can be used individually to perform a task, such as creating a pipeline. Operations can be 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 you add the Power BI automation tools extension to DevOps, you need to create a service connection. The following connections are available:

  • Service principal (recommended) - This connection authenticates by using a service principal and requires the Microsoft Entra app’s secret and application ID. When you use this option, verify that the 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 multifactor authentication. We recommend that you use the service principal connection method because 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 information, see How we store your credentials for Azure DevOps Services.

After 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 following PowerShell scripts 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 semantic model, 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 need the following components. 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 Fabric 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 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 - Because 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 by using APIs is subject to the same limitations as the deployment pipelines user interface.

  • A service principal can't configure OAuth credentials. After you deploy new items, the signed in service principal becomes the owner of any deployed paginated reports and semantic models. In such cases, a refresh can't be completed.

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

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

  • The deployment pipelines APIs currently only support Power BI items.

  • Creating a customized pipeline of 2-10 stages is currently supported only through the UI.

Related content