> 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/it/piattaforma/variables.md). # Variabili Le variabili consentono la definizione globale di variabili disponibili all'interno degli script. È inoltre possibile importare segreti che sono anch'essi disponibili all'interno degli script o come credenziali di esecuzione. {% hint style="info" %} Le variabili sono memorizzate nel file di configurazione `variables.ps1`. {% endhint %} ## Creazione di una variabile Per creare una variabile, si rechi alla pagina Platform \ Variables. Faccia clic su Create Variable per definire una nuova variabile.

Finestra di dialogo Create Variable

Le variabili verranno aggiunte agli script prima della loro esecuzione. ## Creazione di una variabile segreta Le variabili segrete sono memorizzate nella cassaforte selezionata. Il valore di tali variabili non viene mai memorizzato in Universal. Per definire una nuova variabile segreta, faccia clic su Create Secret Variable nella pagina delle variabili e selezioni la scheda Secret. Da questa finestra di dialogo potrà definire stringhe e PSCredentials nella cassaforte specificata.

Finestra di dialogo Secret Variable

### Formato delle credenziali In alcuni ambienti può essere necessario specificare il nome di dominio nel campo del nome utente. È possibile specificarlo nel formato `domain\user` oppure `user@domain`. In caso contrario, riceverà errori quando tenterà di avviare processi, come script o dashboard, con quell'account utente. ### Group Managed Service Accounts Quando utilizza i Group Managed Service Accounts (GMSA), dovrà assicurarsi che la macchina e l'account abbiano accesso all'account GSMA. Può seguire [la guida di Microsoft qui](https://techcommunity.microsoft.com/blog/itopstalkblog/step-by-step-how-to-work-with-group-managed-service-accounts-gmsa/329864). Una volta completata la configurazione, crei una nuova credenziale nella gestione dei segreti di PowerShell Universal e selezioni l'opzione Password Not Required. Inserisca l'account GSMA (ad es. domain\user$). Purché l'account di hosting disponga dei privilegi appropriati, potrà eseguire i job come account GMSA. ### Convalida delle credenziali Su Windows può convalidare le credenziali prima di salvarne il valore. Faccia clic sul pulsante Validate nel campo della password per tentare l'accesso locale dell'utente. Questo pulsante non compare sui sistemi non Windows. ### Ruoli {% hint style="warning" %} L'applicazione di ruoli a un segreto impedirà l'accesso al segreto nei job pianificati, poiché nello scheduler non viene applicato alcun ruolo. {% endhint %} Le variabili segrete possono includere l'accesso basato sui ruoli. I ruoli limitano chi può utilizzare il segreto nei propri script e come credenziali di esecuzione. Quando un segreto ha un ruolo definito, non sarà accessibile nelle risorse che non possono fornire tale ruolo. Ciò può includere quanto segue: * Job pianificati * API o app non autenticate * Terminali ## Casseforti ### Database La cassaforte database memorizza i segreti all'interno del database di PowerShell Universal. Questi segreti sono cifrati mediante crittografia AES con una chiave personalizzabile. Può personalizzare la chiave specificando Secrets \ Database \ EncryptionKey. #### appsettings.json Può configurare questa impostazione in appsettings.json. ```json "Secrets": { "Database": { "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" } } ``` #### Variabile d'ambiente Può configurare questa impostazione con una variabile d'ambiente. ```powershell $Env:Secrets__Database__EncryptionKey = "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" ``` ### BuiltInLocalVault {% hint style="warning" %} Se PowerShell Universal viene eseguito come group managed service account, non può utilizzare il `BuiltInLocalVault`. {% endhint %} I valori dei segreti con il `BuiltInLocalVault` sono memorizzati nell'istanza di Windows Credential Manager del security principal che esegue PSU. Ad esempio, l'account di servizio dell'utente che esegue il servizio Universal. Se cambia utente (ad esempio eseguendolo come account di servizio), l'account non avrà accesso ai segreti dell'utente precedente e dovrà aggiungere nuovamente tali segreti. ### PSUSecretStore {% hint style="warning" %} Se PowerShell Universal viene eseguito come group managed service account, non può utilizzare il `PSUSecretStore`. {% endhint %} La cassaforte `PSUSecretStore` è integrata con il modulo Microsoft `SecretStore` per memorizzare i segreti in un file multipiattaforma. Questo file è associato all'account utente corrente che esegue PowerShell Universal. La password della cassaforte è memorizzata in `appsettings.json`. ### Az.KeyVault {% hint style="info" %} Valuti l'utilizzo della [gestione dei segreti fuori processo](/powershell-universal/it/config/settings.md#Secrets) quando utilizza la cassaforte `Az.KeyVault`, per evitare conflitti di assembly con PowerShell Universal stesso. {% endhint %} Per impostazione predefinita, non includiamo l'estensione Azure Key Vault direttamente in PowerShell Universal. È disponibile un container che include i moduli Az.Accounts e Az.KeyVault richiesti, per consentirle di utilizzare KeyVault immediatamente. Lo può trovare su [Docker Hub](https://hub.docker.com/r/devolutions/powershell-universal). Di seguito troverà come configurarlo. Questo esempio utilizza una versione web-app di PowerShell Universal ospitata in Azure. In Azure dovremo configurare una managed identity per la nostra web app. Questo passaggio non è necessariamente richiesto se esegue al di fuori di Azure. Può abilitare la managed identity nella pagina Identity della sua web app. ![](/files/ueyigQiytF3k8Qf4v6ct) Successivamente dovrà consentire alla sua managed identity di accedere al key vault e di leggere la sua sottoscrizione. Può aggiungere la managed identity al gruppo integrato Reader per consentire l'accesso alla sottoscrizione. ![](/files/LpEUSu3lnUP7XUAF3HPt) Poi ho fornito tutti i privilegi per la gestione di segreti e chiavi alla mia managed identity nella mia risorsa Key Vault. ![](/files/eq9D5Y4o5hOLx55i7D8m) Infine dovremo registrare il key vault e connetterci ad Azure all'avvio della web app. Ciò può essere realizzato utilizzando i moduli Az.Account e Az.KeyVault. Dopo aver distribuito la sua web app, dovrà prima installare i moduli Az.Account e Az.KeyVault. Può farlo nella pagina dei moduli. Verranno installati nel repository locale all'interno della web app. ![](/files/yB3Mi8q9E43oRzpXLRE6) Successivamente, crei uno script in PowerShell Universal per connettersi ad Azure e registrare la cassaforte. Esegua lo script per verificare che funzioni correttamente. ```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 ``` Ora, quando creerà dei segreti, vedrà AzureKeyVault disponibile.

Selettore della cassaforte per le variabili segrete

Per assicurarsi che l'applicazione sia connessa ad Azure e che il key vault sia registrato, esegua lo script all'interno di `vaults.ps1`. Consigliamo di eseguire lo script in un processo PowerShell esterno per evitare conflitti di assembly con le DLL di PowerShell Universal. ```powershell $pwsh = (Get-Command pwsh).Path & $pwsh -File "$PSScriptRoot\registerVault.ps1" ``` Questo script viene eseguito prima che le variabili siano registrate e le casseforti individuate. Può creare questo file direttamente nella directory Repository\\.universal. Verrà eseguito durante l'avvio del sistema, prima che vengano eseguiti gli altri script di configurazione. ### vaults.ps1 Il file `vaults.ps1` contiene i comandi di registrazione delle casseforti. Sebbene l'esempio precedente definisca la registrazione di una cassaforte Azure KeyVault, in questo file può in realtà includere qualsiasi registrazione di cassaforte le occorra. Può modificare le casseforti facendo clic su Platform \ Variables \ Vaults e poi passando alla scheda vaults.ps1. ## Importazione di variabili segrete Può anche importare in Universal segreti preesistenti come variabili. I valori delle variabili non vengono importati, ma verranno recuperati durante l'esecuzione. Faccia clic sul pulsante Import Secret per importare i segreti. ## Utilizzo delle variabili Le variabili possono essere utilizzate in API, script e dashboard. Quando si utilizzano gli ambienti predefiniti, tutte le variabili vengono importate automaticamente. Ciò si ottiene specificando il parametro `-Variable` di `New-PSUEnvironment` con un carattere jolly (\*). Se utilizza ambienti personalizzati, dovrà configurare [quali variabili desidera includere](https://docs.powershelluniversal.com/config/environments#variables). Può fare riferimento a una variabile come a qualsiasi altra variabile PowerShell. La variabile conterrà il valore impostato. Se utilizza un segreto, conterrà il valore del segreto. ``` $MyVariable ``` Può personalizzare quali variabili sono consentite in un ambiente personalizzando il parametro `-Variable` dell'ambiente. Consulti [Environments](/powershell-universal/it/config/environments.md#variables) per maggiori informazioni. ## Scope Secret Per accedere ai segreti che ha aggiunto a PowerShell Universal, può utilizzare lo scope `$Secret`. Ad esempio, se ha definito un segreto denominato `Credential`, potrà accedere a tale segreto ovunque con lo scope secret. Non è possibile impostare segreti utilizzando lo scope secret. ```powershell Invoke-Command -Credential $Secret:Credential { Write-Host "Hello" } ``` ### Accesso alle variabili per nome Può accedere alle variabili per nome utilizzando il prefisso `$Secret:`. ```powershell # PSCredential $Secret:MyNewSecret.UserName $Secret:MyNewSecret.Password # String $Secret:DashboardSecret ``` ### Accesso dinamico ai valori Può accedere allo scope secret in modo dinamico utilizzando `Get-Item`. Lo scope secret è implementato come provider. Ciò è utile se non dispone di nomi di variabile statici. ```powershell # PSCredential (Get-ChildItem "Secret:MyNewSecret").UserName (Get-ChildItem "Secret:MyNewSecret").Password # String (Get-ChildItem "Secret:DashboardSecret") ``` ### ForEach-Object -Parallel Per utilizzare i segreti quando si usa `ForEach-Object` con il parametro `-Parallel`, dovrà sfruttare la parola chiave `$using`. ```powershell 1..5 | ForEach-Object -Parallel { $using:Secret:MySecret } ``` ## Configurazione della password di `PSUSecretStore` Per impostazione predefinita, la password della cassaforte `PSUSecretStore` è memorizzata in `appsettings.json` in Secrets \ SecretStore \ Password. ## Variabili integrate Le seguenti variabili sono disponibili in tutti gli ambienti all'interno di PowerShell Universal. | Nome | Tipo | Descrizione | | --------------- | ------ | ------------------------------------------------------------------------- | | $PSUEnvironment | string | Il nome dell'ambiente in cui viene eseguito lo script (ad es. Integrated) | | $Repository | string | Il percorso assoluto della cartella del repository. | ### API Esiste una serie di variabili predefinite disponibili negli endpoint API. Potrà utilizzare queste variabili nei suoi script. | Variabile | Descrizione | Tipo | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | $Url | URL utilizzato dal client per chiamare l'endpoint | String | | $Method | Il metodo HTTP utilizzato per chiamare l'endpoint | String | | $Headers | Header forniti dal client per chiamare l'endpoint | Hashtable | | $Body | La stringa con codifica UTF8 del contenuto della richiesta | String | | $Data | Array di byte binario per il contenuto della richiesta | Byte\[] | | $RemoteIpAddress | L'indirizzo IP remoto utilizzato per effettuare la richiesta. | String | | $LocalIpAddress | L'indirizzo IP locale utilizzato per servire la richiesta. | String | | $RemotePort | La porta remota chiamata per effettuare la richiesta. | Integer | | $LocalPort | La porta locale utilizzata per servire la richiesta. | Integer | | $Identity | Il nome dell'identità del principal che accede all'API. | String | | $UrlDefinition | La definizione dell'URL. | String | | $ConnectionId | L'[ID connessione del contesto 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 | L'[ID sessione del contesto 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 | L'[ID richiesta del contesto 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 | Il claims principal dell'utente corrente. Si tratta dello stesso oggetto fornito ai criteri di accesso basati sui ruoli. | [ClaimPrincipal](/powershell-universal/it/app/role-based-access.md) | ### App Di seguito sono elencate le variabili disponibili nelle app oltre alle variabili globali. | Nome | Descrizione | Tipo | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | | $User | Il nome utente dell'utente connesso. $Null se l'autenticazione è disabilitata. | String | | $Roles | I ruoli concessi all'utente. $Null se l'autenticazione è disabilitata. | String\[] | | $RemoteIpAddress | L'indirizzo IP remoto dell'utente connesso. | String | | $RemotePort | La porta remota dell'utente connesso. | Int | | $ClaimsPrincipal | Il claims principal dell'utente corrente. Si tratta dello stesso oggetto fornito ai criteri di accesso basati sui ruoli. | [ClaimPrincipal](/powershell-universal/it/app/role-based-access.md) | | $Headers | Le intestazioni fornite dal browser. | hashtable | | $Cookies | I cookie della richiesta forniti dal browser. | hashtable | | $PSUAppToken | Il token dell'app dell'utente corrente. Disponibile solo quando -GrantAppToken è abilitato. | string | | $PSUComputerName | L'URL del server PSU. Disponibile solo quando -GrantAppToken è abilitato. | string | | $DashboardName | Il nome dell'app corrente | string | | $Query | I parametri della stringa di query dall'URL dell'app | Hashtable | | $RefreshToken | Il token di aggiornamento quando si utilizza OpenID Connect | string | | $AccessToken | Il token dell'app quando si utilizza OpenID Connect | string | | $UDPage | Il nome della pagina corrente. | string | ### Script Esistono diverse variabili integrate che vengono definite quando viene eseguito un processo. È possibile utilizzare queste variabili negli script per recuperare informazioni sul processo corrente. | Nome | Descrizione | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | $UAJob | Il processo attualmente in esecuzione. Include proprietà quali lo script, l'utente che ha avviato il processo e il momento in cui il processo è stato avviato. | | $UAJobId | L'ID del processo in esecuzione. | | $UAScript | Lo script in esecuzione. Include proprietà quali il nome dello script e il percorso dello script. | | $UAScriptId | L'ID dello script in esecuzione. | | $UASchedule | La pianificazione utilizzata per avviare lo script. | | $UAScheduleId | L'ID della pianificazione che ha avviato lo script. | | $AccessToken | Quando si utilizza l'autenticazione OIDC, è possibile recuperare il token di accesso dell'utente corrente per accedere alle risorse per suo conto. | | $Roles | I ruoli del chiamante dello script. | #### Struttura dell'oggetto $UAJob Si noti che le proprietà possono essere null. Gli oggetti `DateTime` vengono restituiti nel fuso orario 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 } ``` #### Recupero dell'utente che ha avviato uno script È possibile recuperare il nome dell'utente che ha avviato lo script utilizzando la variabile `UAJob` ``` $UAJob.Identity.Name ``` #### Verifica se un processo è stato eseguito manualmente È possibile verificare se un processo è stato eseguito manualmente utilizzando le proprietà Schedule e Trigger. ```powershell $Manual = $UAJob.Schedule -eq $null -and $UAJob.Trigger -eq $null ``` ## Variabili di preferenza Le variabili di preferenza possono essere configurate su uno script, durante l'esecuzione di un processo e a livello globale. Comprendono: * DebugPreference * ErrorActionPreference * InformationPreference * ProgressPreference * VerbosePreference * WarningPreference Le variabili di preferenza hanno una precedenza. L'elenco seguente è ordinato per precedenza. Ad esempio, se uno script imposta manualmente la variabile `$DebugPreference`, questa sovrascriverà il valore impostato nella finestra di dialogo delle proprietà dello script. * Script * Finestra di dialogo di esecuzione o Invoke-PSUScript * Proprietà dello script * Impostazioni globali ## API * [New-PSUVariable](/powershell-universal/it/comandi-powershell/new-psuvariable.md) * [Get-PSUVariable](/powershell-universal/it/comandi-powershell/get-psuvariable.md) * [Remove-PSUVariable](/powershell-universal/it/comandi-powershell/remove-psuvariable.md) * [Set-PSUVariable](/powershell-universal/it/comandi-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/it/piattaforma/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.