Pipelines - Selective Deploy

Service:

Power BI REST APIs

API Version:

v1.0

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

Permissions

The user must at least be a member 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

Request Body

{
  "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

Status code:

200

{
  "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

Request Body

{
  "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

Status code:

200

{
  "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

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