Automatiser utrullingssamlebåndet ved hjelp av API-er og Azure DevOps

Artikkel
05/25/2023

Verktøyet for utrullingssamlebånd for Microsoft Fabric gjør det mulig for forretningsanalyseteam å bygge en effektiv og gjenbrukbar utgivelsesprosess for Fabric-innholdet.

Viktig

Microsoft Fabric er for øyeblikket i PREVIEW. Denne informasjonen er knyttet til et forhåndsutgitt produkt som kan endres vesentlig før det utgis. Microsoft gir ingen garantier, uttrykt eller underforstått, med hensyn til informasjonen som er oppgitt her.

Mange organisasjoner bruker automatiseringsverktøy, inkludert Azure DevOps, for å oppnå kontinuerlig integrering og kontinuerlig levering (CI/CD) med innhold. Organisasjoner som bruker Azure DevOps, kan bruke fabric-automatiseringsverktøyutvidelsen , som støtter mange av API-operasjonene for utrullingssamlebånd.

Du kan bruke fabric REST-API-er for distribusjonssamlebånd til å integrere Fabric i organisasjonens automatiseringsprosess. Her er noen eksempler på hva som kan gjøres ved hjelp av API-ene:

Administrer datasamlebånd fra start til slutt, inkludert oppretting av et datasamlebånd, tilordning av et arbeidsområde til en hvilken som helst fase og distribusjon og sletting av samlebåndet.
Tilordne og oppheve tilordning av brukere til og fra et datasamlebånd.
Integrer Fabric i kjente DevOps-verktøy som Azure DevOps eller GitHub Actions.
Planlegg at utrullinger av datasamlebånd skal skje automatisk på et bestemt tidspunkt.
Distribuer flere datasamlebånd samtidig.
Gjennomgripende avhengig av utrullinger av datasamlebånd. Hvis du har innhold som er koblet til på tvers av datasamlebånd, kan du kontrollere at noen datasamlebånd distribueres før andre.

API-funksjoner for utrullingssamlebånd

Med Fabric REST-API-er for distribusjonssamlebånd kan du utføre følgende funksjoner:

Få samlebåndinformasjon – Hent informasjon om datasamlebåndet og innholdet. Når du henter samlebåndinformasjonen, kan du dynamisk bygge API-kall for distribusjon. Du kan også kontrollere statusen for en distribusjon eller distribusjonsloggen.
Distribuer – REST-kall gjør det mulig for utviklere å bruke alle typer distribusjoner som er tilgjengelige i Fabric-tjenesten.
Opprett og slett datasamlebånd – Bruk Opprett datasamlebånd og Slett datasamlebånd til å utføre disse operasjonene.
Administrer arbeidsområder – Med Tilordne arbeidsområde og Fjern arbeidsområde kan du tilordne og oppheve tilordningen av arbeidsområder til bestemte samlebåndfaser.
Administrer samlebåndbrukere - Ved å slette samlebåndet kan du fjerne en bruker fra et datasamlebånd. Ved å oppdatere samlebåndet kan du legge til en bruker i samlebåndet.

Hvilke distribusjoner støttes av API-ene?

Her er en liste over de ulike distribusjonstypene som API-ene støtter:

Distribuer alle – et enkelt API-kall som distribuerer alt innholdet i arbeidsområdet til neste fase i samlebåndet. Bruk Distribuer alle API-ene for denne operasjonen.
Selektiv distribuering – Distribuerer bare bestemte elementer, for eksempel rapporter eller instrumentbord, i samlebåndet. Bruk selektiv distribuerings-API for denne operasjonen.
Bakoverdistribusjon – distribuerer nye elementer til forrige fase. Utrulling bakover fungerer bare hvis elementene som er distribuert, ikke allerede finnes i målfasen. For denne operasjonen bruker du enten Distribuer alle eller Selektiv distribuer API-er, med isBackwardDeployment satt til True.
Oppdater app – Som en del av API-kallet for distribusjon kan du oppdatere innholdet i appen som er relatert til dette stadiet. Oppdaterte elementer blir automatisk tilgjengelige for sluttbrukerne etter at en distribusjon er fullført. For denne operasjonen bruker du enten Distribuer alle eller Selektiv distribuer API-er, med PipelineUpdateAppSettings.

Før du begynner

Før du bruker API-er for utrullingssamlebånd, må du kontrollere at du har følgende:

Tjenestekontohaveren, eller brukeren som skal kalle API-ene, trenger samlebånd- og arbeidsområdetillatelser og tilgang til et Azure AD program.
Hvis du skal bruke PowerShell-skript, installerer du Power BI PowerShell cmdlets Install-Module MicrosoftPowerBIMgmt.

Integrer datasamlebåndet med Azure DevOps

Hvis du vil automatisere distribusjonsprosessene fra utgivelsessamlebåndet i Azure DevOps, kan du bruke én av disse metodene:

PowerShell – Skriptet logger seg på Fabric ved hjelp av en tjenestekontohaver eller en bruker.
Verktøy for fabric-automatisering – Denne utvidelsen fungerer med en tjenestekontohaver eller en bruker.

Du kan også bruke andre Fabric REST-API-kall til å fullføre relaterte operasjoner som å importere en PBIX-fil til samlebåndet, oppdatere datakilder og parametere.

Bruk utvidelsen for Fabric-automatiseringsverktøy

Utvidelsen for Fabric-automatiseringsverktøy er en åpen kilde Azure DevOps-utvidelse som tilbyr en rekke operasjoner for utrullingssamlebånd som kan utføres i Azure DevOps. Utvidelsen eliminerer behovet for API-er eller skript for å administrere datasamlebånd. Hver operasjon kan brukes individuelt til å utføre en oppgave, for eksempel opprette et datasamlebånd. Operasjoner kan brukes sammen i et Azure DevOps-datasamlebånd for å opprette et mer komplekst scenario, for eksempel opprette et datasamlebånd, tilordne et arbeidsområde til samlebåndet, legge til brukere og distribuere.

Når du har lagt til utvidelsen for Fabric-automatiseringsverktøy i DevOps, må du opprette en tjenestetilkobling. Følgende tilkoblinger er tilgjengelige:

Tjenestekontohaver (anbefales) – denne tilkoblingen godkjennes ved hjelp av en tjenestekontohaver og krever Azure AD appens hemmelighet og program-ID. Når du bruker dette alternativet, må du kontrollere at tjenesteadministratorinnstillingene for tjenestekontohaveren er aktivert.
Brukernavn og passord – konfigurert som en generisk tjenestetilkobling med et brukernavn og et passord. Denne tilkoblingsmetoden støtter ikke godkjenning med flere faktorer. Vi anbefaler at du bruker tilkoblingsmetoden tjenestekontohaver fordi den ikke krever lagring av brukerlegitimasjon på Azure DevOps.

Obs!

Utvidelsen for Fabric-automatiseringsverktøy bruker en Azure DevOps-tjenestetilkobling til å lagre legitimasjon. Hvis du vil ha mer informasjon, kan du se Hvordan vi lagrer legitimasjonen din for Azure DevOps Services.

Når du har aktivert en tjenestetilkobling for automatiseringsverktøyene i Azure DevOps Fabric, kan du opprette datasamlebåndoppgaver. Utvidelsen inkluderer følgende datasamlebånd for distribusjon:

Opprett et nytt datasamlebånd
Tilordne et arbeidsområde til en samlebåndfase
Legge til en bruker i et datasamlebånd for distribusjon
Legge til en bruker i et arbeidsområde
Distribuer innhold til et utrullingssamlebånd
Fjerne et arbeidsområde fra et utrullingssamlebånd
Slette et datasamlebånd

Få tilgang til PowerShell-eksemplene

Du kan bruke følgende PowerShell-skript til å forstå hvordan du utfører flere automatiseringsprosesser. Hvis du vil vise eller kopiere teksten i et PowerShell-eksempel, bruker du koblingene i denne delen.

Du kan også laste ned hele PowerBI-Developer-Samples GitHub-mappen.

PowerShell-eksempel

Denne delen beskriver et eksempel på Et PowerShell-skript som distribuerer et datasett, en rapport og et instrumentbord, fra utviklingsfasen til testfasen. Skriptet kontrollerer deretter om distribusjonen var vellykket.

Hvis du vil kjøre et PowerShell-skript som utfører en distribusjon, trenger du følgende komponenter. Du kan legge til hvilken som helst av disse delene i oppgaver i azure-samlebåndfasene.

Logg på – Før du kan distribuere innholdet, må du logge på Fabric ved hjelp av en tjenestekontohaver eller en bruker. Bruk kommandoen Connect-PowerBIServiceAccount til å logge på.

Bygg forespørselsteksten – I denne delen av skriptet angir du hvilke elementer (for eksempel rapporter og instrumentbord) du distribuerer.

$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

Distribuer – Her utfører du distribusjonen.

$url = "pipelines/{0}/Deploy" -f "Insert you pipeline ID here"
$deployResult = Invoke-PowerBIRestMethod -Url $url  -Method Post -Body $body | ConvertFrom-Json

(Valgfritt) Varsel om fullføring av distribusjon – Fordi distribusjons-API-en er asynkron, kan du programmere skriptet til å varsle deg når distribusjonen er fullført.

$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
}

Viktige faktorer og begrensninger

Distribusjon ved hjelp av API-er er underlagt de samme begrensningene som brukergrensesnittet for utrullingssamlebånd.
En tjenestekontohaver kan ikke konfigurere OAuth-legitimasjon . Når du distribuerer nye elementer, blir den påloggede tjenestekontohaveren eieren av eventuelle distribuerte paginerte rapporter og datasett. I slike tilfeller kan ikke en oppdatering fullføres.
Distribusjon av dataflyter ved hjelp av en tjenestekontohaver støttes ikke.
Maksimalt antall elementer som kan distribueres i én enkelt distribusjon, er 300.