Pipelines - Selective Deploy

Deploys the specified items from the source stage of the specified deployment pipeline.

Permissions

The user must at least be a contributor on both source and target deployment workspaces. For more information, see Permissions.

Required Scope

Pipeline.Deploy

Limitations

Maximum 300 deployed items per request.

POST https://api.powerbi.com/v1.0/myorg/pipelines/{pipelineId}/deploy

URI Parameters

Name In Required Type Description
pipelineId
path True

string

uuid

The deployment pipeline ID

Request Body

Name Required Type Description
sourceStageOrder True

integer

The numeric identifier of the pipeline deployment stage that the content should be deployed from. Development (0), Test (1), Production (2).

dashboards

DeployArtifactRequest[]

A list of dashboards to be deployed

dataflows

DeployArtifactRequest[]

A list of dataflows to be deployed

datamarts

DeployArtifactRequest[]

A list of datamarts to be deployed

datasets

DeployArtifactRequest[]

A list of datasets to be deployed

isBackwardDeployment

boolean

Whether the deployment will be from a later stage in the deployment pipeline, to an earlier one. The default value is false.

newWorkspace

PipelineNewWorkspaceRequest

The configuration details for creating a new workspace. Required when deploying to a stage that has no assigned workspaces. The deployment will fail if the new workspace configuration details aren't provided when required.

note

string

A note describing the deployment.

options

DeploymentOptions

Options that control the behavior of the entire deployment

reports

DeployArtifactRequest[]

A list of reports to be deployed

updateAppSettings

PipelineUpdateAppSettings

Update org app in the target workspace settings

Responses

Name Type Description
202 Accepted

PipelineOperation

Accepted

Examples

Example of deploying specific Power BI items (such as reports or dashboards) from the 'Development' stage
Example of deploying specific Power BI items with custom options

Example of deploying specific Power BI items (such as reports or dashboards) from the 'Development' stage

Sample request

POST https://api.powerbi.com/v1.0/myorg/pipelines/a5ded933-57b7-41f4-b072-ed4c1f9d5824/deploy
{
  "sourceStageOrder": 0,
  "dataflows": [
    {
      "sourceId": "29efcfb0-0063-44af-a4ed-6c0bee3417d3"
    }
  ],
  "datamarts": [
    {
      "sourceId": "6bfe235c-6d7b-41b7-98a6-2b8276b3e82b"
    }
  ],
  "datasets": [
    {
      "sourceId": "1a201f2a-d1d8-45c0-8c61-1676338517de"
    }
  ],
  "reports": [
    {
      "sourceId": "2d225191-65f8-4ec3-b77d-06100602b1f7"
    }
  ],
  "dashboards": [
    {
      "sourceId": "9046e4cc-8aea-4a7a-a3b5-1a78b1447d82"
    },
    {
      "sourceId": "7f08923c-8f57-49d6-a010-8335bb9cbd1b"
    }
  ],
  "options": {
    "allowOverwriteArtifact": true,
    "allowCreateArtifact": true
  },
  "note": "Deploying business ready items"
}

Sample response

{
  "value": [
    {
      "id": "1065e6a3-a020-4c0c-ada7-92b5fe99eec5",
      "type": "Deploy",
      "status": "NotStarted",
      "lastUpdatedTime": "2020-12-13T09:26:43.153",
      "executionStartTime": "2020-12-13T09:25:43.153Z",
      "executionEndTime": "2020-12-13T09:26:43.153Z",
      "sourceStageOrder": 0,
      "targetStageOrder": 1
    }
  ]
}

Example of deploying specific Power BI items with custom options

Sample request

POST https://api.powerbi.com/v1.0/myorg/pipelines/a5ded933-57b7-41f4-b072-ed4c1f9d5824/deploy
{
  "sourceStageOrder": 0,
  "datamarts": [
    {
      "sourceId": "6bfe235c-6d7b-41b7-98a6-2b8276b3e82b",
      "options": {
        "allowOverwriteArtifact": true,
        "allowCreateArtifact": true
      }
    }
  ],
  "reports": [
    {
      "sourceId": "2d225191-65f8-4ec3-b77d-06100602b1f7",
      "options": {
        "allowOverwriteArtifact": true
      }
    }
  ],
  "note": "Deploying business ready items"
}

Sample response

{
  "value": [
    {
      "id": "1065e6a3-a020-4c0c-ada7-92b5fe99eec5",
      "type": "Deploy",
      "status": "NotStarted",
      "lastUpdatedTime": "2020-12-13T09:26:43.153",
      "executionStartTime": "2020-12-13T09:25:43.153Z",
      "executionEndTime": "2020-12-13T09:26:43.153Z",
      "sourceStageOrder": 0,
      "targetStageOrder": 1
    }
  ]
}

Definitions

Name Description
DeployArtifactRequest

A request to deploy a Power BI item (such as a report or a dashboard)

DeploymentError

Error details for the deployment step

DeploymentExecutionPlan

A deployment execution plan

DeploymentExecutionStep

A deployment execution step

DeploymentExecutionStepPreDeploymentDiffState

Is an item new, different or identical to items in the target stage before deployment.

DeploymentOptions

Deployment configuration options. Can be specified either for the entire deployment or for a specific Power BI item (such as a report or dashboard). If both are specified, only the deployment options for the Power BI item are used.

DeploymentSourceAndTarget

Source and target items

DeploymentStepType

The type of deployment step

PipelineNewWorkspaceRequest

The configuration details for creating a new workspace. Required when deploying to a stage that has no assigned workspaces.

PipelineOperation

A Power BI deployment pipeline operation

PipelineOperationNote

A note describing the deployment.

PipelineOperationStatus

The pipeline operation status

PipelineOperationType

The operation type

PipelineOperationUser

User or service principal that performed the pipeline operation.

PipelineUpdateAppSettings

Configuration update org app after deployment

PreDeploymentDiffInformation

The amount of new, different and identical deployed items before deployment.

PrincipalType

The principal type

SelectiveDeployRequest

A request to selectively deploy items from a deployment pipeline stage

DeployArtifactRequest

A request to deploy a Power BI item (such as a report or a dashboard)

Name Type Description
options

DeploymentOptions

The deployment configuration options for a specific Power BI item (such as a report or a dashboard)

sourceId

string

The ID of the Power BI item (such as a report or a dashboard) to be deployed

DeploymentError

Error details for the deployment step

Name Type Description
errorCode

string

The error code

errorDetails

string

Additional error details

DeploymentExecutionPlan

A deployment execution plan

Name Type Description
steps

DeploymentExecutionStep[]

The collection of execution plan steps

DeploymentExecutionStep

A deployment execution step

Name Type Description
error

DeploymentError

The error details. Only applicable if the pipeline operation failed.

index

integer

The step index

preDeploymentDiffState

DeploymentExecutionStepPreDeploymentDiffState

Is an item new, different or identical to items in the target stage before deployment.

sourceAndTarget

DeploymentSourceAndTarget

The source and target items of the step

status

PipelineOperationStatus

The status of the pipeline operation

type

DeploymentStepType

The type of deployment step

DeploymentExecutionStepPreDeploymentDiffState

Is an item new, different or identical to items in the target stage before deployment.

Name Type Description
Different

string

Before deployment, the item in the source stage wasn't identical to the one in the target stage.

New

string

A new deployed item that doesn't exist in the target stage.

NoDifference

string

Before deployment, the item in the source stage was identical to the one in the target stage.

DeploymentOptions

Deployment configuration options. Can be specified either for the entire deployment or for a specific Power BI item (such as a report or dashboard). If both are specified, only the deployment options for the Power BI item are used.

Name Type Description
allowCreateArtifact

boolean

Whether creating a new Power BI item (such as a report or a dashboard) in the target stage workspace is allowed. If this option isn't set to true when it's required for deployment, the deployment will fail.

allowOverwriteArtifact

boolean

Whether overwriting a Power BI item (such as a report or a dashboard) in the target stage workspace is allowed. If this option isn't set to true when it's required for deployment, the deployment will fail.

allowOverwriteTargetArtifactLabel

boolean

Whether the label of a target Power BI item (such as a report or a dashboard) can be changed. The label gets changed when the source is protected but the target isn't. If this option isn't set to true when it's required for deployment, the deployment will fail.

allowPurgeData

boolean

Whether to delete all data from the target Power BI item (such as a report or a dashboard) when there's a schema mismatch. If this option isn't set to true when it's required for deployment, the deployment will fail.

allowSkipTilesWithMissingPrerequisites

boolean

Whether to skip tiles that don't have a model or a report in the target stage workspace. If this option isn't set to true when it's required for deployment, the deployment will fail.

allowTakeOver

boolean

Whether to allow overriding the previous paginated report owner and becoming the owner of the paginated report. Applicable when deploying a paginated report to a stage that already contains a copy of the paginated report that isn't owned by you. If this option isn't set to true when it's required for deployment, the deployment will fail.

DeploymentSourceAndTarget

Source and target items

Name Type Description
source

string

The ID of the Power BI item that's deployed from the source stage

sourceDisplayName

string

The display name of the Power BI item that's deployed from the source stage

target

string

The ID of the Power BI item that will be overwritten in the target stage. Only applies when overwriting a Power BI item.

targetDisplayName

string

The name of the Power BI item that will be overwritten in the target stage. Only applies when overwriting a Power BI item.

type

string

The type of the Power BI item that will be overwritten in the target stage. Only applies when overwriting a Power BI item.

DeploymentStepType

The type of deployment step

Name Type Description
DashboardDeployment

string

A step for deploying a single dashboard

DataflowDeployment

string

A step for deploying a single dataflow

DatamartDeployment

string

A step for deploying a single datamart

DatasetDeployment

string

A step for deploying a single dataset

ReportDeployment

string

A step for deploying a single report

PipelineNewWorkspaceRequest

The configuration details for creating a new workspace. Required when deploying to a stage that has no assigned workspaces.

Name Type Description
capacityId

string

The ID of the capacity that the new workspace will be assigned to. If unspecified and the API caller has permissions for the source stage workspace capacity, then that capacity will be used. Otherwise, Power BI will select a capacity that the API caller has permissions for.

name

string

The name of the new workspace

PipelineOperation

A Power BI deployment pipeline operation

Name Type Description
executionEndTime

string

The date and time that the operation ended

executionPlan

DeploymentExecutionPlan

The deployment execution plan. Only applicable to a single pipeline operation.

executionStartTime

string

The date and time that the operation started

id

string

The operation ID

lastUpdatedTime

string

The date and time that the operation was last updated

note

PipelineOperationNote

A note representing a description of the operation.

performedBy

PipelineOperationUser

User or service principal that performed the pipeline operation.

preDeploymentDiffInformation

PreDeploymentDiffInformation

The amount of deployed items in the source stage, that are new, identical or different to items in the target stage, before deployment.

sourceStageOrder

integer

The numeric identifier of a source pipeline deployment stage. Development (0), Test (1), Production (2).

status

PipelineOperationStatus

The pipeline operation status

targetStageOrder

integer

The numeric identifier of a target pipeline deployment stage. Development (0), Test (1), Production (2).

type

PipelineOperationType

The operation type

PipelineOperationNote

A note describing the deployment.

Name Type Description
content

string

Text describing the deployment.

isTruncated

boolean

Indicates if the note is incomplete. True, only part of the note is returned. False, the note is complete.

PipelineOperationStatus

The pipeline operation status

Name Type Description
Executing

string

Operation executing

Failed

string

Operation failed

NotStarted

string

Operation not started

Succeeded

string

Operation succeeded

PipelineOperationType

The operation type

Name Type Description
Deploy

string

Deploy content between stages

PipelineOperationUser

User or service principal that performed the pipeline operation.

Name Type Description
principalObjectID

string

The ID of the service principal that performed the deployment.

principalType

PrincipalType

The type of user who performed the deployment.

userPrincipalName

string

The UPN of the user who performed the deployment.

PipelineUpdateAppSettings

Configuration update org app after deployment

Name Type Description
updateAppInTargetWorkspace

boolean

Whether to update the app in the target workspace. Only deployed items that already exist in the app are updated. New deployed items are not added to the app.

PreDeploymentDiffInformation

The amount of new, different and identical deployed items before deployment.

Name Type Description
differentArtifactsCount

integer

The number of deployed items with differences between source and target stages, before deployment.

newArtifactsCount

integer

The number of new items deployed to the target stage.

noDifferenceArtifactsCount

integer

The number of identical deployed items in the source and target stages, before deployment.

PrincipalType

The principal type

Name Type Description
App

string

Service principal type

Group

string

Group principal type

None

string

No principal type. Use for whole organization level access.

User

string

User principal type

SelectiveDeployRequest

A request to selectively deploy items from a deployment pipeline stage

Name Type Description
dashboards

DeployArtifactRequest[]

A list of dashboards to be deployed

dataflows

DeployArtifactRequest[]

A list of dataflows to be deployed

datamarts

DeployArtifactRequest[]

A list of datamarts to be deployed

datasets

DeployArtifactRequest[]

A list of datasets to be deployed

isBackwardDeployment

boolean

Whether the deployment will be from a later stage in the deployment pipeline, to an earlier one. The default value is false.

newWorkspace

PipelineNewWorkspaceRequest

The configuration details for creating a new workspace. Required when deploying to a stage that has no assigned workspaces. The deployment will fail if the new workspace configuration details aren't provided when required.

note

string

A note describing the deployment.

options

DeploymentOptions

Options that control the behavior of the entire deployment

reports

DeployArtifactRequest[]

A list of reports to be deployed

sourceStageOrder

integer

The numeric identifier of the pipeline deployment stage that the content should be deployed from. Development (0), Test (1), Production (2).

updateAppSettings

PipelineUpdateAppSettings

Update org app in the target workspace settings