> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/es/plataforma/variables.md). # Variables Cree variables globales y secretas en PowerShell Universal, gestione bóvedas de secretos y consulte las variables integradas disponibles en scripts, API y aplicaciones. Las variables se pueden usar en API, scripts y dashboards. Cuando se utilizan los entornos predeterminados, todas las variables se importan automáticamente. Esto se consigue especificando el parámetro `-Variable` de `New-PSUEnvironment` con un comodín (\*). Si utiliza sus propios entornos, tendrá que configurar qué variables desea incluir. Puede hacer referencia a una variable igual que a cualquier otra variable de PowerShell. La variable contendrá el valor que haya establecido. Si utiliza un secreto, contendrá el valor del secreto. {% hint style="info" %} Las variables se almacenan en el fichero de configuración `variables.ps1`. {% endhint %} ## Crear una variable Para crear una variable, vaya a la página Gestionar > Variables y secretos > Variables. Haga clic en Crear variable para definir una nueva variable. Las variables se añadirán a sus scripts antes de que se ejecuten. ## Crear una variable secreta Las variables secretas se almacenan dentro de la bóveda seleccionada. El valor de esas variables nunca se almacena en Universal. Para definir una nueva variable secreta, haga clic en Crear variable secreta en la página de variables y seleccione la pestaña Secreto. Desde este cuadro de diálogo podrá definir cadenas y PSCredentials en la bóveda especificada. ### Formato de credenciales En algunos entornos, puede ser necesario especificar el nombre de dominio en el campo de nombre de usuario. Puede especificarlo con el formato `domain\user` o `user@domain`. Si no lo hace, recibirá errores al intentar iniciar procesos, como scripts o dashboards, con esa cuenta de usuario. ### Cuentas de servicio administradas de grupo Cuando se utilizan cuentas de servicio administradas de grupo (GMSA), deberá asegurarse de que la máquina y la cuenta tengan acceso a la cuenta GSMA. Puede seguir [la guía de Microsoft aquí](https://techcommunity.microsoft.com/blog/itopstalkblog/step-by-step-how-to-work-with-group-managed-service-accounts-gmsa/329864). Una vez completada la configuración, cree una nueva credencial en la gestión de secretos de PowerShell Universal y seleccione la opción Contraseña no requerida. Introduzca la cuenta GSMA (p. ej., domain\user$). Siempre que la cuenta de hospedaje tenga los privilegios adecuados, podrá ejecutar trabajos con la cuenta GMSA. ### Validación de credenciales En Windows, puede validar las credenciales antes de guardar su valor. Haga clic en el botón Validar en el campo de contraseña para intentar iniciar sesión con el usuario localmente. Este botón no aparecerá en sistemas que no sean Windows. ### Roles {% hint style="warning" %} Aplicar roles a un secreto impedirá que el secreto sea accesible en trabajos programados, porque no se aplican roles en el programador. {% endhint %} Las variables secretas pueden incluir acceso basado en roles. Los roles limitan quién puede usar el secreto en sus scripts y como credenciales de ejecución. Cuando un secreto tiene un rol definido, no será accesible en los recursos que no puedan proporcionar ese rol. Esto puede incluir lo siguiente: * Trabajos programados * API o aplicaciones no autenticadas * Terminales ## Bóvedas ### Base de datos La bóveda de base de datos almacena los secretos dentro de la base de datos de PowerShell Universal. Estos secretos se cifran mediante cifrado AES con una clave personalizable. Puede personalizar la clave especificando Secrets \ Database \ EncryptionKey. #### appsettings.json Puede configurar este ajuste en appsettings.json. {% code collapsedlinecount="10" %} ```json "Secrets": { "Database": { "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" } } ``` {% endcode %} #### Variable de entorno Puede configurar este ajuste con una variable de entorno. {% code collapsedlinecount="10" %} ```powershell $Env:Secrets__Database__EncryptionKey = "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" ``` {% endcode %} ### BuiltInLocalVault {% hint style="warning" %} Si PowerShell Universal se ejecuta como una cuenta de servicio administrada de grupo, no puede usar `BuiltInLocalVault`. {% endhint %} Los valores de los secretos con `BuiltInLocalVault` se almacenan en la instancia del Administrador de credenciales de Windows de la entidad de seguridad que ejecuta PSU. Por ejemplo, la cuenta de servicio del usuario que ejecuta el servicio Universal. Si cambia de usuario (como al ejecutarlo con una cuenta de servicio), la cuenta no tendrá acceso a los secretos del usuario anterior y tendrá que añadir esos secretos de nuevo. ### PSUSecretStore {% hint style="warning" %} Si PowerShell Universal se ejecuta como una cuenta de servicio administrada de grupo, no puede usar `PSUSecretStore`. {% endhint %} La bóveda `PSUSecretStore` está integrada con el módulo `SecretStore` de Microsoft para almacenar secretos en un fichero multiplataforma. Este fichero está vinculado a la cuenta de usuario actual que ejecuta PowerShell Universal. La contraseña de la bóveda se almacena en `appsettings.json`. ### Az.KeyVault {% hint style="info" %} Utilice el registro de bóveda de Azure Key Vault para configurar Azure Key Vault para PowerShell Universal. {% endhint %} De forma predeterminada, no incluimos la extensión de Azure Key Vault directamente en PowerShell Universal. Hay disponible un contenedor que incluye los módulos Az.Accounts y Az.KeyVault necesarios para permitirle usar KeyVault desde el primer momento. Puede encontrarlo en [Docker Hub](https://hub.docker.com/r/devolutions/powershell-universal). A continuación encontrará cómo configurarlo. Este ejemplo utiliza una versión de aplicación web de PowerShell Universal alojada en Azure. En Azure, tendremos que configurar una identidad administrada para nuestra aplicación web. Este paso no es necesariamente obligatorio si la ejecuta fuera de Azure. Puede habilitar la identidad administrada en la página Identidad de su aplicación web. Por último, tendremos que registrar el almacén de claves y conectarnos a Azure cuando se inicie la aplicación web. Esto se puede conseguir usando los módulos Az.Account y Az.KeyVault. Después de desplegar su aplicación web, primero tendrá que instalar los módulos Az.Account y Az.KeyVault. Puede hacerlo en la página de módulos. Se instalarán en el repositorio local dentro de la aplicación web. A continuación, cree un script en PowerShell Universal para conectarse a Azure y registrar la bóveda. Ejecute el script para comprobar que funciona correctamente. {% code collapsedlinecount="10" %} ```powershell $sub = 'affdf0d4-eed5-48a6-889c-599d482xxxxx' Connect-AzAccount -Id -Scope CurrentUser -SubscriptionId $sub Register-SecretVault -ModuleName Az.KeyVault -Name AzureKeyVault -VaultParameters @{ AZKVaultName = 'psu-demo' SubscriptionId = $sub } -AllowClobber ``` {% endcode %} Ahora, cuando cree secretos, verá AzureKeyVault disponible. Para asegurarse de que la aplicación está conectada a Azure y de que el almacén de claves está registrado, ejecute el script dentro de `vaults.ps1`. Recomendamos ejecutar el script en un proceso externo de PowerShell para evitar conflictos de ensamblados con las DLL de PowerShell Universal. {% code collapsedlinecount="10" %} ```powershell $pwsh = (Get-Command pwsh).Path & $pwsh -File "$PSScriptRoot\registerVault.ps1" ``` {% endcode %} Este script se ejecuta antes de que se registren las variables y se localicen las bóvedas. Puede crear este fichero directamente en el directorio Repository.universal. Se ejecutará durante el inicio del sistema, antes de que se ejecuten otros scripts de configuración. ### vaults.ps1 El fichero `vaults.ps1` contiene comandos de registro de bóvedas. Aunque el ejemplo anterior define un registro de bóveda de secretos de Azure KeyVault, en realidad puede incluir en este fichero cualquier registro de bóveda que necesite. Puede editar las bóvedas haciendo clic en Gestionar > Variables y secretos > Bóvedas y navegando después a la pestaña vaults.ps1. ## Importar variables secretas También puede importar secretos preexistentes como variables en Universal. Los valores de las variables no se importan, pero se buscarán durante la ejecución. Haga clic en el botón Importar secreto para importar secretos. ## Uso de variables Las variables se pueden usar en API, scripts y dashboards. Cuando se utilizan los entornos predeterminados, todas las variables se importan automáticamente. Esto se consigue especificando el parámetro `-Variable` de `New-PSUEnvironment` con un comodín (\*). Si utiliza sus propios entornos, tendrá que configurar [qué variables desea incluir](https://docs.powershelluniversal.com/config/environments#variables). Puede hacer referencia a una variable igual que a cualquier otra variable de PowerShell. La variable contendrá el valor que haya establecido. Si utiliza un secreto, contendrá el valor del secreto. {% code collapsedlinecount="10" %} ``` $MyVariable ``` {% endcode %} Puede personalizar qué variables se permiten en un entorno personalizando el parámetro `-Variable` del entorno. Consulte Entornos para obtener más información. ## Ámbito de secretos Para acceder a los secretos que ha añadido a PowerShell Universal, puede usar el ámbito `$Secret`. Por ejemplo, si ha definido un secreto llamado `Credential`, podría acceder a ese secreto en cualquier lugar con el ámbito de secretos. No puede establecer secretos usando el ámbito de secretos. {% code collapsedlinecount="10" %} ```powershell Invoke-Command -Credential $Secret:Credential { Write-Host "Hello" } ``` {% endcode %} ### Acceder a las variables por nombre Puede acceder a las variables por nombre usando el prefijo `$Secret:`. {% code collapsedlinecount="10" %} ```powershell # PSCredential $Secret:MyNewSecret.UserName $Secret:MyNewSecret.Password # String $Secret:DashboardSecret ``` {% endcode %} ### Acceder a los valores de forma dinámica Puede acceder al ámbito de secretos de forma dinámica usando `Get-Item`. El ámbito de secretos se implementa como un proveedor. Esto resulta útil si no tiene nombres de variables estáticos. {% code collapsedlinecount="10" %} ```powershell # PSCredential (Get-ChildItem "Secret:MyNewSecret").UserName (Get-ChildItem "Secret:MyNewSecret").Password # String (Get-ChildItem "Secret:DashboardSecret") ``` {% endcode %} ### ForEach-Object -Parallel Para usar secretos al utilizar `ForEach-Object` con el parámetro `-Parallel`, tendrá que aprovechar la palabra clave `$using`. {% code collapsedlinecount="10" %} ```powershell 1..5 | ForEach-Object -Parallel { $using:Secret:MySecret } ``` {% endcode %} ## Configurar la contraseña de `PSUSecretStore` De forma predeterminada, la contraseña de la bóveda `PSUSecretStore` se almacena en `appsettings.json`, en Secrets \ SecretStore \ Password. ## Variables integradas Las siguientes variables están disponibles en todos los entornos de PowerShell Universal. Esta referencia enumera las variables de PowerShell Universal destinadas a usarse en su código. `Get-Variable` también devuelve variables automáticas estándar de PowerShell y variables internas de implementación, por lo que su salida no coincidirá exactamente con estas tablas. | Nombre | Tipo | Descripción | | --------------- | ------ | ------------------------------------------------------------------------- | | $PSUEnvironment | string | El nombre del entorno en el que se ejecuta el script (p. ej., Integrated) | | $Repository | string | La ruta absoluta a la carpeta del repositorio. | ### API Existe un conjunto de variables predefinidas disponibles en los endpoints de API. Podrá usar estas variables en sus scripts. | Variable | Descripción | Tipo | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | $Url | URL que el cliente utilizó para llamar al endpoint | String | | $Method | El método HTTP utilizado para llamar al endpoint | String | | $Headers | Encabezados proporcionados por el cliente para llamar al endpoint | Hashtable | | $Body | La cadena codificada en UTF8 del contenido de la solicitud | String | | $Data | Matriz binaria de bytes del contenido de la solicitud | Byte\[] | | $RemoteIpAddress | La dirección IP remota del cliente que realiza la solicitud | String | | $LocalIpAddress | La dirección IP remota del servicio que procesa la solicitud | String | | $RemotePort | El puerto remoto al que se llamó para realizar la solicitud | Integer | | $LocalPort | El puerto local que se utilizó para atender la solicitud | Integer | | $Identity | El nombre de identidad de la entidad de seguridad que accede a la API. | String | | $UrlDefinition | La definición de la URL. | String | | $ConnectionId | El [ID de conexión del contexto HTTP](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.connectioninfo.id?view=aspnetcore-6.0#Microsoft.AspNetCore.Http.ConnectionInfo.Id). | String | | $SessionId | El [ID de sesión del contexto HTTP.](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.isession.id?view=aspnetcore-6.0#Microsoft.AspNetCore.Http.ISession.Id) | String | | $RequestId | El [ID de solicitud del contexto HTTP](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.httpcontext.traceidentifier?view=aspnetcore-6.0#Microsoft.AspNetCore.Http.HttpContext.TraceIdentifier) | String | | $ClaimsPrincipal | La entidad de seguridad de notificaciones del usuario actual. Es el mismo objeto que se proporciona a las políticas de acceso basadas en roles. | ClaimPrincipal | ### Aplicaciones A continuación se muestran las variables disponibles en las aplicaciones, además de las variables globales. | Nombre | Descripción | Tipo | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | $User | El nombre de usuario del usuario conectado. $Null si la autenticación está deshabilitada. | String | | $Roles | Los roles que se han concedido al usuario. $Null si la autenticación está deshabilitada. | String\[] | | $RemoteIpAddress | La dirección IP remota del usuario conectado. | String | | $RemotePort | El puerto remoto del usuario conectado. | Int | | $ClaimsPrincipal | La entidad de seguridad de notificaciones del usuario actual. Es el mismo objeto que se proporciona a las políticas de acceso basadas en roles. | ClaimPrincipal | | $Headers | Las cabeceras proporcionadas por el navegador. | hashtable | | $Cookies | Las cookies de la solicitud proporcionadas por el navegador. | hashtable | | $PSUAppToken | El token de aplicación del usuario actual. Solo está disponible cuando -GrantAppToken está habilitado. | string | | $PSUURL | La URL del servidor PSU. Solo está disponible cuando -GrantAppToken está habilitado. | string | | $DashboardName | El nombre de la aplicación actual | string | | $Query | Los parámetros de la cadena de consulta de la URL de la aplicación | Hashtable | | $RefreshToken | El token de actualización cuando se usa OpenID Connect | string | | $AccessToken | El token de aplicación cuando se usa OpenID Connect | string | | $UDPage | El nombre de la página actual | string | ### Scripts Hay varias variables integradas que se definen cuando se ejecuta un trabajo. Puede usar estas variables en sus scripts para recuperar información sobre el trabajo actual. | Nombre | Descripción | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | $UAJob | El trabajo actual que se está ejecutando. Incluirá propiedades como el script, el usuario que inició el trabajo y cuándo se inició el trabajo. | | $UAJobId | El ID del trabajo en ejecución. | | $UAScript | El script que se está ejecutando. Incluirá propiedades como el nombre del script y la ruta al script. | | $UAScriptId | El ID del script en ejecución. | | $UASchedule | La programación que se usó para iniciar el script. | | $UAScheduleId | El ID de la programación que inició el script. | | $AccessToken | Cuando se usa autenticación OIDC, puede recuperar el token de acceso del usuario actual para acceder a recursos en su nombre. | | $Roles | Los roles del autor de la llamada al script. | #### Estructura del objeto $UAJob Tenga en cuenta que las propiedades pueden ser nulas. Los objetos `DateTime` se devuelven en la zona horaria UTC. {% code collapsedlinecount="10" %} ```csharp class Job { public long Id { get; set; } public DateTime CreatedTime { get; set; } public DateTime StartTime { get; set; } public DateTime EndTime { get; set; } public JobStatus Status { get; set; } public string Output { get; set; } public string ScriptFullPath { get; set; } public Identity Identity { get; set; } public Job ParentJob { get; set; } public int ParentLineNumber { get; set; } public string ComputerName { get; set; } public int ProcessId { get; set; } public long MemoryBytes { get; set; } public int RunspaceId { get; set; } public string Activity { get; set; } public string CurrentOperation { get; set; } public int PercentComplete { get; set; } public int SecondsRemaining { get; set; } public string StatusDescription { get; set; } public string Environment { get; set; } public Computer Computer { get; set; } public ActionPreference ErrorAction { get; set; } public IEnumerable Children { get; set; } public IEnumerable Parameters { get; set; } public string Credential { get; set; } public long ScheduleId { get; set; } public bool Triggered { get; set; } public string Trigger { get; set; } public int RetryCount { get; set; } public string Tags { get; set; } public string Schedule { get; set; } public bool Archived { get; set; } public bool Batch { get; set; } public Guid? RunId { get; set; } public string Roles { get; set; } } public enum JobStatus { Queued, Running, Completed, Failed, WaitingOnFeedback, Canceled, Canceling, Historical, Active, TimedOut, Warning, Error } ``` {% endcode %} #### Recuperar el usuario que inició un script Puede recuperar el nombre del usuario que inició un script usando la variable `UAJob` {% code collapsedlinecount="10" %} ``` $UAJob.Identity.Name ``` {% endcode %} #### Comprobar si un trabajo se ejecutó manualmente Puede comprobar si un trabajo se ejecutó manualmente usando las propiedades Schedule y Trigger. {% code collapsedlinecount="10" %} ```powershell $Manual = $UAJob.Schedule -eq $null -and $UAJob.Trigger -eq $null ``` {% endcode %} ## Variables de preferencia Las variables de preferencia se pueden configurar en un script, durante la ejecución de un trabajo y a nivel global. Estas incluyen: * DebugPreference * ErrorActionPreference * InformationPreference * ProgressPreference * VerbosePreference * WarningPreference Las variables de preferencia tienen precedencia. La siguiente lista está ordenada por precedencia. Por ejemplo, si un script establece manualmente la variable `$DebugPreference`, esta anulará el valor establecido en el cuadro de diálogo de propiedades del script. * Script * Cuadro de diálogo Ejecutar o Invoke-PSUScript * Propiedades del script * Configuración global ## API * New-PSUVariable * Get-PSUVariable * Remove-PSUVariable * Set-PSUVariable ### Véase también * [Devolutions Academy – Adding user unlock feature](https://academy.devolutions.net/student/activity/3546024-part-4-adding-user-unlock-feature) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/es/plataforma/variables.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.