Trabajos

Los trabajos son el resultado de ejecutar un script. Los trabajos se conservan según la configuración a nivel de script y de servidor.

Visualización de trabajos

Los trabajos se pueden ver haciendo clic en la página Automation / Jobs. Haga clic en el botón View para navegar hasta el trabajo. Los trabajos en curso también se pueden cancelar.

Lista de trabajos

Ver la salida del trabajo

Los flujos estándar de PowerShell, como information, host, error, warning y verbose, se muestran en el panel de salida.

Salida del flujo del trabajo

Ver la salida de canalización del trabajo

Almacenar grandes cantidades de salida de canalización puede afectar negativamente al rendimiento. Puede descartar la salida de canalización estableciendo la configuración Discard Pipeline en los scripts.

La salida de canalización de los trabajos también se almacena en PowerShell Universal. Cualquier objeto que se escriba en la canalización se almacena como CliXml y está disponible para su visualización en la pestaña Pipeline Output.

Puede expandir la vista de árbol para ver los objetos y propiedades de la canalización.

Salida de canalización del trabajo

Visualización de errores

Cualquier error escrito en el flujo de errores estará disponible en la pestaña Error dentro de la página del trabajo.

Salida de error del trabajo

Estado

Los trabajos devolverán varios estados en función de la configuración y del resultado de la ejecución. Los ajustes que pueden afectar al estado del trabajo incluyen:

• ErrorActionPreference
• WarningActionPreference

En la tabla siguiente se describe cómo PowerShell Universal trata los estados.

Estado	Descripción	Suprimir
Error	Un script tuvo un error no terminante.	Establezca ErrorActionPreference en SilentlyContinue
Advertencia	Un script tuvo una advertencia.	Establezca WarningActionPreference en SilentlyContinue
Fallido	Un script tuvo un error terminante.	Gestione el error terminante o captúrelo.
En espera de respuesta	Un script está esperando una respuesta, como Read-Host.	Evite las llamadas de retorno al usuario, como read-host.
En ejecución	El script se está ejecutando actualmente.	N\A
En cola	El script está actualmente en cola para ejecutarse.	N\A

Respuesta

Algunos trabajos requerirán una respuesta. Cualquier script que contenga una llamada Read-Host esperará hasta que haya interacción del usuario con ese trabajo. El trabajo estará en estado Waiting for Feedback y puede responder a esa solicitud haciendo clic en el botón Response to Feedback en la página del trabajo.

Trabajo en espera de respuesta

Para aceptar un SecureString con un campo de entrada de contraseña, puede usar el parámetro -AsSecureString de Read-Host.

Invocar trabajos desde PowerShell

Puede usar Invoke-PSUScript para invocar trabajos desde la línea de comandos. Necesitará un App Token válido para ello. Los parámetros se definen mediante parámetros dinámicos en el cmdlet Invoke-PSUScript.

Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello'

Llamar a scripts desde scripts

También puede llamar a scripts de UA desde scripts de UA. Al ejecutar un trabajo en UA, no necesita definir manualmente un token de aplicación ni el nombre del ordenador. Estos se definirán automáticamente. Puede simplemente llamar a Invoke-PSUScript dentro de su script para iniciar otro script. Ambos trabajos se mostrarán en la interfaz de usuario. Si desea esperar a que el script termine, use Wait-PSUJob.

Esperar a que un script finalice

Puede usar el cmdlet Wait-PSUJob para esperar a que un trabajo finalice. Canalice el valor devuelto de Invoke-PSUScript a Wait-UAJob para esperar a que el trabajo se complete. Wait-PSUJob esperará indefinidamente a menos que se especifique el parámetro -Timeout.

Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello' | Wait-PSUJob

Devolver datos de canalización

Puede usar el cmdlet Get-PSUJobPipelineOutput para devolver la salida de canalización producida por un trabajo. Esta salida de canalización serán objetos deserializados que se escribieron en la canalización durante el trabajo. Puede acceder a estos datos desde donde tenga acceso a la API de gestión de PowerShell Universal.

Get-PSUJobPipelineOutput -JobId 10

Devolver la salida del último trabajo

Puede ser necesario devolver la salida de la última ejecución de trabajo de un script. Para ello, necesitará usar una combinación de cmdlets para recuperar el script, el ID del último trabajo y luego devolver la salida de canalización o de host.

$Job = Get-PSUScript -Name 'Script.ps1' | Get-PSUJob -OrderDirection Descending -First 1
Get-PSUJobPipelineOutput -Job $Job
Get-PSUJobOutput -Job $Job

Devuelve la salida del último trabajo como un objeto

De forma predeterminada, Get-PSUJobOutput devolverá la salida como una cadena. Para devolver la salida como un objeto con información sobre la salida, use -AsObject.

$Job = Get-PSUScript -Name 'Script.ps1' | Get-PSUJob -OrderDirection Descending -First 1
Get-PSUJobOutput -Job $Job -AsObject

Invocar un script y esperar la salida

Puede usar el parámetro -Wait de Invoke-PSUScript para lograrlo.

$Output = Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello' -Wait

Además, el siguiente ejemplo invoca un script, almacena el objeto de trabajo en una variable $job, espera a que el trabajo se complete y luego devuelve la salida de canalización y de host.

Invoke-PSUScript -Script 'Script1.ps1' -RequiredParameter 'Hello' | Tee-Object -Variable job | Wait-PSUJob

$Output = Get-PSUJobPipelineOutput -Job $Job
Get-PSUJobOutput -Job $Job

Modo integrado

El modo integrado permite llamar a estos cmdlets desde dentro de PowerShell Universal sin un token de aplicación ni un nombre de ordenador. Utiliza el canal RPC interno para comunicarse.

Puede establecer el parámetro -Integrated para cambiar al modo integrado. Este parámetro no funciona fuera de PowerShell Universal.

Invoke-PSUScript -Script 'Script.ps1' -Integrated

Los siguientes cmdlets admiten el modo integrado.

• Get-PSUScript
• Invoke-PSUScript
• Get-PSUJob
• Get-PSUJobOutput
• Get-PSUJobPipelineOutput
• Get-PSUJobFeedback
• Set-PSUJobFeedback
• Wait-PSUJob

Invocar trabajos con REST

Puede llamar a trabajos mediante REST usando la API de gestión de PowerShell Universal. Necesitará un token de aplicación válido para invocar trabajos.

Llamar a scripts con REST

Para llamar a un script, se realiza un HTTP POST al endpoint del script con el ID del script que desea ejecutar.

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body "" -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Proporcionar parámetros

Puede proporcionar parámetros al trabajo mediante una cadena de consulta. Los parámetros se proporcionarán a su script como cadenas.

$Parameters = @{
    Uri = "http://localhost:5000/api/v1/script/path/PNP.ps1?Server=tester&Domain=test" 
    Method = "POST"
    Headers = @{Authorization = "Bearer $Apptoken"}
    ContentType = 'application/json'
    Body = '{}'
}

Invoke-RestMethod @Parameters

Configurar el entorno

Puede establecer el entorno pasando la propiedad environment al contexto del trabajo. La propiedad debe ser el nombre de un entorno definido dentro de su instancia de PSU.

$JobContext = @{
    Environment = "PowerShell 7"
} | ConvertTo-Json

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body $JobContext -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Configurar la cuenta de ejecución

Puede establecer la cuenta de ejecución pasando el nombre de una variable PSCredential a la propiedad Credential.

$JobContext = @{
    Credential = "MyUser"
} | ConvertTo-Json

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body $JobContext -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Invocar trabajos desde aplicaciones

Puede usar los mismos cmdlets que usa en otros scripts de PowerShell para ejecutar scripts en aplicaciones. Puede que desee una experiencia más interactiva al hacerlo. A continuación se muestran algunos ejemplos de cómo lograrlo usando el framework de aplicaciones.

Mostrar la salida

Puede usar los cmdlets Invoke-PSUScript y Get-PSUJobOutput para crear un elemento de interfaz de usuario que se actualiza a medida que se ejecuta el script. Supongamos que tiene un script como el siguiente. Simplemente escribe en el flujo Information cada 100 milisegundos, 100 veces.

1..100 | % {
    Write-Output "Hello $_"
    Start-Sleep -Milliseconds 100
}

Dentro de su aplicación, puede iniciar el script en función de alguna interacción del usuario y luego actualizar un elemento mientras el script se está ejecutando. El siguiente ejemplo crea un botón y un elemento de etiqueta pre que sirve como destino para la salida del script. Cuando el usuario hace clic en el botón, se iniciará el trabajo y se esperará a que finalice. Dentro del bucle, recupera la salida del script y luego actualiza el elemento pre con el contenido de la salida.

Por último, recupera un estado actualizado del trabajo y espera 100 milisegundos antes de ejecutarse de nuevo.

New-UDApp -Content {
    New-UDButton -Text "Run Script" -OnClick {
        $Job = Invoke-PSUScript -Name "AppExample.ps1" -Integrated
        while($Job.Status -eq 'Queued' -or $Job.Status -eq 'Running')
        {
            $Output = Get-PSUJobOutput -Job $Job
            Set-UDElement -Id 'output' -Content {
                $Output | ForEach-Object {
                    $_ +  [Environment]::NewLine
                }
            }
            $Job = Get-PSUJob -Id $Job.Id
            Start-Sleep -Milliseconds 100
        }
    } -ShowLoading

    New-UDElement -Tag 'pre' -Id 'output'
}

Mostrar el progreso

El host de PowerShell del framework de aplicaciones se conectará automáticamente con las funciones de PowerShell, como Write-Progress.

Si usa el parámetro -Wait de Invoke-PSUScript , mostrará automáticamente el progreso del script en un cuadro de diálogo en su aplicación. Supongamos que tenemos un script definido como el siguiente. Este script escribe el progreso cada 100 milisegundos.

1..100 | % {
    Write-Progress -Activity "Working..." -PercentComplete $_
    Start-Sleep -Milliseconds 100
}

Dentro de nuestra aplicación, podemos simplemente llamar al script con el parámetro -Wait. Cuando el usuario haga clic en el botón, el progreso se mostrará en la aplicación.

New-UDApp -Content {
    New-UDButton -Text "Run Script" -OnClick {
        Invoke-PSUScript -Name "AppExample.ps1" -Integrated -Wait
    } -ShowLoading
}

Solicitar entrada

El host de PowerShell del framework de aplicaciones se conectará automáticamente con las funciones de PowerShell, como Read-Host.

Si usa el parámetro -Wait de Invoke-PSUScript , solicitará automáticamente la entrada al usuario cuando encuentre el comando Read-Host. Supongamos que tenemos un script que solicita la entrada del usuario mediante Read-Host.

Read-Host -Prompt "What should I say?"

En su aplicación, simplemente llame al script con el parámetro -Wait.

New-UDApp -Content {
    New-UDButton -Text "Run Script" -OnClick {
        Invoke-PSUScript -Name "AppExample.ps1" -Integrated -Wait
    } -ShowLoading
}

A continuación, se solicitará al usuario a medida que se ejecuta el script.

Variables definidas en los trabajos

Las variables definidas en los trabajos se pueden encontrar en la página de variables.

ID de ejecución del trabajo

El comportamiento predeterminado de PowerShell Universal es realizar el seguimiento de los trabajos según un ID autoincremental basado en int64. Cada vez que se ejecuta un nuevo trabajo, el ID del trabajo es uno más alto que el anterior. Debido a este comportamiento, es fácil adivinar otros ID de trabajo y puede suponer potencialmente un riesgo de seguridad.

Para evitar este problema, puede habilitar la función experimental JobRunID. Aunque internamente el sistema sigue creando trabajos con ID numéricos ascendentes, no puede acceder a los trabajos según esos ID. En su lugar, se usa un nuevo campo llamado RunID. RunID utiliza un GUID en lugar de un ID para las búsquedas. Esto reduce considerablemente la capacidad de un atacante para adivinar un ID de trabajo.

Necesitará habilitar esta función para usarla.

Set-PSUSetting -JobRunId

API

• Invoke-PSUScript
• Get-PSUJob
• Get-PSUJobFeedback
• Get-PSUJobOutput
• Get-PSUJobPipelineOutput
• Wait-PSUJob