> 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 Las variables permiten la definición global de variables que están disponibles dentro de los scripts. También puede importar secretos que están disponibles dentro de los scripts o como credenciales de ejecución. {% hint style="info" %} Las variables se almacenan en el fichero de configuración `variables.ps1`. {% endhint %} ## Crear una variable Para crear una variable, navegue a la página Plataforma \ Variables. Haga clic en Crear variable para definir una nueva variable.

Diálogo Crear 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 dentro de 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 diálogo podrá definir cadenas y PSCredentials en la bóveda especificada.

Diálogo de variable secreta

### Formato de credencial En algunos entornos, puede ser necesario especificar el nombre de dominio en el campo de nombre de usuario. Puede especificarlo en 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 utilice 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 alojamiento tenga los privilegios adecuados, podrá ejecutar trabajos como 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 la sesión del 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 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 secretos dentro de la base de datos de PowerShell Universal. Estos secretos se cifran mediante cifrado AES usando una clave personalizable. Puede personalizar la clave especificando Secrets \ Database \ EncryptionKey. #### appsettings.json Puede configurar este ajuste en appsettings.json. ```json "Secrets": { "Database": { "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" } } ``` #### Variable de entorno Puede configurar este ajuste con una variable de entorno. ```powershell $Env:Secrets__Database__EncryptionKey = "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" ``` ### 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 dentro de la instancia del Administrador de credenciales de Windows del principal de seguridad que ejecuta PSU. Por ejemplo, la cuenta de servicio del usuario que ejecuta el servicio Universal. Si cambia de usuario (como al ejecutar como una cuenta de servicio), la cuenta no tendrá acceso a los secretos del usuario anterior y deberá 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" %} Considere usar [la gestión de secretos fuera de proceso](/powershell-universal/es/config/settings.md#Secrets) cuando use la bóveda `Az.KeyVault` para evitar conflictos de ensamblados con PowerShell Universal. {% endhint %} Por defecto, no incluimos la extensión de Azure Key Vault directamente en PowerShell Universal. Está disponible un contenedor que incluye los módulos Az.Accounts y Az.KeyVault requeridos 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 alojada en Azure de PowerShell Universal. En Azure, necesitaremos configurar una identidad administrada para nuestra aplicación web. Este paso no es necesariamente obligatorio si se ejecuta fuera de Azure. Puede habilitar la identidad administrada en la página Identidad de su aplicación web. ![](/files/0Lh7FEj3WRMk1lws9C7K) A continuación, deberá permitir que su identidad administrada acceda a su key vault y lea su suscripción. Puede añadir la identidad administrada al grupo integrado Reader para permitir el acceso a la suscripción. ![](/files/K4yxBomir5wG9TVbqfd3) Después, proporcioné todos los privilegios de gestión de secretos y claves a mi identidad administrada en mi recurso Key Vault. ![](/files/tB9SqFQOTRA5gyk4wtJK) Finalmente, necesitaremos registrar el key vault y conectarnos a Azure cuando se inicie la aplicación web. Esto se puede lograr usando los módulos Az.Account y Az.KeyVault. Después de implementar su aplicación web, primero deberá 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. ![](/files/fOtCoKAqmld42bHIJofQ) A continuación, cree un script dentro de PowerShell Universal para conectarse a Azure y registrar la bóveda. Ejecute el script para verificar que funciona correctamente. ```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 ``` Ahora, cuando esté creando secretos, verá AzureKeyVault disponible.

Selector de bóveda de variables secretas

Para garantizar que la aplicación esté conectada a Azure y que el key vault 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. ```powershell $pwsh = (Get-Command pwsh).Path & $pwsh -File "$PSScriptRoot\registerVault.ps1" ``` 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 los comandos de registro de bóvedas. Aunque el ejemplo anterior define un registro de bóveda de secretos de Azure KeyVault, puede incluir en este fichero cualquier registro de bóveda que necesite. Puede editar las bóvedas haciendo clic en Plataforma \ Variables \ Bóvedas y luego navegando 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. Al usar los entornos por defecto, todas las variables se importan automáticamente. Esto se logra 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 referenciar una variable como haría con cualquier otra variable de PowerShell. La variable contendrá el valor que haya establecido. Si usa un secreto, contendrá el valor del secreto. ``` $MyVariable ``` Puede personalizar qué variables se permiten en un entorno personalizando el parámetro `-Variable` de los entornos. Consulte [Entornos](/powershell-universal/es/config/environments.md#variables) para más información. ## Ámbito de secreto Para acceder a los secretos que ha añadido a PowerShell Universal, puede usar el ámbito `$Secret`. Por ejemplo, si definió un secreto llamado `Credential`, podría acceder a ese secreto en cualquier lugar con el ámbito de secreto. No puede establecer secretos usando el ámbito de secreto. ```powershell Invoke-Command -Credential $Secret:Credential { Write-Host "Hello" } ``` ### Acceder a las variables por nombre Puede acceder a las variables por nombre usando el prefijo `$Secret:`. ```powershell # PSCredential $Secret:MyNewSecret.UserName $Secret:MyNewSecret.Password # String $Secret:DashboardSecret ``` ### Acceder a los valores dinámicamente Puede acceder al ámbito de secreto dinámicamente usando `Get-Item`. El ámbito de secreto se implementa como un proveedor. Esto es útil si no tiene nombres de variables estáticos. ```powershell # PSCredential (Get-ChildItem "Secret:MyNewSecret").UserName (Get-ChildItem "Secret:MyNewSecret").Password # String (Get-ChildItem "Secret:DashboardSecret") ``` ### ForEach-Object -Parallel Para usar secretos al utilizar `ForEach-Object` con el parámetro `-Parallel`, deberá aprovechar la palabra clave `$using`. ```powershell 1..5 | ForEach-Object -Parallel { $using:Secret:MySecret } ``` ## Configurar la contraseña de `PSUSecretStore` Por defecto, la contraseña de la bóveda `PSUSecretStore` se almacena dentro de `appsettings.json` en Secrets \ SecretStore \ Password. ## Variables integradas Las siguientes variables están disponibles en todos los entornos dentro de PowerShell Universal. | Nombre | Tipo | Descripción | | --------------- | ------ | -------------------------------------------------------------------------------- | | $PSUEnvironment | string | El nombre del entorno en el que se está ejecutando el script (p. ej. Integrated) | | $Repository | string | La ruta absoluta a la carpeta del repositorio. | ### API Existe un conjunto de variables predefinidas que están disponibles en los endpoints de API. Podrá usar estas variables en sus scripts. | Variable | Descripción | Tipo | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | $Url | URL que el cliente usó para llamar al endpoint | String | | $Method | El método HTTP usado para llamar al endpoint | String | | $Headers | Cabeceras proporcionadas por el cliente para llamar al endpoint | Hashtable | | $Body | La cadena codificada en UTF8 del contenido de la solicitud | String | | $Data | Array de bytes binario para el contenido de la solicitud | Byte\[] | | $RemoteIpAddress | La dirección IP remota usada para realizar la solicitud. | String | | $LocalIpAddress | La dirección IP local usada para atender la solicitud. | String | | $RemotePort | El puerto remoto al que se llamó para realizar la solicitud. | Integer | | $LocalPort | El puerto local que se usó para atender la solicitud. | Integer | | $Identity | El nombre de identidad del principal que accede a la API. | Cadena | | $UrlDefinition | La definición de la URL. | Cadena | | $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). | Cadena | | $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) | Cadena | | $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) | Cadena | | $ClaimsPrincipal | La entidad de seguridad de reclamaciones del usuario actual. Es el mismo objeto que se proporciona a las políticas de acceso basadas en roles. | [ClaimPrincipal](/powershell-universal/es/aplicaciones/role-based-access.md) | ### 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 que ha iniciado sesión. $Null si la autenticación está deshabilitada. | Cadena | | $Roles | Los roles que se han concedido al usuario. $Null si la autenticación está deshabilitada. | Cadena\[] | | $RemoteIpAddress | La dirección IP remota del usuario conectado. | Cadena | | $RemotePort | El puerto remoto del usuario conectado. | Int | | $ClaimsPrincipal | La entidad de seguridad de reclamaciones del usuario actual. Es el mismo objeto que se proporciona a las políticas de acceso basadas en roles. | [ClaimPrincipal](/powershell-universal/es/aplicaciones/role-based-access.md) | | $Headers | Las cabeceras proporcionadas por el navegador. | hashtable | | $Cookies | Las cookies de solicitud proporcionadas por el navegador. | hashtable | | $PSUAppToken | El token de aplicación del usuario actual. Solo está disponible cuando -GrantAppToken está habilitado. | cadena | | $PSUComputerName | La URL del servidor PSU. Solo está disponible cuando -GrantAppToken está habilitado. | cadena | | $DashboardName | El nombre de la aplicación actual | cadena | | $Query | Los parámetros de la cadena de consulta de la URL de la aplicación | Hashtable | | $RefreshToken | El token de actualización al usar OpenID Connect | cadena | | $AccessToken | El token de aplicación al usar OpenID Connect | cadena | | $UDPage | El nombre de la página actual. | cadena | ### 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 utilizó para iniciar el script. | | $UAScheduleId | El ID de la programación que inició el script. | | $AccessToken | Cuando se usa la autenticación OIDC, puede recuperar el token de acceso del usuario actual para acceder a los recursos en su nombre. | | $Roles | Los roles del llamador del script. | #### Estructura del objeto $UAJob Tenga en cuenta que las propiedades pueden ser nulas. Los objetos `DateTime` se devuelven en la zona horaria UTC. ```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 } ``` #### Recuperar el usuario que inició un script Puede recuperar el nombre del usuario que inició el script usando la variable `UAJob` ``` $UAJob.Identity.Name ``` #### Comprobar si un trabajo se ejecutó manualmente Puede comprobar si un trabajo se ejecutó manualmente usando las propiedades Schedule y Trigger. ```powershell $Manual = $UAJob.Schedule -eq $null -and $UAJob.Trigger -eq $null ``` ## 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](/powershell-universal/es/comandos-de-powershell/new-psuvariable.md) * [Get-PSUVariable](/powershell-universal/es/comandos-de-powershell/get-psuvariable.md) * [Remove-PSUVariable](/powershell-universal/es/comandos-de-powershell/remove-psuvariable.md) * [Set-PSUVariable](/powershell-universal/es/comandos-de-powershell/set-psuvariable.md) --- # 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.