Scripts/Restore/Restore-CohesityRemoteFile.ps1

function Restore-CohesityRemoteFile {
    <#
        .SYNOPSIS
        Restores the specified files or folders from a previous backup from a remote cluster.
        .DESCRIPTION
        Restores the specified files or folders from a previous backup from a remote cluster.
        .NOTES
        Published by Cohesity
        .LINK
        https://cohesity.github.io/cohesity-powershell-module/#/README
        .EXAMPLE
        Restore-CohesityRemoteFile -TaskName "restore-file-vm" -FileNames /C/data/file.txt -JobId 1234 -SourceId 843 -TargetSourceId 856 -TargetParentSourceId 828 -TargetHostCredential (Get-Credential)
        Restores the specified file to the target windows VM with the source id 843 from the latest backup.
        Get the job id from $jobs = Get-CohesityProtectionJob -Environments KVMware
        Get the source id from $jobs[0].sourceIds
        Get the target details $targets = Get-CohesityProtectionSourceObject -Environments KVMware
        Get the target source id $targets[2].id
        Get the target parent source id $targets[2].parentId
 
        .EXAMPLE
        Restore-CohesityRemoteFile -FileNames "/C/myFolder" -NewBaseDirectory "C:\temp\restore" -JobId 61592 -SourceId 3517 -TargetSourceId 3098
        Restores the specified file to the target physical server with the source id 3517 from the latest backup.
    #>


    [CmdletBinding(DefaultParameterSetName = "Default", SupportsShouldProcess = $True, ConfirmImpact = "High")]
    Param(
        [Parameter(Mandatory = $false)]
        # Specifies the name of the Restore Task.
        [string]$TaskName = "Recover-File-" + (Get-Date -Format "dddd-MM-dd-yyyy-HH-mm-ss").ToString(),
        [Parameter(Mandatory = $true)]
        # Specifies the full names of the files or folders to be restored.
        [string[]]$FileNames,
        [Parameter(Mandatory = $true)]
        [ValidateRange(1, [long]::MaxValue)]
        # Specifies the job id that backed up the files and will be used for this restore.
        [long]$JobId,
        [Parameter(Mandatory = $true)]
        [ValidateRange(1, [long]::MaxValue)]
        # Specifies the id of the original protection source (that was backed up) containing the files and folders.
        [long]$SourceId,
        [Parameter(Mandatory = $false)]
        # Specifies an optional base directory where the specified files and folders will be restored.
        # By default, files and folders are restored to their original path.
        [string]$NewBaseDirectory,
        [Parameter(Mandatory = $false)]
        [ValidateRange(1, [long]::MaxValue)]
        # Specifies the Job Run id that captured the snapshot.
        # If not specified, the latest backup run is used.
        [long]$JobRunId,
        [Parameter(Mandatory = $false)]
        [ValidateRange(1, [long]::MaxValue)]
        # Specifies the time when the Job Run started capturing a snapshot.
        # Specified as a Unix epoch Timestamp (in microseconds).
        # This must be specified if the job run id is specified.
        [long]$StartTime,
        [Parameter(Mandatory = $false)]
        # Specifies that any existing files and folders should not be overwritten during the restore.
        # By default, any existing files and folders are overwritten by restored files and folders.
        [switch]$DoNotOverwrite,
        [Parameter(Mandatory = $false)]
        # Specifies if the Restore Task should continue even if the restore of some files and folders fails.
        # If specified, the Restore Task ignores errors and restores as many files and folders as possible.
        # By default, the Restore Task stops restoring if any operation fails.
        [switch]$ContinueOnError,
        [Parameter(Mandatory = $false)]
        # Specifies that the Restore Task should not preserve the original attributes of the files and folders.
        # By default, the original attributes are preserved.
        [switch]$DoNotPreserveAttributes,
        [Parameter(Mandatory = $true)]
        [ValidateRange(1, [long]::MaxValue)]
        # Specifies the id of the target source (such as a VM or Physical server) where the files and folders are to be restored.
        [long]$TargetSourceId,
        [Parameter(Mandatory = $false)]
        # User credentials for accessing the target host for restore.
        # This is not required when restoring to a Physical Server but must be specified when restoring to a VM.
        [System.Management.Automation.PSCredential]
        [System.Management.Automation.Credential()]
        $TargetHostCredential
    )
    Begin {
    }

    Process {
        if ($PSCmdlet.ShouldProcess($SourceId)) {
            $job = Get-CohesityProtectionJob -Ids $JobId
            if (-not $job) {
                $errorMsg = "Cannot proceed, the job id '$JobId' is invalid"
                Write-Output $errorMsg
                CSLog -Message $errorMsg -Severity 2
                return
            }
            if ($JobRunId -le 0) {
                $runs = Get-CohesityProtectionJobRun -JobId $JobId -ExcludeErrorRuns:$true -NumRuns 2
                $run = $runs[0]
                $JobRunId = $run.backupRun.jobRunId
                $StartTime = $run.backupRun.stats.startTimeUsecs
            }

            $searchURL = '/irisservices/api/v1/searchvms?entityIds=' + $SourceId
            $sourceVMSearchResult = Invoke-RestApi -Method Get -Uri $searchURL
            if ($null -eq $sourceVMSearchResult) {
                $errorMsg = "Could not search VM with the Source id $SourceId"
                Write-Output $errorMsg
                CSLog -Message $errorMsg -Severity 2
                return
            }
            $sourceVMDetails = $sourceVMSearchResult.vms | Where-Object { $_.vmDocument.objectId.jobId -eq $JobId -and $_.vmDocument.objectId.entity.id -eq $SourceId }
            if ($null -eq $sourceVMDetails) {
                $errorMsg = "Could not find details for VM id = $SourceId"
                Write-Output $errorMsg
                CSLog -Message $errorMsg -Severity 2
                return
            }
            $targetSourceDetail = Get-CohesityProtectionSourceObject -Id $TargetSourceId
            if (-not $targetSourceDetail) {
                $errorMsg = "Details for target source '$TargetSourceId' not found."
                Write-Output $errorMsg
                CSLog -Message $errorMsg -Severity 2
                return
            }

            $restoreToOriginalPaths = $true
            if ($NewBaseDirectory) {
                $restoreToOriginalPaths = $false
            }
            $TARGET_ENTITY_TYPE = 1
            $TARGET_ENTITY_PARENT_SOURCE_TYPE = 1
            $TARGET_HOST_TYPE = 1
            $targetEntity = $null
            $targetUserName = ""
            $targetPassword = ""
            $sourceObjectEntity = $null
            $parentSource = $null
            $targetEntityParentSource = $null
            if ($job.environment -eq "kVMware") {
                $TARGET_ENTITY_VMWARE_TYPE = 8
                $targetUserName = $TargetHostCredential.GetNetworkCredential().UserName
                $targetPassword = $TargetHostCredential.GetNetworkCredential().Password
                $targetEntity = @{
                    id           = $targetSourceDetail.id
                    parentId     = $targetSourceDetail.parentId
                    type         = $TARGET_ENTITY_TYPE
                    displayName  = $targetSourceDetail.name
                    vmwareEntity = @{
                        type = $TARGET_ENTITY_VMWARE_TYPE
                        name = $targetSourceDetail.name
                    }
                }
                $sourceObjectEntity = @{
                    type         = $sourceVMDetails.vmDocument.objectId.entity.type
                    vmwareEntity = @{
                        type = $sourceVMDetails.vmDocument.objectId.entity.vmwareEntity.type
                    }
                    id           = $sourceVMDetails.vmDocument.objectId.entity.id
                    parentId     = $sourceVMDetails.vmDocument.objectId.entity.parentId
                    displayName  = $sourceVMDetails.vmDocument.objectId.entity.displayName
                }
                $parentSource = @{
                    id = $sourceVMDetails.registeredSource.id
                }
                $targetEntityParentSource = @{
                    type = $TARGET_ENTITY_PARENT_SOURCE_TYPE
                    id   = $targetSourceDetail.parentId
                }
            }
            else {
                # for files from physical server
                $TARGET_ENTITY_TYPE = 6
                $TARGET_ENTITY_PHYSICAL_TYPE = 1
                $TARGET_HOST_TYPE = $null
                $targetEntity = @{
                    id             = $targetSourceDetail.id
                    type           = $TARGET_ENTITY_TYPE
                    displayName    = $targetSourceDetail.name
                    physicalEntity = @{
                        type     = $TARGET_ENTITY_PHYSICAL_TYPE
                        name     = $targetSourceDetail.name
                        hostType = $targetSourceDetail.physicalProtectionSource.hostType
                    }
                }
                $sourceObjectEntity = @{
                    type           = $sourceVMDetails.vmDocument.objectId.entity.type
                    physicalEntity = @{
                        type     = $sourceVMDetails.vmDocument.objectId.entity.physicalEntity.type
                        hostType = $sourceVMDetails.vmDocument.objectId.entity.physicalEntity.hostType
                    }
                    id             = $sourceVMDetails.vmDocument.objectId.entity.id
                    displayName    = $sourceVMDetails.vmDocument.objectId.entity.displayName
                }
            }

            $payload = @{
                filenames        = @($FileNames)
                name             = $TaskName
                params           = @{
                    targetEntity             = $targetEntity
                    targetEntityParentSource = $targetEntityParentSource
                    targetEntityCredentials  = @{
                        username = $targetUserName
                        password = $targetPassword
                    }
                    restoreFilesPreferences  = @{
                        restoreToOriginalPaths        = $restoreToOriginalPaths
                        overrideOriginals             = -not ($DoNotOverwrite.IsPresent)
                        preserveTimestamps            = $true
                        preserveAcls                  = $true
                        preserveAttributes            = -not ($DoNotPreserveAttributes.IsPresent)
                        continueOnError               = $ContinueOnError.IsPresent
                        alternateRestoreBaseDirectory = $NewBaseDirectory
                    }
                    targetHostType           = $TARGET_HOST_TYPE
                    useExistingAgent         = $false
                }
                sourceObjectInfo = @{
                    jobId          = $sourceVMDetails.vmDocument.objectId.jobId
                    jobInstanceId  = $JobRunId
                    startTimeUsecs = $StartTime
                    parentSource   = $parentSource
                    entity         = $sourceObjectEntity
                    jobUid         = $sourceVMDetails.vmDocument.objectId.jobUid
                }
            }

            $version = $sourceVMDetails.vmDocument.versions | Where-Object {$_.instanceId.jobInstanceId -eq $JobRunId}
            if(($version.replicaInfo.replicaVec | Sort-Object -Property {$_.target.type})[0].target.type -eq 3){
                $payload.sourceObjectInfo['archivalTarget'] = $version.replicaInfo.replicaVec[0].target.archivalTarget
            }
            $url = '/irisservices/api/v1/restoreFiles'
            $payloadJson = $payload | ConvertTo-Json -Depth 100

            $resp = Invoke-RestApi -Method 'Post' -Uri $url -Body $payloadJson
            if ($Global:CohesityAPIStatus.StatusCode -eq 200) {
                $taskId = $resp.restoreTask.performRestoreTaskState.base.taskId
                if ($taskId) {
                    $resp = Get-CohesityRestoreTask -Ids $taskId
                    $resp
                }
                else {
                    $resp
                }
            }
            else {
                $errorMsg = $Global:CohesityAPIStatus.ErrorMessage + ", File operation : Failed to recover."
                Write-Output $errorMsg
                CSLog -Message $errorMsg
            }
        }
    }
    End {
    }
}