> 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 Crei variabili globali e segrete in PowerShell Universal, gestisca le casseforti dei segreti e consulti le variabili integrate disponibili in script, API e app. 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 i propri ambienti, dovrà configurare quali variabili includere. È possibile fare riferimento a una variabile come a qualsiasi altra variabile di PowerShell. La variabile conterrà il valore impostato. Se utilizza un segreto, conterrà il valore del segreto. {% hint style="info" %} Le variabili sono memorizzate nel file di configurazione `variables.ps1`. {% endhint %} ## Creazione di una variabile Per creare una variabile, vada alla pagina Manage > Variables & Secrets > Variables. Faccia clic su Create Variable per definire una nuova variabile. 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. ### 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`. Se non lo fa, riceverà errori quando tenterà di avviare processi, come script o dashboard, con quell'account utente. ### Account del servizio gestiti di gruppo Quando si utilizzano gli account del servizio gestiti di gruppo (GMSA), dovrà assicurarsi che il computer 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 è possibile 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à che il segreto sia accessibile nei job pianificati, poiché nel pianificatore 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 (run as). Quando per un segreto è definito un ruolo, esso 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 del database memorizza i segreti all'interno del database di PowerShell Universal. Questi segreti sono crittografati tramite crittografia AES con una chiave personalizzabile. È possibile personalizzare la chiave specificando Secrets \ Database \ EncryptionKey. #### appsettings.json È possibile configurare questa impostazione in appsettings.json. {% code collapsedlinecount="10" %} ```json "Secrets": { "Database": { "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" } } ``` {% endcode %} #### Variabile di ambiente È possibile configurare questa impostazione con una variabile di ambiente. {% code collapsedlinecount="10" %} ```powershell $Env:Secrets__Database__EncryptionKey = "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" ``` {% endcode %} ### BuiltInLocalVault {% hint style="warning" %} Se PowerShell Universal viene eseguito come account del servizio gestito di gruppo, non può utilizzare `BuiltInLocalVault`. {% endhint %} I valori dei segreti con `BuiltInLocalVault` sono memorizzati nell'istanza di Gestione credenziali di Windows dell'entità di sicurezza che esegue PSU. Ad esempio, l'account del servizio dell'utente che esegue il servizio Universal. Se cambia utente (ad esempio eseguendo il servizio come account del servizio), l'account non avrà accesso ai segreti dell'utente precedente e dovrà aggiungere di nuovo tali segreti. ### PSUSecretStore {% hint style="warning" %} Se PowerShell Universal viene eseguito come account del servizio gestito di gruppo, non può utilizzare `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" %} Utilizzi la registrazione della cassaforte Azure Key Vault per configurare Azure Key Vault per PowerShell Universal. {% 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 configurarla. Questo esempio utilizza una versione di PowerShell Universal ospitata in Azure come web-app. In Azure dovremo configurare un'identità gestita per la nostra web app. Questo passaggio non è necessariamente richiesto se esegue il prodotto al di fuori di Azure. È possibile abilitare l'identità gestita nella pagina Identity della web app. Infine, dovremo registrare la key vault e connetterci ad Azure all'avvio della web app. Ciò si può ottenere utilizzando i moduli Az.Account e Az.KeyVault. Dopo aver distribuito la 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. Successivamente, crei uno script all'interno di PowerShell Universal per connettersi ad Azure e registrare la cassaforte. Esegua lo script per verificare che funzioni correttamente. {% 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 %} Ora, quando creerà i segreti, vedrà AzureKeyVault disponibile. Per garantire che l'applicazione sia connessa ad Azure e che la key vault sia registrata, 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. {% code collapsedlinecount="10" %} ```powershell $pwsh = (Get-Command pwsh).Path & $pwsh -File "$PSScriptRoot\registerVault.ps1" ``` {% endcode %} Questo script viene eseguito prima che le variabili vengano registrate e le casseforti individuate. È possibile creare questo file direttamente nella directory Repository.universal. Verrà eseguito durante l'avvio del sistema, prima dell'esecuzione degli altri script di configurazione. ### vaults.ps1 Il file `vaults.ps1` contiene i comandi di registrazione delle casseforti. Sebbene l'esempio precedente definisca una registrazione di cassaforte dei segreti Azure KeyVault, in questo file può includere qualsiasi registrazione di cassaforte necessaria. È possibile modificare le casseforti facendo clic su Manage > Variables & Secrets > Vaults e quindi 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 cercati 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 i propri ambienti, dovrà configurare [quali variabili includere](https://docs.powershelluniversal.com/config/environments#variables). È possibile fare riferimento a una variabile come a qualsiasi altra variabile di PowerShell. La variabile conterrà il valore impostato. Se utilizza un segreto, conterrà il valore del segreto. {% code collapsedlinecount="10" %} ``` $MyVariable ``` {% endcode %} È possibile personalizzare quali variabili sono consentite in un ambiente personalizzando il parametro `-Variable` degli ambienti. Consulti Ambienti per maggiori informazioni. ## Ambito Secret Per accedere ai segreti aggiunti a PowerShell Universal, può utilizzare l'ambito `$Secret`. Ad esempio, se ha definito un segreto denominato `Credential`, potrebbe accedere a tale segreto in qualsiasi punto con l'ambito secret. Non è possibile impostare i segreti utilizzando l'ambito secret. {% code collapsedlinecount="10" %} ```powershell Invoke-Command -Credential $Secret:Credential { Write-Host "Hello" } ``` {% endcode %} ### Accesso alle variabili tramite nome È possibile accedere alle variabili tramite nome utilizzando il prefisso `$Secret:`. {% code collapsedlinecount="10" %} ```powershell # PSCredential $Secret:MyNewSecret.UserName $Secret:MyNewSecret.Password # String $Secret:DashboardSecret ``` {% endcode %} ### Accesso dinamico ai valori È possibile accedere dinamicamente all'ambito secret utilizzando `Get-Item`. L'ambito secret è implementato come provider. Ciò è utile se non dispone di nomi di variabile statici. {% code collapsedlinecount="10" %} ```powershell # PSCredential (Get-ChildItem "Secret:MyNewSecret").UserName (Get-ChildItem "Secret:MyNewSecret").Password # String (Get-ChildItem "Secret:DashboardSecret") ``` {% endcode %} ### ForEach-Object -Parallel Per utilizzare i segreti quando si usa `ForEach-Object` con il parametro `-Parallel`, dovrà sfruttare la parola chiave `$using`. {% code collapsedlinecount="10" %} ```powershell 1..5 | ForEach-Object -Parallel { $using:Secret:MySecret } ``` {% endcode %} ## 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 di PowerShell Universal. Questo riferimento elenca le variabili di PowerShell Universal destinate all'uso nel suo codice. `Get-Variable` restituisce anche le variabili automatiche standard di PowerShell e le variabili di implementazione interne, pertanto il suo output non corrisponderà esattamente a queste tabelle. | 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 un insieme 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 del client che effettua la richiesta | String | | $LocalIpAddress | L'indirizzo IP remoto del servizio che elabora la richiesta | String | | $RemotePort | La porta remota che è stata chiamata per effettuare la richiesta | Integer | | $LocalPort | La porta locale utilizzata per servire la richiesta | Integer | | $Identity | Il nome dell'identità dell'entità 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. È lo stesso oggetto fornito ai criteri di accesso basati sui ruoli. | ClaimPrincipal | ### App Di seguito sono elencate le variabili disponibili nelle app in aggiunta 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. È lo stesso oggetto fornito ai criteri di accesso basati sui ruoli. | ClaimPrincipal | | $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 | | $PSUURL | 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 job. Può utilizzare queste variabili nei suoi script per recuperare informazioni sul job corrente. | Nome | Descrizione | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | $UAJob | Il job attualmente in esecuzione. Include proprietà come lo script, l'utente che ha avviato il job e il momento in cui il job è stato avviato. | | $UAJobId | L'ID del job in esecuzione. | | $UAScript | Lo script in esecuzione. Include proprietà come 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 a suo nome. | | $Roles | I ruoli del chiamante dello script. | #### Struttura dell'oggetto $UAJob Tenga presente che le proprietà possono essere null. Gli oggetti `DateTime` vengono restituiti nel fuso orario 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 %} #### Recupero dell'utente che ha avviato uno script È possibile recuperare il nome dell'utente che ha avviato uno script utilizzando la variabile `UAJob` {% code collapsedlinecount="10" %} ``` $UAJob.Identity.Name ``` {% endcode %} #### Verificare se un job è stato eseguito manualmente È possibile verificare se un job è stato eseguito manualmente utilizzando le proprietà Schedule e Trigger. {% code collapsedlinecount="10" %} ```powershell $Manual = $UAJob.Schedule -eq $null -and $UAJob.Trigger -eq $null ``` {% endcode %} ## Variabili di preferenza Le variabili di preferenza possono essere configurate su uno script, durante l'esecuzione di un job e a livello globale. Includono: * DebugPreference * ErrorActionPreference * InformationPreference * ProgressPreference * VerbosePreference * WarningPreference Le variabili di preferenza hanno una precedenza. L'elenco seguente è ordinato per precedenza. Per 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 Esegui o Invoke-PSUScript * Proprietà dello script * Impostazioni globali ## API * New-PSUVariable * Get-PSUVariable * Remove-PSUVariable * Set-PSUVariable ### Vedi anche * [Devolutions Academy – Aggiunta della funzionalità di sblocco utente](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/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.