แก้ไข

แชร์ผ่าน

Microsoft Power BI Cmdlets for Windows PowerShell and PowerShell Core

  • บทความ

Welcome to the PowerShell reference for Microsoft Power BI. Here you will find resources for PowerShell modules targeting Power BI.

PowerShell modules

Below is a table of the Power BI PowerShell modules covered in this reference.

Description Module Name PowerShell Gallery link
Rollup module for Power BI Cmdlets MicrosoftPowerBIMgmt MicrosoftPowerBIMgmt
Admin module for Power BI Cmdlets MicrosoftPowerBIMgmt.Admin MicrosoftPowerBIMgmt.Admin
Capacities module for Power BI Cmdlets MicrosoftPowerBIMgmt.Capacities MicrosoftPowerBIMgmt.Capacities
Data module for Power BI Cmdlets MicrosoftPowerBIMgmt.Data MicrosoftPowerBIMgmt.Data
Profile module for Power BI Cmdlets MicrosoftPowerBIMgmt.Profile MicrosoftPowerBIMgmt.Profile
Reports module for Power BI MicrosoftPowerBIMgmt.Reports MicrosoftPowerBIMgmt.Reports
Workspaces module for Power BI MicrosoftPowerBIMgmt.Workspaces MicrosoftPowerBIMgmt.Workspaces

Supported environments and PowerShell versions

  • Windows PowerShell v3.0 and up with .NET 4.7.1 or above.
  • PowerShell Core (v6) and up on any OS platform supported by PowerShell Core.

Installation

The cmdlets are available on PowerShell Gallery and can be installed in an elevated PowerShell session:

Install-Module -Name MicrosoftPowerBIMgmt

Optionally you could install individual modules (based on your needs) instead of the rollup module, for example if you only wanted the Workspaces module:

Install-Module -Name MicrosoftPowerBIMgmt.Workspaces

If you have an earlier version, you can update to the latest version by running:

Update-Module -Name MicrosoftPowerBIMgmt

Uninstall

If you want to uninstall all the Power BI PowerShell cmdlets, run the following in an elevated PowerShell session:

Get-Module MicrosoftPowerBIMgmt* -ListAvailable | Uninstall-Module -Force

Usage

Two scopes are supported by cmdlets that interact with Power BI entities:

  • Individual is used to access entities that belong to the current user.
  • Organization is used to access entities across the entire company. Only Power BI tenant admins are allowed to use.

If the -Scope parameter doesn't exist on the cmdlet, the entity doesn't support an Administrative API.

Log in to Power BI

Connect-PowerBIServiceAccount   # or use aliases: Login-PowerBIServiceAccount, Login-PowerBI

Get workspaces

Get workspaces for the user. By default (i.e. without -First parameter) it shows the first 100 workspaces assigned to the user:

Get-PowerBIWorkspace

Use the -All parameter to show all workspaces assigned to the user:

Get-PowerBIWorkspace -All

If you are a tenant administrator, you can view all workspaces in your tenant by adding -Scope Organization:

Get-PowerBIWorkspace -Scope Organization -All

Update a workspace

Update the name or description of a user's workspace:

Set-PowerBIWorkspace -Scope Organization -Id "3244f1c1-01cf-457f-9383-6035e4950fdc" -Name "Test Name" -Description "Test Description"

Add a new user to a workspace

Add a user to a given workspace:

Add-PowerBIWorkspaceUser -Scope Organization -Id 3244f1c1-01cf-457f-9383-6035e4950fdc -UserEmailAddress john@contoso.com -AccessRight Admin

Remove a user from a given workspace

Remove user's permissions from a given workspace:

Remove-PowerBIWorkspaceUser -Scope Organization -Id 3244f1c1-01cf-457f-9383-6035e4950fdc -UserEmailAddress john@contoso.com

Get workspace migration status

Get Power BI workspace migration status:

Get-PowerBIWorkspaceMigrationStatus -Id 038f9a64-1fcd-42f2-957a-13a63b3d3235

Restore a workspace

To view deleted workspaces as a tenant administrator:

Get-PowerBIWorkspace -Scope Organization -Deleted -All

Restore a deleted workspace:

Restore-PowerBIWorkspace -Id "3244f1c1-01cf-457f-9383-6035e4950fdc" -RestoredName "TestWorkspace" -AdminEmailAddress "john@contoso.com"

Recover an orphaned workspace

A workspace becomes orphaned when it has no assigned administrators. If you are a tenant administrator, run the following to view all orphaned workspaces:

Get-PowerBIWorkspace -Scope Organization -Orphaned -All

To correct this issue, use:

Add-PowerBIWorkspaceUser -Scope Organization -Id f2a0fae5-1c37-4ee6-97da-c9d31851fe17 -UserPrincipalName 'john@contoso.com' -AccessRight Admin

Get reports

Get all reports for the user:

Get-PowerBIReport

If you are a tenant administrator, you can view all reports in your tenant by using assigning -Scope Organization:

Get-PowerBIReport -Scope Organization

Get dashboards

Get dashboards for the user:

Get-PowerBIDashboard

If you are a tenant administrator, you can view all dashboards in your tenant by adding -Scope Organization:

Get-PowerBIDashboard -Scope Organization

Get tiles

Get tiles within a dashboard:

Get-PowerBITile -DashboardId 9a58d5e5-61bc-447c-86c4-e221128b1c99

Get imports

Get Power BI imports:

Get-PowerBIImport

Create a report

Create a report in Power BI by uploading a *.pbix file:

New-PowerBIReport -Path .\newReport.pbix -Name 'New Report'

By default, the report is placed in the user's My Workspace. To place in a different workspace, use the -WorkspaceId or -Workspace parameters:

New-PowerBIReport -Path .\newReport.pbix -Name 'New Report' -WorkspaceId f95755a1-950c-46bd-a912-5aab4012a06d

Export a report

Export a Power BI report to *.pbix file:

Export-PowerBIReport -Id b48c088c-6f4e-4b7a-b015-d844ab534b2a -OutFile .\exportedReport.pbix

If the workspace exists outside the My Workspace, export with the WorkspaceId or -Workspace parameter:

Export-PowerBIReport -Id b48c088c-6f4e-4b7a-b015-d844ab534b2a -OutFile .\exportedReport.pbix -WorkspaceId 3bdd9735-0ab5-4f21-bd5d-87e7f1d7fb84

Get datasets

Get Power BI datasets:

Get-PowerBIDataset

Update dataset storage mode

Set Power BI dataset to use Premium Files for storage mode:

Set-PowerBIDataset -Id 038f9a64-1fcd-42f2-957a-13a63b3d3235 -TargetStorageMode PremiumFiles

Get datasources

Get Power BI datasources for a dataset:

Get-PowerBIDatasource -DatasetId 65d7d7e5-8af0-4e94-b20b-50a882ae15e1

Get tables

Get Power BI tables contained within a dataset:

Get-PowerBITable -DatasetId 65d7d7e5-8af0-4e94-b20b-50a882ae15e1

Call the Power BI Rest API

For Power BI API that lacks corresponding cmdlets, you can reuse the authenticated session from Connect-PowerBIServiceAccount to make custom REST requests:

Invoke-PowerBIRestMethod -Url 'reports/4eb4c303-d5ac-4a2d-bf1e-39b35075d983/Clone' -Method Post -Body ([pscustomobject]@{name='Cloned report'; targetModelId='adf823b5-a0de-4b9f-bcce-b17d774d2961'; targetWorkspaceId='45ee15a7-0e8e-45b0-8111-ea304ada8d7d'} | ConvertTo-Json -Depth 2 -Compress)

If you want to use the authenticated session outside of PowerShell, get the access token by using:

Get-PowerBIAccessToken -AsString

Troubleshooting errors

To get more information about an error returned back from the cmdlets, use:

Resolve-PowerBIError -Last

This information can be useful for opening support tickets for Power BI.

Issues and feedback

If you find any bugs or would like to see certain functionality implemented for the PowerShell Cmdlets for Power BI, please file an issue.

If your issue is broader than just the PowerShell cmdlets, please submit your feedback to the Power BI Community or the official Power BI Support site.