Public/Save-DattoDtcAssetScreenshot.ps1
|
function Save-DattoDtcAssetScreenshot { <# .SYNOPSIS Saves the latest Direct-to-Cloud asset screenshot. .DESCRIPTION Implements GET /v1/dtc/{clientId}/assets/{assetUuid}/screenshot/latest and writes the returned JPEG bytes to disk. Existing files are never overwritten unless -Force is specified. .PARAMETER ClientId The Direct-to-Cloud client ID. .PARAMETER AssetUuid The asset UUID. .PARAMETER Path A destination file or directory. A .jpg extension is appended when no extension is supplied. .PARAMETER CreateDirectory Creates a missing destination directory only after ShouldProcess approval. In -WhatIf mode, no directory is created. .PARAMETER Force Overwrites an existing file. .PARAMETER PassThru Returns the resulting FileInfo object. .PARAMETER Connection A connection object, name, or ID. .EXAMPLE Save-DattoDtcAssetScreenshot -ClientId 12345 -AssetUuid 'deadbeef-dead-beef-dead-beefdeadbeef' -Path '.\screenshots\' -CreateDirectory -PassThru #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Low')] param( [Parameter(Mandatory, ValueFromPipelineByPropertyName)][ValidateRange(1, [int]::MaxValue)][int]$ClientId, [Parameter(Mandatory, ValueFromPipelineByPropertyName)][ValidateNotNullOrEmpty()][string]$AssetUuid, [Parameter(Mandatory)][ValidateNotNullOrEmpty()][string]$Path, [Parameter()][switch]$CreateDirectory, [Parameter()][switch]$Force, [Parameter()][switch]$PassThru, [Parameter()][AllowNull()][object]$Connection ) process { $safeAsset = ConvertTo-DattoApiSafeFileComponent -Value $AssetUuid $destination = Resolve-DattoApiOutputPath -Path $Path -DefaultFileName "Datto-DTC-$ClientId-$safeAsset-latest.jpg" -RequiredExtension '.jpg' -CreateDirectory:$CreateDirectory if ((Test-Path -LiteralPath $destination -PathType Leaf) -and -not $Force) { throw [System.IO.IOException]::new("The destination file already exists: $destination. Use -Force to overwrite it.") } if (-not $PSCmdlet.ShouldProcess($destination, 'Save latest Datto Direct-to-Cloud screenshot')) { return } $destinationDirectory = Split-Path -Path $destination -Parent if (-not (Test-Path -LiteralPath $destinationDirectory -PathType Container)) { if (-not $CreateDirectory) { throw [System.IO.DirectoryNotFoundException]::new("The destination directory does not exist: $destinationDirectory") } $null = New-Item -ItemType Directory -Path $destinationDirectory -Force } $asset = ConvertTo-DattoApiPathSegment -Value $AssetUuid $response = Invoke-DattoApiHttpRequest -Method GET -Path "/v1/dtc/$ClientId/assets/$asset/screenshot/latest" -Connection $Connection -Accept 'image/jpeg' -AsByteArray Assert-DattoApiImageResponse -Response $response -ImageType Jpeg Write-DattoApiFileAtomically -Path $destination -Bytes $response.Bytes -Force:$Force if ($PassThru) { Get-Item -LiteralPath $destination } } } |