New functions to facilitate Deployment pipelines in Fabric #144

New functions to facilitate Deployment pipelines in Fabric

Author: NowinskiK

.gitignore

@@ -2,6 +2,7 @@
 *.local.*
 !**/README.md
 .kitchen/
+*.code-workspace
 
 ~*.*
 *.nupkg

CHANGELOG.md

@@ -6,29 +6,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- added unit tests for `Get-FabricWorkspaceUser` function to ensure it works correctly with multiple workspaces both in the pipeline and passed to a parameter.
+
+- Added unit tests for `Get-FabricWorkspaceUser` function to ensure it works correctly with multiple workspaces both in the pipeline and passed to a parameter.
 - Added unit tests for Aliases for `Get-FabricWorkspaceUser` function to ensure backward compatibility.
-- Added credits for authors to all functions and Unit tests to verify the existence of such tags #89
+- Added credits for authors to all functions and Unit tests to verify the existence of such tags (#89)
 - Added `NoWait` switch parameter to `New-FabricSQLDatabase` (#123)
+- Added functions related to Deployment Pipelines (#121):  
+  - `Add-FabricWorkspaceToStage`,  
+  - `Get-FabricDeploymentPipeline`,  
+  - `Get-FabricDeploymentPipelineOperation`,  
+  - `Get-FabricDeploymentPipelineRoleAssignments`,  
+  - `Get-FabricDeploymentPipelineStage`,  
+  - `Get-FabricDeploymentPipelineStageItem`,  
+  - `New-FabricDeploymentPipeline`,  
+  - `Remove-FabricDeploymentPipeline`,  
+  - `Remove-FabricWorkspaceFromStage`,  
+  - `Start-FabricDeploymentPipelineStage`
+- Added private function `Get-FabricContinuationToken` to facilitate pagination
 
 ### Changed
+
 - Updated `Get-FabricWorkspaceUser` to support pipeline input for `WorkspaceId` and `WorkspaceName` parameters.
 - Renamed `Get-FabricWorkspaceUsers` to match the singular form
-- Get-FabricSqlDatabase accepts Workspace as a pipeline, handles errors correctly and can filter by name (#117).
+- `Get-FabricSqlDatabase` accepts Workspace as a pipeline, handles errors correctly and can filter by name (#117).
 - Applied splatting for several parameters in `Invoke-FabricRestMethod` and output results in debug mode
 - `Remove-FabricSQLDatabase` uses unified function to handle API results
 
 Updated the `WorkspaceId`, `CapacitiesIds`,`CapacityId`,`CopyJobId`,`datamartId`,`DataPipelineId`,`DataWarehouseGUID`,`DomainId`,`EnvironmentId`,`EventhouseId`,`EventstreamId`,`ExternalDataShareId`,`ItemId`,`KQLDashboardId`,`KQLDatabaseId`,`KQLQuerysetId`,`LakehouseId`,`MirroredDatabaseId`,`MirroredWarehouseId`,`MLExperimentId`,`MLModelId`,`NotebookId`,`operationId`,`PaginatedReportId`,`ParentDomainId`,`parentEventhouseId`,`PrincipalId`,`ReflexId`,`ReportId`,`SemanticModelId`,`SparkCustomPoolId`,`SparkJobDefinitionId`,`SQLDatabaseId`,`SQLEndpointId`,`subscriptionID`,`UserId`,`WarehouseId`,`WorkspaceGUID`,`WorkspaceId`,`WorkspaceIds`,and `WorkspaceRoleAssignmentId` parameters to the datatype GUID [#125](https://github.com/dataplat/FabricTools/issues/125)
 
-
-
 ### Fixed
+
 - Enhanced logic in unified function `Test-FabricApiResponse` to handle API results and moved it to private functions
 - Fixed bug in `Get-FabricLongRunningOperation` - Uri was incorectly created (#131)
 - Fixed bug in `Get-FabricLongRunningOperationResult` - uses correct statusCode (#131)
 
 ### Deprecated
+
 ### Removed
+
 - Removed Revision History from `Get-FabricSQLDatabase`, `Get-FabricSQLDatabase`
 
 ### Security

FabricTools.code-workspace

@@ -0,0 +1,27 @@
+$PSVersionTable
+
+Import-module PSScriptAnalyzer
+
+Find-Module Microsoft.PowerShell.PSResourceGet
+.\build.ps1 -ResolveDependency -Tasks noop -UsePSResourceGet
+
+
+######### BUILD #########
+
+./build.ps1 -ResolveDependency -Tasks noop
+
+Remove-Module -Name FabricTools -ErrorAction SilentlyContinue
+./build.ps1 -Tasks build
+ipmo .\output\module\FabricTools\0.0.1\FabricTools.psd1
+Get-Module Fab*
+
+Invoke-ScriptAnalyzer -Path .\source\Public\**
+
+
+$tests = Invoke-Pester .\tests\ -PassThru
+$tests.Tests | where Result -eq 'Failed' | Measure-Object | Select-Object -ExpandProperty Count
+$tests.Tests | where Result -eq 'Failed' | ft -Property ExpandedName, ErrorRecord
+$tests.Tests | where Result -eq 'Failed' | ft -Property Name, Result, ErrorRecord -AutoSize
+
+$e = $tests.Tests | where Result -eq 'Failed' | Select-Object -First 1
+$e.ErrorRecord

helper/build-and-test.ps1

@@ -0,0 +1,9 @@
+Remove-Module -Name FabricTools -ErrorAction SilentlyContinue
+./build.ps1 -Tasks build
+ipmo .\output\module\FabricTools\0.0.1\FabricTools.psd1
+Get-Module FabricTools
+
+Write-Host "Connecting to Fabric Account..." -ForegroundColor Cyan
+Connect-FabricAccount
+
+Write-Host "Build completed successfully!" -ForegroundColor Green

helper/build.ps1

@@ -0,0 +1,43 @@
+<#
+.SYNOPSIS
+Internal function to handle continuation token logic for Fabric API calls.
+
+.DESCRIPTION
+The `Get-FabricContinuationToken` function processes the API response to extract and handle continuation tokens.
+It returns the continuation token variable and provides debug logging.
+
+.PARAMETER Response
+The API response object that may contain a continuation token.
+
+.EXAMPLE
+Get-FabricContinuationToken -Response $response
+
+Processes the response and returns the continuation token if present.
+
+.NOTES
+This is an internal function used by other functions in the module.
+
+Author: Kamil Nowinski
+#>
+
+function Get-FabricContinuationToken {
+    [CmdletBinding()]
+    param (
+        [Parameter(Mandatory = $true)]
+        [object]$Response
+    )
+
+    $continuationToken = $null
+    if ($null -ne $Response) {
+        # Update the continuation token if present
+        if ($Response.PSObject.Properties.Match("continuationToken")) {
+            $continuationToken = $Response.continuationToken
+            Write-Message -Message "New continuation token: $continuationToken" -Level Debug
+        } else {
+            Write-Message -Message "New continuation token to null" -Level Debug
+        }
+    } else {
+        Write-Message -Message "No data received from the API." -Level Warning
+    }
+    $continuationToken
+}

source/Private/Get-FabricContinuationToken.ps1

@@ -53,6 +53,8 @@ function Test-FabricApiResponse {
         [switch] $NoWait = $false
     )
 
+    Write-Message -Message "[Test-FabricApiResponse]::Begin" -Level Debug
+
     $responseHeader = $script:responseHeader
     $statusCode = $script:statusCode
     $result = $null
@@ -114,15 +116,14 @@ function Test-FabricApiResponse {
     }
 
     switch ($verb) {
-        'New'    { $msg = "$TypeName '$ObjectIdOrName' created successfully!" }
-        'Update' { $msg = "$TypeName '$ObjectIdOrName' updated successfully!" }
-        'Remove' { $msg = "$TypeName '$ObjectIdOrName' deleted successfully!" }
-        'Get'    { $msg = "" }
-        default  { $msg = "Received $statusCode status code for $verb operation on $TypeName '$ObjectIdOrName'." }
-    }
-    if ($msg) {
-        Write-Message -Message $msg -Level Info
+        'New'    { $msg = "$TypeName '$ObjectIdOrName' created successfully."; $level = 'Info' }
+        'Update' { $msg = "$TypeName '$ObjectIdOrName' updated successfully."; $level = 'Info' }
+        'Remove' { $msg = "$TypeName '$ObjectIdOrName' deleted successfully."; $level = 'Info' }
+        'Get'    { $msg = "Successfully retrieved $TypeName details."; $level = 'Debug' }
+        default  { $msg = "Received $statusCode status code for $verb operation on $TypeName '$ObjectIdOrName'."; $level = 'Info' }
     }
+    Write-Message -Message $msg -Level $level
+    Write-Message -Message "[Test-FabricApiResponse]::End" -Level Debug
 
     $result
 

source/Private/Test-FabricApiResponse.ps1

@@ -0,0 +1,78 @@
+<#
+.SYNOPSIS
+Assigns a workspace to a deployment pipeline stage.
+
+.DESCRIPTION
+The `Add-FabricWorkspaceToStage` function assigns the specified workspace to the specified deployment pipeline stage.
+This operation will fail if there's an active deployment operation.
+
+.PARAMETER DeploymentPipelineId
+Required. The ID of the deployment pipeline.
+
+.PARAMETER StageId
+Required. The ID of the deployment pipeline stage.
+
+.PARAMETER WorkspaceId
+Required. The ID of the workspace to assign to the stage.
+
+.EXAMPLE
+Add-FabricWorkspaceToStage -DeploymentPipelineId "GUID-GUID-GUID-GUID" -StageId "GUID-GUID-GUID-GUID" -WorkspaceId "GUID-GUID-GUID-GUID"
+
+Assigns the specified workspace to the deployment pipeline stage.
+
+.NOTES
+- Calls `Confirm-TokenState` to ensure token validity before making the API request.
+- Requires Pipeline.ReadWrite.All and Workspace.ReadWrite.All delegated scopes.
+- Requires admin deployment pipelines role and admin workspace role.
+- This operation will fail if:
+  * There's an active deployment operation
+  * The specified stage is already assigned to another workspace
+  * The specified workspace is already assigned to another stage
+  * The caller is not a workspace admin
+- This API is in preview.
+
+Author: Kamil Nowinski
+#>
+
+function Add-FabricWorkspaceToStage {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [Guid]$DeploymentPipelineId,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [Guid]$StageId,
+
+        [Parameter(Mandatory = $true)]
+        [ValidateNotNullOrEmpty()]
+        [Guid]$WorkspaceId
+    )
+
+    try {
+        # Step 1: Ensure token validity
+        Confirm-TokenState
+
+        # Step 2: Construct the API URL
+        $apiEndpointUrl = ("deploymentPipelines/{0}/stages/{1}/assignWorkspace" -f $DeploymentPipelineId, $StageId)
+        Write-Message -Message "API Endpoint: $apiEndpointUrl" -Level Debug
+
+        # Step 3: Construct the request body
+        $requestBody = @{
+            workspaceId = $WorkspaceId
+        }
+
+        # Step 4: Make the API request and validate response
+        $response = Invoke-FabricRestMethod -Uri $apiEndpointUrl -Method Post -Body $requestBody
+        Test-FabricApiResponse -Response $response
+
+        # Step 5: Return results
+        Write-Message -Message "Successfully assigned workspace to deployment pipeline stage." -Level Info
+        $response
+    } catch {
+        # Step 6: Error handling
+        $errorDetails = $_.Exception.Message
+        Write-Message -Message "Failed to assign workspace to deployment pipeline stage. Error: $errorDetails" -Level Error
+    }
+}

source/Public/Deployment Pipeline/Add-FabricWorkspaceToStage.ps1

@@ -0,0 +1,137 @@
+<#
+.SYNOPSIS
+Retrieves deployment pipeline(s) from Microsoft Fabric.
+
+.DESCRIPTION
+The `Get-FabricDeploymentPipeline` function fetches deployment pipeline(s) from the Fabric API.
+It can either retrieve all pipelines or a specific pipeline by ID.
+It automatically handles pagination when retrieving all pipelines.
+
+.PARAMETER DeploymentPipelineId
+Optional. The ID of a specific deployment pipeline to retrieve. If not provided, all pipelines will be retrieved.
+
+.PARAMETER DeploymentPipelineName
+Optional. The display name of a specific deployment pipeline to retrieve. If provided, it will filter the results to match this name.
+
+.EXAMPLE
+Get-FabricDeploymentPipeline
+
+Retrieves all deployment pipelines that the user can access.
+
+.EXAMPLE
+Get-FabricDeploymentPipeline -DeploymentPipelineId "GUID-GUID-GUID-GUID"
+
+Retrieves a specific deployment pipeline with detailed information including its stages.
+
+.NOTES
+- Calls `Confirm-TokenState` to ensure token validity before making the API request.
+- Returns a collection of deployment pipelines with their IDs, display names, and descriptions.
+- When retrieving a specific pipeline, returns extended information including stages.
+- Requires Pipeline.Read.All or Pipeline.ReadWrite.All delegated scopes.
+
+Author: Kamil Nowinski
+#>
+
+function Get-FabricDeploymentPipeline {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory = $false)]
+        [ValidateNotNullOrEmpty()]
+        [Guid]$DeploymentPipelineId,
+
+        [Parameter(Mandatory = $false)]
+        [Alias("Name", "DisplayName")]
+        [string]$DeploymentPipelineName
+    )
+
+    try {
+        # Step 1: Ensure token validity
+        Confirm-TokenState
+
+        if ($PSBoundParameters.ContainsKey("DeploymentPipelineName") -and $PSBoundParameters.ContainsKey("DeploymentPipelineId"))
+        {
+            Write-Warning "The parameters DeploymentPipelineName and DeploymentPipelineId cannot be used together"
+            return
+        }
+
+        # If DeploymentPipelineId is provided, get specific pipeline
+        if ($DeploymentPipelineId) {
+            Write-Message -Message "Retrieving specific deployment pipeline with ID: $DeploymentPipelineId" -Level Debug
+            $apiEndpointUrl = "deploymentPipelines/$DeploymentPipelineId"
+
+            $response = Invoke-FabricRestMethod -Uri $apiEndpointUrl -Method Get
+
+            # Validate response
+            Test-FabricApiResponse -response $response -ObjectIdOrName $DeploymentPipelineId -typeName "deployment pipeline"
+
+            if ($response) {
+                Write-Message -Message "Successfully retrieved deployment pipeline." -Level Debug
+                return $response
+            } else {
+                Write-Message -Message "No deployment pipeline found with the specified ID." -Level Warning
+                return $null
+            }
+        }
+
+        # Step 2: Initialize variables for listing all pipelines
+        $continuationToken = $null
+        $pipelines = @()
+
+        if (-not ([AppDomain]::CurrentDomain.GetAssemblies() | Where-Object { $_.GetName().Name -eq "System.Web" })) {
+            Add-Type -AssemblyName System.Web
+        }
+
+        # Step 3: Loop to retrieve all pipelines with continuation token
+        Write-Message -Message "Loop started to get continuation token" -Level Debug
+        $baseApiEndpointUrl = "deploymentPipelines"
+
+        do {
+            # Step 4: Construct the API URL
+            $apiEndpointUrl = $baseApiEndpointUrl
+
+            if ($null -ne $continuationToken) {
+                # URL-encode the continuation token
+                $encodedToken = [System.Web.HttpUtility]::UrlEncode($continuationToken)
+                $apiEndpointUrl = "{0}?continuationToken={1}" -f $apiEndpointUrl, $encodedToken
+            }
+            Write-Message -Message "API Endpoint: $apiEndpointUrl" -Level Debug
+
+            # Step 5: Make the API request
+            $response = Invoke-FabricRestMethod -Uri $apiEndpointUrl -Method Get
+
+            # Validate response
+            Test-FabricApiResponse -response $response -typeName "deployment pipeline"
+
+            # Step 6: Process response and update continuation token
+            if ($null -ne $response) {
+                $pipelines += $response.value
+            }
+            $continuationToken = Get-FabricContinuationToken -Response $response
+
+        } while ($null -ne $continuationToken)
+
+        Write-Message -Message "Loop finished and all data added to the list" -Level Debug
+
+        if ($DeploymentPipelineName)
+        {
+            # Filter the list by name
+            Write-Message -Message "Filtering deployment pipelines by name: $DeploymentPipelineName" -Level Debug
+            $pipelines = $pipelines | Where-Object { $_.displayName -eq $DeploymentPipelineName }
+        }
+
+        # Step 7: Handle results
+        $pipelines
+        # if ($pipelines) {
+        #     Write-Message -Message "Successfully retrieved deployment pipelines." -Level Debug
+        #     return $pipelines
+        # } else {
+        #     Write-Message -Message "No deployment pipelines found." -Level Warning
+        #     return $null
+        # }
+
+    } catch {
+        # Step 8: Error handling
+        $errorDetails = $_.Exception.Message
+        Write-Message -Message "Failed to retrieve deployment pipelines. Error: $errorDetails" -Level Error
+    }
+}