Introduzione

Completato

Lo sviluppo di una soluzione di automazione è utile quando è necessario riprodurre operazioni di gestione. L'automazione consente di velocizzare e rendere più accurata la gestione della soluzione.

Quando si sviluppano app che incorporano contenuto di Power BI, l'automazione è disponibile per diverse operazioni, tra cui la gestione del ciclo di vita, l'aggiunta di nuovi tenant (clienti) in un'app multi-tenant, nonché varie operazioni IT.

È possibile usare tre librerie di automazione:

  • Microsoft Graph

  • API Rest di Microsoft Power BI

  • API REST ARM (Azure Resource Manager) di Power BI Embedded

Microsoft Graph

Microsoft Graph fornisce un modello di programmabilità unificato. Espone le API REST e una libreria client per accedere ai dati ed eseguire operazioni su vari servizi cloud Microsoft. Per quanto riguarda l'automazione delle soluzioni Power BI, Microsoft Graph consente di configurare gli oggetti di sicurezza di Microsoft Azure Active Directory (Azure AD). L'app o gli script di PowerShell possono richiamare chiamate API Graph.

Lo script seguente illustra come installare il modulo Azure AD PowerShell per Graph in PowerShell. Per altre informazioni, vedere Installazione del modulo Azure AD.

Install-Module -Name AzureAD

I blocchi di codice seguenti fanno parte della prima parte di uno script di configurazione di PowerShell per configurare gli oggetti di sicurezza per una nuova app che incorpora contenuto di Power BI. In particolare, i blocchi di codice illustrano come completare le azioni seguenti, rispettivamente:

  1. Generare un segreto dell'app Azure AD.

  2. Creare una registrazione dell'app Azure AD.

  3. Creare l'entità servizio di registrazione dell'app Azure AD.

  4. Assegnare l'utente corrente come proprietario della registrazione dell'app Azure AD.

  5. Aggiungere l'entità servizio al gruppo di sicurezza App Power BI.

Il primo blocco di codice inizializza due variabili. La variabile $appDisplayName consente di archiviare il nome della nuova app Azure AD, la variabile $adSecurityGroupName consente di archiviare il nome di un gruppo di sicurezza esistente. Nelle impostazioni del tenant Power BI un amministratore di Power BI ha già assegnato questo gruppo di sicurezza quando ha consentito l'uso delle entità servizio.

# The new app display name
$appDisplayName = "My app"

# The name of an existing security group
$adSecurityGroupName = "Power BI Apps"

Il blocco di codice successivo si connette a un account autenticato per usare le richieste di cmdlet di Azure AD. Inizializza anche le variabili con fact utili sul tenant e sull'account utente corrente. Questi fact verranno usati nei blocchi di codice successivi.

$authResult = Connect-AzureAD

$tenantId = $authResult.TenantId.ToString()
$tenantDomain = $authResult.TenantDomain

$userAccountId = $authResult.Account.Id
$user = Get-AzureADUser -ObjectId $userAccountId

Il blocco di codice successivo genera un segreto dell'app che diventerà la password usata per una registrazione dell'app Azure AD. Il segreto dell'app è basato su un GUID ed è valido per un anno dalla data corrente.

# Generate an app secret
$newGuid = New-Guid
$appSecret = ([System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes(($newGuid))))+"="
$startDate = Get-Date
$passwordCredential = New-Object -TypeName Microsoft.Open.AzureAD.Model.PasswordCredential
$passwordCredential.StartDate = $startDate
$passwordCredential.EndDate = $startDate.AddYears(1)
$passwordCredential.KeyId = $newGuid
$passwordCredential.Value = $appSecret

Il blocco di codice successivo crea una registrazione dell'app Azure AD usando il segreto dell'app.

# Create an Azure AD app
$replyUrl = "https://localhost:5001/signin-oidc"

$aadApplication = New-AzureADApplication `
    -DisplayName $appDisplayName `
    -PublicClient $false `
    -AvailableToOtherTenants $false `
    -ReplyUrls @($replyUrl) `
    -Homepage $replyUrl `
    -PasswordCredentials $passwordCredential

Il blocco di codice successivo crea l'entità servizio della registrazione dell'app. Assegna inoltre l'utente corrente come proprietario e aggiunge l'entità servizio al gruppo di sicurezza.

# Create the app's service principal
$appId = $aadApplication.AppId
$appObjectId = $aadApplication.ObjectId
$serviceServicePrincipal = New-AzureADServicePrincipal -AppId $appId
$serviceServicePrincipalObjectId = $serviceServicePrincipal.ObjectId

# Assign the current user as the app owner
Add-AzureADApplicationOwner -ObjectId $aadApplication.ObjectId -RefObjectId $user.ObjectId

# Add the service principal to the security group
Add-AzureADGroupMember -ObjectId $($adSecurityGroup.ObjectId) `
    -RefObjectId $($serviceServicePrincipalObjectId)

Le variabili di script seguenti contengono informazioni utili per l'app. I relativi valori devono essere scritti e aggiunti al file di configurazione dell'app.

  • $tenantDomain: obbligatoria per l'autenticazione con Azure AD.

  • $tenantId: obbligatoria per l'autenticazione con Azure AD.

  • $appId: obbligatoria per la generazione di un token di accesso di Azure AD.

  • $appSecret: obbligatoria per la generazione di un token di accesso di Azure AD. I segreti non devono però essere distribuiti con l'app. È invece necessario accedervi tramite un mezzo controllato, ad esempio variabili di ambiente o Microsoft Azure Key Vault. Per altre informazioni, vedere Archiviazione sicura dei segreti delle app in fase di sviluppo in ASP.NET Core.

La variabile $serviceServicePrincipalObjectId consente di archiviare un riferimento alla nuova entità servizio. Nell'argomento successivo questa variabile verrà usata in una continuazione dello script.

API REST di Power BI

L'API REST di Power BI fornisce endpoint di servizio per l'incorporamento, l'amministrazione, la governance e le risorse utente. Per quanto riguarda l'automazione delle soluzioni Power BI, l'API REST di Power BI consente di eseguire le attività seguenti:

  • Creare aree di lavoro

  • Assegnare un'area di lavoro a una capacità

  • Configurare l'accesso all'area di lavoro

  • Creare e configurare contenuto di Power BI

Lo script seguente illustra come installare il modulo di gestione di Power BI in PowerShell. Per altre informazioni, vedere Cmdlet di Microsoft Power BI per Windows PowerShell e PowerShell Core.

Install-Module -Name MicrosoftPowerBIMgmt

I blocchi di codice seguenti fanno parte della seconda parte di uno script di configurazione di PowerShell. Si tratta di una continuazione dello script descritto nell'argomento precedente. I blocchi di codice consentono di configurare l'ambiente di Power BI. In particolare, illustrano come completare le attività seguenti:

  • Creare un'area di lavoro.

  • Aggiungere un'entità servizio come amministratore dell'area di lavoro.

  • Importare un file di Power BI Desktop per creare un set di dati e un report.

Il primo blocco di codice inizializza due variabili. La variabile $workspaceName consente di archiviare il nome della nuova area di lavoro, la variabile $pbixFilePath consente di archiviare il percorso del file in un file di Power BI Desktop.

# The new workspace name
$workspaceName = "Sales Reporting"

# The file path to a Power BI Desktop file (.pbix)
$pbixFilePath = "D:\Sales Analysis.pbix"

Il blocco di codice successivo si connette al servizio Power BI con un account autenticato. In seguito prova a recuperare un riferimento all'area di lavoro. Se il tentativo non riesce perché l'area di lavoro non esiste, ne crea una. Infine, la variabile $workspaceId consente di archiviare l'ID area di lavoro denominato GroupID.

Connect-PowerBIServiceAccount

# Create the workspace (if it doesn't already exist)
$workspace = Get-PowerBIWorkspace -Name $workspaceName

if (!$workspace) {
    $workspace = New-PowerBIWorkspace -Name $workspaceName
}

$workspaceId = $workspace.Id

Il blocco di codice successivo aggiunge l'entità servizio come amministratore dell'area di lavoro.

# Add the service principal as a workspace admin
Add-PowerBIWorkspaceUser -Scope Organization `
    -Id $workspaceId `
    -AccessRight Admin `
    -Identifier $serviceServicePrincipalObjectId `
    -PrincipalType App

Il blocco di codice successivo importa un file di Power BI Desktop nella nuova area di lavoro.

# Import the Power BI Desktop file
$import = New-PowerBIReport -Path $pbixFilePath -Workspace $workspace -ConflictAction CreateOrOverwrite

La variabile $workspaceId contiene informazioni utili per l'app. È necessario scrivere il valore della variabile e aggiungerlo al file di configurazione dell'app. È possibile usare la variabile per enumerare gli artefatti dell'area di lavoro per recuperare le proprietà necessarie per incorporarli.

API REST ARM di Power BI Embedded

L'API REST ARM di Power BI Embedded consente di creare, recuperare, aggiornare ed eliminare capacità di Power BI Embedded.

Nota

Non è possibile usare questa API per gestire le capacità di Power BI Premium. Per altre informazioni, vedere Configurare e gestire le capacità in Power BI Premium.

È possibile usare l'operazione Update per dimensionare una risorsa di capacità, ad esempio quando si verifica un aumento improvviso della domanda relativa alle risorse di calcolo. Altre operazioni sospendono o riprendono una capacità.

Nota

Per informazioni sulla gestione e sul ridimensionamento delle risorse di capacità, vedere il modulo Selezionare un prodotto di analisi incorporata di Power BI.

Per altre informazioni, vedere Informazioni di riferimento sull'API REST Azure Resource Manager di Power BI Embedded.